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