Commit 431a30b7 authored by Prashant Malani's avatar Prashant Malani Committed by Rob Herring
Browse files

dt-bindings: Convert usb-connector to YAML format. 

Convert the usb-connector.txt bindings file to YAML format. This allows
it to be used in dt_bindings_check verification. This patch was
born out of a patch series for the addition of a Type C connector
class port driver[1].

An attempt has been made to maintain the same documentation text and
example structure as was in the .txt file, but wherever needed
modifications have been made to satisfy dt_bindings_check.

Also, update all references to usb-connector.txt to now use
usb-connector.yaml.

[1]: https://lkml.org/lkml/2020/2/19/1232



Signed-off-by: default avatarPrashant Malani <pmalani@chromium.org>
Reviewed-by: default avatarBenson Leung <bleung@chromium.org>
Signed-off-by: default avatarRob Herring <robh@kernel.org>
parent e329f87d

Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt

+1 −1
Original line number Diff line number Diff line
@@ -19,7 +19,7 @@ Required nodes: 
    0: High Speed (HS),

    3: Mobile High-Definition Link (MHL), specific to 11-pin Samsung micro-USB.



[1]: bindings/connector/usb-connector.txt

[1]: bindings/connector/usb-connector.yaml



Example

-------

Documentation/devicetree/bindings/connector/usb-connector.txt

deleted100644 → 0
+0 −135
Original line number Diff line number Diff line 
USB Connector

=============



A USB connector node represents a physical USB connector. It should be

a child of a USB interface controller.



Required properties:

- compatible: describes type of the connector, must be one of:

    "usb-a-connector",

    "usb-b-connector",

    "usb-c-connector".



Optional properties:

- label: symbolic name for the connector,

- type: size of the connector, should be specified in case of USB-A, USB-B

  non-fullsize connectors: "mini", "micro".

- self-powered: Set this property if the usb device that has its own power

  source.



Optional properties for usb-b-connector:

- id-gpios: an input gpio for USB ID pin.

- vbus-gpios: an input gpio for USB VBUS pin, used to detect presence of

  VBUS 5V.

  see gpio/gpio.txt.

- vbus-supply: a phandle to the regulator for USB VBUS if needed when host

  mode or dual role mode is supported.

  Particularly, if use an output GPIO to control a VBUS regulator, should

  model it as a regulator.

  see regulator/fixed-regulator.yaml

- pinctrl-names : a pinctrl state named "default" is optional

- pinctrl-0 : pin control group

  see pinctrl/pinctrl-bindings.txt



Optional properties for usb-c-connector:

- power-role: should be one of "source", "sink" or "dual"(DRP) if typec

  connector has power support.

- try-power-role: preferred power role if "dual"(DRP) can support Try.SNK

  or Try.SRC, should be "sink" for Try.SNK or "source" for Try.SRC.

- data-role: should be one of "host", "device", "dual"(DRD) if typec

  connector supports USB data.



Required properties for usb-c-connector with power delivery support:

- source-pdos: An array of u32 with each entry providing supported power

  source data object(PDO), the detailed bit definitions of PDO can be found

  in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2

  Source_Capabilities Message, the order of each entry(PDO) should follow

  the PD spec chapter 6.4.1. Required for power source and power dual role.

  User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO()

  defined in dt-bindings/usb/pd.h.

- sink-pdos: An array of u32 with each entry providing supported power

  sink data object(PDO), the detailed bit definitions of PDO can be found

  in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3

  Sink Capabilities Message, the order of each entry(PDO) should follow

  the PD spec chapter 6.4.1. Required for power sink and power dual role.

  User can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined

  in dt-bindings/usb/pd.h.

- op-sink-microwatt: Sink required operating power in microwatt, if source

  can't offer the power, Capability Mismatch is set. Required for power

  sink and power dual role.



Required nodes:

