From sacadmin Wed Aug 29 06:08:37 2007 Received: from sac.sfbay.sun.com (localhost [127.0.0.1]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7TD8b2i009829; Wed, 29 Aug 2007 06:08:37 -0700 (PDT) Received: (from ehring@localhost) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8/Submit) id l7TD8bbL009825; Wed, 29 Aug 2007 06:08:37 -0700 (PDT) Date: Wed, 29 Aug 2007 06:08:37 -0700 (PDT) From: Stephen Ehring Message-Id: <200708291308.l7TD8bbL009825@sac.sfbay.sun.com> To: FWARC-record@sac.sfbay.sun.com Subject: Vendor FCode For MD Node Retrieval [FWARC/2007/496 FastTrack timeout 09/05/2007] Status: RO Content-Length: 576 Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI This information is Copyright 2007 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: Vendor FCode For MD Node Retrieval 1.2. Name of Document Author/Supplier: Author: Stephen Ehring 1.3 Date of This Document: 29 August, 2007 4. Technical Description See the case directory for more detail 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: unknown 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open From sacadmin Wed Aug 29 06:13:15 2007 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7TDDEEt009905 for ; Wed, 29 Aug 2007 06:13:14 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l7TDA9BM049957 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Wed, 29 Aug 2007 07:10:10 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNJ00H1TDXOBT00@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 06:10:36 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNJ00B4RDXMB240@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 06:10:35 -0700 (PDT) Received: from fe-amer-01.sun.com ([192.18.108.175]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l7TDAYfJ024914 for ; Wed, 29 Aug 2007 13:10:34 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNJ00H01DHKIA00@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 07:10:34 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNJ00FN6DXLC55A@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 07:10:34 -0600 (MDT) Date: Wed, 29 Aug 2007 09:10:33 -0400 From: Stephen Ehring Subject: FWARC 2007/496 Vendor FCode For MD Node Retrieval Sender: Stephen.Ehring@sun.com To: Firmware Arch Message-id: <46D57049.8040808@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 User-Agent: Thunderbird 2.0.0.7pre (X11/20070826) Status: RO Content-Length: 3884 I'm sponsoring this fast track case for myself. Timer is set to expire on September 5th. The case defines a new vendor FCode to allow device drivers to easily find the current device instance's node in the MD. The interface can be released in a micro/minor version of the firmware. http://sac.eng.sun.com/Archives/CaseLog/arc/FWARC/2007/496/materials/onepager.txt Steve Copyright 2007 Sun Microsystems, Inc. All Rights Reserved 1. Introduction 1.1. Project/Component Working Name: Vendor FCode For MD Node Retrieval 1.2. Name of Document Author/Supplier: Stephen Ehring 1.3. Date of This Document: 08/28/2007 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: HS PAC 1.4.2. The ARC(s) you expect to review your project: FWARC 1.4.3. The Director/VP who is "Sponsoring" this project: N/A 1.4.4. The name of your business unit: Systems Group 1.5. Email Aliases: 1.5.1. Responsible Manager: chad.solomon@sun.com 1.5.2. Responsible Engineer: stephen.ehring@sun.com 2. Project Summary 2.1. Project Description: This project proposes to add an additional vendor FCode to allow device drivers to easily access their corresponding machine description node. 2.2. Risks and Assumptions: This project, when implemented, will modify the tokenizer. 3. Business Summary 3.1. Problem Area: Currently, any FCode driver that needs to access the machine description to extract property information (such as MAC addresses, hotplug capabilities, etc) must replicate the code to parse through the MD to find the device instance's MD node. 3.2. Market/Requester: Openboot developers and FCode driver developers are the consumers of the interfaces presented in this case. 3.3. Business Justification: These changes will maximize code sharing and minimize FCode driver development complexity. 4. Technical Description: 4.1. Details: FWARC case 2007/070 defined a mechanism where certain IO devices which had Openboot device tree nodes had corresponding nodes in the machine description. This allows hardware-specific information to be extracted from Openboot and the device FCode drivers and migrated into the guest MD. In order for device FCode drivers to easily access it's corresponding MD node, this case defines a new vendor FCode which will return a node pointer to the current device instance's node in the guest MD. This case extends the current set of MD parsing vendor FCodes established by FWARC case 2006/392. ============================================================================= MD-FIND-MY-NODE ( node -- node' | 0 ) VFCODE# 0x641 Where: "node" and "node'" are pointers to node elements in the machine description. Returns the node element in the machine description that corresponds to the current device instance. Search begins at node element "node". To start a search from the beginning of the machine description, specify "node" as 0. Returns 0 if no match was found. ============================================================================= 4.5. Interfaces: Exported Interface Classification Description ======================================================= "md-find-my-node" Uncommitted method to search for the current device instance's node in a machine description 5. Reference Documents: FWARC/2000/166 - Establish VFCODE Registry FWARC/2005/115 - Sun4v Machine Description FWARC/2006/392 - Machine Description Vendor FCodes FWARC/2007/070 - Machine Description IO Device Node Definitions From sacadmin Wed Aug 29 08:19:18 2007 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7TFJHgG012445 for ; Wed, 29 Aug 2007 08:19:17 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l7TFGan5004937 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Wed, 29 Aug 2007 08:16:39 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNJ00N01JRR0700@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 08:16:39 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNJ00BO7JRQAVA0@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 08:16:38 -0700 (PDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id l7TFGcFS015790 for ; Wed, 29 Aug 2007 08:16:38 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) id <0JNJ00801JC72U00@fe-sfbay-09.sun.com> (original mail from Stephen.Kelly@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 08:16:38 -0700 (PDT) Received: from Stephen-Kellys-Computer.local ([129.150.20.24]) by fe-sfbay-09.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) with ESMTPSA id <0JNJ00EVQJRKFGG0@fe-sfbay-09.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 08:16:32 -0700 (PDT) Date: Wed, 29 Aug 2007 08:16:32 -0700 From: Stephen Kelly Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D57049.8040808@sun.com> Sender: Stephen.Kelly@sun.com To: Stephen Ehring Cc: Firmware Arch Message-id: <46D58DD0.3090109@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D57049.8040808@sun.com> User-Agent: Thunderbird 2.0.0.6 (Macintosh/20070728) Status: RO Content-Length: 1435 > > > ============================================================================= > > > MD-FIND-MY-NODE ( node -- node' | 0 ) VFCODE# 0x641 > > Where: > "node" and "node'" are pointers to node elements in the machine > description. > > Returns the node element in the machine description that corresponds to > the current device instance. Search begins at node element "node". > To start a search from the beginning of the machine description, > specify > "node" as 0. I'm confused as to how the node input argument would be used. When/why would it not be 0? Presumably there's only one node in the MD that corresponds to that device instance no matter where you start searching... right? -Steve > Returns 0 if no match was found. > ============================================================================= > > > 4.5. Interfaces: > > Exported Interface Classification Description > ======================================================= > > "md-find-my-node" Uncommitted method to search for the > current device > instance's node in a machine > description > > 5. Reference Documents: > > FWARC/2000/166 - Establish VFCODE Registry > FWARC/2005/115 - Sun4v Machine Description > FWARC/2006/392 - Machine Description Vendor FCodes > FWARC/2007/070 - Machine Description IO Device Node Definitions > > From sacadmin Wed Aug 29 10:42:09 2007 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7THg8G7018485 for ; Wed, 29 Aug 2007 10:42:09 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l7THdQhd015086 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Wed, 29 Aug 2007 18:39:29 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNJ00B01QDSQY00@nwk-avmta-1.sfbay.Sun.COM> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 10:39:28 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNJ005X1QDRMF30@nwk-avmta-1.sfbay.Sun.COM> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 10:39:28 -0700 (PDT) Received: from fe-amer-04.sun.com ([192.18.108.178]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l7THdRhx013010 for ; Wed, 29 Aug 2007 17:39:27 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNJ00A01Q8UWB00@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 11:39:27 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNJ00D7OQDRENN9@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 11:39:27 -0600 (MDT) Date: Wed, 29 Aug 2007 13:39:26 -0400 From: Stephen Ehring Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D58DD0.3090109@sun.com> Sender: Stephen.Ehring@Sun.COM To: Firmware Arch Message-id: <46D5AF4E.5060909@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D57049.8040808@sun.com> <46D58DD0.3090109@sun.com> User-Agent: Thunderbird 2.0.0.7pre (X11/20070826) Status: RO Content-Length: 1397 Stephen Kelly wrote: >> >> ============================================================================= >> >> >> MD-FIND-MY-NODE ( node -- node' | 0 ) VFCODE# 0x641 > > > I'm confused as to how the node input argument would be used. > When/why would it not be 0? Presumably there's only one node in the > MD that corresponds to that device instance no matter where you start > searching... right? It's an optional parameter to reduce MD parsing time. For example, in the recursive PCI probing code if we know we've already parsed the MD to a certain point, then there's no need to parse from the start again. Now that you mention it, this may generate dependencies on MD node positioning in the linear representation of the DAG MD . Since it's optional, I'll remove it. I've also clarified the text somewhat based on feedback from DaveK. Please let me know if it's not clear or if you feel I should add something. ============================================================================= md-find-my-node ( -- node | 0 ) vfcode# 0x641 Where: "node" is a pointer to a node element in the machine description. Returns the node element in the machine description that corresponds to the device pathname of the current instance. Returns 0 if no match was found. ============================================================================= Steve From sacadmin Wed Aug 29 10:48:01 2007 Received: from sunmail4.Singapore.Sun.COM (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7THm0bO018594 for ; Wed, 29 Aug 2007 10:48:01 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail4.Singapore.Sun.COM (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id l7THjG3Q028525 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Thu, 30 Aug 2007 01:45:21 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNJ0060RQNHE700@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 10:45:17 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNJ006EQQNG1E00@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 10:45:16 -0700 (PDT) Received: from fe-amer-06.sun.com ([192.18.108.180]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l7THjGPd015695 for ; Wed, 29 Aug 2007 17:45:16 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNJ00201QK6TH00@mail-amer.sun.com> (original mail from Eduardo.Horvath@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 11:45:16 -0600 (MDT) Received: from [129.146.96.43] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNJ00F3MQN5VU09@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 11:45:05 -0600 (MDT) Date: Wed, 29 Aug 2007 10:45:04 -0700 From: Eduardo E Horvath - Sun Microsystems - Newark United States Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D5AF4E.5060909@sun.com> Sender: Eduardo.Horvath@Sun.COM To: Stephen Ehring Cc: Firmware Arch Message-id: <46D5B0A0.5040800@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D57049.8040808@sun.com> <46D58DD0.3090109@sun.com> <46D5AF4E.5060909@sun.com> User-Agent: Thunderbird 2.0.0.7pre (X11/20070826) Status: RO Content-Length: 1551 Stephen Ehring wrote: > Stephen Kelly wrote: >>> >>> ============================================================================= >>> >>> >>> MD-FIND-MY-NODE ( node -- node' | 0 ) VFCODE# 0x641 >> >> >> I'm confused as to how the node input argument would be used. >> When/why would it not be 0? Presumably there's only one node in the >> MD that corresponds to that device instance no matter where you start >> searching... right? > It's an optional parameter to reduce MD parsing time. For example, in > the recursive PCI probing code if we know we've already parsed the MD to > a certain point, then there's no need to parse from the start again. > > Now that you mention it, this may generate dependencies on MD node > positioning in the linear representation of the DAG MD . Since it's > optional, I'll remove it. > > I've also clarified the text somewhat based on feedback from DaveK. > Please let me know if it's not clear or if you feel I should add something. > > ============================================================================= > > > md-find-my-node ( -- node | 0 ) vfcode# 0x641 > > Where: > "node" is a pointer to a node element in the machine description. > > Returns the node element in the machine description that corresponds to > the device pathname of the current instance. Returns 0 if no match was > found. > > ============================================================================= Will this thing work even if NON-MD-IODEVICE is set? -- Eduardo Horvath From sacadmin Wed Aug 29 13:00:30 2007 Received: from sunmail4.Singapore.Sun.COM (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7TK0Tk4023841 for ; Wed, 29 Aug 2007 13:00:30 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail4.Singapore.Sun.COM (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id l7TJvjJg024475 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Thu, 30 Aug 2007 03:57:50 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNJ00C07WSDPR00@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 12:57:49 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNJ006V4WSC1870@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 12:57:48 -0700 (PDT) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id l7TJvmHq024582 for ; Wed, 29 Aug 2007 12:57:48 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) id <0JNJ00201WQQNM00@fe-sfbay-09.sun.com> (original mail from Mir.J.Hyder@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 12:57:48 -0700 (PDT) Received: from [129.145.155.97] by fe-sfbay-09.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) with ESMTPSA id <0JNJ00MRDWSB1L10@fe-sfbay-09.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 29 Aug 2007 12:57:48 -0700 (PDT) Date: Wed, 29 Aug 2007 12:57:47 -0700 From: Mir.J.Hyder@Sun.COM Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D5AF4E.5060909@sun.com> Sender: Mir.J.Hyder@Sun.COM To: Stephen Ehring Cc: Firmware Arch Message-id: <46D5CFBB.9050400@Sun.COM> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-Accept-Language: en-us, en X-PMX-Version: 5.2.0.264296 References: <46D57049.8040808@sun.com> <46D58DD0.3090109@sun.com> <46D5AF4E.5060909@sun.com> User-Agent: Mozilla/5.0 (X11; U; SunOS sun4v; en-US; rv:1.7) Gecko/20070109 Status: RO Content-Length: 1783 Stephen Ehring wrote: > Stephen Kelly wrote: > >>> >>> ============================================================================= >>> >>> >>> MD-FIND-MY-NODE ( node -- node' | 0 ) VFCODE# 0x641 >> >> >> >> I'm confused as to how the node input argument would be used. >> When/why would it not be 0? Presumably there's only one node in the >> MD that corresponds to that device instance no matter where you start >> searching... right? > > It's an optional parameter to reduce MD parsing time. For example, in > the recursive PCI probing code if we know we've already parsed the MD > to a certain point, then there's no need to parse from the start again. > > Now that you mention it, this may generate dependencies on MD node > positioning in the linear representation of the DAG MD . Since it's > optional, I'll remove it. > > I've also clarified the text somewhat based on feedback from DaveK. > Please let me know if it's not clear or if you feel I should add > something. > > ============================================================================= > > > md-find-my-node ( -- node | 0 ) vfcode# 0x641 > > Where: > "node" is a pointer to a node element in the machine description. > > Returns the node element in the machine description that > corresponds to > the device pathname of the current instance. Returns 0 if no match was > found. > > ============================================================================= > > > Steve Would not a name like "current-md-node" or "my-md-node" be more appropriate, since at any given instance in the PCI probe phase only one device is active with a associated phandle/ihandle with it and at the same time the MD node pointer points to a given MD node. - Jamal From sacadmin Fri Aug 31 11:47:03 2007 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7VIl2Vc028142 for ; Fri, 31 Aug 2007 11:47:03 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l7VIiCv0015450 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Fri, 31 Aug 2007 19:44:18 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNN00505IPT6E00@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 11:44:17 -0700 (PDT) Received: from brmea-mail-3.sun.com ([192.18.98.34]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNN00G71IPSRXC0@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 11:44:17 -0700 (PDT) Received: from fe-amer-02.sun.com ([192.18.108.176]) by brmea-mail-3.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l7VIiGVY027023 for ; Fri, 31 Aug 2007 18:44:16 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNN00E01IKEQO00@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 12:44:16 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNN00JM6IPRSVRB@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 12:44:16 -0600 (MDT) Date: Fri, 31 Aug 2007 14:44:15 -0400 From: Stephen Ehring Subject: FWARC 2007/496 Vendor FCode For MD Node Retrieval Sender: Stephen.Ehring@sun.com To: Firmware Arch Message-id: <46D8617F.2000106@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 User-Agent: Thunderbird 2.0.0.7pre (X11/20070826) Status: RO Content-Length: 8947 I've updated this case such that it modifies the description of all MD parsing vendor FCodes to use new opaque entities called 'md-node-handle's instead of pointers to node entries as function arguments and results. Because of how the vendor FCodes have been used, this should not require any code changes. Details in section 4 of the onepager. Steve http://sac.eng/Archives/CaseLog/arc/FWARC/2007/496/materials/onepager.txt Copyright 2007 Sun Microsystems, Inc. All Rights Reserved 1. Introduction 1.1. Project/Component Working Name: Vendor FCode For MD Node Retrieval 1.2. Name of Document Author/Supplier: Stephen Ehring 1.3. Date of This Document: 08/28/2007 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: HS PAC 1.4.2. The ARC(s) you expect to review your project: FWARC 1.4.3. The Director/VP who is "Sponsoring" this project: N/A 1.4.4. The name of your business unit: Systems Group 1.5. Email Aliases: 1.5.1. Responsible Manager: chad.solomon@sun.com 1.5.2. Responsible Engineer: stephen.ehring@sun.com 2. Project Summary 2.1. Project Description: This project proposes to add an additional vendor FCode to allow device drivers to easily access their corresponding machine description node. 2.2. Risks and Assumptions: This project, when implemented, will modify the tokenizer. 3. Business Summary 3.1. Problem Area: Currently, any FCode driver that needs to access the machine description to extract property information (such as MAC addresses, hotplug capabilities, etc) must replicate the code to parse through the MD to find the device instance's MD node. 3.2. Market/Requester: Openboot developers and FCode driver developers are the consumers of the interfaces presented in this case. 3.3. Business Justification: These changes will maximize code sharing and minimize FCode driver development complexity. 4. Technical Description: 4.1. Details: FWARC case 2007/070 defined a mechanism where certain IO devices which had Openboot device tree nodes had corresponding nodes in the machine description. This allows hardware-specific information to be extracted from Openboot and the device FCode drivers and migrated into the guest MD. In order for device FCode drivers to easily access it's corresponding MD node, this case defines a new vendor FCode which will return an MD node handle which represents the machine description node corresponding to the device pathname of the current device instance. In addition to the definition of a new vendor FCode, the descriptions of the previously defined vendor FCodes (defined in FWARC 2006/392) are being slightly modified. Many of the vendor FCodes would pass pointers to node elements as input and output arguments. These pointers represented virtual addresses pointing to some offset into the guest's copy of the machine description, but the data structures they point to have never been well defined. Instead of pointers, this case is introducing the term 'md-node-handle' which is an opaque element which uniquely describes a machine description node and will be used as an argument or result of the various FCodes. Methods will not be allowed to use these handles as pointers, they can only be used as arguments to other methods. This case supersedes FWARC 2006/392, although we are only updating the FCode arguments and results in such a way as to be compatible with that case. The only new vendor FCode is the last one in the list below. ============================================================================= md-find-node ( md-node-handle name-str name-len -- md-node-handle' | 0 ) VFCODE# 0x639 Where: "md-node-handle" and "md-node-handle'" are nodes in the guest MD. "name-string" is a forth string that is not null terminated. Returns the next node element in the machine description with name field matching "name-string". Search begins at node element "md-node-handle". To start a search from the beginning of the machine description, specify "md-node-handle" as 0. Returns 0 if no match was found. md-node-name ( md-node-handle -- name-str name-len ) VFCODE# 0x63A Where: "md-node-handle" is a node in the guest MD "name-string" is a forth string that is not null terminated Returns the name field of node element "md-node-handle". md-next-node ( md-node-handle -- md-node-handle' | 0 ) VFCODE# 0x63B Where: "md-node-handle" and "md-node-handle'" are nodes in the guest MD. Returns the next node element in the machine description following node element "md-node-handle". If there are no further node elements, returns 0. md-find-prop ( md-node-handle name-str name-len type -- prop | 0 ) VFCODE# 0x63C Where: "md-node-handle" is a is a node in the guest MD. "name-string" is a forth string that is not null terminated. "type" is the tag type of a machine description property element. "prop" is a pointer to a property element in the machine description. Returns the property element with name field matching "name-string" and tag type equal to "type" within the bounds of the machine description node beginning at "md-node-handle". To search without regards to tag type specify a "type" of -1. Returns 0 if no match was found. md-prop-name ( prop -- name-str name-len ) VFCODE# 0x63D Where: "prop" is a pointer to a property element in the machine description. "name-string" is a forth string that is not null terminated. Returns the name field of property element "prop". md-next-prop ( md-node-handle prop -- prop' | 0 ) VFCODE# 0x63E Where: "md-node-handle" is a is a node in the guest MD "prop" and "prop'" are pointers to property elements in the machine description Returns the next property element following property element "prop" within the bounds of the machine description node beginning at "md-node-handle". If there are no further property elements within "md-node-handle", returns 0. md-prop-type ( prop -- type ) VFCODE# 0x63F Where: "prop" is a pointer to a property element in the machine description. "type" is the tag type of a machine description property element. Returns the tag type of property element "prop". (see FWARC/2005/115 for valid tag types) md-decode-prop ( prop -- [val type] | [buf len type] | 0 ) VFCODE# 0x640 Where: "prop" is a pointer to a property element in the machine description. "val" is a integer value. "type" is the tag type of a machine description property element. "buf" is a pointer to an array of data in the data block. "len" is the length of the data pointed to by "buf". Returns the data and tag type associated with the property element "prop". Return values depend on tag type as follows: Tag Type Return Values --------------------------------------------- For MD_PROP_VAL -- ( value ASCII-v ) For MD_PROP_STR -- ( buf,len-1 ASCII-s ) For MD_PROP_DATA -- ( buf,len ASCII-d ) For MD_PROP_ARC -- ( md-node-handle ASCII-a ) All others -- ( 0 ) For tag type MD_PROP_STR the trailing null character is discarded and for tag type MD_PROP_ARC "md-node-handle" is a pointer to a node element in the machine description. md-find-my-node ( -- md-node-handle | 0 ) VFCODE# 0x641 Where: "md-node-handle" is a is a node in the guest MD Returns the node element in the machine description that corresponds to the device pathname of the current instance. Returns 0 if no match was found. ============================================================================= 4.5. Interfaces: Exported Interface Classification Description ======================================================= "md-find-my-node" Uncommitted method to search for the current device instance's node in a machine description 5. Reference Documents: FWARC/2000/166 - Establish VFCODE Registry FWARC/2005/115 - Sun4v Machine Description FWARC/2006/392 - Machine Description Vendor FCodes FWARC/2007/070 - Machine Description IO Device Node Definitions From sacadmin Fri Aug 31 12:03:42 2007 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7VJ3gOw028799 for ; Fri, 31 Aug 2007 12:03:42 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l7VJ107H012343 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Fri, 31 Aug 2007 12:01:02 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNN00F0DJHPPS00@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:01:01 -0600 (MDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNN00ERCJHN0410@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:00:59 -0600 (MDT) Received: from fe-amer-01.sun.com ([192.18.108.175]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l7VJ0xNi012530 for ; Fri, 31 Aug 2007 19:00:59 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNN00601J8WQ300@mail-amer.sun.com> (original mail from S.Jain@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:00:59 -0600 (MDT) Received: from [129.150.19.131] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNN00ICNJHMT8W7@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:00:59 -0600 (MDT) Date: Fri, 31 Aug 2007 12:01:13 -0700 From: Sunit Jain Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D8617F.2000106@sun.com> Sender: S.Jain@sun.com To: Stephen Ehring Cc: Firmware Arch Reply-to: S.Jain@sun.com Message-id: <46D86579.8000501@Sun.Com> Organization: Sun Microsystems, Inc. MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D8617F.2000106@sun.com> User-Agent: Thunderbird 2.0.0.7pre (Windows/20070831) Status: RO Content-Length: 9768 FWARC/2006/392 defines MD-FIND_NODE with VFCODE 638. You are changing it to 639. Other VFCODES are also different between the two cases. Is that what your case intends to change? I got the impression that you are only changing the description and arguments. Imported interfaces should include FWARC/2006/392. Also, I believe you need to update vfcodes.txt registry with the new FCode. Regards, Sunit Stephen Ehring wrote: > I've updated this case such that it modifies the description of all MD > parsing vendor FCodes to use new opaque entities called > 'md-node-handle's instead of pointers to node entries as function > arguments and results. Because of how the vendor FCodes have been > used, this should not require any code changes. Details in section 4 > of the onepager. > > Steve > > http://sac.eng/Archives/CaseLog/arc/FWARC/2007/496/materials/onepager.txt > > Copyright 2007 Sun Microsystems, Inc. All Rights Reserved > > 1. Introduction > 1.1. Project/Component Working Name: > Vendor FCode For MD Node Retrieval > > 1.2. Name of Document Author/Supplier: > Stephen Ehring > > 1.3. Date of This Document: > 08/28/2007 > > 1.4. Name of Major Document Customer(s)/Consumer(s): > 1.4.1. The PAC or CPT you expect to review your project: > HS PAC > 1.4.2. The ARC(s) you expect to review your project: > FWARC > 1.4.3. The Director/VP who is "Sponsoring" this project: > N/A > 1.4.4. The name of your business unit: > Systems Group > > 1.5. Email Aliases: > 1.5.1. Responsible Manager: chad.solomon@sun.com > 1.5.2. Responsible Engineer: stephen.ehring@sun.com > > 2. Project Summary > 2.1. Project Description: > This project proposes to add an additional vendor FCode to allow > device drivers to easily access their corresponding machine > description > node. > > 2.2. Risks and Assumptions: > This project, when implemented, will modify the tokenizer. > > 3. Business Summary > 3.1. Problem Area: > Currently, any FCode driver that needs to access the machine > description > to extract property information (such as MAC addresses, hotplug > capabilities, etc) must replicate the code to parse through the > MD to > find the device instance's MD node. > > 3.2. Market/Requester: > Openboot developers and FCode driver developers are the consumers > of the > interfaces presented in this case. > > 3.3. Business Justification: > These changes will maximize code sharing and minimize FCode driver > development complexity. > > > 4. Technical Description: > > 4.1. Details: > > FWARC case 2007/070 defined a mechanism where certain IO > devices which > had Openboot device tree nodes had corresponding nodes in the > machine > description. This allows hardware-specific information to be > extracted > from Openboot and the device FCode drivers and migrated into > the guest > MD. In order for device FCode drivers to easily access it's > corresponding > MD node, this case defines a new vendor FCode which will return > an MD node > handle which represents the machine description node > corresponding to > the device pathname of the current device instance. > > In addition to the definition of a new vendor FCode, the > descriptions of > the previously defined vendor FCodes (defined in FWARC > 2006/392) are being > slightly modified. Many of the vendor FCodes would pass > pointers to node > elements as input and output arguments. These pointers > represented virtual > addresses pointing to some offset into the guest's copy of the > machine > description, but the data structures they point to have never > been well defined. > > Instead of pointers, this case is introducing the term > 'md-node-handle' which > is an opaque element which uniquely describes a machine > description node and > will be used as an argument or result of the various FCodes. > Methods will > not be allowed to use these handles as pointers, they can only > be used as > arguments to other methods. > > This case supersedes FWARC 2006/392, although we are only > updating the FCode > arguments and results in such a way as to be compatible with > that case. The > only new vendor FCode is the last one in the list below. > > ============================================================================= > > md-find-node ( md-node-handle name-str name-len -- md-node-handle' | 0 ) > VFCODE# > 0x639 > > Where: > "md-node-handle" and "md-node-handle'" are nodes in the guest MD. > "name-string" is a forth string that is not null terminated. > > Returns the next node element in the machine description with name > field > matching "name-string". Search begins at node element > "md-node-handle". > To start a search from the beginning of the machine description, > specify > "md-node-handle" as 0. > Returns 0 if no match was found. > > > md-node-name ( md-node-handle -- name-str name-len ) > VFCODE# 0x63A > > Where: > "md-node-handle" is a node in the guest MD > "name-string" is a forth string that is not null terminated > > Returns the name field of node element "md-node-handle". > > > md-next-node ( md-node-handle -- md-node-handle' | 0 ) > VFCODE# 0x63B > > Where: > "md-node-handle" and "md-node-handle'" are nodes in the guest MD. > > Returns the next node element in the machine description following node > element "md-node-handle". If there are no further node elements, > returns 0. > > > md-find-prop ( md-node-handle name-str name-len type -- prop | 0 ) > VFCODE# > 0x63C > > Where: > "md-node-handle" is a is a node in the guest MD. > "name-string" is a forth string that is not null terminated. > "type" is the tag type of a machine description property element. > "prop" is a pointer to a property element in the machine > description. > > Returns the property element with name field matching "name-string" and > tag type equal to "type" within the bounds of the machine > description node > beginning at "md-node-handle". > To search without regards to tag type specify a "type" of -1. > Returns 0 if no match was found. > > > md-prop-name ( prop -- name-str name-len ) > VFCODE# 0x63D > > Where: > "prop" is a pointer to a property element in the machine > description. > "name-string" is a forth string that is not null terminated. > > Returns the name field of property element "prop". > > > md-next-prop ( md-node-handle prop -- prop' | 0 ) > VFCODE# 0x63E > > Where: > "md-node-handle" is a is a node in the guest MD > "prop" and "prop'" are pointers to property elements in the machine > description > > Returns the next property element following property element "prop" > within the bounds of the machine description node beginning at > "md-node-handle". > If there are no further property elements within "md-node-handle", > returns 0. > > > md-prop-type ( prop -- type ) > VFCODE# 0x63F > > Where: > "prop" is a pointer to a property element in the machine > description. > "type" is the tag type of a machine description property element. > > Returns the tag type of property element "prop". > (see FWARC/2005/115 for valid tag types) > > md-decode-prop ( prop -- [val type] | [buf len type] | 0 ) > VFCODE# 0x640 > > Where: > "prop" is a pointer to a property element in the machine > description. > "val" is a integer value. > "type" is the tag type of a machine description property element. > "buf" is a pointer to an array of data in the data block. > "len" is the length of the data pointed to by "buf". > > Returns the data and tag type associated with the property element > "prop". > Return values depend on tag type as follows: > > Tag Type Return Values > --------------------------------------------- > For MD_PROP_VAL -- ( value ASCII-v ) > For MD_PROP_STR -- ( buf,len-1 ASCII-s ) > For MD_PROP_DATA -- ( buf,len ASCII-d ) > For MD_PROP_ARC -- ( md-node-handle ASCII-a ) > All others -- ( 0 ) > > For tag type MD_PROP_STR the trailing null character is discarded and > for tag type MD_PROP_ARC "md-node-handle" is a pointer to a node > element in > the machine description. > > md-find-my-node ( -- md-node-handle | 0 > ) VFCODE# 0x641 > > Where: > "md-node-handle" is a is a node in the guest MD > > Returns the node element in the machine description that corresponds to > the device pathname of the current instance. Returns 0 if no match was > found. > > ============================================================================= > > > 4.5. Interfaces: > > Exported Interface Classification Description > ======================================================= > > "md-find-my-node" Uncommitted method to search for the > current device > instance's node in a machine > description > > 5. Reference Documents: > > FWARC/2000/166 - Establish VFCODE Registry > FWARC/2005/115 - Sun4v Machine Description > FWARC/2006/392 - Machine Description Vendor FCodes > FWARC/2007/070 - Machine Description IO Device Node Definitions > > > > From sacadmin Fri Aug 31 12:12:57 2007 Received: from sunmail4.Singapore.Sun.COM (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l7VJCuDW028972 for ; Fri, 31 Aug 2007 12:12:57 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.Singapore.Sun.COM (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id l7VJAC5v010462 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Sat, 1 Sep 2007 03:10:16 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNN00G03JX18Z00@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:10:13 -0600 (MDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNN00D6QJX0ZW20@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:10:12 -0600 (MDT) Received: from fe-amer-01.sun.com ([192.18.108.175]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l7VJA7OU004133 for ; Fri, 31 Aug 2007 19:10:07 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNN00601J8WQ300@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:10:07 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNN007TBJWVMQW6@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Fri, 31 Aug 2007 13:10:07 -0600 (MDT) Date: Fri, 31 Aug 2007 15:10:06 -0400 From: Stephen Ehring Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D86579.8000501@Sun.Com> Sender: Stephen.Ehring@sun.com To: S.Jain@sun.com Cc: Firmware Arch Message-id: <46D8678E.8010209@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D8617F.2000106@sun.com> <46D86579.8000501@Sun.Com> User-Agent: Thunderbird 2.0.0.7pre (X11/20070826) Status: RO Content-Length: 802 Sunit Jain wrote: > > > FWARC/2006/392 defines MD-FIND_NODE with VFCODE 638. You are changing > it to 639. Other VFCODES are also different between the two cases. Is > that what your case intends to change? I got the impression that you > are only changing the description and arguments. > The VFCodes tokens were updated in FWARC/2006/428 to the new values that I'm using. I've added that case to the reference cases of this one. > Imported interfaces should include FWARC/2006/392. I'm not using any of those interfaces, though (I'm just updating their description). I was under the impression we only have to import an interface if we are using it. > > Also, I believe you need to update vfcodes.txt registry with the new > FCode. > Of course, once this case has been approved. Steve From sacadmin Tue Sep 4 16:11:05 2007 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l84NB5mt029175 for ; Tue, 4 Sep 2007 16:11:05 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l84N8IRu016682 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Tue, 4 Sep 2007 16:08:21 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNV005039LWKF00@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 17:08:20 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNV00HGN9LVXIB0@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 17:08:19 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id l84N8JFL012900 for ; Tue, 04 Sep 2007 16:08:19 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) id <0JNV0030190NLC00@fe-sfbay-10.sun.com> (original mail from Hitendra.Zhangada@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 16:08:19 -0700 (PDT) Received: from [129.150.33.110] by fe-sfbay-10.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) with ESMTPSA id <0JNV008V09LR5F90@fe-sfbay-10.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 16:08:16 -0700 (PDT) Date: Tue, 04 Sep 2007 16:09:43 -0700 From: Hitendra Zhangada Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46D8678E.8010209@sun.com> Sender: Hitendra.Zhangada@sun.com To: Firmware Arch Message-id: <46DDE5B7.10200@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D8617F.2000106@sun.com> <46D86579.8000501@Sun.Com> <46D8678E.8010209@sun.com> User-Agent: Thunderbird 2.0.0.6 (Windows/20070728) Status: RO Content-Length: 1833 Stephen Ehring wrote: > Sunit Jain wrote: >> >> >> FWARC/2006/392 defines MD-FIND_NODE with VFCODE 638. You are changing >> it to 639. Other VFCODES are also different between the two cases. Is >> that what your case intends to change? I got the impression that you >> are only changing the description and arguments. >> > > The VFCodes tokens were updated in FWARC/2006/428 to the new values > that I'm using. I've added that case to the reference cases of this one. > >> Imported interfaces should include FWARC/2006/392. > > I'm not using any of those interfaces, though (I'm just updating their > description). I was under the impression we only have to import an > interface if we are using it. You need to list all of them in the "exported" interface table (not just one). You are modifying an existing interface as defined by 2006/392 since the arguments to the interface have a slightly different meaning now. These interfaces, however, need not be listed in the "imported" interface as Sunit had suggested. I went through long e-mail thread on this particular topic of where do we list interfaces which are modified by a project. The consensus of that mail thread was that they go into "exported" interface table with a note in the comments column stating that these are modified from previous xyz case. So, please add all of the interfaces to the exported interfaces with a reference to 2006/392 for most of them (except one) in the comments section. Also, use new commitment level for all of them (evolving -> uncommited). BTW, is timer set to a week from today or earlier? -- Hitendra Zhangada ============================================= SPS Common SW Features Engineering Software Group, Sun Microsystems, Inc. Work Ph# (858) 625 3757, Ext. x53757 SUN Internal homepage http://esp.west/~hitu From sacadmin Tue Sep 4 19:08:34 2007 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l8528XmV002525 for ; Tue, 4 Sep 2007 19:08:33 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l8525nV9004049 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Tue, 4 Sep 2007 19:05:49 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNV0071FHTPZ200@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 19:05:49 -0700 (PDT) Received: from brmea-mail-3.sun.com ([192.18.98.34]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNV005RCHTOER10@nwk-avmta-2.sfbay.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 19:05:48 -0700 (PDT) Received: from fe-amer-01.sun.com ([192.18.108.175]) by brmea-mail-3.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l8525mEC026916 for ; Wed, 05 Sep 2007 02:05:48 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNV00I01GN0F700@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 20:05:48 -0600 (MDT) Received: from [192.168.2.48] ([76.19.29.74]) by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNV0049CHTNDMLB@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Tue, 04 Sep 2007 20:05:48 -0600 (MDT) Date: Tue, 04 Sep 2007 22:07:09 -0400 From: Stephen Ehring Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46DDE5B7.10200@sun.com> Sender: Stephen.Ehring@sun.com To: Hitendra Zhangada Cc: Firmware Arch Message-id: <46DE0F4D.7040500@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46D8617F.2000106@sun.com> <46D86579.8000501@Sun.Com> <46D8678E.8010209@sun.com> <46DDE5B7.10200@sun.com> User-Agent: Thunderbird 1.5.0.13 (Macintosh/20070809) Status: RO Content-Length: 388 Hitendra Zhangada wrote: > > You need to list all of them in the "exported" interface table (not > just one). > > Okay, I'm updating the text based on feedback from DaveK anyway, so I'll send out a notification when it's ready for re-review. > BTW, is timer set to a week from today or earlier? I'll set it for a week from the day the materials are finalized. No rush here. Steve From sacadmin Wed Sep 5 10:57:59 2007 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l85Hvxjs026174 for ; Wed, 5 Sep 2007 10:57:59 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l85HtDmd018381 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Wed, 5 Sep 2007 10:55:13 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JNW00201PS0Q700@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 05 Sep 2007 11:55:12 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JNW00M80PRTHM40@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 05 Sep 2007 11:55:11 -0600 (MDT) Received: from fe-amer-02.sun.com ([192.18.108.176]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l85Ht5JT017084 for ; Wed, 05 Sep 2007 17:55:05 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JNW00F01PCW7P00@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 05 Sep 2007 11:55:05 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JNW00E1HPRSLRG9@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 05 Sep 2007 11:55:05 -0600 (MDT) Date: Wed, 05 Sep 2007 13:55:04 -0400 From: Stephen Ehring Subject: FWARC 2007/496 Vendor FCode For MD Node Retrieval Sender: Stephen.Ehring@Sun.COM To: Firmware Arch Message-id: <46DEED78.8040403@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 User-Agent: Thunderbird 2.0.0.7pre (X11/20070826) Status: RO Content-Length: 12612 I've updated the onepager based on feedback. None of the interfaces have functionally changed, just lots of edits to the textual descriptions. Biggest difference from the last iteration is that the 'prop' elements that are passed between the various FCodes are no longer pointers, but opaque handles, too. Timer is reset to 9/12 to give everyone ample time to review. http://sac.eng/Archives/CaseLog/arc/FWARC/2007/496/materials/onepager.txt Steve Copyright 2007 Sun Microsystems, Inc. All Rights Reserved 1. Introduction 1.1. Project/Component Working Name: Vendor FCode For MD Node Retrieval 1.2. Name of Document Author/Supplier: Stephen Ehring 1.3. Date of This Document: 08/28/2007 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: HS PAC 1.4.2. The ARC(s) you expect to review your project: FWARC 1.4.3. The Director/VP who is "Sponsoring" this project: N/A 1.4.4. The name of your business unit: Systems Group 1.5. Email Aliases: 1.5.1. Responsible Manager: chad.solomon@sun.com 1.5.2. Responsible Engineer: stephen.ehring@sun.com 2. Project Summary 2.1. Project Description: This project proposes to add an additional vendor FCode to allow device drivers to easily access their corresponding machine description node. 2.2. Risks and Assumptions: This project, when implemented, will modify the tokenizer. 3. Business Summary 3.1. Problem Area: Currently, any FCode driver that needs to access the machine description to extract property information (such as MAC addresses, hotplug capabilities, etc) must replicate the code to parse through the MD to find the device instance's MD node. 3.2. Market/Requester: Openboot developers and FCode driver developers are the consumers of the interfaces presented in this case. 3.3. Business Justification: These changes will maximize code sharing and minimize FCode driver development complexity. 4. Technical Description: 4.1. Details: FWARC case 2007/070 defined a mechanism where certain IO devices which had Openboot device tree nodes had corresponding nodes in the machine description. This allows hardware-specific information to be extracted from Openboot and the device FCode drivers and migrated into the guest MD. In order for device FCode drivers to easily access it's corresponding MD node, this case defines a new vendor FCode which will return an MD node handle which represents the machine description node corresponding to the device pathname of the current device instance. In addition to the definition of a new vendor FCode, the descriptions of the previously defined vendor FCodes (defined in FWARC 2006/392) are being slightly modified. Many of the vendor FCodes would pass pointers to node elements as input and output arguments. These pointers represented opaque handles that were never fully defined since the data structures they pointed to were never defined. This case formalizes these arguments as opaque handles without changing the definition or implementation of any of the existing md node or md property vendor FCodes. Instead of pointers, this case is introducing the term 'md-node-handle' which is an opaque element which uniquely describes a machine description node and 'md-prop-handle' which is an opaque element which uniquely describes a property name and value in the machine description node. These elements will be used as arguments or results of the various FCodes. Methods will not be allowed to use these handles as pointers, they can only be used as arguments to other methods. This case supersedes FWARC 2006/392 (and 2006/482 which updated the token values of some of the vendor FCodes), although we are only updating the FCode arguments and results in such a way as to be compatible with that case. The only new vendor FCode is the last one in the list below. Definitions: md-node-handle An opaque 32 bit value that uniquely represents a machine description node as an argument or result to a method. md-prop-handle An opaque 32 bit value that uniquely represents a machine description property as an argument or result to a method. md-prop-type The tag type of machine description property elements. See FWARC/2005/115 for valid tag types. The stack representation of the various property types are defined in the table below Tag Type Tag Type Property Data Stack Value Representation --------------------------------------------- MD_PROP_VAL -- ASCII-v -- ( u ) MD_PROP_STR -- ASCII-s -- ( prop-str prop-len ) MD_PROP_DATA -- ASCII-d -- ( addr len ) MD_PROP_ARC -- ASCII-a -- ( md-node-handle ) xyz-str xyz-len These values describe an FCode-string (non-null terminated) where "xyz" means an arbitrary sequence of characters. ============================================================================= md-find-node ( md-node-handle name-str name-len -- md-node-handle' | 0 ) VFCODE# 0x639 Where: "md-node-handle" and "md-node-handle'" describe nodes in the guest MD. "name-str" and "name-len" describe a read-only string which contains the name of a machine description node. Returns the next node element in the machine description with name field matching "name-str". Search begins at node element "md-node-handle". To start a search from the beginning of the machine description, specify "md-node-handle" as 0. Returns 0 if no match was found. md-node-name ( md-node-handle -- name-str name-len ) VFCODE# 0x63A Where: "md-node-handle" describes a node in the guest MD "name-str" and "name-len" describe a read-only string which contains the name of a machine description node. Returns the name field of node element "md-node-handle". md-next-node ( md-node-handle -- md-node-handle' | 0 ) VFCODE# 0x63B Where: "md-node-handle" and "md-node-handle'" describe nodes in the guest MD. Returns the next node element in the machine description following node element "md-node-handle". If there are no further node elements, returns 0. md-find-prop ( md-node-handle name-str name-len md-prop-type -- md-prop-handle | 0 ) VFCODE# 0x63C Where: "md-node-handle" describes a node in the guest MD. "name-str" and "name-len" describe a read-only string which contains the name of a machine description node. "md-prop-type" is the tag type of a machine description property element. "md-prop-handle" describes a property element in the machine description. Returns the property element with name field matching "name-str" and tag type equal to "md-prop-type" within the machine description node described by "md-node-handle". To search without regards to tag type specify a "md-prop-type" of -1. Returns 0 if no match was found. md-prop-name ( md-prop-handle -- name-str name-len ) VFCODE# 0x63D Where: "md-prop-handle" describes a property element in the machine description. "name-str" and "name-len" describe a read-only string which contains the name of a machine description property element. Returns the name field of property element "md-prop-handle". md-next-prop ( md-node-handle md-prop-handle -- md-prop-handle' | 0 ) VFCODE# 0x63E Where: "md-node-handle" describes is a node in the guest MD "md-prop-handle" and "md-prop-handle'" describe property elements in the machine description. Returns the next property element following property element "md-prop-handle" within the machine description node described by "md-node-handle". If there are no further property elements within "md-node-handle", returns 0. md-prop-type ( md-prop-handle -- md-prop-type ) VFCODE# 0x63F Where: "md-prop-handle" describes a property element in the machine description. "md-prop-type" is the tag type of a machine description property element. Returns the tag type of the property element described by "md-prop-handle" md-decode-prop ( md-prop-handle -- [ x1 [ ... xn ] md-prop-type ] | 0 VFCODE# 0x640 Where: "md-prop-handle" describes a property element in the machine description. "md-prop-type" is the tag type of a machine description property element. "x1 [ ... xn ]" represents the property data associated with the property element If the topmost stack item is not zero, returns the md-prop-type and the property data in x1 [ ... xn ] whose values, type and number of stack items depends on the value of md-prop-type. The stack representation of the various property data types can be found in the definitions section above. md-find-my-node ( -- md-node-handle | 0 ) VFCODE# 0x641 Where: "md-node-handle" describes is a node in the guest MD Returns the node element in the machine description that corresponds to the device pathname of the current instance. Returns 0 if no match was found. ============================================================================= 4.5. Interfaces: Exported Interface Classification Description ======================================================= "md-find-node" Uncomitted method to search for specific node elements in a machine description "md-node-name" Uncomitted method that returns the name field associated with a specific node element in a machine description. "md-next-node" Uncomitted method that returns the next node element in a machine description. "md-find-prop" Uncomitted method to search for specific property elements within the scope of a machine description node. "md-prop-name" Uncomitted method that returns the name field associated with a specific property element in a machine description. "md-next-prop" Uncomitted method that returns the next property element within the scope of a machine description node "md-prop-type" Uncomitted method that returns the tag type associated with a specific property element in a machine description "md-decode-prop" Uncomitted method that returns the data and tag type unassociated with a specific property element in a machine description "md-find-my-node" Uncommitted method to search for the current device instance's node in a machine description Imported Interface Classification Description ======================================================= Sun4v Machine Sun Private MD nodes definitions as Description nodes defined by FWARC/2005/115 5. Reference Documents: FWARC/2000/166 - Establish VFCODE Registry FWARC/2005/115 - Sun4v Machine Description FWARC/2006/392 - Machine Description Vendor FCodes FWARC/2006/428 - MD-FCODE Reassignment FWARC/2007/070 - Machine Description IO Device Node Definitions From sacadmin Wed Sep 12 10:35:38 2007 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l8CHZbnQ029321 for ; Wed, 12 Sep 2007 10:35:37 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id l8CHWiav006638 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Wed, 12 Sep 2007 18:32:45 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JO90041FNEK2400@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 12 Sep 2007 11:32:44 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JO900G4INEIW8F0@brm-avmta-1.central.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 12 Sep 2007 11:32:42 -0600 (MDT) Received: from fe-amer-04.sun.com ([192.18.108.178]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l8CHWfKj018666 for ; Wed, 12 Sep 2007 17:32:42 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) id <0JO900I01NC7K900@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 12 Sep 2007 11:32:41 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-6.01 (built Apr 3 2006)) with ESMTPSA id <0JO900GLINEHFPW0@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Wed, 12 Sep 2007 11:32:41 -0600 (MDT) Date: Wed, 12 Sep 2007 13:32:40 -0400 From: Stephen Ehring Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46DEED78.8040403@sun.com> Sender: Stephen.Ehring@sun.com To: Stephen Ehring Cc: Firmware Arch Message-id: <46E822B8.7050604@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46DEED78.8040403@sun.com> User-Agent: Thunderbird 2.0.0.7pre (X11/20070910) Status: RO Content-Length: 247 The timeout on this case has expired, the case is closed as approved. The interfaces can be released in a micro/minor version of the firmware. The VFCode registry has been updated: http://sac.eng.sun.com/arc/FWARC/Registries/vfcodes.txt Steve From sacadmin Thu Sep 13 11:43:55 2007 Received: from sunmail4.Singapore.Sun.COM (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id l8DIhswE005522 for ; Thu, 13 Sep 2007 11:43:54 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.Singapore.Sun.COM (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id l8DIelnK024267 for <@sunmail2sca.sfbay.sun.com:fwarc@sun.com>; Fri, 14 Sep 2007 02:41:01 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JOB0060NL8CTT00@nwk-avmta-1.sfbay.Sun.COM> for fwarc@sun.com (ORCPT fwarc@sun.com); Thu, 13 Sep 2007 11:41:00 -0700 (PDT) Received: from brmea-mail-3.sun.com ([192.18.98.34]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JOB00C0HL8BG3D0@nwk-avmta-1.sfbay.Sun.COM> for fwarc@sun.com (ORCPT fwarc@sun.com); Thu, 13 Sep 2007 11:41:00 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-3.sun.com (8.13.6+Sun/8.12.9) with ESMTP id l8DIexNx001107 for ; Thu, 13 Sep 2007 18:40:59 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) id <0JOB00201K8F5300@mail-amer.sun.com> (original mail from Stephen.Ehring@Sun.COM) for fwarc@sun.com (ORCPT fwarc@sun.com); Thu, 13 Sep 2007 12:40:59 -0600 (MDT) Received: from [129.148.131.33] by mail-amer.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) with ESMTPSA id <0JOB00M6YL7MS860@mail-amer.sun.com> for fwarc@sun.com (ORCPT fwarc@sun.com); Thu, 13 Sep 2007 12:40:34 -0600 (MDT) Date: Thu, 13 Sep 2007 14:40:33 -0400 From: Stephen Ehring Subject: Re: FWARC 2007/496 Vendor FCode For MD Node Retrieval In-reply-to: <46E9818D.5090507@sun.com> Sender: Stephen.Ehring@sun.com To: Firmware Arch Message-id: <46E98421.409@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.2.0.264296 References: <46E84B14.2080501@sun.com> <46E95932.6060300@sun.com> <46E95C46.2010106@sun.com> <46E9818D.5090507@sun.com> User-Agent: Thunderbird 2.0.0.7pre (X11/20070910) Status: RO Content-Length: 12859 Dave Kahn pointed out a minor clarification that had to be made to the onepager for this case, which I've just updated. Since the change is very minor (and affects the description only), I'm not filing another case even though the timer expired yesterday. If any of the ARC members insist that I do so, let me know. Steve {dmk@centrino:109} diff onepager.txt.case onepager.txt 151a152 > If md-node-handle is 0, returns the first node. 189a191 > or the first property if md-prop-handle is 0, {dmk@centrino:110} Steve http://sac.eng/Archives/CaseLog/arc/FWARC/2007/496/materials/onepager.txt Copyright 2007 Sun Microsystems, Inc. All Rights Reserved 1. Introduction 1.1. Project/Component Working Name: Vendor FCode For MD Node Retrieval 1.2. Name of Document Author/Supplier: Stephen Ehring 1.3. Date of This Document: 08/28/2007 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: HS PAC 1.4.2. The ARC(s) you expect to review your project: FWARC 1.4.3. The Director/VP who is "Sponsoring" this project: N/A 1.4.4. The name of your business unit: Systems Group 1.5. Email Aliases: 1.5.1. Responsible Manager: chad.solomon@sun.com 1.5.2. Responsible Engineer: stephen.ehring@sun.com 2. Project Summary 2.1. Project Description: This project proposes to add an additional vendor FCode to allow device drivers to easily access their corresponding machine description node. 2.2. Risks and Assumptions: This project, when implemented, will modify the tokenizer. 3. Business Summary 3.1. Problem Area: Currently, any FCode driver that needs to access the machine description to extract property information (such as MAC addresses, hotplug capabilities, etc) must replicate the code to parse through the MD to find the device instance's MD node. 3.2. Market/Requester: Openboot developers and FCode driver developers are the consumers of the interfaces presented in this case. 3.3. Business Justification: These changes will maximize code sharing and minimize FCode driver development complexity. 4. Technical Description: 4.1. Details: FWARC case 2007/070 defined a mechanism where certain IO devices which had Openboot device tree nodes had corresponding nodes in the machine description. This allows hardware-specific information to be extracted from Openboot and the device FCode drivers and migrated into the guest MD. In order for device FCode drivers to easily access it's corresponding MD node, this case defines a new vendor FCode which will return an MD node handle which represents the machine description node corresponding to the device pathname of the current device instance. In addition to the definition of a new vendor FCode, the descriptions of the previously defined vendor FCodes (defined in FWARC 2006/392) are being slightly modified. Many of the vendor FCodes would pass pointers to node elements as input and output arguments. These pointers represented opaque handles that were never fully defined since the data structures they pointed to were never defined. This case formalizes these arguments as opaque handles without changing the definition or implementation of any of the existing md node or md property vendor FCodes. Instead of pointers, this case is introducing the term 'md-node-handle' which is an opaque element which uniquely describes a machine description node and 'md-prop-handle' which is an opaque element which uniquely describes a property name and value in the machine description node. These elements will be used as arguments or results of the various FCodes. Methods will not be allowed to use these handles as pointers, they can only be used as arguments to other methods. This case supersedes FWARC 2006/392 (and 2006/482 which updated the token values of some of the vendor FCodes), although we are only updating the FCode arguments and results in such a way as to be compatible with that case. The only new vendor FCode is the last one in the list below. Definitions: md-node-handle An opaque 32 bit value that uniquely represents a machine description node as an argument or result to a method. md-prop-handle An opaque 32 bit value that uniquely represents a machine description property as an argument or result to a method. md-prop-type The tag type of machine description property elements. See FWARC/2005/115 for valid tag types. The stack representation of the various property types are defined in the table below Tag Type Tag Type Property Data Stack Value Representation --------------------------------------------- MD_PROP_VAL -- ASCII-v -- ( u ) MD_PROP_STR -- ASCII-s -- ( prop-str prop-len ) MD_PROP_DATA -- ASCII-d -- ( addr len ) MD_PROP_ARC -- ASCII-a -- ( md-node-handle ) xyz-str xyz-len These values describe an FCode-string (non-null terminated) where "xyz" means an arbitrary sequence of characters. ============================================================================= md-find-node ( md-node-handle name-str name-len -- md-node-handle' | 0 ) VFCODE# 0x639 Where: "md-node-handle" and "md-node-handle'" describe nodes in the guest MD. "name-str" and "name-len" describe a read-only string which contains the name of a machine description node. Returns the next node element in the machine description with name field matching "name-str". Search begins at node element "md-node-handle". To start a search from the beginning of the machine description, specify "md-node-handle" as 0. Returns 0 if no match was found. md-node-name ( md-node-handle -- name-str name-len ) VFCODE# 0x63A Where: "md-node-handle" describes a node in the guest MD "name-str" and "name-len" describe a read-only string which contains the name of a machine description node. Returns the name field of node element "md-node-handle". md-next-node ( md-node-handle -- md-node-handle' | 0 ) VFCODE# 0x63B Where: "md-node-handle" and "md-node-handle'" describe nodes in the guest MD. Returns the next node element in the machine description following node element "md-node-handle". If there are no further node elements, returns 0. If md-node-handle is 0, returns the first node. md-find-prop ( md-node-handle name-str name-len md-prop-type -- md-prop-handle | 0 ) VFCODE# 0x63C Where: "md-node-handle" describes a node in the guest MD. "name-str" and "name-len" describe a read-only string which contains the name of a machine description node. "md-prop-type" is the tag type of a machine description property element. "md-prop-handle" describes a property element in the machine description. Returns the property element with name field matching "name-str" and tag type equal to "md-prop-type" within the machine description node described by "md-node-handle". To search without regards to tag type specify a "md-prop-type" of -1. Returns 0 if no match was found. md-prop-name ( md-prop-handle -- name-str name-len ) VFCODE# 0x63D Where: "md-prop-handle" describes a property element in the machine description. "name-str" and "name-len" describe a read-only string which contains the name of a machine description property element. Returns the name field of property element "md-prop-handle". md-next-prop ( md-node-handle md-prop-handle -- md-prop-handle' | 0 ) VFCODE# 0x63E Where: "md-node-handle" describes is a node in the guest MD "md-prop-handle" and "md-prop-handle'" describe property elements in the machine description. Returns the next property element following property element "md-prop-handle" within the machine description node described by "md-node-handle" or the first property if md-prop-handle is 0,. If there are no further property elements within "md-node-handle", returns 0. md-prop-type ( md-prop-handle -- md-prop-type ) VFCODE# 0x63F Where: "md-prop-handle" describes a property element in the machine description. "md-prop-type" is the tag type of a machine description property element. Returns the tag type of the property element described by "md-prop-handle" md-decode-prop ( md-prop-handle -- [ x1 [ ... xn ] md-prop-type ] | 0 VFCODE# 0x640 Where: "md-prop-handle" describes a property element in the machine description. "md-prop-type" is the tag type of a machine description property element. "x1 [ ... xn ]" represents the property data associated with the property element If the topmost stack item is not zero, returns the md-prop-type and the property data in x1 [ ... xn ] whose values, type and number of stack items depends on the value of md-prop-type. The stack representation of the various property data types can be found in the definitions section above. md-find-my-node ( -- md-node-handle | 0 ) VFCODE# 0x641 Where: "md-node-handle" describes is a node in the guest MD Returns the node element in the machine description that corresponds to the device pathname of the current instance. Returns 0 if no match was found. ============================================================================= 4.5. Interfaces: Exported Interface Classification Description ======================================================= "md-find-node" Uncomitted method to search for specific node elements in a machine description "md-node-name" Uncomitted method that returns the name field associated with a specific node element in a machine description. "md-next-node" Uncomitted method that returns the next node element in a machine description. "md-find-prop" Uncomitted method to search for specific property elements within the scope of a machine description node. "md-prop-name" Uncomitted method that returns the name field associated with a specific property element in a machine description. "md-next-prop" Uncomitted method that returns the next property element within the scope of a machine description node "md-prop-type" Uncomitted method that returns the tag type associated with a specific property element in a machine description "md-decode-prop" Uncomitted method that returns the data and tag type unassociated with a specific property element in a machine description "md-find-my-node" Uncommitted method to search for the current device instance's node in a machine description Imported Interface Classification Description ======================================================= Sun4v Machine Sun Private MD nodes definitions as Description nodes defined by FWARC/2005/115 5. Reference Documents: FWARC/2000/166 - Establish VFCODE Registry FWARC/2005/115 - Sun4v Machine Description FWARC/2006/392 - Machine Description Vendor FCodes FWARC/2006/428 - MD-FCODE Reassignment FWARC/2007/070 - Machine Description IO Device Node Definitions