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
7title: USB Connector
8
9maintainers:
10  - Rob Herring <[email protected]>
11
12description:
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
17properties:
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  power-role:
70    description: Determines the power role that the Type C connector will
71      support. "dual" refers to Dual Role Port (DRP).
72    $ref: /schemas/types.yaml#/definitions/string
73
74    enum:
75      - source
76      - sink
77      - dual
78
79  try-power-role:
80    description: Preferred power role.
81    $ref: /schemas/types.yaml#/definitions/string
82
83    enum:
84      - source
85      - sink
86      - dual
87
88  data-role:
89    description: Data role if Type C connector supports USB data. "dual" refers
90      Dual Role Device (DRD).
91    $ref: /schemas/types.yaml#/definitions/string
92
93    enum:
94      - host
95      - device
96      - dual
97
98  typec-power-opmode:
99    description: Determines the power operation mode that the Type C connector
100      will support and will advertise through CC pins when it has no power
101      delivery support.
102      - "default" corresponds to default USB voltage and current defined by the
103        USB 2.0 and USB 3.2 specifications, 5V 500mA for USB 2.0 ports and
104        5V 900mA or 1500mA for USB 3.2 ports in single-lane or dual-lane
105        operation respectively.
106      - "1.5A" and "3.0A", 5V 1.5A and 5V 3.0A respectively, as defined in USB
107        Type-C Cable and Connector specification, when Power Delivery is not
108        supported.
109    $ref: /schemas/types.yaml#/definitions/string
110    enum:
111      - default
112      - 1.5A
113      - 3.0A
114
115  pd-disable:
116    description: Set this property if the Type-C connector has no power delivery support.
117    type: boolean
118
119  # The following are optional properties for "usb-c-connector" with power
120  # delivery support.
121  sink-vdos:
122    description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
123      providing additional information corresponding to the product, the detailed bit
124      definitions and the order of each VDO can be found in
125      "USB Power Delivery Specification Revision 3.0, Version 2.0 + ECNs 2020-12-10"
126      chapter 6.4.4.3.1 Discover Identity. User can specify the VDO array via
127      VDO_IDH/_CERT/_PRODUCT/_UFP/_DFP/_PCABLE/_ACABLE(1/2)/_VPD() defined in
128      dt-bindings/usb/pd.h.
129    minItems: 3
130    maxItems: 6
131    $ref: /schemas/types.yaml#/definitions/uint32-array
132
133  sink-vdos-v1:
134    description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
135      providing additional information corresponding to the product, the detailed bit
136      definitions and the order of each VDO can be found in
137      "USB Power Delivery Specification Revision 2.0, Version 1.3" chapter 6.4.4.3.1 Discover
138      Identity. User can specify the VDO array via VDO_IDH/_CERT/_PRODUCT/_CABLE/_AMA defined in
139      dt-bindings/usb/pd.h.
140    minItems: 3
141    maxItems: 6
142    $ref: /schemas/types.yaml#/definitions/uint32-array
143
144  accessory-mode-audio:
145    type: boolean
146    description: Whether the device supports Audio Adapter Accessory Mode. This
147      is only necessary if there are no other means to discover supported
148      alternative modes (e.g. through the UCSI firmware interface).
149
150  accessory-mode-debug:
151    type: boolean
152    description: Whether the device supports Debug Accessory Mode. This
153      is only necessary if there are no other means to discover supported
154      alternative modes (e.g. through the UCSI firmware interface).
155
156  altmodes:
157    type: object
158    description: List of Alternative Modes supported by the schematics on the
159      particular device. This is only necessary if there are no other means to
160      discover supported alternative modes (e.g. through the UCSI firmware
161      interface).
162
163    additionalProperties: false
164
165    patternProperties:
166      "^(displayport)$":
167        type: object
168        description:
169          A single USB-C Alternative Mode as supported by the USB-C connector logic.
170
171        additionalProperties: false
172
173        properties:
174          svid:
175            $ref: /schemas/types.yaml#/definitions/uint16
176            description: Unique value assigned by USB-IF to the Vendor / AltMode.
177            enum: [ 0xff01 ]
178          vdo:
179            $ref: /schemas/types.yaml#/definitions/uint32
180            description: VDO returned by Discover Modes USB PD command.
181
182  port:
183    $ref: /schemas/graph.yaml#/properties/port
184    description: OF graph bindings modeling a data bus to the connector, e.g.
185      there is a single High Speed (HS) port present in this connector. If there
186      is more than one bus (several port, with 'reg' property), they can be grouped
187      under 'ports'.
188
189  ports:
190    $ref: /schemas/graph.yaml#/properties/ports
191    description: OF graph bindings modeling any data bus to the connector
192      unless the bus is between parent node and the connector. Since a single
193      connector can have multiple data buses every bus has an assigned OF graph
194      port number as described below.
195
196    properties:
197      port@0:
198        $ref: /schemas/graph.yaml#/properties/port
199        description: High Speed (HS), present in all connectors.
200
201      port@1:
202        $ref: /schemas/graph.yaml#/properties/port
203        description: Super Speed (SS), present in SS capable connectors.
204
205      port@2:
206        $ref: /schemas/graph.yaml#/properties/port
207        description: Sideband Use (SBU), present in USB-C. This describes the
208          alternate mode connection of which SBU is a part.
209
210    required:
211      - port@0
212
213  new-source-frs-typec-current:
214    description: Initial current capability of the new source when vSafe5V
215      is applied during PD3.0 Fast Role Swap. "Table 6-14 Fixed Supply PDO - Sink"
216      of "USB Power Delivery Specification Revision 3.0, Version 1.2" provides the
217      different power levels and "6.4.1.3.1.6 Fast Role Swap USB Type-C Current"
218      provides a detailed description of the field. The sink PDO from current source
219      reflects the current source's(i.e. transmitter of the FRS signal) power
220      requirement during fr swap. The current sink (i.e. receiver of the FRS signal),
221      a.k.a new source, should check if it will be able to satisfy the current source's,
222      new sink's, requirement during frswap before enabling the frs signal reception.
223      This property refers to maximum current capability that the current sink can
224      satisfy. During FRS, VBUS voltage is at 5V, as the partners are in implicit
225      contract, hence, the power level is only a function of the current capability.
226      "1" refers to default USB power level as described by "Table 6-14 Fixed Supply PDO - Sink".
227      "2" refers to 1.5A@5V.
228      "3" refers to 3.0A@5V.
229    $ref: /schemas/types.yaml#/definitions/uint32
230    enum: [1, 2, 3]
231
232  slow-charger-loop:
233    description: Allows PMIC charger loops which are slow(i.e. cannot meet the 15ms deadline) to
234      still comply to pSnkStby i.e Maximum power that can be consumed by sink while in Sink Standby
235      state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification
236      Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W -
237      5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during
238      SNK_DISCOVERY) and the actual current limit after reception of PS_Ready for PD link or during
239      SNK_READY for non-pd link.
240    type: boolean
241
242  capabilities:
243    description: A child node to contain all the selectable USB Power Delivery capabilities.
244    type: object
245
246    patternProperties:
247      "^caps-[0-9]+$":
248        description: Child nodes under "capabilities" node. Each node contains a selectable USB
249          Power Delivery capability.
250        type: object
251        $ref: "#/$defs/capabilities"
252        unevaluatedProperties: false
253
254    additionalProperties: false
255
256  sink-wait-cap-time-ms:
257    description: Represents the max time in ms that USB Type-C port (in sink
258      role) should wait for the port partner (source role) to send source caps.
259      SinkWaitCap timer starts when port in sink role attaches to the source.
260      This timer will stop when sink receives PD source cap advertisement before
261      timeout in which case it'll move to capability negotiation stage. A
262      timeout leads to a hard reset message by the port.
263    minimum: 310
264    maximum: 620
265    default: 310
266
267  ps-source-off-time-ms:
268    description: Represents the max time in ms that a DRP in source role should
269      take to turn off power after the PsSourceOff timer starts. PsSourceOff
270      timer starts when a sink's PHY layer receives EOP of the GoodCRC message
271      (corresponding to an Accept message sent in response to a PR_Swap or a
272      FR_Swap request). This timer stops when last bit of GoodCRC EOP
273      corresponding to the received PS_RDY message is transmitted by the PHY
274      layer. A timeout shall lead to error recovery in the type-c port.
275    minimum: 750
276    maximum: 920
277    default: 920
278
279  cc-debounce-time-ms:
280    description: Represents the max time in ms that a port shall wait to
281      determine if it's attached to a partner.
282    minimum: 100
283    maximum: 200
284    default: 200
285
286  sink-bc12-completion-time-ms:
287    description: Represents the max time in ms that a port in sink role takes
288      to complete Battery Charger (BC1.2) Detection. BC1.2 detection is a
289      hardware mechanism, which in some TCPC implementations, can run in
290      parallel once the Type-C connection state machine reaches the "potential
291      connect as sink" state. In TCPCs where this causes delays to respond to
292      the incoming PD messages, sink-bc12-completion-time-ms is used to delay
293      PD negotiation till BC1.2 detection completes.
294    default: 0
295
296  pd-revision:
297    description: Specifies the maximum USB PD revision and version supported by
298      the connector. This property is specified in the following order;
299      <revision_major, revision_minor, version_major, version_minor>.
300    $ref: /schemas/types.yaml#/definitions/uint8-array
301    maxItems: 4
302
303dependencies:
304  sink-vdos-v1: [ sink-vdos ]
305  sink-vdos: [ sink-vdos-v1 ]
306
307required:
308  - compatible
309
310$defs:
311  capabilities:
312    type: object
313
314    properties:
315      source-pdos:
316        description: An array of u32 with each entry providing supported power
317          source data object(PDO), the detailed bit definitions of PDO can be found
318          in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2
319          Source_Capabilities Message, the order of each entry(PDO) should follow
320          the PD spec chapter 6.4.1. Required for power source and power dual role.
321          User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO()
322          defined in dt-bindings/usb/pd.h.
323        minItems: 1
324        maxItems: 7
325        $ref: /schemas/types.yaml#/definitions/uint32-array
326
327      sink-pdos:
328        description: An array of u32 with each entry providing supported power sink
329          data object(PDO), the detailed bit definitions of PDO can be found in
330          "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3
331          Sink Capabilities Message, the order of each entry(PDO) should follow the
332          PD spec chapter 6.4.1. Required for power sink and power dual role. User
333          can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined
334          in dt-bindings/usb/pd.h.
335        minItems: 1
336        maxItems: 7
337        $ref: /schemas/types.yaml#/definitions/uint32-array
338
339      op-sink-microwatt:
340        description: Sink required operating power in microwatt, if source can't
341          offer the power, Capability Mismatch is set. Required for power sink and
342          power dual role.
343
344allOf:
345  - $ref: "#/$defs/capabilities"
346  - if:
347      properties:
348        compatible:
349          contains:
350            const: gpio-usb-b-connector
351    then:
352      anyOf:
353        - required:
354            - vbus-gpios
355        - required:
356            - id-gpios
357
358  - if:
359      properties:
360        compatible:
361          contains:
362            const: samsung,usb-connector-11pin
363    then:
364      properties:
365        type:
366          const: micro
367
368anyOf:
369  - not:
370      required:
371        - typec-power-opmode
372        - new-source-frs-typec-current
373
374unevaluatedProperties: false
375
376examples:
377  # Micro-USB connector with HS lines routed via controller (MUIC).
378  - |
379    muic-max77843 {
380        usb_con1: connector {
381            compatible = "usb-b-connector";
382            label = "micro-USB";
383            type = "micro";
384        };
385    };
386
387  # USB-C connector attached to CC controller (s2mm005), HS lines routed
388  # to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.
389  # DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.
390  - |
391    ccic: s2mm005 {
392        usb_con2: connector {
393            compatible = "usb-c-connector";
394            label = "USB-C";
395
396            altmodes {
397                displayport {
398                    svid = /bits/ 16 <0xff01>;
399                    vdo = <0x00001c46>;
400                };
401            };
402
403            ports {
404                #address-cells = <1>;
405                #size-cells = <0>;
406
407                port@0 {
408                    reg = <0>;
409                    usb_con_hs: endpoint {
410                        remote-endpoint = <&max77865_usbc_hs>;
411                    };
412                };
413                port@1 {
414                    reg = <1>;
415                    usb_con_ss: endpoint {
416                        remote-endpoint = <&usbdrd_phy_ss>;
417                    };
418                };
419                port@2 {
420                    reg = <2>;
421                    usb_con_sbu: endpoint {
422                        remote-endpoint = <&dp_aux>;
423                    };
424                };
425            };
426        };
427    };
428
429  # USB-C connector attached to a typec port controller(ptn5110), which has
430  # power delivery support, explicitly defines time properties and enables drp.
431  - |
432    #include <dt-bindings/usb/pd.h>
433    typec: ptn5110 {
434        usb_con3: connector {
435            compatible = "usb-c-connector";
436            label = "USB-C";
437            power-role = "dual";
438            try-power-role = "sink";
439            source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;
440            sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)
441                         PDO_VAR(5000, 12000, 2000)>;
442            op-sink-microwatt = <10000000>;
443            sink-wait-cap-time-ms = <465>;
444            ps-source-off-time-ms = <835>;
445            cc-debounce-time-ms = <101>;
446            sink-bc12-completion-time-ms = <500>;
447        };
448    };
449
450  # USB-C connector attached to SoC with a single High-Speed controller
451  - |
452    connector {
453        compatible = "usb-c-connector";
454        label = "USB-C";
455
456        port {
457            high_speed_ep: endpoint {
458                remote-endpoint = <&usb_hs_ep>;
459            };
460        };
461    };
462
463  # USB-C connector attached to SoC and USB3 typec port controller(hd3ss3220)
464  # with SS 2:1 MUX. HS lines routed to SoC, SS lines routed to the MUX and
465  # the output of MUX is connected to the SoC.
466  - |
467    connector {
468        compatible = "usb-c-connector";
469        label = "USB-C";
470        data-role = "dual";
471
472        ports {
473            #address-cells = <1>;
474            #size-cells = <0>;
475            port@0 {
476                reg = <0>;
477                hs_ep: endpoint {
478                    remote-endpoint = <&usb3_hs_ep>;
479                };
480            };
481            port@1 {
482                reg = <1>;
483                ss_ep: endpoint {
484                    remote-endpoint = <&hd3ss3220_in_ep>;
485                };
486            };
487        };
488    };
489
490  # USB connector with GPIO control lines
491  - |
492    #include <dt-bindings/gpio/gpio.h>
493
494    usb {
495        connector {
496            compatible = "gpio-usb-b-connector", "usb-b-connector";
497            type = "micro";
498            id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>;
499            vbus-supply = <&usb_p0_vbus>;
500        };
501    };
502
503  # Micro-USB connector with HS lines routed via controller (MUIC) and MHL
504  # lines connected to HDMI-MHL bridge (sii8620) on Samsung Exynos5433-based
505  # mobile phone
506  - |
507    muic-max77843 {
508        usb_con4: connector {
509            compatible = "samsung,usb-connector-11pin", "usb-b-connector";
510            label = "micro-USB";
511            type = "micro";
512
513            ports {
514                #address-cells = <1>;
515                #size-cells = <0>;
516
517                port@0 {
518                    reg = <0>;
519                    muic_to_usb: endpoint {
520                        remote-endpoint = <&usb_to_muic>;
521                    };
522                };
523                port@3 {
524                    reg = <3>;
525                    usb_con_mhl: endpoint {
526                        remote-endpoint = <&sii8620_mhl>;
527                    };
528                };
529            };
530        };
531    };
532