- any data bus to the connector should be modeled using the OF graph bindings

  specified in bindings/graph.txt, unless the bus is between parent node and

  the connector. Since single connector can have multiple data buses every bus

  has assigned OF graph port number as follows:

    0: High Speed (HS), present in all connectors,

    1: Super Speed (SS), present in SS capable connectors,

    2: Sideband use (SBU), present in USB-C.



Examples

--------



1. Micro-USB connector with HS lines routed via controller (MUIC):



muic-max77843@66 {

	...

	usb_con: connector {

		compatible = "usb-b-connector";

		label = "micro-USB";

		type = "micro";

	};

};



2. USB-C connector attached to CC controller (s2mm005), HS lines routed

to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.

DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.



ccic: s2mm005@33 {

	...

	usb_con: connector {

		compatible = "usb-c-connector";

		label = "USB-C";



		ports {

			#address-cells = <1>;

			#size-cells = <0>;



			port@0 {

				reg = <0>;

				usb_con_hs: endpoint {

					remote-endpoint = <&max77865_usbc_hs>;

				};

			};

			port@1 {

				reg = <1>;

				usb_con_ss: endpoint {

					remote-endpoint = <&usbdrd_phy_ss>;

				};

			};

			port@2 {

				reg = <2>;

				usb_con_sbu: endpoint {

					remote-endpoint = <&dp_aux>;

				};

			};

		};

	};

};



3. USB-C connector attached to a typec port controller(ptn5110), which has

power delivery support and enables drp.



typec: ptn5110@50 {

	...

	usb_con: connector {

		compatible = "usb-c-connector";

		label = "USB-C";

		power-role = "dual";

		try-power-role = "sink";

		source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;

		sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)

			     PDO_VAR(5000, 12000, 2000)>;

		op-sink-microwatt = <10000000>;

	};

};

Documentation/devicetree/bindings/connector/usb-connector.yaml

0 → 100644
+206 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: GPL-2.0-only

%YAML 1.2

---

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

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



title: USB Connector



maintainers:

  - Rob Herring <robh@kernel.org>



description:

  A USB connector node represents a physical USB connector. It should be a child

  of a USB interface controller.



properties:

  compatible:

    enum:

      - usb-a-connector

      - usb-b-connector

      - usb-c-connector



  label:

    description: Symbolic name for the connector.



  type:

    description: Size of the connector, should be specified in case of

      non-fullsize 'usb-a-connector' or 'usb-b-connector' compatible

      connectors.

    allOf:

      - $ref: /schemas/types.yaml#definitions/string

    enum:

      - mini

      - micro



  self-powered:

    description: Set this property if the USB device has its own power source.

    type: boolean



  # The following are optional properties for "usb-b-connector".

  id-gpios:

    description: An input gpio for USB ID pin.

    maxItems: 1



  vbus-gpios:

    description: An input gpio for USB VBus pin, used to detect presence of

      VBUS 5V.

    maxItems: 1



  vbus-supply:

    description: A phandle to the regulator for USB VBUS if needed when host

      mode or dual role mode is supported.

      Particularly, if use an output GPIO to control a VBUS regulator, should

      model it as a regulator. See bindings/regulator/fixed-regulator.yaml



  # The following are optional properties for "usb-c-connector".

  power-role:

    description: Determines the power role that the Type C connector will

      support. "dual" refers to Dual Role Port (DRP).

    allOf:

      - $ref: /schemas/types.yaml#definitions/string

    enum:

      - source

      - sink

      - dual



  try-power-role:

    description: Preferred power role.

    allOf:

      - $ref: /schemas/types.yaml#definitions/string

    enum:

     - source

     - sink

     - dual



  data-role:

    description: Data role if Type C connector supports USB data. "dual" refers

      Dual Role Device (DRD).

    allOf:

      - $ref: /schemas/types.yaml#definitions/string

    enum:

      - host

      - device

      - dual



  # The following are optional properties for "usb-c-connector" with power

  # delivery support.

  source-pdos:

    description: An array of u32 with each entry providing supported power

      source data object(PDO), the detailed bit definitions of PDO can be found

      in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2

      Source_Capabilities Message, the order of each entry(PDO) should follow

      the PD spec chapter 6.4.1. Required for power source and power dual role.

      User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO()

      defined in dt-bindings/usb/pd.h.

    minItems: 1

    maxItems: 7

    allOf:

      - $ref: /schemas/types.yaml#/definitions/uint32-array



  sink-pdos:

    description: An array of u32 with each entry providing supported power sink

      data object(PDO), the detailed bit definitions of PDO can be found in

      "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3

      Sink Capabilities Message, the order of each entry(PDO) should follow the

      PD spec chapter 6.4.1. Required for power sink and power dual role. User

      can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined

      in dt-bindings/usb/pd.h.

    minItems: 1

    maxItems: 7

    allOf:

      - $ref: /schemas/types.yaml#/definitions/uint32-array



  op-sink-microwatt:

    description: Sink required operating power in microwatt, if source can't

      offer the power, Capability Mismatch is set. Required for power sink and

      power dual role.



  ports:

    description: OF graph bindings (specified in bindings/graph.txt) that model

      any data bus to the connector unless the bus is between parent node and

      the connector. Since a single connector can have multiple data buses every

      bus has an assigned OF graph port number as described below.

    type: object

    properties:

      port@0:

        type: object

        description: High Speed (HS), present in all connectors.



      port@1:

        type: object

        description: Super Speed (SS), present in SS capable connectors.



      port@2:

        type: object

        description: Sideband Use (SBU), present in USB-C. This describes the

          alternate mode connection of which SBU is a part.



    required:

      - port@0



