*** old_usb_binding.txt Fri Dec 15 18:51:44 2006 --- usb_binding.txt Fri Dec 15 18:22:05 2006 *************** *** 1,4 **** - #ident "@(#)usb_binding.txt 1.2 06/11/01 SMI" Open Firmware --- 1,3 ---- *************** *** 27,36 **** Revision History - 1. Overview and References --- 26,36 ---- 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 *************** *** 48,57 **** [1] IEEE Std 1275-1994 IEEE Standard for Boot (Initialization Configuration) ! Firmware: Core Requirements and Practices ! [2] Universal Serial Bus Specification, 1.0 - 1.2. Definitions of Terms --- 48,60 ---- [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 *************** *** 70,75 **** --- 73,81 ---- 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]. *************** *** 82,108 **** USB interface: An independent piece of functionality of a USB device. ! 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.2. Fields referenced by this binding: bNumInterfaces, bConfigurationValue. INTERFACE ! See [2] section 9.6.3. Fields referenced by this binding: bInterfaceNumber, bAlternateSetting, bInterfaceClass, bInterfaceSubClass, bInterfaceProtocol. 2. Bus Characteristics --- 88,124 ---- 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 ! The USB 2.0 Spec [2] defines a number of data structures that are referenced ! in this document. They are: DEVICE ! See USB 2.0 Spec [2] section 9.6.1. Fields referenced by this binding: bDeviceClass, bDeviceSubClass, bDeviceProtocol, idVendor, idProduct, bcdDevice, bNumConfigurations. CONFIGURATION ! See USB 2.0 Spec [2] section 9.6.3. Fields referenced by this binding: bNumInterfaces, bConfigurationValue. INTERFACE ! See USB 2.0 Spec [2] section 9.6.5. Fields referenced by this binding: bInterfaceNumber, bAlternateSetting, bInterfaceClass, bInterfaceSubClass, bInterfaceProtocol. + The USB IA ECN [3] defines a new data structure that is referenced in this + document. It is: + + INTERFACE ASSOCIATION + See USB IA ECN [3] section 9.X.Y. Fields referenced by this binding: + bFirstInterface, bInterfaceCount, bFunctionClass, bFunctionSubClass, + bFunctionProtocol. + 2. Bus Characteristics *************** *** 136,150 **** 3. Device Tree Structure ! This document defines four types of device tree nodes for USB: host ! controller nodes, device nodes, interface nodes, and combined nodes. ! Generally, USB devices are represented as two 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. ! For special cases the device and interface nodes are combined into a ! single combined node. ! 3.1. Host Controller Nodes --- 152,167 ---- 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 representing ! an interface association with child interfaces. For a common special case, the ! device and interface nodes are combined into a single combined node. 3.1. Host Controller Nodes *************** *** 155,166 **** 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. "#size-cells" S Standard prop-name to define the package's address size format. --- 172,183 ---- 3.1.1.1. Open Firmware-defined Properties for Host Controller Nodes ! The following standard properties, as defined in IEEE-1275 [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. *************** *** 185,192 **** 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 ) --- 202,209 ---- A package implementing a host controller node shall implement the following ! standard methods as defined in IEEE-1275 [1], with physical address ! representation as specified in section 3.2.1. decode-unit ( addr len -- port ) *************** *** 224,231 **** 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: --- 241,248 ---- 3.2.2.1. Open Firmware-defined Properties for Device Nodes ! The following properties, as defined in IEEE-1275 [1], have special meanings ! or interpretations for device nodes. These properties shall be created for each device node created. The following notation is used: *************** *** 247,253 **** "#address-cells" S Standard property to define the address format. Its value shall be 2, ! encoded as with encode-int. "compatible" S Standard prop-name --- 264,271 ---- "#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 *************** *** 257,263 **** 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 --- 275,281 ---- 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 *************** *** 287,308 **** The name of the node should be chosen from the following table, using the first name applicable: ! bDeviceClass bDeviceSubclass bDeviceProtocol Name --------------------------------------------------------------- ! 9 any any hub ! [MASS] 1 any storage ! [MASS] 2 any cdrom ! [MASS] 3 any tape ! [MASS] 4 any solid-state ! [MASS] any any storage ! any any any device - Note: The USB Device Working Group has not yet completed - standardization of the Mass Storage Device Class, and so a device - class code has not yet been assigned and the subclass codes are not - final. The names above should be used, as appropriate, when the Mass - Storage Device Class specification is complete. - "reg" S Standard prop-name. --- 305,320 ---- 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. *************** *** 309,317 **** 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 port or the USB host controller port to which this USB device is ! attached. As specified in [2] section 11.11.2.1, port numbers range ! from 1 to 255. "#size-cells" S Standard prop-name. --- 321,329 ---- 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 USB 2.0 spec [2] section 11.23.2.1, port numbers range from ! 1 to 255. Do note the unusual 1-based numbering, a source of confusion. "#size-cells" S Standard prop-name. *************** *** 360,367 **** 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. decode-unit ( addr len -- config# interface# ) --- 372,379 ---- A package implementing a device node shall implement the following ! standard methods as defined in IEEE-1275 [1], with physical address ! representation as specified in section 3.3.1 or 3.5.1. decode-unit ( addr len -- config# interface# ) *************** *** 378,386 **** Interface nodes represent the USB interfaces present on a USB device. ! Normally, each interface represents independently controlled functionality, ! although for some device classes (e.g. Communications, Audio) one interface ! may provide "out of band" control for another. Unless otherwise specified, an interface node shall be created for each USB interface. --- 390,398 ---- 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. *************** *** 411,417 **** 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. --- 423,429 ---- 3.3.2.1. Open Firmware-defined Properties for Interface Nodes ! The following properties, as defined in IEEE-1275 [1], have special meanings or interpretations for interface nodes. These properties shall be created for each interface node created. *************** *** 472,501 **** bInterface bInterface bInterface Class Subclass Protocol Name ------------------------------------------------------------- ! 1 1 any sound-control ! 1 2 any sound ! 1 3 any midi ! 1 any any sound ! 3 1 1 keyboard ! 3 1 2 mouse ! 7 any any printer ! 9 any any hub ! [POWER] any any power ! [MONITOR] any any display-control ! [COMM] 1 any modem ! [COMM] 2 any modem ! [COMM] 3 any telephone ! [COMM] any any communications ! [DATA] any any data ! any any any interface - Note: The USB Device Working Group has not yet completed - standardization of the Audio, Power, Monitor, Communications, or - Data Interface Classes, and so interface class codes have not yet - been assigned and the subclass codes are not final. The names - above should be used, as appropriate, when the various specifications - are complete. - "reg" S Standard prop-name. --- 484,529 ---- 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. *************** *** 537,549 **** 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, and (2) bNumConfigurations is 1, and reports in its CONFIGURATION descriptor the following: (3) bNumInterfaces is 1. --- 565,578 ---- 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. *************** *** 563,570 **** 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: --- 592,599 ---- 3.4.2.1. Open Firmware-defined Properties for Combined Nodes ! The following standard properties, as defined in IEEE-1275 [1], have special ! meaning or interpretation for combined nodes. The following notation is used: *************** *** 629,670 **** bInterface bInterface bInterface Class Subclass Protocol Name ------------------------------------------------------------- ! 1 1 any sound-control ! 1 2 any sound ! 1 3 any midi ! 1 any any sound ! 3 1 1 keyboard ! 3 1 2 mouse ! 7 any any printer ! 9 any any hub ! [POWER] any any power ! [MONITOR] any any display-control ! [COMM] 1 any modem ! [COMM] 2 any modem ! [COMM] 3 any telephone ! [COMM] any any communications ! [DATA] any any data ! 9 any any hub ! [MASS] 1 any storage ! [MASS] 2 any cdrom ! [MASS] 3 any tape ! [MASS] 4 any solid-state ! [MASS] any any storage ! any any any device - Note: The USB Device Working Group has not yet completed - standardization of the Audio, Power, Monitor, Communications, or - Data Interface Classes, and so interface class codes have not yet - been assigned and the subclass codes are not yet final. The names - above should be used, as appropriate, when the various specifications - are complete. - Note: The USB Device Working Group has not yet completed - standardization of the Mass Storage Device Class, and so a device - class code has not yet been assigned and the subclass codes are not - yet final. The names above should be used, as appropriate, - when the Mass Storage Device Class specification is complete. - "reg" S Standard prop-name. --- 658,704 ---- 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. *************** *** 672,679 **** 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 --- 706,713 ---- 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 USB 2.0 [2] section 11.11.2.1, port numbers range ! from 1 to 255. Do note the unusual 1-based numbering. 3.4.2.2. Bus-specific Properties for Combined Nodes *************** *** 712,717 **** --- 746,905 ---- 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 USB IA ECN [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 [5] and + wusb docs [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 IEEE-1275 [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 *************** *** 729,736 **** 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, --- 917,924 ---- 4.1.1.1. Open Firmware-defined Properties for Hub Nodes ! The following standard properties, as defined in IEEE-1275 [1], have special ! meaning or interpretation for hub nodes. "#address-cells" S Standard property to define the address format. Its value shall be 1, *************** *** 758,765 **** 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 ) --- 946,953 ---- A package implementing a hub node shall implement the following ! standard methods as defined in IEEE-1275 [1], with physical address ! representations as specified in section 3.2.1. decode-unit ( addr len -- port ) *************** *** 770,793 **** None. - - - 4.2. Requirements for Combined Node Hubs - - - A combined node (see section 3.4.) which reports in its INTERFACE descriptor - with value 0 for bAlternateSetting the following: - bInterfaceClass is 9, - is a combined node hub. - - A combined node hub shall include all the properties, methods and requirements - of "Common Requirements for Hub Nodes" as described in section 4.1 - - - 4.3. Requirements for Interface Node Hubs - - - An interface node (see section 3.3.) which represents a USB hub - shall include all the properties, methods and requirements of - "Common Requirements for Hub Nodes" as described in section 4.1 --- 958,961 ----