| #ident "@(#)usb_binding.txt 1.4 06/11/15 SMI" Open Firmware Recommended Practice: USB Bus Binding to IEEE Std 1275-1994 This document is a voluntary-use recommended practice of the Open Firmware Working Group. The Open Firmware Working Group is an ad hoc committee composed of individuals interested in Open Firmware as defined by IEEE 1275-1994, related standards, and their application to various computer systems. The Open Firmware Working Group is involved both in IEEE sanctioned standards activities, whose final results are published by IEEE, and in informal recommendations such as this, which are published on the Internet at: http://playground.sun.com/pub/1275 Membership in the Open Firmware Working Group is open to all interested parties. The working group meets at regular intervals at various locations. For more information send email to: p1275-wg@risc.sps.mot.com Revision History | [1] Jun 01, 1998: Initial Revision. | [2] Oct 24, 2006: Add a new type of node, Interface-Association Node. 1. Overview and References This document describes the application of Open Firmware to the Universal Serial Bus (USB) and addresses nodes representing USB devices. Since there is no provision for FCode on USB devices, this binding restricts itself to providing a common framework for a USB device tree. Implementations that support USB devices as boot, input, and output devices, will define their own methods and properties to communicate with USB endpoints. Those methods are beyond the scope of this document. 1.1. References [1] IEEE Std 1275-1994 IEEE Standard for Boot (Initialization Configuration) | Firmware: Core Requirements and Practices | [2] Universal Serial Bus Specification, 2.0 | [3] Interface Association Descriptor Engineering Change Notice (ECN) | [4] USB Defined 1.0 Class Codes (http://www.usb.org/developers/defined_class) | [5] USB class specs (http://www.usb.org/developers/devclass_docs#approved) | [6] Certified Wireless USB (http://www.usb.org/developers/wusb) 1.2. Definitions of Terms combined node: A device tree node that represents both a USB device and a USB interface. device node: A device tree node that represents a USB device. USB host controller: A hardware device that interfaces between a computer system and a USB bus. host controller node: A device tree node that represents a USB host controller. hub node: 1. A device tree node that represents a USB hub. 2. A combined node whose USB interface is a USB hub. interface node: A device tree node that represents a USB interface. | interface-association (IA) node: A device tree node that represents a USB | interface association. See [3]. | low speed: 1.5 Mbs, rather than the normal 12.0 Mbs signalling speed. See [2]. transaction: The delivery of service to an endpoint. See [2]. transfer: One or more transactions. See [2]. USB device: A hardware device that connects to a USB bus. USB hub: A USB interface that provides additional connections to the USB bus. USB interface: An independent piece of functionality of a USB device. | USB interface association: An independent piece of functionality composed of a | group a interfaces. See [3]. | 1.2.1. USB Descriptors [2] defines a number of data structures that are referenced in this document. They are: DEVICE See [2] section 9.6.1. Fields referenced by this binding: bDeviceClass, bDeviceSubClass, bDeviceProtocol, idVendor, idProduct, bcdDevice, bNumConfigurations. CONFIGURATION | See [2] section 9.6.3. Fields referenced by this binding: bNumInterfaces, bConfigurationValue. INTERFACE | See [2] section 9.6.5. Fields referenced by this binding: bInterfaceNumber, bAlternateSetting, bInterfaceClass, bInterfaceSubClass, bInterfaceProtocol. | [3] defines a new data structures that are referenced in this document. It is: | | INTERFACE ASSOCIATION | See [3] section 9.X.Y. Fields referenced by this binding: | bFirstInterface, bInterfaceCount, bFunctionClass, bFunctionSubClass, | bFunctionProtocol. | 2. Bus Characteristics USB is not a memory-mapped bus. An operation with a USB device is performed by executing a transfer consisting of one or more bus transactions to move information between the host system and the device. A bus transaction consists of multiple packets, including a token packet, possibly a data packet, and possibly a handshake packet. The specific packets are allowed and/or required based on the transaction type. Four transfer types are defined: control, interrupt, bulk, and isochronous. 2.1. Bus-specific Configuration Variables None. 2.2. Format of a Probe List None. 2.3. FCode Evaluation Semantics None. (USB has no provision for device identification via FCode.) 3. Device Tree Structure | This document defines five types of device tree nodes for USB: host controller | nodes, device nodes, interface nodes, combined nodes and interface-association | (IA) nodes. | Generally, USB devices are represented as up to three levels of device tree | nodes: a device node representing the entire USB device, with one or more | child interface nodes representing the individual USB interfaces on the device, | possibly with an intervening level of interface association nodes represnenting | an interface association with child interfaces. For special cases the device | and interface nodes are combined into a single combined node. 3.1. Host Controller Nodes 3.1.1. Host Controller Node Properties 3.1.1.1. Open Firmware-defined Properties for Host Controller Nodes The following standard properties, as defined in [1], have special meaning or interpretation for host controller nodes. "#address-cells" S Standard property to define the address format. Its value shall be 1, | encoded as with encode-int, representing the port for the device. "#size-cells" S Standard prop-name to define the package's address size format. prop-encoded-array: 0, encoded as with encode-int. The value of "#size-cells" for host controller nodes shall be 0, representing the fact that host controller addresses are an enumeration rather than memory-like address ranges. 3.1.1.2. Bus-specific Properties for Host Controller Nodes None. 3.1.2. Host Controller Node Methods 3.1.2.1. Open Firmware-defined Methods for Host Controller Nodes A package implementing a host controller node shall implement the following standard methods as defined in [1], with physical address representation as specified in section 3.2.1. decode-unit ( addr len -- port ) encode-unit ( port -- addr len ) 3.1.2.2. Bus-specific Methods for Host Controller Nodes None. 3.2. Device Nodes Device nodes represent USB devices. USB devices may require device-specific support to enable choice of the USB device configuration and/or to enable operation of multiple USB interfaces in a coordinated fashion. Unless otherwise specified, a device node shall be created for each USB device. 3.2.1. Device Node Address Representation The textual representation of a device node unit address shall be the number of the USB hub port or the USB host controller port to which this USB device is attached, in lower case hexadecimal with leading zeroes suppressed. 3.2.2. Device Node Properties 3.2.2.1. Open Firmware-defined Properties for Device Nodes The following properties, as defined in [1], have special meanings or interpretations for device nodes. These properties shall be created for each device node created. The following notation is used: From the DEVICE descriptor for this USB device: VID idVendor PID idProduct REV bcdDevice DC bDeviceClass DSC bDeviceSubClass DPROTO bDeviceProtocol From the CONFIGURATION descriptor for this USB device: CN bConfigurationValue for the selected configuration. The textual representation of VID, PID, REV, DC, DSC, DPROTO, and CN shall be in lower case hexadecimal with leading zeroes suppressed. "#address-cells" S Standard property to define the address format. Its value shall be 2, | encoded as with encode-int, representing the interface and possibly | configuration number. "compatible" S Standard prop-name prop-encoded-array; a list of strings, each encoded with encode-string and concatenated with encode+. Construct encoded strings as enumerated in the following list. All of the applicable strings shall be included in the value of "compatible". Their relative order shall be as in the list, string 1) before string 2), and so forth. Strings containing a configuration number (1 and 3) shall be omitted for a single-configuration USB device. Strings containing a device class (5..10) shall be omitted if the device class is 0. 1) usbVID,PID.REV.configCN 2) usbVID,PID.REV 3) usbVID,PID.configCN 4) usbVID,PID 5) usbVID,classDC.DSC.DPROTO 6) usbVID,classDC.DSC 7) usbVID,classDC 8) usb,classDC.DSC.DPROTO 9) usb,classDC.DSC 10) usb,classDC 11) usb,device Note: entry 11, "usb,device", provides a mechanism to bind a generic driver to a USB device. "name" S Standard prop-name. prop-encoded-array: a string encoded with encode-string. The name of the node should be chosen from the following table, using the first name applicable: | bDeviceClass bDeviceSubClass bDeviceProtocol Name --------------------------------------------------------------- | 0x02 any any communications | 0x09 any any hub | 0xDC any any diagnostics | 0xEF any any miscellaneous | any any any device | | Note: refer to USB defined 1.0 class codes[4] and class specs [5]. | "reg" S Standard prop-name. prop-encoded-array: one integer, encoded as with encode-int. The "reg" property for a device node shall consist of the number of the | USB hub or host controller port to which this USB device is attached. As | specified in [2] section 11.23.2.1, port numbers range from 1 to 255. Note | that it's 1-based, not 0-based. "#size-cells" S Standard prop-name. prop-encoded-array: 0, encoded as with encode-int. The value of "#size-cells" for device nodes shall be 0, representing the fact that USB device addresses are an enumeration rather than memory-like address ranges. 3.2.2.2. Bus-specific Properties for Device Nodes "assigned-address" prop-name to indicate the assigned USB bus address. prop-encoded-array: one integer, encoded as with encode-int. This property supplies the USB bus address assigned to this USB device Each USB device that is assigned a USB address shall be assigned a USB address that is unique among all USB devices on this USB bus. "configuration#" prop-name to indicate the selected configuration. prop-encoded-array: one integer, encoded as with encode-int. This property indicates the bConfigurationValue contained in the CONFIGURATION descriptor for the configuration selected for this USB device. "low-speed" prop-name to indicate that the USB device is low speed. prop-encoded-array: None; presence or absence of the property conveys the information. This property, if present, indicates that the USB device is low speed. 3.2.3. Device Node Methods 3.2.3.1. Open Firmware-defined Methods for Device Nodes A package implementing a device node shall implement the following standard methods as defined in [1], with physical address representation | as specified in section 3.3.1 or 3.5.1. decode-unit ( addr len -- config# interface# ) encode-unit ( config# interface# -- addr len ) 3.2.3.2. Bus-specific Methods for Device Nodes None. 3.3. Interface Nodes Interface nodes represent the USB interfaces present on a USB device. | Normally, each interface represents an independently controlled functionality | as the child of a device node, or a sub-functionality as a child of an | interface-association node (see 3.5). Unless otherwise specified, an interface node shall be created for each USB interface. 3.3.1. Interface Node Address Representation The textual representation of an interface node unit address shall be constructed as follows: If the bConfigurationValue of the CONFIGURATION descriptor associated with this USB interface is equal to 1, the textual representation shall be the bInterfaceNumber of the INTERFACE descriptor with value 0 for bAlternateSetting associated with this USB interface, expressed in lower case hexadecimal with leading zeroes suppressed. If the bConfigurationValue is not equal to 1, the textual representation shall be the bInterfaceNumber of the INTERFACE descriptor with value 0 for bAlternateSetting associated with this USB interface, a comma, and the bConfigurationValue, with both values expressed in lower case hexadecimal with leading zeroes suppressed. 3.3.2. Interface Node Properties 3.3.2.1. Open Firmware-defined Properties for Interface Nodes The following properties, as defined in [1], have special meanings or interpretations for interface nodes. These properties shall be created for each interface node created. The following notation is used: From the DEVICE descriptor for this USB interface: VID idVendor PID idProduct REV bcdDevice DC bDeviceClass DSC bDeviceSubClass DPROTO bDeviceProtocol From the INTERFACE descriptor with the value of 0 for bAlternateSetting for this USB interface: IN bInterfaceNumber IC bInterfaceClass ISC bInterfaceSubClass IPROTO bInterfaceProtocol The textual representation of VID, PID, REV, DC, DSC, DPROTO, IN, IC, ISC, and IPROTO shall be in lower case hexadecimal with leading zeroes suppressed. "compatible" S Standard prop-name. prop-encoded-array; a list of strings, encoded with encode-string and concatenated with encode+. Construct encoded strings as enumerated in the following list. All of the applicable strings shall be included in the value of "compatible". Their relative order shall be as in the list, string 1) before string 2), and so forth. Strings containing an interface class (3..8) shall be omitted if the interface class is 0. 1) usbifVID,PID.REV.configCN.IN 2) usbifVID,PID.configCN.IN 3) usbifVID,classIC.ISC.IPROTO 4) usbifVID,classIC.ISC 5) usbifVID,classIC 6) usbif,classIC.ISC.IPROTO 7) usbif,classIC.ISC 8) usbif,classIC "name" S Standard prop-name. prop-encoded-array: a string encoded with encode-string. The name of the node should be chosen from the following table, using the first name applicable: bInterface bInterface bInterface Class Subclass Protocol Name ------------------------------------------------------------- | 0x01 1 any sound-control | 0x01 2 any sound | 0x01 3 any midi | 0x01 any any sound | 0x02 1 any line | 0x02 2 any modem | 0x02 3 any telephone | 0x02 4 any isdn | 0x02 5 any isdn | 0x02 6 any ethernet | 0x02 7 any atm-network | 0x02 any any communications | 0x03 1 1 keyboard | 0x03 1 2 mouse | 0x03 any any input | 0x05 any any physical | 0x06 any any image | 0x07 any any printer | 0x08 1 any storage | 0x08 2 any cdrom | 0x08 3 any tape | 0x08 4 any floppy | 0x08 5 any storage | 0x08 6 any storage | 0x08 any any storage | 0x09 any any hub | 0x0A any any data | 0x0B any any smartcard | 0x0D any any security | 0x0E 1 any video-control | 0x0E 2 any video-stream | 0x0E any any video | 0xDC any any diagnostics | 0xE0 any any wireless-controller | 0xEF any any miscellaneous | 0xFE any any application | any any any interface | | Note: refer to USB defined 1.0 class codes[4] and class specs [5] [6]. "reg" S Standard prop-name. prop-encoded-array: two integers, each encoded as with encode-int. The "reg" property for an interface node shall be constructed as follows: The first integer shall contain the bInterfaceNumber from the INTERFACE descriptor with value 0 for bAlternateSetting associated with this USB interface. The second integer shall contain the bConfigurationValue from the CONFIGURATION descriptor associated with this USB interface. 3.3.2.2. Bus-specific Properties for Interface Nodes None. 3.3.3. Interface Node Methods 3.3.3.1. Open Firmware-defined Methods for Interface Nodes None. 3.3.3.2. Bus-specific Methods for Interface Nodes None. 3.4. Combined Nodes A combined node is a special case node, combining some of the properties of both device nodes and interface nodes, and is typically used to simplify | the representation of a simple USB device with a single configuration and a single interface. Neither a device node (see section 3.2.) nor an interface node (see section 3.3.) shall be created when a USB device reports in its DEVICE descriptor the following: | (1) bDeviceClass is 0 or 9, | or (2) bNumConfigurations is 1, and reports in its CONFIGURATION descriptor the following: (3) bNumInterfaces is 1. Instead, a combined node shall be created. 3.4.1. Combined Node Address Representation The textual representation of a combined node unit address shall be the number of the USB hub port or USB host controller port to which this USB device is attached, in lower case hexadecimal with leading zeroes suppressed. 3.4.2. Combined Node Properties 3.4.2.1. Open Firmware-defined Properties for Combined Nodes The following standard properties, as defined in [1], have special meaning or interpretation for combined nodes. The following notation is used: From the DEVICE descriptor for this USB device: VID idVendor PID idProduct REV bcdDevice DC bDeviceClass DSC bDeviceSubClass DPROTO bDeviceProtocol From the INTERFACE descriptor with the value of 0 for bAlternateSetting for this USB interface: IC bInterfaceClass ISC bInterfaceSubClass IPROTO bInterfaceProtocol The textual representation of VID, PID, REV, DC, DSC, DPROTO, IC, ISC, and IPROTO shall be in lower case hexadecimal with leading zeroes suppressed. "compatible" S Standard prop-name. prop-encoded-array; a list of strings, encoded with encode-string and concatenated with encode+. Construct encoded strings as enumerated in the following list. All of the applicable strings shall be included in the value of "compatible". Their relative order shall be as in the list, string 1) before string 2), and so forth. Strings containing a device class (3..8) shall be omitted if the device class is 0. Strings containing an interface class (9..14) shall be omitted if the interface class is 0. 1) usbVID,PID.REV 2) usbVID,PID 3) usbVID,classDC.DSC.DPROTO 4) usbVID,classDC.DSC 5) usbVID,classDC 6) usb,classDC.DSC.DPROTO 7) usb,classDC.DSC 8) usb,classDC 9) usbifVID,classIC.ISC.IPROTO 10) usbifVID,classIC.ISC 11) usbifVID,classIC 12) usbif,classIC.ISC.IPROTO 13) usbif,classIC.ISC 14) usbif,classIC "name" S Standard prop-name. prop-encoded-array: one string, encoded with encode-string. The name of the node should be chosen from the following table, using the first name applicable: bInterface bInterface bInterface Class Subclass Protocol Name ------------------------------------------------------------- | 0x01 1 any sound-control | 0x01 2 any sound | 0x01 3 any midi | 0x01 any any sound | 0x02 1 any line | 0x02 2 any modem | 0x02 3 any telephone | 0x02 4 any isdn | 0x02 5 any isdn | 0x02 6 any ethernet | 0x02 7 any atm-network | 0x02 any any communications | 0x03 1 1 keyboard | 0x03 1 2 mouse | 0x03 any any input | 0x05 any any physical | 0x06 any any image | 0x07 any any printer | 0x08 1 any storage | 0x08 2 any cdrom | 0x08 3 any tape | 0x08 4 any floppy | 0x08 5 any storage | 0x08 6 any storage | 0x08 any any storage | 0x09 any any hub | 0x0A any any data | 0x0B any any smartcard | 0x0D any any security | 0x0E 1 any video-control | 0x0E 2 any video-stream | 0x0E any any video | 0xDC any any diagnostics | 0xE0 any any wireless-controller | 0xEF any any miscellaneous | 0xFE any any application | any any any device | | Note: refer to USB defined 1.0 class codes[4] and class specs [5] [6]. "reg" S Standard prop-name. prop-encoded-array: one integer, encoded as with encode-int. The "reg" property for a combined node shall be the number of the USB hub port or the USB host controller port to which this USB device is attached. As specified [2] section 11.11.2.1, port numbers range from 1 to 255. 3.4.2.2. Bus-specific Properties for Combined Nodes "assigned-address" prop-name to indicate the assigned USB bus address. prop-encoded-array: one integer, encoded as with encode-int. This property supplies the USB bus address assigned to this USB device. Each USB device that is assigned a USB address shall be assigned a USB address that is unique among all USB devices on this USB bus. "low-speed" prop-name to indicate that the USB device is low speed. prop-encoded-array: None; presence or absence of the property conveys the information. This property, if present, indicates that the USB device is low speed. 3.4.3. Combined Node Methods 3.4.3.1. Open Firmware-defined Methods for Combined Nodes None. 3.4.3.2. Bus-specific Methods for Combined Nodes None. | 3.5. Interface-Association Nodes | | Interface-Association (IA) nodes represent the USB interface-association present | on a USB device. This is an extended interface which has the ability to manage | multiple interfaces for a logical function. The Interface Association Descriptor | (IAD, see [3]) associates two or more interfaces into a single function. The | interface nodes representing the individual interfaces in an IA appear as | children of the IA node rather than directly as children of the device node. | | Unless otherwise specified, an IA node shall be created for each USB interface | association. | | 3.5.1. Interface-Association Node Address Representation | | The textual representation of an IA node unit address shall be constructed as | follows: | | If the bConfigurationValue of the CONFIGURATION descriptor associated with this | USB interface association is equal to 1, the textual representation shall be | bFirstInterface of INTERFACE ASSOCIATION descriptor, expressed in lower case | hexadecimal with leading zeroes suppressed. | | IF the bConfigurationValue is not equal to 1, the textual representation shall | be the bFirstInterface of INTERFACE ASSOCIATION descriptor, a comma, and the | bConguration Value, with both values expressed in lower case hexadecimal with | leading zeroes suppressed. | | 3.5.2. Interface-Association Node Properties | | 3.5.2.1. Open Firmware-defined Properties for Interface-Association Nodes | | The following properties have special meanings for IA nodes. These properties | shall be created for each IA node. | | The following notation is used: | | From the DEVICE descriptor for this USB interface association: | | VID idVendor | PID idProduct | REV bcdDevice | DC bDeviceClass | DSC bDeviceSubClass | DPROTO bDeviceProtocol | | From the INTERFACE ASSOCIATION descriptor: | | FN bFirstInterface | FC bFunctionClass | FSC bFunctionSubClass | FPROTO bFunctionProtocol | | The textual representation of VID, PID, REV, DC, DSC, DPROTO, FN, FC, FSC and | FPROTO shall be in lower case hexadecimal with leading zeroes suppressed. | | "#address-cells" S | Standard property to define the address format. It's value shall be 2, | encoded as with encode-int, representing bFirstInterface and possibly | configuration number. | | "compatible" S | Standard prop-name. | | prop-encoded-array; a list of strings, encoded with encode- string and | concatenated with encode+. | | Construct encoded strings as enumerated in the following list.All of the | applicable strings shall be included in the value of "compatible". their | relative order shall be as in the list, string 1) before string 2), and so | forth. | | Strings containing a function class(3..8) shall be omitted if the function | class is 0. | | 1) usbiaVID,PID.REV.configCN.FN | 2) usbiaVID,PID.configCN.FN | 3) usbiaVID,classFC.FSC.FPROTO | 4) usbiaVID,classFC.FSC | 5) usbiaVID,classFC | 6) usbia,classFC.FSC.FPROTO | 7) usbia,classFC.FSC | 8) usbia,classFC | 9) usb,ia | | Note: entry 9), "usb,ia", provides a mechanism to bind a generic driver to a | USB IA node. | | "name" S | Standard prop-name. | | prop-encoded-array: a string encoded with encode-string. | | The name of the node should be chosen from the following table, using the | first name applicable: | | bFunction bFunctionSub bFunction Name | Class Class Protocol | ----------------------------------------------------------------------------- | 0x01 any any audio | 0x0E any any video | 0xE0 0x02 0x02 device-wire-adapter | 0xE0 any any wireless-controller | any any any interface-association | | Note: refer to audio 2.0 class, video class 1.1 specs (see [5]) and | wusb docs (see [6]). | | "reg" S | Standard prop-name. | | prop-encoded-array: two integers, each encoded as with encode-int. | | The "reg" property for in IA node shall be constructed as: | | The first integer shall contain the bFirstInterface from INTERFACE ASSOCIATION | descriptor. | | The second integer shall contain the bConfigurationValue from CONFIGURATION | descriptor associated with this USB interface association. | | "#size-cells" S | Standard prop-name. | | prop-encoded-array: 0, encoded as with encode-int. | | The value of "#size-cells" for IA nodes shall be 0, representing the fact | that USB IA addresses are an enumeration rather than memory-like address | ranges. | | | 3.5.2.2. Bus-specific Properties for Interface-Association Nodes | | None. | | 3.5.3. Interface-Association Node Methods | | 3.5.3.1. Open Firmware-defined Methods for Interface-Association Nodes | | A package implementing an IA node shall implement the following standard methods | as defined in [1], with physical address representation as specified in section 3.3.1; | | decode-unit ( addr len -- config# interface# ) M | | encode-unit ( config# interface# -- addr len ) M | | | 3.5.3.2. Bus-specific Methods for Interface-Association Nodes | | None. | | | 4. Hub Nodes This section includes special requirements for devices implementing a hub node. 4.1. Common Requirements for Hub Nodes This section contains the common requirements for hub nodes. 4.1.1. Hub Node Properties 4.1.1.1. Open Firmware-defined Properties for Hub Nodes The following standard properties, as defined in [1], have special meaning or interpretation for hub nodes. "#address-cells" S Standard property to define the address format. Its value shall be 1, encoded as with encode-int. "#size-cells" S Standard prop-name to define the package's address size format. prop-encoded-array: 0, encoded as with encode-int. The value of "#size-cells" shall be 0, representing the fact that child device addresses are an enumeration rather than memory-like address ranges. 4.1.1.2. Bus-specific Properties for Hub Nodes None. 4.1.2. Hub Node Methods 4.1.2.1. Open Firmware-defined Methods for Hub Nodes A package implementing a hub node shall implement the following standard methods as defined in [1], with physical address representations as specified in section 3.2.1. decode-unit ( addr len -- port ) encode-unit ( port -- addr len ) 4.1.2.2. Bus-specific Methods for Hub Nodes None. | 4.2. Requirements for Combined Node and Interface Node Hubs | A combined node (see section 3.4.) hub and an interface node (see section 3.3.) | hub shall both include all the properties, methods and requirements of "Common Requirements for Hub Nodes" as described in section 4.1