1# SPDX-License-Identifier: GPL-2.0
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/usb/snps,dwc3.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Synopsys DesignWare USB3 Controller
8
9maintainers:
10  - Felipe Balbi <balbi@kernel.org>
11
12description:
13  This is usually a subnode to DWC3 glue to which it is connected, but can also
14  be presented as a standalone DT node with an optional vendor-specific
15  compatible string.
16
17allOf:
18  - $ref: usb-drd.yaml#
19  - if:
20      properties:
21        dr_mode:
22          const: peripheral
23
24      required:
25        - dr_mode
26    then:
27      $ref: usb.yaml#
28    else:
29      $ref: usb-xhci.yaml#
30
31properties:
32  compatible:
33    contains:
34      oneOf:
35        - const: snps,dwc3
36        - const: synopsys,dwc3
37          deprecated: true
38
39  reg:
40    maxItems: 1
41
42  interrupts:
43    description:
44      It's either a single common DWC3 interrupt (dwc_usb3) or individual
45      interrupts for the host, gadget and DRD modes.
46    minItems: 1
47    maxItems: 4
48
49  interrupt-names:
50    minItems: 1
51    maxItems: 4
52    oneOf:
53      - const: dwc_usb3
54      - items:
55          enum: [host, peripheral, otg, wakeup]
56
57  clocks:
58    description:
59      In general the core supports three types of clocks. bus_early is a
60      SoC Bus Clock (AHB/AXI/Native). ref generates ITP when the UTMI/ULPI
61      PHY is suspended. suspend clocks a small part of the USB3 core when
62      SS PHY in P3. But particular cases may differ from that having less
63      or more clock sources with another names.
64
65  clock-names:
66    contains:
67      anyOf:
68        - enum: [bus_early, ref, suspend]
69        - true
70
71  dma-coherent: true
72
73  extcon:
74    maxItems: 1
75    deprecated: true
76
77  iommus:
78    maxItems: 1
79
80  usb-phy:
81    minItems: 1
82    items:
83      - description: USB2/HS PHY
84      - description: USB3/SS PHY
85
86  phys:
87    minItems: 1
88    maxItems: 2
89
90  phy-names:
91    minItems: 1
92    maxItems: 2
93    items:
94      enum:
95        - usb2-phy
96        - usb3-phy
97
98  power-domains:
99    description:
100      The DWC3 has 2 power-domains. The power management unit (PMU) and
101      everything else. The PMU is typically always powered and may not have an
102      entry.
103    minItems: 1
104    items:
105      - description: Core
106      - description: Power management unit
107
108  resets:
109    minItems: 1
110
111  snps,usb2-lpm-disable:
112    description: Indicate if we don't want to enable USB2 HW LPM for host
113      mode.
114    type: boolean
115
116  snps,usb3_lpm_capable:
117    description: Determines if platform is USB3 LPM capable
118    type: boolean
119
120  snps,usb2-gadget-lpm-disable:
121    description: Indicate if we don't want to enable USB2 HW LPM for gadget
122      mode.
123    type: boolean
124
125  snps,dis-start-transfer-quirk:
126    description:
127      When set, disable isoc START TRANSFER command failure SW work-around
128      for DWC_usb31 version 1.70a-ea06 and prior.
129    type: boolean
130
131  snps,disable_scramble_quirk:
132    description:
133      True when SW should disable data scrambling. Only really useful for FPGA
134      builds.
135    type: boolean
136
137  snps,has-lpm-erratum:
138    description: True when DWC3 was configured with LPM Erratum enabled
139    type: boolean
140
141  snps,lpm-nyet-threshold:
142    description: LPM NYET threshold
143    $ref: /schemas/types.yaml#/definitions/uint8
144
145  snps,u2exit_lfps_quirk:
146    description: Set if we want to enable u2exit lfps quirk
147    type: boolean
148
149  snps,u2ss_inp3_quirk:
150    description: Set if we enable P3 OK for U2/SS Inactive quirk
151    type: boolean
152
153  snps,req_p1p2p3_quirk:
154    description:
155      When set, the core will always request for P1/P2/P3 transition sequence.
156    type: boolean
157
158  snps,del_p1p2p3_quirk:
159    description:
160      When set core will delay P1/P2/P3 until a certain amount of 8B10B errors
161      occur.
162    type: boolean
163
164  snps,del_phy_power_chg_quirk:
165    description: When set core will delay PHY power change from P0 to P1/P2/P3.
166    type: boolean
167
168  snps,lfps_filter_quirk:
169    description: When set core will filter LFPS reception.
170    type: boolean
171
172  snps,rx_detect_poll_quirk:
173    description:
174      when set core will disable a 400us delay to start Polling LFPS after
175      RX.Detect.
176    type: boolean
177
178  snps,tx_de_emphasis_quirk:
179    description: When set core will set Tx de-emphasis value
180    type: boolean
181
182  snps,tx_de_emphasis:
183    description:
184      The value driven to the PHY is controlled by the LTSSM during USB3
185      Compliance mode.
186    $ref: /schemas/types.yaml#/definitions/uint8
187    enum:
188      - 0 # -6dB de-emphasis
189      - 1 # -3.5dB de-emphasis
190      - 2 # No de-emphasis
191
192  snps,dis_u3_susphy_quirk:
193    description: When set core will disable USB3 suspend phy
194    type: boolean
195
196  snps,dis_u2_susphy_quirk:
197    description: When set core will disable USB2 suspend phy
198    type: boolean
199
200  snps,dis_enblslpm_quirk:
201    description:
202      When set clears the enblslpm in GUSB2PHYCFG, disabling the suspend signal
203      to the PHY.
204    type: boolean
205
206  snps,dis-u1-entry-quirk:
207    description: Set if link entering into U1 needs to be disabled
208    type: boolean
209
210  snps,dis-u2-entry-quirk:
211    description: Set if link entering into U2 needs to be disabled
212    type: boolean
213
214  snps,dis_rxdet_inp3_quirk:
215    description:
216      When set core will disable receiver detection in PHY P3 power state.
217    type: boolean
218
219  snps,dis-u2-freeclk-exists-quirk:
220    description:
221      When set, clear the u2_freeclk_exists in GUSB2PHYCFG, specify that USB2
222      PHY doesn't provide a free-running PHY clock.
223    type: boolean
224
225  snps,dis-del-phy-power-chg-quirk:
226    description:
227      When set core will change PHY power from P0 to P1/P2/P3 without delay.
228    type: boolean
229
230  snps,dis-tx-ipgap-linecheck-quirk:
231    description: When set, disable u2mac linestate check during HS transmit
232    type: boolean
233
234  snps,parkmode-disable-ss-quirk:
235    description:
236      When set, all SuperSpeed bus instances in park mode are disabled.
237    type: boolean
238
239  snps,parkmode-disable-hs-quirk:
240    description:
241      When set, all HighSpeed bus instances in park mode are disabled.
242    type: boolean
243
244  snps,dis_metastability_quirk:
245    description:
246      When set, disable metastability workaround. CAUTION! Use only if you are
247      absolutely sure of it.
248    type: boolean
249
250  snps,dis-split-quirk:
251    description:
252      When set, change the way URBs are handled by the driver. Needed to
253      avoid -EPROTO errors with usbhid on some devices (Hikey 970).
254    type: boolean
255
256  snps,gfladj-refclk-lpm-sel-quirk:
257    description:
258      When set, run the SOF/ITP counter based on ref_clk.
259    type: boolean
260
261  snps,resume-hs-terminations:
262    description:
263      Fix the issue of HS terminations CRC error on resume by enabling this
264      quirk. When set, all the termsel, xcvrsel, opmode becomes 0 during end
265      of resume. This option is to support certain legacy ULPI PHYs.
266    type: boolean
267
268  snps,ulpi-ext-vbus-drv:
269    description:
270      Some ULPI USB PHY does not support internal VBUS supply, and driving
271      the CPEN pin, requires the configuration of the ulpi DRVVBUSEXTERNAL
272      bit. When set, the xhci host will configure the USB2 PHY drives VBUS
273      with an external supply.
274    type: boolean
275
276  snps,is-utmi-l1-suspend:
277    description:
278      True when DWC3 asserts output signal utmi_l1_suspend_n, false when
279      asserts utmi_sleep_n.
280    type: boolean
281
282  snps,hird-threshold:
283    description: HIRD threshold
284    $ref: /schemas/types.yaml#/definitions/uint8
285
286  snps,hsphy_interface:
287    description:
288      High-Speed PHY interface selection between UTMI+ and ULPI when the
289      DWC_USB3_HSPHY_INTERFACE has value 3.
290    $ref: /schemas/types.yaml#/definitions/string
291    enum: [utmi, ulpi]
292
293  snps,quirk-frame-length-adjustment:
294    description:
295      Value for GFLADJ_30MHZ field of GFLADJ register for post-silicon frame
296      length adjustment when the fladj_30mhz_sdbnd signal is invalid or
297      incorrect.
298    $ref: /schemas/types.yaml#/definitions/uint32
299    minimum: 0
300    maximum: 0x3f
301
302  snps,ref-clock-period-ns:
303    description:
304      Value for REFCLKPER field of GUCTL register for reference clock period in
305      nanoseconds, when the hardware set default does not match the actual
306      clock.
307
308      This binding is deprecated. Instead, provide an appropriate reference clock.
309    minimum: 8
310    maximum: 62
311    deprecated: true
312
313  snps,rx-thr-num-pkt:
314    description:
315      USB RX packet threshold count. In host mode, this field specifies
316      the space that must be available in the RX FIFO before the core can
317      start the corresponding USB RX transaction (burst).
318      In device mode, this field specifies the space that must be
319      available in the RX FIFO before the core can send ERDY for a
320      flow-controlled endpoint. It is only used for SuperSpeed.
321      The valid values for this field are from 1 to 15. (DWC3 SuperSpeed
322      USB 3.0 Controller Databook)
323    $ref: /schemas/types.yaml#/definitions/uint8
324    minimum: 1
325    maximum: 15
326
327  snps,rx-max-burst:
328    description:
329      Max USB RX burst size. In host mode, this field specifies the
330      Maximum Bulk IN burst the DWC_usb3 core can perform. When the system
331      bus is slower than the USB, RX FIFO can overrun during a long burst.
332      You can program a smaller value to this field to limit the RX burst
333      size that the core can perform. It only applies to SS Bulk,
334      Isochronous, and Interrupt IN endpoints in the host mode.
335      In device mode, this field specifies the NUMP value that is sent in
336      ERDY for an OUT endpoint.
337      The valid values for this field are from 1 to 16. (DWC3 SuperSpeed
338      USB 3.0 Controller Databook)
339    $ref: /schemas/types.yaml#/definitions/uint8
340    minimum: 1
341    maximum: 16
342
343  snps,tx-thr-num-pkt:
344    description:
345      USB TX packet threshold count. This field specifies the number of
346      packets that must be in the TXFIFO before the core can start
347      transmission for the corresponding USB transaction (burst).
348      This count is valid in both host and device modes. It is only used
349      for SuperSpeed operation.
350      Valid values are from 1 to 15. (DWC3 SuperSpeed USB 3.0 Controller
351      Databook)
352    $ref: /schemas/types.yaml#/definitions/uint8
353    minimum: 1
354    maximum: 15
355
356  snps,tx-max-burst:
357    description:
358      Max USB TX burst size. When the system bus is slower than the USB,
359      TX FIFO can underrun during a long burst. Program a smaller value
360      to this field to limit the TX burst size that the core can execute.
361      In Host mode, it only applies to SS Bulk, Isochronous, and Interrupt
362      OUT endpoints. This value is not used in device mode.
363      Valid values are from 1 to 16. (DWC3 SuperSpeed USB 3.0 Controller
364      Databook)
365    $ref: /schemas/types.yaml#/definitions/uint8
366    minimum: 1
367    maximum: 16
368
369  snps,rx-thr-num-pkt-prd:
370    description:
371      Periodic ESS RX packet threshold count (host mode only). Set this and
372      snps,rx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
373      programming guide section 1.2.4) to enable periodic ESS RX threshold.
374    $ref: /schemas/types.yaml#/definitions/uint8
375    minimum: 1
376    maximum: 16
377
378  snps,rx-max-burst-prd:
379    description:
380      Max periodic ESS RX burst size (host mode only). Set this and
381      snps,rx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
382      programming guide section 1.2.4) to enable periodic ESS RX threshold.
383    $ref: /schemas/types.yaml#/definitions/uint8
384    minimum: 1
385    maximum: 16
386
387  snps,tx-thr-num-pkt-prd:
388    description:
389      Periodic ESS TX packet threshold count (host mode only). Set this and
390      snps,tx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
391      programming guide section 1.2.3) to enable periodic ESS TX threshold.
392    $ref: /schemas/types.yaml#/definitions/uint8
393    minimum: 1
394    maximum: 16
395
396  snps,tx-max-burst-prd:
397    description:
398      Max periodic ESS TX burst size (host mode only). Set this and
399      snps,tx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
400      programming guide section 1.2.3) to enable periodic ESS TX threshold.
401    $ref: /schemas/types.yaml#/definitions/uint8
402    minimum: 1
403    maximum: 16
404
405  tx-fifo-resize:
406    description: Determines if the TX fifos can be dynamically resized depending
407      on the number of IN endpoints used and if bursting is supported.  This
408      may help improve bandwidth on platforms with higher system latencies, as
409      increased fifo space allows for the controller to prefetch data into its
410      internal memory.
411    type: boolean
412
413  tx-fifo-max-num:
414    description: Specifies the max number of packets the txfifo resizing logic
415      can account for when higher endpoint bursting is used. (bMaxBurst > 6) The
416      higher the number, the more fifo space the txfifo resizing logic will
417      allocate for that endpoint.
418    $ref: /schemas/types.yaml#/definitions/uint8
419    minimum: 3
420
421  snps,incr-burst-type-adjustment:
422    description:
423      Value for INCR burst type of GSBUSCFG0 register, undefined length INCR
424      burst type enable and INCRx type. A single value means INCRX burst mode
425      enabled. If more than one value specified, undefined length INCR burst
426      type will be enabled with burst lengths utilized up to the maximum
427      of the values passed in this property.
428    $ref: /schemas/types.yaml#/definitions/uint32-array
429    minItems: 1
430    maxItems: 8
431    uniqueItems: true
432    items:
433      enum: [1, 4, 8, 16, 32, 64, 128, 256]
434
435  num-hc-interrupters:
436    maximum: 8
437    default: 1
438
439  port:
440    $ref: /schemas/graph.yaml#/properties/port
441    description:
442      This port is used with the 'usb-role-switch' property  to connect the
443      dwc3 to type C connector.
444
445  ports:
446    $ref: /schemas/graph.yaml#/properties/ports
447    description:
448      Those ports should be used with any connector to the data bus of this
449      controller using the OF graph bindings specified if the "usb-role-switch"
450      property is used.
451
452    properties:
453      port@0:
454        $ref: /schemas/graph.yaml#/properties/port
455        description: High Speed (HS) data bus.
456
457      port@1:
458        $ref: /schemas/graph.yaml#/properties/port
459        description: Super Speed (SS) data bus.
460
461  wakeup-source:
462    $ref: /schemas/types.yaml#/definitions/flag
463    description:
464      Enable USB remote wakeup.
465
466unevaluatedProperties: false
467
468required:
469  - compatible
470  - reg
471  - interrupts
472
473examples:
474  - |
475    usb@4a030000 {
476      compatible = "snps,dwc3";
477      reg = <0x4a030000 0xcfff>;
478      interrupts = <0 92 4>;
479      usb-phy = <&usb2_phy>, <&usb3_phy>;
480      snps,incr-burst-type-adjustment = <1>, <4>, <8>, <16>;
481    };
482  - |
483    usb@4a000000 {
484      compatible = "snps,dwc3";
485      reg = <0x4a000000 0xcfff>;
486      interrupts = <0 92 4>;
487      clocks = <&clk 1>, <&clk 2>, <&clk 3>;
488      clock-names = "bus_early", "ref", "suspend";
489      phys = <&usb2_phy>, <&usb3_phy>;
490      phy-names = "usb2-phy", "usb3-phy";
491      snps,dis_u2_susphy_quirk;
492      snps,dis_enblslpm_quirk;
493    };
494...
495