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: 3
  48
  49   interrupt-names:
  50     minItems: 1
  51     maxItems: 3
  52     oneOf:
  53       - const: dwc_usb3
  54       - items:
  55           enum: [host, peripheral, otg]
  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,dis_metastability_quirk:
 240     description:
 241       When set, disable metastability workaround. CAUTION! Use only if you are
 242       absolutely sure of it.
 243     type: boolean
 244
 245   snps,dis-split-quirk:
 246     description:
 247       When set, change the way URBs are handled by the driver. Needed to
 248       avoid -EPROTO errors with usbhid on some devices (Hikey 970).
 249     type: boolean
 250
 251   snps,gfladj-refclk-lpm-sel-quirk:
 252     description:
 253       When set, run the SOF/ITP counter based on ref_clk.
 254     type: boolean
 255
 256   snps,resume-hs-terminations:
 257     description:
 258       Fix the issue of HS terminations CRC error on resume by enabling this
 259       quirk. When set, all the termsel, xcvrsel, opmode becomes 0 during end
 260       of resume. This option is to support certain legacy ULPI PHYs.
 261     type: boolean
 262
 263   snps,ulpi-ext-vbus-drv:
 264     description:
 265       Some ULPI USB PHY does not support internal VBUS supply, and driving
 266       the CPEN pin, requires the configuration of the ulpi DRVVBUSEXTERNAL
 267       bit. When set, the xhci host will configure the USB2 PHY drives VBUS
 268       with an external supply.
 269     type: boolean
 270
 271   snps,is-utmi-l1-suspend:
 272     description:
 273       True when DWC3 asserts output signal utmi_l1_suspend_n, false when
 274       asserts utmi_sleep_n.
 275     type: boolean
 276
 277   snps,hird-threshold:
 278     description: HIRD threshold
 279     $ref: /schemas/types.yaml#/definitions/uint8
 280
 281   snps,hsphy_interface:
 282     description:
 283       High-Speed PHY interface selection between UTMI+ and ULPI when the
 284       DWC_USB3_HSPHY_INTERFACE has value 3.
 285     $ref: /schemas/types.yaml#/definitions/uint8
 286     enum: [utmi, ulpi]
 287
 288   snps,quirk-frame-length-adjustment:
 289     description:
 290       Value for GFLADJ_30MHZ field of GFLADJ register for post-silicon frame
 291       length adjustment when the fladj_30mhz_sdbnd signal is invalid or
 292       incorrect.
 293     $ref: /schemas/types.yaml#/definitions/uint32
 294     minimum: 0
 295     maximum: 0x3f
 296
 297   snps,ref-clock-period-ns:
 298     description:
 299       Value for REFCLKPER field of GUCTL register for reference clock period in
 300       nanoseconds, when the hardware set default does not match the actual
 301       clock.
 302
 303       This binding is deprecated. Instead, provide an appropriate reference clock.
 304     minimum: 8
 305     maximum: 62
 306     deprecated: true
 307
 308   snps,rx-thr-num-pkt-prd:
 309     description:
 310       Periodic ESS RX packet threshold count (host mode only). Set this and
 311       snps,rx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
 312       programming guide section 1.2.4) to enable periodic ESS RX threshold.
 313     $ref: /schemas/types.yaml#/definitions/uint8
 314     minimum: 1
 315     maximum: 16
 316
 317   snps,rx-max-burst-prd:
 318     description:
 319       Max periodic ESS RX burst size (host mode only). Set this and
 320       snps,rx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
 321       programming guide section 1.2.4) to enable periodic ESS RX threshold.
 322     $ref: /schemas/types.yaml#/definitions/uint8
 323     minimum: 1
 324     maximum: 16
 325
 326   snps,tx-thr-num-pkt-prd:
 327     description:
 328       Periodic ESS TX packet threshold count (host mode only). Set this and
 329       snps,tx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
 330       programming guide section 1.2.3) to enable periodic ESS TX threshold.
 331     $ref: /schemas/types.yaml#/definitions/uint8
 332     minimum: 1
 333     maximum: 16
 334
 335   snps,tx-max-burst-prd:
 336     description:
 337       Max periodic ESS TX burst size (host mode only). Set this and
 338       snps,tx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
 339       programming guide section 1.2.3) to enable periodic ESS TX threshold.
 340     $ref: /schemas/types.yaml#/definitions/uint8
 341     minimum: 1
 342     maximum: 16
 343
 344   tx-fifo-resize:
 345     description: Determines if the TX fifos can be dynamically resized depending
 346       on the number of IN endpoints used and if bursting is supported.  This
 347       may help improve bandwidth on platforms with higher system latencies, as
 348       increased fifo space allows for the controller to prefetch data into its
 349       internal memory.
 350     type: boolean
 351
 352   tx-fifo-max-num:
 353     description: Specifies the max number of packets the txfifo resizing logic
 354       can account for when higher endpoint bursting is used. (bMaxBurst > 6) The
 355       higher the number, the more fifo space the txfifo resizing logic will
 356       allocate for that endpoint.
 357     $ref: /schemas/types.yaml#/definitions/uint8
 358     minimum: 3
 359
 360   snps,incr-burst-type-adjustment:
 361     description:
 362       Value for INCR burst type of GSBUSCFG0 register, undefined length INCR
 363       burst type enable and INCRx type. A single value means INCRX burst mode
 364       enabled. If more than one value specified, undefined length INCR burst
 365       type will be enabled with burst lengths utilized up to the maximum
 366       of the values passed in this property.
 367     $ref: /schemas/types.yaml#/definitions/uint32-array
 368     minItems: 1
 369     maxItems: 8
 370     uniqueItems: true
 371     items:
 372       enum: [1, 4, 8, 16, 32, 64, 128, 256]
 373
 374   port:
 375     $ref: /schemas/graph.yaml#/properties/port
 376     description:
 377       This port is used with the 'usb-role-switch' property  to connect the
 378       dwc3 to type C connector.
 379
 380   ports:
 381     $ref: /schemas/graph.yaml#/properties/ports
 382     description:
 383       Those ports should be used with any connector to the data bus of this
 384       controller using the OF graph bindings specified if the "usb-role-switch"
 385       property is used.
 386
 387     properties:
 388       port@0:
 389         $ref: /schemas/graph.yaml#/properties/port
 390         description: High Speed (HS) data bus.
 391
 392       port@1:
 393         $ref: /schemas/graph.yaml#/properties/port
 394         description: Super Speed (SS) data bus.
 395
 396   wakeup-source:
 397     $ref: /schemas/types.yaml#/definitions/flag
 398     description:
 399       Enable USB remote wakeup.
 400
 401 unevaluatedProperties: false
 402
 403 required:
 404   - compatible
 405   - reg
 406   - interrupts
 407
 408 examples:
 409   - |
 410     usb@4a030000 {
 411       compatible = "snps,dwc3";
 412       reg = <0x4a030000 0xcfff>;
 413       interrupts = <0 92 4>;
 414       usb-phy = <&usb2_phy>, <&usb3_phy>;
 415       snps,incr-burst-type-adjustment = <1>, <4>, <8>, <16>;
 416     };
 417   - |
 418     usb@4a000000 {
 419       compatible = "snps,dwc3";
 420       reg = <0x4a000000 0xcfff>;
 421       interrupts = <0 92 4>;
 422       clocks = <&clk 1>, <&clk 2>, <&clk 3>;
 423       clock-names = "bus_early", "ref", "suspend";
 424       phys = <&usb2_phy>, <&usb3_phy>;
 425       phy-names = "usb2-phy", "usb3-phy";
 426       snps,dis_u2_susphy_quirk;
 427       snps,dis_enblslpm_quirk;
 428     };
 429 ...