dt-bindings: usb: convert usb-device.txt to YAML schema

Generic USB Device Properties

Usually, we only use device tree for hard wired USB device.

The reference binding doc is from:

http://www.devicetree.org/open-firmware/bindings/usb/usb-1_0.ps

Four types of device-tree nodes are defined: "host-controller nodes"

representing USB host controllers, "device nodes" representing USB devices,

"interface nodes" representing USB interfaces and "combined nodes"

representing simple USB devices.

A combined node shall be used instead of a device node and an interface node

for devices of class 0 or 9 (hub) with a single configuration and a single

interface.

A "hub node" is a combined node or an interface node that represents a USB

hub.

Required properties for device nodes:

- compatible: "usbVID,PID", where VID is the vendor id and PID the product id.

  The textual representation of VID and PID shall be in lower case hexadecimal

  with leading zeroes suppressed. The other compatible strings from the above

  standard binding could also be used, but a device adhering to this binding

  may leave out all except for "usbVID,PID".

- reg: the number of the USB hub port or the USB host-controller port to which

  this device is attached. The range is 1-255.

Required properties for device nodes with interface nodes:

- #address-cells: shall be 2

- #size-cells: shall be 0

Required properties for interface nodes:

- compatible: "usbifVID,PID.configCN.IN", where VID is the vendor id, PID is

  the product id, CN is the configuration value and IN is the interface

  number. The textual representation of VID, PID, CN and IN shall be in lower

  case hexadecimal with leading zeroes suppressed. The other compatible

  strings from the above standard binding could also be used, but a device

  adhering to this binding may leave out all except for

  "usbifVID,PID.configCN.IN".

- reg: the interface number and configuration value

The configuration component is not included in the textual representation of

an interface-node unit address for configuration 1.

Required properties for combined nodes:

- compatible: "usbVID,PID", where VID is the vendor id and PID the product id.

  The textual representation of VID and PID shall be in lower case hexadecimal

  with leading zeroes suppressed. The other compatible strings from the above

  standard binding could also be used, but a device adhering to this binding

  may leave out all except for "usbVID,PID".

- reg: the number of the USB hub port or the USB host-controller port to which

  this device is attached. The range is 1-255.

Required properties for hub nodes with device nodes:

- #address-cells: shall be 1

- #size-cells: shall be 0

Required properties for host-controller nodes with device nodes:

- #address-cells: shall be 1

- #size-cells: shall be 0

Example:

&usb1 {	/* host controller */

	#address-cells = <1>;

	#size-cells = <0>;

	hub@1 {		/* hub connected to port 1 */

		compatible = "usb5e3,608";

		reg = <1>;

	};

	device@2 {	/* device connected to port 2 */

		compatible = "usb123,4567";

		reg = <2>;

	};

	device@3 { 	/* device connected to port 3 */

		compatible = "usb123,abcd";

		reg = <3>;

		#address-cells = <2>;

		#size-cells = <0>;

		interface@0 {	/* interface 0 of configuration 1 */

			compatible = "usbif123,abcd.config1.0";

			reg = <0 1>;

		};

		interface@0,2 {	/* interface 0 of configuration 2 */

			compatible = "usbif123,abcd.config2.0";

			reg = <0 2>;

		};

	};

};

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

%YAML 1.2

---

$id: http://devicetree.org/schemas/usb/usb-device.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#

title: The device tree bindings for the Generic USB Device

maintainers:

  - Greg Kroah-Hartman <gregkh@linuxfoundation.org>

description: |

  Usually, we only use device tree for hard wired USB device.

  The reference binding doc is from:

  http://www.devicetree.org/open-firmware/bindings/usb/usb-1_0.ps

  Four types of device-tree nodes are defined: "host-controller nodes"

  representing USB host controllers, "device nodes" representing USB devices,

  "interface nodes" representing USB interfaces and "combined nodes"

  representing simple USB devices.

  A combined node shall be used instead of a device node and an interface node

  for devices of class 0 or 9 (hub) with a single configuration and a single

  interface.

  A "hub node" is a combined node or an interface node that represents a USB

  hub.

properties:

  compatible:

    pattern: "^usb[0-9a-f]{1,4},[0-9a-f]{1,4}$"

    description: Device nodes or combined nodes.

      "usbVID,PID", where VID is the vendor id and PID the product id.

      The textual representation of VID and PID shall be in lower case

      hexadecimal with leading zeroes suppressed. The other compatible

      strings from the above standard binding could also be used,

      but a device adhering to this binding may leave out all except

      for "usbVID,PID".

  reg:

    description: the number of the USB hub port or the USB host-controller

      port to which this device is attached. The range is 1-255.

    maxItems: 1

  "#address-cells":

    description: should be 1 for hub nodes with device nodes,

      should be 2 for device nodes with interface nodes.

    enum: [1, 2]

  "#size-cells":

    const: 0

patternProperties:

  "^interface@[0-9a-f]{1,2}(,[0-9a-f]{1,2})$":

    type: object

    description: USB interface nodes.

      The configuration component is not included in the textual

      representation of an interface-node unit address for configuration 1.

    properties:

      compatible:

        pattern: "^usbif[0-9a-f]{1,4},[0-9a-f]{1,4}.config[0-9a-f]{1,2}.[0-9a-f]{1,2}$"

        description: Interface nodes.

          "usbifVID,PID.configCN.IN", where VID is the vendor id, PID is

          the product id, CN is the configuration value and IN is the interface

          number. The textual representation of VID, PID, CN and IN shall be

          in lower case hexadecimal with leading zeroes suppressed.

          The other compatible strings from the above standard binding could

          also be used, but a device adhering to this binding may leave out

          all except for "usbifVID,PID.configCN.IN".

      reg:

        description: should be 2 cells long, the first cell represents

          the interface number and the second cell represents the

          configuration value.

        maxItems: 1

required:

  - compatile

  - reg

additionalProperties: true

examples:

  #hub connected to port 1

  #device connected to port 2

  #device connected to port 3

  #    interface 0 of configuration 1

  #    interface 0 of configuration 2

  - |

    usb@11270000 {

        reg = <0x11270000 0x1000>;

        interrupts = <0x0 0x4e 0x0>;

        #address-cells = <1>;

        #size-cells = <0>;

        hub@1 {

            compatible = "usb5e3,608";

            reg = <1>;

        };

        device@2 {

            compatible = "usb123,4567";

            reg = <2>;

        };

        device@3 {

            compatible = "usb123,abcd";

            reg = <3>;

            #address-cells = <2>;

            #size-cells = <0>;

            interface@0 {

                compatible = "usbif123,abcd.config1.0";

                reg = <0 1>;

            };

            interface@0,2 {

                compatible = "usbif123,abcd.config2.0";

                reg = <0 2>;

            };

        };

    };

      targeted hosts (non-PC hosts).

      targeted hosts (non-PC hosts).

    type: boolean

    type: boolean

  "#address-cells":

    const: 1

  "#size-cells":

    const: 0

patternProperties:

  "^.*@[0-9a-f]{1,2}$":

    description: The hard wired USB devices

    type: object

    $ref: /usb/usb-device.yaml

additionalProperties: true

additionalProperties: true

examples:

examples:

    usb {

    usb {

        phys = <&usb2_phy1>, <&usb3_phy1>;

        phys = <&usb2_phy1>, <&usb3_phy1>;

        phy-names = "usb";

        phy-names = "usb";

        #address-cells = <1>;

        #size-cells = <0>;

        hub@1 {

            compatible = "usb5e3,610";

            reg = <1>;

        };

    };

    };