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