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