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: > + - linux-usb@xxxxxxxxxxxxxxx > + > +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>; > + }; > + };
