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