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

   1 # SPDX-License-Identifier: GPL-2.0-only
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/connector/usb-connector.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: USB Connector
   8
   9 maintainers:
  10   - Rob Herring <robh@kernel.org>
  11
  12 description:
  13   A USB connector node represents a physical USB connector. It should be a child
  14   of a USB interface controller or a separate node when it is attached to both
  15   MUX and USB interface controller.
  16
  17 properties:
  18   compatible:
  19     oneOf:
  20       - enum:
  21           - usb-a-connector
  22           - usb-b-connector
  23           - usb-c-connector
  24
  25       - items:
  26           - const: gpio-usb-b-connector
  27           - const: usb-b-connector
  28
  29       - items:
  30           - const: samsung,usb-connector-11pin
  31           - const: usb-b-connector
  32
  33   label:
  34     description: Symbolic name for the connector.
  35
  36   type:
  37     description: Size of the connector, should be specified in case of
  38       non-fullsize 'usb-a-connector' or 'usb-b-connector' compatible
  39       connectors.
  40     $ref: /schemas/types.yaml#/definitions/string
  41
  42     enum:
  43       - mini
  44       - micro
  45
  46   self-powered:
  47     description: Set this property if the USB device has its own power source.
  48     type: boolean
  49
  50   # The following are optional properties for "usb-b-connector".
  51   id-gpios:
  52     description: An input gpio for USB ID pin.
  53     maxItems: 1
  54
  55   vbus-gpios:
  56     description: An input gpio for USB VBus pin, used to detect presence of
  57       VBUS 5V.
  58     maxItems: 1
  59
  60   vbus-supply:
  61     description: A phandle to the regulator for USB VBUS if needed when host
  62       mode or dual role mode is supported.
  63       Particularly, if use an output GPIO to control a VBUS regulator, should
  64       model it as a regulator. See bindings/regulator/fixed-regulator.yaml
  65
  66   # The following are optional properties for "usb-c-connector".
  67   power-role:
  68     description: Determines the power role that the Type C connector will
  69       support. "dual" refers to Dual Role Port (DRP).
  70     $ref: /schemas/types.yaml#/definitions/string
  71
  72     enum:
  73       - source
  74       - sink
  75       - dual
  76
  77   try-power-role:
  78     description: Preferred power role.
  79     $ref: /schemas/types.yaml#/definitions/string
  80
  81     enum:
  82       - source
  83       - sink
  84       - dual
  85
  86   data-role:
  87     description: Data role if Type C connector supports USB data. "dual" refers
  88       Dual Role Device (DRD).
  89     $ref: /schemas/types.yaml#/definitions/string
  90
  91     enum:
  92       - host
  93       - device
  94       - dual
  95
  96   typec-power-opmode:
  97     description: Determines the power operation mode that the Type C connector
  98       will support and will advertise through CC pins when it has no power
  99       delivery support.
 100       - "default" corresponds to default USB voltage and current defined by the
 101         USB 2.0 and USB 3.2 specifications, 5V 500mA for USB 2.0 ports and
 102         5V 900mA or 1500mA for USB 3.2 ports in single-lane or dual-lane
 103         operation respectively.
 104       - "1.5A" and "3.0A", 5V 1.5A and 5V 3.0A respectively, as defined in USB
 105         Type-C Cable and Connector specification, when Power Delivery is not
 106         supported.
 107     allOf:
 108       - $ref: /schemas/types.yaml#/definitions/string
 109     enum:
 110       - default
 111       - 1.5A
 112       - 3.0A
 113
 114   # The following are optional properties for "usb-c-connector" with power
 115   # delivery support.
 116   source-pdos:
 117     description: An array of u32 with each entry providing supported power
 118       source data object(PDO), the detailed bit definitions of PDO can be found
 119       in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2
 120       Source_Capabilities Message, the order of each entry(PDO) should follow
 121       the PD spec chapter 6.4.1. Required for power source and power dual role.
 122       User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO()
 123       defined in dt-bindings/usb/pd.h.
 124     minItems: 1
 125     maxItems: 7
 126     $ref: /schemas/types.yaml#/definitions/uint32-array
 127
 128   sink-pdos:
 129     description: An array of u32 with each entry providing supported power sink
 130       data object(PDO), the detailed bit definitions of PDO can be found in
 131       "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3
 132       Sink Capabilities Message, the order of each entry(PDO) should follow the
 133       PD spec chapter 6.4.1. Required for power sink and power dual role. User
 134       can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined
 135       in dt-bindings/usb/pd.h.
 136     minItems: 1
 137     maxItems: 7
 138     $ref: /schemas/types.yaml#/definitions/uint32-array
 139
 140   op-sink-microwatt:
 141     description: Sink required operating power in microwatt, if source can't
 142       offer the power, Capability Mismatch is set. Required for power sink and
 143       power dual role.
 144
 145   ports:
 146     description: OF graph bindings (specified in bindings/graph.txt) that model
 147       any data bus to the connector unless the bus is between parent node and
 148       the connector. Since a single connector can have multiple data buses every
 149       bus has an assigned OF graph port number as described below.
 150     type: object
 151     properties:
 152       port@0:
 153         type: object
 154         description: High Speed (HS), present in all connectors.
 155
 156       port@1:
 157         type: object
 158         description: Super Speed (SS), present in SS capable connectors.
 159
 160       port@2:
 161         type: object
 162         description: Sideband Use (SBU), present in USB-C. This describes the
 163           alternate mode connection of which SBU is a part.
 164
 165     required:
 166       - port@0
 167
 168   new-source-frs-typec-current:
 169     description: Initial current capability of the new source when vSafe5V
 170       is applied during PD3.0 Fast Role Swap. "Table 6-14 Fixed Supply PDO - Sink"
 171       of "USB Power Delivery Specification Revision 3.0, Version 1.2" provides the
 172       different power levels and "6.4.1.3.1.6 Fast Role Swap USB Type-C Current"
 173       provides a detailed description of the field. The sink PDO from current source
 174       reflects the current source's(i.e. transmitter of the FRS signal) power
 175       requirement during fr swap. The current sink (i.e. receiver of the FRS signal),
 176       a.k.a new source, should check if it will be able to satisfy the current source's,
 177       new sink's, requirement during frswap before enabling the frs signal reception.
 178       This property refers to maximum current capability that the current sink can
 179       satisfy. During FRS, VBUS voltage is at 5V, as the partners are in implicit
 180       contract, hence, the power level is only a function of the current capability.
 181       "1" refers to default USB power level as described by "Table 6-14 Fixed Supply PDO - Sink".
 182       "2" refers to 1.5A@5V.
 183       "3" refers to 3.0A@5V.
 184     $ref: /schemas/types.yaml#/definitions/uint32
 185     enum: [1, 2, 3]
 186
 187 required:
 188   - compatible
 189
 190 allOf:
 191   - if:
 192       properties:
 193         compatible:
 194           contains:
 195             const: gpio-usb-b-connector
 196     then:
 197       anyOf:
 198         - required:
 199             - vbus-gpios
 200         - required:
 201             - id-gpios
 202
 203   - if:
 204       properties:
 205         compatible:
 206           contains:
 207             const: samsung,usb-connector-11pin
 208     then:
 209       properties:
 210         type:
 211           const: micro
 212
 213 anyOf:
 214   - not:
 215       required:
 216         - typec-power-opmode
 217         - new-source-frs-typec-current
 218
 219 additionalProperties: true
 220
 221 examples:
 222   # Micro-USB connector with HS lines routed via controller (MUIC).
 223   - |
 224     muic-max77843 {
 225       usb_con1: connector {
 226         compatible = "usb-b-connector";
 227         label = "micro-USB";
 228         type = "micro";
 229       };
 230     };
 231
 232   # USB-C connector attached to CC controller (s2mm005), HS lines routed
 233   # to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.
 234   # DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.
 235   - |
 236     ccic: s2mm005 {
 237       usb_con2: connector {
 238         compatible = "usb-c-connector";
 239         label = "USB-C";
 240
 241         ports {
 242           #address-cells = <1>;
 243           #size-cells = <0>;
 244
 245           port@0 {
 246             reg = <0>;
 247             usb_con_hs: endpoint {
 248               remote-endpoint = <&max77865_usbc_hs>;
 249             };
 250           };
 251           port@1 {
 252             reg = <1>;
 253             usb_con_ss: endpoint {
 254               remote-endpoint = <&usbdrd_phy_ss>;
 255             };
 256           };
 257           port@2 {
 258             reg = <2>;
 259             usb_con_sbu: endpoint {
 260               remote-endpoint = <&dp_aux>;
 261             };
 262           };
 263         };
 264       };
 265     };
 266
 267   # USB-C connector attached to a typec port controller(ptn5110), which has
 268   # power delivery support and enables drp.
 269   - |
 270     #include <dt-bindings/usb/pd.h>
 271     typec: ptn5110 {
 272       usb_con3: connector {
 273         compatible = "usb-c-connector";
 274         label = "USB-C";
 275         power-role = "dual";
 276         try-power-role = "sink";
 277         source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;
 278         sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)
 279                      PDO_VAR(5000, 12000, 2000)>;
 280         op-sink-microwatt = <10000000>;
 281       };
 282     };
 283
 284   # USB-C connector attached to SoC and USB3 typec port controller(hd3ss3220)
 285   # with SS 2:1 MUX. HS lines routed to SoC, SS lines routed to the MUX and
 286   # the output of MUX is connected to the SoC.
 287   - |
 288     connector {
 289         compatible = "usb-c-connector";
 290         label = "USB-C";
 291         data-role = "dual";
 292
 293         ports {
 294                 #address-cells = <1>;
 295                 #size-cells = <0>;
 296                 port@0 {
 297                         reg = <0>;
 298                         hs_ep: endpoint {
 299                                 remote-endpoint = <&usb3_hs_ep>;
 300                         };
 301                 };
 302                 port@1 {
 303                         reg = <1>;
 304                         ss_ep: endpoint {
 305                                 remote-endpoint = <&hd3ss3220_in_ep>;
 306                         };
 307                 };
 308         };
 309     };
 310
 311   # USB connector with GPIO control lines
 312   - |
 313     #include <dt-bindings/gpio/gpio.h>
 314
 315     usb {
 316       connector {
 317         compatible = "gpio-usb-b-connector", "usb-b-connector";
 318         type = "micro";
 319         id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>;
 320         vbus-supply = <&usb_p0_vbus>;
 321       };
 322     };
 323
 324   # Micro-USB connector with HS lines routed via controller (MUIC) and MHL
 325   # lines connected to HDMI-MHL bridge (sii8620) on Samsung Exynos5433-based
 326   # mobile phone
 327   - |
 328     muic-max77843 {
 329       usb_con4: connector {
 330         compatible = "samsung,usb-connector-11pin", "usb-b-connector";
 331         label = "micro-USB";
 332         type = "micro";
 333
 334         ports {
 335           #address-cells = <1>;
 336           #size-cells = <0>;
 337
 338           port@0 {
 339             reg = <0>;
 340             muic_to_usb: endpoint {
 341               remote-endpoint = <&usb_to_muic>;
 342             };
 343           };
 344           port@3 {
 345             reg = <3>;
 346             usb_con_mhl: endpoint {
 347               remote-endpoint = <&sii8620_mhl>;
 348             };
 349           };
 350         };
 351       };
 352     };