required:

  - compatible



examples:

  # Micro-USB connector with HS lines routed via controller (MUIC).

  - |+

    muic-max77843 {

      usb_con1: connector {

        compatible = "usb-b-connector";

        label = "micro-USB";

        type = "micro";

      };

    };



  # USB-C connector attached to CC controller (s2mm005), HS lines routed

  # to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.

  # DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.

  - |+

    ccic: s2mm005 {

      usb_con2: connector {

        compatible = "usb-c-connector";

        label = "USB-C";



        ports {

          #address-cells = <1>;

          #size-cells = <0>;



          port@0 {

            reg = <0>;

            usb_con_hs: endpoint {

              remote-endpoint = <&max77865_usbc_hs>;

            };

          };

          port@1 {

            reg = <1>;

            usb_con_ss: endpoint {

              remote-endpoint = <&usbdrd_phy_ss>;

            };

          };

          port@2 {

            reg = <2>;

            usb_con_sbu: endpoint {

              remote-endpoint = <&dp_aux>;

            };

          };

        };

      };

    };



  # USB-C connector attached to a typec port controller(ptn5110), which has

  # power delivery support and enables drp.

  - |+

    #include <dt-bindings/usb/pd.h>

    typec: ptn5110 {

      usb_con3: connector {

        compatible = "usb-c-connector";

        label = "USB-C";

        power-role = "dual";

        try-power-role = "sink";

        source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;

        sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)

                     PDO_VAR(5000, 12000, 2000)>;

        op-sink-microwatt = <10000000>;

      };

    };

Documentation/devicetree/bindings/usb/fcs,fusb302.txt

+1 −1
Original line number Diff line number Diff line
@@ -9,7 +9,7 @@ Required sub-node: 
- connector : The "usb-c-connector" attached to the FUSB302 IC. The bindings

  of the connector node are specified in:



	Documentation/devicetree/bindings/connector/usb-connector.txt

	Documentation/devicetree/bindings/connector/usb-connector.yaml





Example:

Documentation/devicetree/bindings/usb/generic.txt

+1 −1
Original line number Diff line number Diff line
@@ -34,7 +34,7 @@ Optional properties: 
 - usb-role-switch: boolean, indicates that the device is capable of assigning

			the USB data role (USB host or USB device) for a given

			USB connector, such as Type-C, Type-B(micro).

			see connector/usb-connector.txt.

			see connector/usb-connector.yaml.



This is an attribute to a USB controller such as:

CRA Git | Maintained and supported by SUSTech CRA and CCSE