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   reg:
  34     maxItems: 1
  35
  36   label:
  37     description: Symbolic name for the connector.
  38
  39   type:
  40     description: Size of the connector, should be specified in case of
  41       non-fullsize 'usb-a-connector' or 'usb-b-connector' compatible
  42       connectors.
  43     $ref: /schemas/types.yaml#/definitions/string
  44
  45     enum:
  46       - mini
  47       - micro
  48
  49   self-powered:
  50     description: Set this property if the USB device has its own power source.
  51     type: boolean
  52
  53   # The following are optional properties for "usb-b-connector".
  54   id-gpios:
  55     description: An input gpio for USB ID pin.
  56     maxItems: 1
  57
  58   vbus-gpios:
  59     description: An input gpio for USB VBus pin, used to detect presence of
  60       VBUS 5V.
  61     maxItems: 1
  62
  63   vbus-supply:
  64     description: A phandle to the regulator for USB VBUS if needed when host
  65       mode or dual role mode is supported.
  66       Particularly, if use an output GPIO to control a VBUS regulator, should
  67       model it as a regulator. See bindings/regulator/fixed-regulator.yaml
  68
  69   # The following are optional properties for "usb-c-connector".
  70   power-role:
  71     description: Determines the power role that the Type C connector will
  72       support. "dual" refers to Dual Role Port (DRP).
  73     $ref: /schemas/types.yaml#/definitions/string
  74
  75     enum:
  76       - source
  77       - sink
  78       - dual
  79
  80   try-power-role:
  81     description: Preferred power role.
  82     $ref: /schemas/types.yaml#/definitions/string
  83
  84     enum:
  85       - source
  86       - sink
  87       - dual
  88
  89   data-role:
  90     description: Data role if Type C connector supports USB data. "dual" refers
  91       Dual Role Device (DRD).
  92     $ref: /schemas/types.yaml#/definitions/string
  93
  94     enum:
  95       - host
  96       - device
  97       - dual
  98
  99   typec-power-opmode:
 100     description: Determines the power operation mode that the Type C connector
 101       will support and will advertise through CC pins when it has no power
 102       delivery support.
 103       - "default" corresponds to default USB voltage and current defined by the
 104         USB 2.0 and USB 3.2 specifications, 5V 500mA for USB 2.0 ports and
 105         5V 900mA or 1500mA for USB 3.2 ports in single-lane or dual-lane
 106         operation respectively.
 107       - "1.5A" and "3.0A", 5V 1.5A and 5V 3.0A respectively, as defined in USB
 108         Type-C Cable and Connector specification, when Power Delivery is not
 109         supported.
 110     $ref: /schemas/types.yaml#/definitions/string
 111     enum:
 112       - default
 113       - 1.5A
 114       - 3.0A
 115
 116   pd-disable:
 117     description: Set this property if the Type-C connector has no power delivery support.
 118     type: boolean
 119
 120   # The following are optional properties for "usb-c-connector" with power
 121   # delivery support.
 122   source-pdos:
 123     description: An array of u32 with each entry providing supported power
 124       source data object(PDO), the detailed bit definitions of PDO can be found
 125       in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2
 126       Source_Capabilities Message, the order of each entry(PDO) should follow
 127       the PD spec chapter 6.4.1. Required for power source and power dual role.
 128       User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO()
 129       defined in dt-bindings/usb/pd.h.
 130     minItems: 1
 131     maxItems: 7
 132     $ref: /schemas/types.yaml#/definitions/uint32-array
 133
 134   sink-pdos:
 135     description: An array of u32 with each entry providing supported power sink
 136       data object(PDO), the detailed bit definitions of PDO can be found in
 137       "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3
 138       Sink Capabilities Message, the order of each entry(PDO) should follow the
 139       PD spec chapter 6.4.1. Required for power sink and power dual role. User
 140       can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined
 141       in dt-bindings/usb/pd.h.
 142     minItems: 1
 143     maxItems: 7
 144     $ref: /schemas/types.yaml#/definitions/uint32-array
 145
 146   sink-vdos:
 147     description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
 148       providing additional information corresponding to the product, the detailed bit
 149       definitions and the order of each VDO can be found in
 150       "USB Power Delivery Specification Revision 3.0, Version 2.0 + ECNs 2020-12-10"
 151       chapter 6.4.4.3.1 Discover Identity. User can specify the VDO array via
 152       VDO_IDH/_CERT/_PRODUCT/_UFP/_DFP/_PCABLE/_ACABLE(1/2)/_VPD() defined in
 153       dt-bindings/usb/pd.h.
 154     minItems: 3
 155     maxItems: 6
 156     $ref: /schemas/types.yaml#/definitions/uint32-array
 157
 158   sink-vdos-v1:
 159     description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
 160       providing additional information corresponding to the product, the detailed bit
 161       definitions and the order of each VDO can be found in
 162       "USB Power Delivery Specification Revision 2.0, Version 1.3" chapter 6.4.4.3.1 Discover
 163       Identity. User can specify the VDO array via VDO_IDH/_CERT/_PRODUCT/_CABLE/_AMA defined in
 164       dt-bindings/usb/pd.h.
 165     minItems: 3
 166     maxItems: 6
 167     $ref: /schemas/types.yaml#/definitions/uint32-array
 168
 169   op-sink-microwatt:
 170     description: Sink required operating power in microwatt, if source can't
 171       offer the power, Capability Mismatch is set. Required for power sink and
 172       power dual role.
 173
 174   port:
 175     $ref: /schemas/graph.yaml#/properties/port
 176     description: OF graph bindings modeling a data bus to the connector, e.g.
 177       there is a single High Speed (HS) port present in this connector. If there
 178       is more than one bus (several port, with 'reg' property), they can be grouped
 179       under 'ports'.
 180
 181   ports:
 182     $ref: /schemas/graph.yaml#/properties/ports
 183     description: OF graph bindings modeling any data bus to the connector
 184       unless the bus is between parent node and the connector. Since a single
 185       connector can have multiple data buses every bus has an assigned OF graph
 186       port number as described below.
 187
 188     properties:
 189       port@0:
 190         $ref: /schemas/graph.yaml#/properties/port
 191         description: High Speed (HS), present in all connectors.
 192
 193       port@1:
 194         $ref: /schemas/graph.yaml#/properties/port
 195         description: Super Speed (SS), present in SS capable connectors.
 196
 197       port@2:
 198         $ref: /schemas/graph.yaml#/properties/port
 199         description: Sideband Use (SBU), present in USB-C. This describes the
 200           alternate mode connection of which SBU is a part.
 201
 202     required:
 203       - port@0
 204
 205   new-source-frs-typec-current:
 206     description: Initial current capability of the new source when vSafe5V
 207       is applied during PD3.0 Fast Role Swap. "Table 6-14 Fixed Supply PDO - Sink"
 208       of "USB Power Delivery Specification Revision 3.0, Version 1.2" provides the
 209       different power levels and "6.4.1.3.1.6 Fast Role Swap USB Type-C Current"
 210       provides a detailed description of the field. The sink PDO from current source
 211       reflects the current source's(i.e. transmitter of the FRS signal) power
 212       requirement during fr swap. The current sink (i.e. receiver of the FRS signal),
 213       a.k.a new source, should check if it will be able to satisfy the current source's,
 214       new sink's, requirement during frswap before enabling the frs signal reception.
 215       This property refers to maximum current capability that the current sink can
 216       satisfy. During FRS, VBUS voltage is at 5V, as the partners are in implicit
 217       contract, hence, the power level is only a function of the current capability.
 218       "1" refers to default USB power level as described by "Table 6-14 Fixed Supply PDO - Sink".
 219       "2" refers to 1.5A@5V.
 220       "3" refers to 3.0A@5V.
 221     $ref: /schemas/types.yaml#/definitions/uint32
 222     enum: [1, 2, 3]
 223
 224   slow-charger-loop:
 225     description: Allows PMIC charger loops which are slow(i.e. cannot meet the 15ms deadline) to
 226       still comply to pSnkStby i.e Maximum power that can be consumed by sink while in Sink Standby
 227       state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification
 228       Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W -
 229       5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during
 230       SNK_DISCOVERY) and the actual current limit after reception of PS_Ready for PD link or during
 231       SNK_READY for non-pd link.
 232     type: boolean
 233
 234 dependencies:
 235   sink-vdos-v1: [ sink-vdos ]
 236   sink-vdos: [ sink-vdos-v1 ]
 237
 238 required:
 239   - compatible
 240
 241 allOf:
 242   - if:
 243       properties:
 244         compatible:
 245           contains:
 246             const: gpio-usb-b-connector
 247     then:
 248       anyOf:
 249         - required:
 250             - vbus-gpios
 251         - required:
 252             - id-gpios
 253
 254   - if:
 255       properties:
 256         compatible:
 257           contains:
 258             const: samsung,usb-connector-11pin
 259     then:
 260       properties:
 261         type:
 262           const: micro
 263
 264 anyOf:
 265   - not:
 266       required:
 267         - typec-power-opmode
 268         - new-source-frs-typec-current
 269
 270 additionalProperties: false
 271
 272 examples:
 273   # Micro-USB connector with HS lines routed via controller (MUIC).
 274   - |
 275     muic-max77843 {
 276         usb_con1: connector {
 277             compatible = "usb-b-connector";
 278             label = "micro-USB";
 279             type = "micro";
 280         };
 281     };
 282
 283   # USB-C connector attached to CC controller (s2mm005), HS lines routed
 284   # to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.
 285   # DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.
 286   - |
 287     ccic: s2mm005 {
 288         usb_con2: connector {
 289             compatible = "usb-c-connector";
 290             label = "USB-C";
 291
 292             ports {
 293                 #address-cells = <1>;
 294                 #size-cells = <0>;
 295
 296                 port@0 {
 297                     reg = <0>;
 298                     usb_con_hs: endpoint {
 299                         remote-endpoint = <&max77865_usbc_hs>;
 300                     };
 301                 };
 302                 port@1 {
 303                     reg = <1>;
 304                     usb_con_ss: endpoint {
 305                         remote-endpoint = <&usbdrd_phy_ss>;
 306                     };
 307                 };
 308                 port@2 {
 309                     reg = <2>;
 310                     usb_con_sbu: endpoint {
 311                         remote-endpoint = <&dp_aux>;
 312                     };
 313                 };
 314             };
 315         };
 316     };
 317
 318   # USB-C connector attached to a typec port controller(ptn5110), which has
 319   # power delivery support and enables drp.
 320   - |
 321     #include <dt-bindings/usb/pd.h>
 322     typec: ptn5110 {
 323         usb_con3: connector {
 324             compatible = "usb-c-connector";
 325             label = "USB-C";
 326             power-role = "dual";
 327             try-power-role = "sink";
 328             source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;
 329             sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)
 330                          PDO_VAR(5000, 12000, 2000)>;
 331             op-sink-microwatt = <10000000>;
 332         };
 333     };
 334
 335   # USB-C connector attached to SoC with a single High-Speed controller
 336   - |
 337     connector {
 338         compatible = "usb-c-connector";
 339         label = "USB-C";
 340
 341         port {
 342             high_speed_ep: endpoint {
 343                 remote-endpoint = <&usb_hs_ep>;
 344             };
 345         };
 346     };
 347
 348   # USB-C connector attached to SoC and USB3 typec port controller(hd3ss3220)
 349   # with SS 2:1 MUX. HS lines routed to SoC, SS lines routed to the MUX and
 350   # the output of MUX is connected to the SoC.
 351   - |
 352     connector {
 353         compatible = "usb-c-connector";
 354         label = "USB-C";
 355         data-role = "dual";
 356
 357         ports {
 358             #address-cells = <1>;
 359             #size-cells = <0>;
 360             port@0 {
 361                 reg = <0>;
 362                 hs_ep: endpoint {
 363                     remote-endpoint = <&usb3_hs_ep>;
 364                 };
 365             };
 366             port@1 {
 367                 reg = <1>;
 368                 ss_ep: endpoint {
 369                     remote-endpoint = <&hd3ss3220_in_ep>;
 370                 };
 371             };
 372         };
 373     };
 374
 375   # USB connector with GPIO control lines
 376   - |
 377     #include <dt-bindings/gpio/gpio.h>
 378
 379     usb {
 380         connector {
 381             compatible = "gpio-usb-b-connector", "usb-b-connector";
 382             type = "micro";
 383             id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>;
 384             vbus-supply = <&usb_p0_vbus>;
 385         };
 386     };
 387
 388   # Micro-USB connector with HS lines routed via controller (MUIC) and MHL
 389   # lines connected to HDMI-MHL bridge (sii8620) on Samsung Exynos5433-based
 390   # mobile phone
 391   - |
 392     muic-max77843 {
 393         usb_con4: connector {
 394             compatible = "samsung,usb-connector-11pin", "usb-b-connector";
 395             label = "micro-USB";
 396             type = "micro";
 397
 398             ports {
 399                 #address-cells = <1>;
 400                 #size-cells = <0>;
 401
 402                 port@0 {
 403                     reg = <0>;
 404                     muic_to_usb: endpoint {
 405                         remote-endpoint = <&usb_to_muic>;
 406                     };
 407                 };
 408                 port@3 {
 409                     reg = <3>;
 410                     usb_con_mhl: endpoint {
 411                         remote-endpoint = <&sii8620_mhl>;
 412                     };
 413                 };
 414             };
 415         };
 416     };