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: Prashant Malani <[email protected]>
---
Changes in v2:
- Added type references for some properties.
- Removed pinctrl properties.
- Updated power-role, try-power-role and data-role properties to be in
valid schema format.
- Added OF graph data bus binding property according to reviewer
suggestions.
.../connector/samsung,usb-connector-11pin.txt | 2 +-
.../bindings/connector/usb-connector.txt | 135 ------------
.../bindings/connector/usb-connector.yaml | 203 ++++++++++++++++++
.../devicetree/bindings/usb/fcs,fusb302.txt | 2 +-
.../devicetree/bindings/usb/generic.txt | 2 +-
.../devicetree/bindings/usb/mediatek,mtu3.txt | 2 +-
.../devicetree/bindings/usb/mediatek,musb.txt | 2 +-
.../bindings/usb/richtek,rt1711h.txt | 2 +-
.../devicetree/bindings/usb/ti,hd3ss3220.txt | 2 +-
.../devicetree/bindings/usb/typec-tcpci.txt | 2 +-
.../devicetree/bindings/usb/usb-conn-gpio.txt | 4 +-
11 files changed, 213 insertions(+), 145 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/connector/usb-connector.txt
create mode 100644 Documentation/devicetree/bindings/connector/usb-connector.yaml
diff --git a/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt b/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt
index 22256e295a7a1..3dd8961154abf 100644
--- a/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt
+++ b/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt
@@ -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
-------
diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt
deleted file mode 100644
index 88578ac1a8a76..0000000000000
--- a/Documentation/devicetree/bindings/connector/usb-connector.txt
+++ /dev/null
@@ -1,135 +0,0 @@
-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>;
- };
-};
diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
new file mode 100644
index 0000000000000..b386e2880405c
--- /dev/null
+++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
@@ -0,0 +1,203 @@
+# 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:
+ - [email protected]
+
+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 USB-A,
+ USB-B non-fullsize connectors.
+ $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. See gpio/gpio.txt.
+ 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 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 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.
+
+ required:
+ - port@0
+
+required:
+ - compatible
+
+examples:
+ # Micro-USB connector with HS lines routed via controller (MUIC).
+ - |+
+ muic-max77843@66 {
+ 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@33 {
+ 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@50 {
+ 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>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt
index ba2e32d500c02..60e4654297af7 100644
--- a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt
+++ b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt
@@ -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:
diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt
index e6790d2a4da9b..474e74c06522d 100644
--- a/Documentation/devicetree/bindings/usb/generic.txt
+++ b/Documentation/devicetree/bindings/usb/generic.txt
@@ -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:
diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
index e0ae6096f7ac8..a82ca438aec1f 100644
--- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
+++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
@@ -34,7 +34,7 @@ Optional properties:
dual-role mode.
it's considered valid for compatibility reasons, not allowed for
new bindings, and put into a usb-connector node.
- see connector/usb-connector.txt.
+ see connector/usb-connector.yaml.
- pinctrl-names : a pinctrl state named "default" is optional, and need be
defined if auto drd switch is enabled, that means the property dr_mode
is set as "otg", and meanwhile the property "mediatek,enable-manual-drd"
diff --git a/Documentation/devicetree/bindings/usb/mediatek,musb.txt b/Documentation/devicetree/bindings/usb/mediatek,musb.txt
index 2b8a87c90d9ea..5eedb02965622 100644
--- a/Documentation/devicetree/bindings/usb/mediatek,musb.txt
+++ b/Documentation/devicetree/bindings/usb/mediatek,musb.txt
@@ -23,7 +23,7 @@ Optional properties:
MTCMOS
Required child nodes:
- usb connector node as defined in bindings/connector/usb-connector.txt
+ usb connector node as defined in bindings/connector/usb-connector.yaml
Optional properties:
- id-gpios : input GPIO for USB ID pin.
- vbus-gpios : input GPIO for USB VBUS pin.
diff --git a/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt b/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt
index e3fc57e605ed6..6f8115db2ea9b 100644
--- a/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt
+++ b/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt
@@ -9,7 +9,7 @@ Required properties:
Required sub-node:
- connector: The "usb-c-connector" attached to the tcpci chip, the bindings
of connector node are specified in
- Documentation/devicetree/bindings/connector/usb-connector.txt
+ Documentation/devicetree/bindings/connector/usb-connector.yaml
Example :
rt1711h@4e {
diff --git a/Documentation/devicetree/bindings/usb/ti,hd3ss3220.txt b/Documentation/devicetree/bindings/usb/ti,hd3ss3220.txt
index 25780e945b154..2bd21b22ce95b 100644
--- a/Documentation/devicetree/bindings/usb/ti,hd3ss3220.txt
+++ b/Documentation/devicetree/bindings/usb/ti,hd3ss3220.txt
@@ -9,7 +9,7 @@ Required sub-node:
- connector: The "usb-c-connector" attached to the hd3ss3220 chip. The
bindings of the connector node are specified in:
- Documentation/devicetree/bindings/connector/usb-connector.txt
+ Documentation/devicetree/bindings/connector/usb-connector.yaml
Example:
hd3ss3220@47 {
diff --git a/Documentation/devicetree/bindings/usb/typec-tcpci.txt b/Documentation/devicetree/bindings/usb/typec-tcpci.txt
index 0dd1469e73180..2082522b1c326 100644
--- a/Documentation/devicetree/bindings/usb/typec-tcpci.txt
+++ b/Documentation/devicetree/bindings/usb/typec-tcpci.txt
@@ -13,7 +13,7 @@ Required properties:
Required sub-node:
- connector: The "usb-c-connector" attached to the tcpci chip, the bindings
of connector node are specified in
- Documentation/devicetree/bindings/connector/usb-connector.txt
+ Documentation/devicetree/bindings/connector/usb-connector.yaml
Example:
diff --git a/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt b/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt
index 3d05ae56cb0dc..ec80641208a53 100644
--- a/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt
+++ b/Documentation/devicetree/bindings/usb/usb-conn-gpio.txt
@@ -8,11 +8,11 @@ Required properties:
- compatible : should include "gpio-usb-b-connector" and "usb-b-connector".
- id-gpios, vbus-gpios : input gpios, either one of them must be present,
and both can be present as well.
- see connector/usb-connector.txt
+ see connector/usb-connector.yaml
Optional properties:
- vbus-supply : can be present if needed when supports dual role mode.
- see connector/usb-connector.txt
+ see connector/usb-connector.yaml
- Sub-nodes:
- port : can be present.
--
2.25.0.265.gbab2e86ba0-goog
Quoting Prashant Malani (2020-03-04 19:01:30)
> diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> new file mode 100644
> index 0000000000000..b386e2880405c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> @@ -0,0 +1,203 @@
> +# 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:
> + - [email protected]
> +
> +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 USB-A,
> + USB-B non-fullsize connectors.
Maybe "should be specified in case of non-fullsize 'usb-a-connector' or
'usb-b-connector' compatible connectors"?
> + $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. See gpio/gpio.txt.
Can this be written as bindings/gpio/gpio.txt?
> + 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 regulator/fixed-regulator.yaml
And bindings/regulator/fixed-regulator.yaml? The idea is to
disambiguate from kernel Documentation/ directory.
> +
> + # The following are optional properties for "usb-c-connector".
Is there a way to constrain the binding so that this can't be put in a
connector that doesn't have the usb-c-connector compatible string?
> + 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
Is there a way to maintain a description for each possible string
property? Then we could move the last sentence in the description above
to be attached to '- dual' here.
> +
> + # 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 assigned OF graph port number as described below.
has an assigned?
> + 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.
Likewise, is it possible to constrain this to only usb-c-connector
compatible string based bindings? And if so, does it become required for
that compatible string?
> +
> + required:
> + - port@0
> +
> +required:
> + - compatible
> +
> +examples:
> + # Micro-USB connector with HS lines routed via controller (MUIC).
> + - |+
> + muic-max77843@66 {
Add a reg = <0x66>; here? Or drop the unit address above.
> + 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@33 {
Same unit address comment.
> + 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>;
> + };
Tabs should be replaced with spaces.
> + };
> + };
> + };
> + };
> +
> + # 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@50 {
Same unit address comment.
> + 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>;
> + };
> + };
On Wed, Mar 4, 2020 at 9:01 PM Prashant Malani <[email protected]> wrote:
>
> 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: Prashant Malani <[email protected]>
> ---
>
> Changes in v2:
> - Added type references for some properties.
> - Removed pinctrl properties.
> - Updated power-role, try-power-role and data-role properties to be in
> valid schema format.
> - Added OF graph data bus binding property according to reviewer
> suggestions.
>
> .../connector/samsung,usb-connector-11pin.txt | 2 +-
> .../bindings/connector/usb-connector.txt | 135 ------------
> .../bindings/connector/usb-connector.yaml | 203 ++++++++++++++++++
> .../devicetree/bindings/usb/fcs,fusb302.txt | 2 +-
> .../devicetree/bindings/usb/generic.txt | 2 +-
> .../devicetree/bindings/usb/mediatek,mtu3.txt | 2 +-
> .../devicetree/bindings/usb/mediatek,musb.txt | 2 +-
> .../bindings/usb/richtek,rt1711h.txt | 2 +-
> .../devicetree/bindings/usb/ti,hd3ss3220.txt | 2 +-
> .../devicetree/bindings/usb/typec-tcpci.txt | 2 +-
> .../devicetree/bindings/usb/usb-conn-gpio.txt | 4 +-
> 11 files changed, 213 insertions(+), 145 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/connector/usb-connector.txt
> create mode 100644 Documentation/devicetree/bindings/connector/usb-connector.yaml
> diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> new file mode 100644
> index 0000000000000..b386e2880405c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> @@ -0,0 +1,203 @@
> +# 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:
> + - [email protected]
Person please. You can put me if no one else.
> +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 USB-A,
> + USB-B non-fullsize connectors.
> + $ref: /schemas/types.yaml#definitions/string
Needs to be under an 'allOf' or the enum is ignored.
Rob
On Thu, Mar 5, 2020 at 3:20 PM Stephen Boyd <[email protected]> wrote:
>
> Quoting Prashant Malani (2020-03-04 19:01:30)
> > diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > new file mode 100644
> > index 0000000000000..b386e2880405c
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > @@ -0,0 +1,203 @@
> > +# 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:
> > + - [email protected]
> > +
> > +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 USB-A,
> > + USB-B non-fullsize connectors.
>
> Maybe "should be specified in case of non-fullsize 'usb-a-connector' or
> 'usb-b-connector' compatible connectors"?
>
> > + $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. See gpio/gpio.txt.
>
> Can this be written as bindings/gpio/gpio.txt?
Or just drop the reference so we don't have to fix it later.
> > + 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 regulator/fixed-regulator.yaml
>
> And bindings/regulator/fixed-regulator.yaml? The idea is to
> disambiguate from kernel Documentation/ directory.
>
> > +
> > + # The following are optional properties for "usb-c-connector".
>
> Is there a way to constrain the binding so that this can't be put in a
> connector that doesn't have the usb-c-connector compatible string?
Yes, with if/then and setting excluded properties to 'false'.
Personally, I don't think it is worth the messiness. I'm not too
worried if folks put in properties that are going to be ignored.
Rob
> > + 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
>
> Is there a way to maintain a description for each possible string
> property? Then we could move the last sentence in the description above
> to be attached to '- dual' here.
>
> > +
> > + # 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 assigned OF graph port number as described below.
>
> has an assigned?
>
> > + 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.
>
> Likewise, is it possible to constrain this to only usb-c-connector
> compatible string based bindings? And if so, does it become required for
> that compatible string?
Not required as alternate modes are not required. (BTW, it should
probably be clarified this is supposed to be the alternate mode
connection of which SBU is part of).
Rob
Hi Stephen,
Thanks for reviewing the patch. Kindly see my responses inline.
Best regards,
-Prashant
On Thu, Mar 05, 2020 at 01:20:04PM -0800, Stephen Boyd wrote:
> Quoting Prashant Malani (2020-03-04 19:01:30)
> > diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > new file mode 100644
> > index 0000000000000..b386e2880405c
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > @@ -0,0 +1,203 @@
> > +# 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:
> > + - [email protected]
> > +
> > +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 USB-A,
> > + USB-B non-fullsize connectors.
>
> Maybe "should be specified in case of non-fullsize 'usb-a-connector' or
> 'usb-b-connector' compatible connectors"?
>
Done.
> > + $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. See gpio/gpio.txt.
>
> Can this be written as bindings/gpio/gpio.txt?
Dropping it based on Rob's later comment.
>
> > + 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 regulator/fixed-regulator.yaml
>
> And bindings/regulator/fixed-regulator.yaml? The idea is to
> disambiguate from kernel Documentation/ directory.
Done.
>
> > +
> > + # The following are optional properties for "usb-c-connector".
>
> Is there a way to constrain the binding so that this can't be put in a
> connector that doesn't have the usb-c-connector compatible string?
>
> > + 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
>
> Is there a way to maintain a description for each possible string
> property? Then we could move the last sentence in the description above
> to be attached to '- dual' here.
>
I'm not sure of a way to do this, so leaving this as is for now.
> > +
> > + # 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 assigned OF graph port number as described below.
>
> has an assigned?
Done.
>
> > + 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.
>
> Likewise, is it possible to constrain this to only usb-c-connector
> compatible string based bindings? And if so, does it become required for
> that compatible string?
>
> > +
> > + required:
> > + - port@0
> > +
> > +required:
> > + - compatible
> > +
> > +examples:
> > + # Micro-USB connector with HS lines routed via controller (MUIC).
> > + - |+
> > + muic-max77843@66 {
>
> Add a reg = <0x66>; here? Or drop the unit address above.
Dropped the unit address.
>
> > + 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@33 {
>
> Same unit address comment.
Dropped the unit address.
>
> > + 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>;
> > + };
>
> Tabs should be replaced with spaces.
Fixed the spacing here.
>
> > + };
> > + };
> > + };
> > + };
> > +
> > + # 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@50 {
>
> Same unit address comment.
Dropped the unit address.
>
> > + 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>;
> > + };
> > + };
Thanks Rob for reviewing this patch. Kindly see my responses inline.
Best regards,
-Prashant
On Thu, Mar 05, 2020 at 03:40:18PM -0600, Rob Herring wrote:
> On Thu, Mar 5, 2020 at 3:20 PM Stephen Boyd <[email protected]> wrote:
> >
> > Quoting Prashant Malani (2020-03-04 19:01:30)
> > > diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > > new file mode 100644
> > > index 0000000000000..b386e2880405c
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > > @@ -0,0 +1,203 @@
> > > +# 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:
> > > + - [email protected]
> > > +
> > > +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 USB-A,
> > > + USB-B non-fullsize connectors.
> >
> > Maybe "should be specified in case of non-fullsize 'usb-a-connector' or
> > 'usb-b-connector' compatible connectors"?
> >
> > > + $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. See gpio/gpio.txt.
> >
> > Can this be written as bindings/gpio/gpio.txt?
>
> Or just drop the reference so we don't have to fix it later.
Dropped the reference.
>
> > > + 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 regulator/fixed-regulator.yaml
> >
> > And bindings/regulator/fixed-regulator.yaml? The idea is to
> > disambiguate from kernel Documentation/ directory.
> >
> > > +
> > > + # The following are optional properties for "usb-c-connector".
> >
> > Is there a way to constrain the binding so that this can't be put in a
> > connector that doesn't have the usb-c-connector compatible string?
>
> Yes, with if/then and setting excluded properties to 'false'.
> Personally, I don't think it is worth the messiness. I'm not too
> worried if folks put in properties that are going to be ignored.
Leaving this as is for now, based on the above comment.
>
> Rob
>
> > > + 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
> >
> > Is there a way to maintain a description for each possible string
> > property? Then we could move the last sentence in the description above
> > to be attached to '- dual' here.
> >
> > > +
> > > + # 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 assigned OF graph port number as described below.
> >
> > has an assigned?
> >
> > > + 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.
> >
> > Likewise, is it possible to constrain this to only usb-c-connector
> > compatible string based bindings? And if so, does it become required for
> > that compatible string?
>
> Not required as alternate modes are not required. (BTW, it should
> probably be clarified this is supposed to be the alternate mode
> connection of which SBU is part of).
I've changed the description text for port@2 to:
"Sideband Use (SBU), present in USB-C. This describes the alternate mode connection of which SBU is a part. "
>
> Rob
Hi Rob, Kindly see inline. Thanks as always.
On Thu, Mar 05, 2020 at 03:29:00PM -0600, Rob Herring wrote:
> On Wed, Mar 4, 2020 at 9:01 PM Prashant Malani <[email protected]> wrote:
> >
> > 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: Prashant Malani <[email protected]>
> > ---
> >
> > Changes in v2:
> > - Added type references for some properties.
> > - Removed pinctrl properties.
> > - Updated power-role, try-power-role and data-role properties to be in
> > valid schema format.
> > - Added OF graph data bus binding property according to reviewer
> > suggestions.
> >
> > .../connector/samsung,usb-connector-11pin.txt | 2 +-
> > .../bindings/connector/usb-connector.txt | 135 ------------
> > .../bindings/connector/usb-connector.yaml | 203 ++++++++++++++++++
> > .../devicetree/bindings/usb/fcs,fusb302.txt | 2 +-
> > .../devicetree/bindings/usb/generic.txt | 2 +-
> > .../devicetree/bindings/usb/mediatek,mtu3.txt | 2 +-
> > .../devicetree/bindings/usb/mediatek,musb.txt | 2 +-
> > .../bindings/usb/richtek,rt1711h.txt | 2 +-
> > .../devicetree/bindings/usb/ti,hd3ss3220.txt | 2 +-
> > .../devicetree/bindings/usb/typec-tcpci.txt | 2 +-
> > .../devicetree/bindings/usb/usb-conn-gpio.txt | 4 +-
> > 11 files changed, 213 insertions(+), 145 deletions(-)
> > delete mode 100644 Documentation/devicetree/bindings/connector/usb-connector.txt
> > create mode 100644 Documentation/devicetree/bindings/connector/usb-connector.yaml
>
>
> > diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > new file mode 100644
> > index 0000000000000..b386e2880405c
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> > @@ -0,0 +1,203 @@
> > +# 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:
> > + - [email protected]
>
> Person please. You can put me if no one else.
>
I will list you as the maintainer.
> > +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 USB-A,
> > + USB-B non-fullsize connectors.
> > + $ref: /schemas/types.yaml#definitions/string
>
> Needs to be under an 'allOf' or the enum is ignored.
Done.
>
> Rob