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   sink-vdos:
 141     description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
 142       providing additional information corresponding to the product, the detailed bit
 143       definitions and the order of each VDO can be found in
 144       "USB Power Delivery Specification Revision 3.0, Version 2.0 + ECNs 2020-12-10"
 145       chapter 6.4.4.3.1 Discover Identity. User can specify the VDO array via
 146       VDO_IDH/_CERT/_PRODUCT/_UFP/_DFP/_PCABLE/_ACABLE(1/2)/_VPD() defined in
 147       dt-bindings/usb/pd.h.
 148     minItems: 3
 149     maxItems: 6
 150     $ref: /schemas/types.yaml#/definitions/uint32-array
 151
 152   sink-vdos-v1:
 153     description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
 154       providing additional information corresponding to the product, the detailed bit
 155       definitions and the order of each VDO can be found in
 156       "USB Power Delivery Specification Revision 2.0, Version 1.3" chapter 6.4.4.3.1 Discover
 157       Identity. User can specify the VDO array via VDO_IDH/_CERT/_PRODUCT/_CABLE/_AMA defined in
 158       dt-bindings/usb/pd.h.
 159     minItems: 3
 160     maxItems: 6
 161     $ref: /schemas/types.yaml#/definitions/uint32-array
 162
 163   op-sink-microwatt:
 164     description: Sink required operating power in microwatt, if source can't
 165       offer the power, Capability Mismatch is set. Required for power sink and
 166       power dual role.
 167
 168   ports:
 169     $ref: /schemas/graph.yaml#/properties/ports
 170     description: OF graph bindings modeling any data bus to the connector
 171       unless the bus is between parent node and the connector. Since a single
 172       connector can have multiple data buses every bus has an assigned OF graph
 173       port number as described below.
 174
 175     properties:
 176       port@0:
 177         $ref: /schemas/graph.yaml#/properties/port
 178         description: High Speed (HS), present in all connectors.
 179
 180       port@1:
 181         $ref: /schemas/graph.yaml#/properties/port
 182         description: Super Speed (SS), present in SS capable connectors.
 183
 184       port@2:
 185         $ref: /schemas/graph.yaml#/properties/port
 186         description: Sideband Use (SBU), present in USB-C. This describes the
 187           alternate mode connection of which SBU is a part.
 188
 189     required:
 190       - port@0
 191
 192   new-source-frs-typec-current:
 193     description: Initial current capability of the new source when vSafe5V
 194       is applied during PD3.0 Fast Role Swap. "Table 6-14 Fixed Supply PDO - Sink"
 195       of "USB Power Delivery Specification Revision 3.0, Version 1.2" provides the
 196       different power levels and "6.4.1.3.1.6 Fast Role Swap USB Type-C Current"
 197       provides a detailed description of the field. The sink PDO from current source
 198       reflects the current source's(i.e. transmitter of the FRS signal) power
 199       requirement during fr swap. The current sink (i.e. receiver of the FRS signal),
 200       a.k.a new source, should check if it will be able to satisfy the current source's,
 201       new sink's, requirement during frswap before enabling the frs signal reception.
 202       This property refers to maximum current capability that the current sink can
 203       satisfy. During FRS, VBUS voltage is at 5V, as the partners are in implicit
 204       contract, hence, the power level is only a function of the current capability.
 205       "1" refers to default USB power level as described by "Table 6-14 Fixed Supply PDO - Sink".
 206       "2" refers to 1.5A@5V.
 207       "3" refers to 3.0A@5V.
 208     $ref: /schemas/types.yaml#/definitions/uint32
 209     enum: [1, 2, 3]
 210
 211   slow-charger-loop:
 212     description: Allows PMIC charger loops which are slow(i.e. cannot meet the 15ms deadline) to
 213       still comply to pSnkStby i.e Maximum power that can be consumed by sink while in Sink Standby
 214       state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification
 215       Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W -
 216       5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during
 217       SNK_DISCOVERY) and the actual currrent limit after reception of PS_Ready for PD link or during
 218       SNK_READY for non-pd link.
 219     type: boolean
 220
 221 dependencies:
 222   sink-vdos-v1: [ 'sink-vdos' ]
 223   sink-vdos: [ 'sink-vdos-v1' ]
 224
 225 required:
 226   - compatible
 227
 228 allOf:
 229   - if:
 230       properties:
 231         compatible:
 232           contains:
 233             const: gpio-usb-b-connector
 234     then:
 235       anyOf:
 236         - required:
 237             - vbus-gpios
 238         - required:
 239             - id-gpios
 240
 241   - if:
 242       properties:
 243         compatible:
 244           contains:
 245             const: samsung,usb-connector-11pin
 246     then:
 247       properties:
 248         type:
 249           const: micro
 250
 251 anyOf:
 252   - not:
 253       required:
 254         - typec-power-opmode
 255         - new-source-frs-typec-current
 256
 257 additionalProperties: true
 258
 259 examples:
 260   # Micro-USB connector with HS lines routed via controller (MUIC).
 261   - |
 262     muic-max77843 {
 263       usb_con1: connector {
 264         compatible = "usb-b-connector";
 265         label = "micro-USB";
 266         type = "micro";
 267       };
 268     };
 269
 270   # USB-C connector attached to CC controller (s2mm005), HS lines routed
 271   # to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.
 272   # DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.
 273   - |
 274     ccic: s2mm005 {
 275       usb_con2: connector {
 276         compatible = "usb-c-connector";
 277         label = "USB-C";
 278
 279         ports {
 280           #address-cells = <1>;
 281           #size-cells = <0>;
 282
 283           port@0 {
 284             reg = <0>;
 285             usb_con_hs: endpoint {
 286               remote-endpoint = <&max77865_usbc_hs>;
 287             };
 288           };
 289           port@1 {
 290             reg = <1>;
 291             usb_con_ss: endpoint {
 292               remote-endpoint = <&usbdrd_phy_ss>;
 293             };
 294           };
 295           port@2 {
 296             reg = <2>;
 297             usb_con_sbu: endpoint {
 298               remote-endpoint = <&dp_aux>;
 299             };
 300           };
 301         };
 302       };
 303     };
 304
 305   # USB-C connector attached to a typec port controller(ptn5110), which has
 306   # power delivery support and enables drp.
 307   - |
 308     #include <dt-bindings/usb/pd.h>
 309     typec: ptn5110 {
 310       usb_con3: connector {
 311         compatible = "usb-c-connector";
 312         label = "USB-C";
 313         power-role = "dual";
 314         try-power-role = "sink";
 315         source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;
 316         sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)
 317                      PDO_VAR(5000, 12000, 2000)>;
 318         op-sink-microwatt = <10000000>;
 319       };
 320     };
 321
 322   # USB-C connector attached to SoC and USB3 typec port controller(hd3ss3220)
 323   # with SS 2:1 MUX. HS lines routed to SoC, SS lines routed to the MUX and
 324   # the output of MUX is connected to the SoC.
 325   - |
 326     connector {
 327         compatible = "usb-c-connector";
 328         label = "USB-C";
 329         data-role = "dual";
 330
 331         ports {
 332                 #address-cells = <1>;
 333                 #size-cells = <0>;
 334                 port@0 {
 335                         reg = <0>;
 336                         hs_ep: endpoint {
 337                                 remote-endpoint = <&usb3_hs_ep>;
 338                         };
 339                 };
 340                 port@1 {
 341                         reg = <1>;
 342                         ss_ep: endpoint {
 343                                 remote-endpoint = <&hd3ss3220_in_ep>;
 344                         };
 345                 };
 346         };
 347     };
 348
 349   # USB connector with GPIO control lines
 350   - |
 351     #include <dt-bindings/gpio/gpio.h>
 352
 353     usb {
 354       connector {
 355         compatible = "gpio-usb-b-connector", "usb-b-connector";
 356         type = "micro";
 357         id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>;
 358         vbus-supply = <&usb_p0_vbus>;
 359       };
 360     };
 361
 362   # Micro-USB connector with HS lines routed via controller (MUIC) and MHL
 363   # lines connected to HDMI-MHL bridge (sii8620) on Samsung Exynos5433-based
 364   # mobile phone
 365   - |
 366     muic-max77843 {
 367       usb_con4: connector {
 368         compatible = "samsung,usb-connector-11pin", "usb-b-connector";
 369         label = "micro-USB";
 370         type = "micro";
 371
 372         ports {
 373           #address-cells = <1>;
 374           #size-cells = <0>;
 375
 376           port@0 {
 377             reg = <0>;
 378             muic_to_usb: endpoint {
 379               remote-endpoint = <&usb_to_muic>;
 380             };
 381           };
 382           port@3 {
 383             reg = <3>;
 384             usb_con_mhl: endpoint {
 385               remote-endpoint = <&sii8620_mhl>;
 386             };
 387           };
 388         };
 389       };
 390     };