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