Documentation/devicetree/bindings/usb/snps,dwc3.yaml

   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
   7 title: Synopsys DesignWare USB3 Controller
   8
   9 maintainers:
  10   - Felipe Balbi <balbi@kernel.org>
  11
  12 description:
  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
  17 allOf:
  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
  31 properties:
  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   port:
 436     $ref: /schemas/graph.yaml#/properties/port
 437     description:
 438       This port is used with the 'usb-role-switch' property  to connect the
 439       dwc3 to type C connector.
 440
 441   ports:
 442     $ref: /schemas/graph.yaml#/properties/ports
 443     description:
 444       Those ports should be used with any connector to the data bus of this
 445       controller using the OF graph bindings specified if the "usb-role-switch"
 446       property is used.
 447
 448     properties:
 449       port@0:
 450         $ref: /schemas/graph.yaml#/properties/port
 451         description: High Speed (HS) data bus.
 452
 453       port@1:
 454         $ref: /schemas/graph.yaml#/properties/port
 455         description: Super Speed (SS) data bus.
 456
 457   wakeup-source:
 458     $ref: /schemas/types.yaml#/definitions/flag
 459     description:
 460       Enable USB remote wakeup.
 461
 462 unevaluatedProperties: false
 463
 464 required:
 465   - compatible
 466   - reg
 467   - interrupts
 468
 469 examples:
 470   - |
 471     usb@4a030000 {
 472       compatible = "snps,dwc3";
 473       reg = <0x4a030000 0xcfff>;
 474       interrupts = <0 92 4>;
 475       usb-phy = <&usb2_phy>, <&usb3_phy>;
 476       snps,incr-burst-type-adjustment = <1>, <4>, <8>, <16>;
 477     };
 478   - |
 479     usb@4a000000 {
 480       compatible = "snps,dwc3";
 481       reg = <0x4a000000 0xcfff>;
 482       interrupts = <0 92 4>;
 483       clocks = <&clk 1>, <&clk 2>, <&clk 3>;
 484       clock-names = "bus_early", "ref", "suspend";
 485       phys = <&usb2_phy>, <&usb3_phy>;
 486       phy-names = "usb2-phy", "usb3-phy";
 487       snps,dis_u2_susphy_quirk;
 488       snps,dis_enblslpm_quirk;
 489     };
 490 ...