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,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-prd:
 314     description:
 315       Periodic ESS RX packet threshold count (host mode only). Set this and
 316       snps,rx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
 317       programming guide section 1.2.4) to enable periodic ESS RX threshold.
 318     $ref: /schemas/types.yaml#/definitions/uint8
 319     minimum: 1
 320     maximum: 16
 321
 322   snps,rx-max-burst-prd:
 323     description:
 324       Max periodic ESS RX burst size (host mode only). Set this and
 325       snps,rx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
 326       programming guide section 1.2.4) to enable periodic ESS RX threshold.
 327     $ref: /schemas/types.yaml#/definitions/uint8
 328     minimum: 1
 329     maximum: 16
 330
 331   snps,tx-thr-num-pkt-prd:
 332     description:
 333       Periodic ESS TX packet threshold count (host mode only). Set this and
 334       snps,tx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
 335       programming guide section 1.2.3) to enable periodic ESS TX threshold.
 336     $ref: /schemas/types.yaml#/definitions/uint8
 337     minimum: 1
 338     maximum: 16
 339
 340   snps,tx-max-burst-prd:
 341     description:
 342       Max periodic ESS TX burst size (host mode only). Set this and
 343       snps,tx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
 344       programming guide section 1.2.3) to enable periodic ESS TX threshold.
 345     $ref: /schemas/types.yaml#/definitions/uint8
 346     minimum: 1
 347     maximum: 16
 348
 349   tx-fifo-resize:
 350     description: Determines if the TX fifos can be dynamically resized depending
 351       on the number of IN endpoints used and if bursting is supported.  This
 352       may help improve bandwidth on platforms with higher system latencies, as
 353       increased fifo space allows for the controller to prefetch data into its
 354       internal memory.
 355     type: boolean
 356
 357   tx-fifo-max-num:
 358     description: Specifies the max number of packets the txfifo resizing logic
 359       can account for when higher endpoint bursting is used. (bMaxBurst > 6) The
 360       higher the number, the more fifo space the txfifo resizing logic will
 361       allocate for that endpoint.
 362     $ref: /schemas/types.yaml#/definitions/uint8
 363     minimum: 3
 364
 365   snps,incr-burst-type-adjustment:
 366     description:
 367       Value for INCR burst type of GSBUSCFG0 register, undefined length INCR
 368       burst type enable and INCRx type. A single value means INCRX burst mode
 369       enabled. If more than one value specified, undefined length INCR burst
 370       type will be enabled with burst lengths utilized up to the maximum
 371       of the values passed in this property.
 372     $ref: /schemas/types.yaml#/definitions/uint32-array
 373     minItems: 1
 374     maxItems: 8
 375     uniqueItems: true
 376     items:
 377       enum: [1, 4, 8, 16, 32, 64, 128, 256]
 378
 379   port:
 380     $ref: /schemas/graph.yaml#/properties/port
 381     description:
 382       This port is used with the 'usb-role-switch' property  to connect the
 383       dwc3 to type C connector.
 384
 385   ports:
 386     $ref: /schemas/graph.yaml#/properties/ports
 387     description:
 388       Those ports should be used with any connector to the data bus of this
 389       controller using the OF graph bindings specified if the "usb-role-switch"
 390       property is used.
 391
 392     properties:
 393       port@0:
 394         $ref: /schemas/graph.yaml#/properties/port
 395         description: High Speed (HS) data bus.
 396
 397       port@1:
 398         $ref: /schemas/graph.yaml#/properties/port
 399         description: Super Speed (SS) data bus.
 400
 401   wakeup-source:
 402     $ref: /schemas/types.yaml#/definitions/flag
 403     description:
 404       Enable USB remote wakeup.
 405
 406 unevaluatedProperties: false
 407
 408 required:
 409   - compatible
 410   - reg
 411   - interrupts
 412
 413 examples:
 414   - |
 415     usb@4a030000 {
 416       compatible = "snps,dwc3";
 417       reg = <0x4a030000 0xcfff>;
 418       interrupts = <0 92 4>;
 419       usb-phy = <&usb2_phy>, <&usb3_phy>;
 420       snps,incr-burst-type-adjustment = <1>, <4>, <8>, <16>;
 421     };
 422   - |
 423     usb@4a000000 {
 424       compatible = "snps,dwc3";
 425       reg = <0x4a000000 0xcfff>;
 426       interrupts = <0 92 4>;
 427       clocks = <&clk 1>, <&clk 2>, <&clk 3>;
 428       clock-names = "bus_early", "ref", "suspend";
 429       phys = <&usb2_phy>, <&usb3_phy>;
 430       phy-names = "usb2-phy", "usb3-phy";
 431       snps,dis_u2_susphy_quirk;
 432       snps,dis_enblslpm_quirk;
 433     };
 434 ...