Synopsys DesignWare USB3 Common Properties

Synopsys DWC3 공통 속성

GPL-2.0으로 배포되는 이 스키마는 vendor별 구현에 내장되거나 standalone component로 쓰이는 Synopsys DesignWare USB3 DWC3 core의 공통 속성을 정의합니다. 관리자는 Felipe Balbi입니다.

DRD와 peripheral·host schema 선택

공통 `usb-drd.yaml`을 상속합니다. `dr_mode`가 `peripheral`이고 명시적으로 필수이면 `usb.yaml` device schema를, 그 밖의 경우에는 `usb-xhci.yaml` host schema를 적용합니다.

allOf:
  - $ref: usb-drd.yaml#
  - if:
      properties:
        dr_mode:
          const: peripheral

      required:
        - dr_mode
    then:
      $ref: usb.yaml#
    else:
      $ref: usb-xhci.yaml#

extcon과 다중 USB PHY

`extcon` 하나는 deprecated입니다. 구형 `usb-phy` 배열은 USB2/HighSpeed PHY와 USB3/SuperSpeed PHY 순서로 최소 하나를 받습니다. 일반 `phys`와 `phy-names`는 1~19개입니다.

PHY 이름은 단일 controller에서 `usb2-phy`, `usb3-phy`를 쓰거나 다중 port에서 USB2 index 0~14와 USB3 index 0~3을 `usb2-N`, `usb3-N` 형식으로 지정합니다.

properties:
  extcon:
    maxItems: 1
    deprecated: true

  usb-phy:
    minItems: 1
    items:
      - description: USB2/HS PHY
      - description: USB3/SS PHY

  phys:
    minItems: 1
    maxItems: 19

  phy-names:
    minItems: 1
    maxItems: 19
    oneOf:
      - items:
          enum: [ usb2-phy, usb3-phy ]
      - items:
          pattern: "^usb(2-([0-9]|1[0-4])|3-[0-3])$"

LPM, reserved endpoint와 초기 quirk

`snps,usb2-lpm-disable`은 host mode의 USB2 hardware LPM을, `snps,usb2-gadget-lpm-disable`은 gadget mode의 USB2 hardware LPM을 끕니다. `snps,usb3_lpm_capable`은 platform의 USB3 LPM 지원을 표시합니다.

`snps,reserved-endpoints`는 tracing 같은 다른 용도로 endpoint 2~31을 1~30개 예약해 일반 USB transfer에서 제외합니다. `snps,dis-start-transfer-quirk`는 DWC_usb31 1.70a-ea06 이하의 isochronous START TRANSFER 실패 workaround를 끄고, `snps,disable_scramble_quirk`는 주로 FPGA build에서 data scrambling을 끕니다.

`snps,has-lpm-erratum`은 LPM erratum 설정을 표시하고 `snps,lpm-nyet-threshold`는 8-bit NYET threshold를 지정합니다.

snps,usb2-lpm-disable:
  description: Indicate if we don't want to enable USB2 HW LPM for host
    mode.
  type: boolean

snps,usb3_lpm_capable:
  description: Determines if platform is USB3 LPM capable
  type: boolean

snps,usb2-gadget-lpm-disable:
  description: Indicate if we don't want to enable USB2 HW LPM for gadget
    mode.
  type: boolean

snps,reserved-endpoints:
  description:
    Reserve endpoints for other needs, e.g, for tracing control and output.
    When set, the driver will avoid using them for the regular USB transfers.
  $ref: /schemas/types.yaml#/definitions/uint8-array
  minItems: 1
  maxItems: 30
  items:
    minimum: 2
    maximum: 31

snps,dis-start-transfer-quirk:
  description:
    When set, disable isoc START TRANSFER command failure SW work-around
    for DWC_usb31 version 1.70a-ea06 and prior.
  type: boolean

snps,disable_scramble_quirk:
  description:
    True when SW should disable data scrambling. Only really useful for FPGA
    builds.
  type: boolean

snps,has-lpm-erratum:
  description: True when DWC3 was configured with LPM Erratum enabled
  type: boolean

snps,lpm-nyet-threshold:
  description: LPM NYET threshold
  $ref: /schemas/types.yaml#/definitions/uint8

U2·P-state·LFPS·TX de-emphasis

`snps,u2exit_lfps_quirk`는 U2 exit LFPS를, `snps,u2ss_inp3_quirk`는 U2/SS Inactive에서 P3 허용을 활성화합니다. `snps,req_p1p2p3_quirk`는 P1/P2/P3 전환 sequence를 항상 요청하고 `snps,del_p1p2p3_quirk`는 일정 수의 8B10B error가 생길 때까지 이를 지연합니다.

`snps,del_phy_power_chg_quirk`는 P0에서 P1/P2/P3로의 PHY power change를 지연합니다. LFPS filter, RX.Detect 뒤 400us polling 지연 제거, TX de-emphasis quirk도 선택할 수 있습니다. `snps,tx_de_emphasis` 값 0·1·2는 각각 -6dB, -3.5dB, de-emphasis 없음이며 USB3 compliance mode에서 LTSSM이 PHY 구동값을 제어합니다.

snps,u2exit_lfps_quirk:
  description: Set if we want to enable u2exit lfps quirk
  type: boolean

snps,u2ss_inp3_quirk:
  description: Set if we enable P3 OK for U2/SS Inactive quirk
  type: boolean

snps,req_p1p2p3_quirk:
  description:
    When set, the core will always request for P1/P2/P3 transition sequence.
  type: boolean

snps,del_p1p2p3_quirk:
  description:
    When set core will delay P1/P2/P3 until a certain amount of 8B10B errors
    occur.
  type: boolean

snps,del_phy_power_chg_quirk:
  description: When set core will delay PHY power change from P0 to P1/P2/P3.
  type: boolean

snps,lfps_filter_quirk:
  description: When set core will filter LFPS reception.
  type: boolean

snps,rx_detect_poll_quirk:
  description:
    when set core will disable a 400us delay to start Polling LFPS after
    RX.Detect.
  type: boolean

snps,tx_de_emphasis_quirk:
  description: When set core will set Tx de-emphasis value
  type: boolean

snps,tx_de_emphasis:
  description:
    The value driven to the PHY is controlled by the LTSSM during USB3
    Compliance mode.
  $ref: /schemas/types.yaml#/definitions/uint8
  enum:
    - 0 # -6dB de-emphasis
    - 1 # -3.5dB de-emphasis
    - 2 # No de-emphasis

suspend·U1/U2·park mode와 split quirk

USB3 또는 USB2 suspend PHY를 끄는 quirk, GUSB2PHYCFG의 `enblslpm`을 지워 PHY suspend signal을 끄는 quirk가 있습니다. U1·U2 entry, PHY P3 receiver detection, USB2 free-running clock 존재 표시, PHY power-change delay, HS transmit 중 u2mac line-state check도 각각 비활성화할 수 있습니다.

SuperSpeed·HighSpeed park mode를 따로 끌 수 있습니다. metastability workaround 비활성화는 확실한 경우에만 사용해야 합니다. `snps,dis-split-quirk`는 일부 장치의 usbhid `-EPROTO` 오류를 피하도록 driver의 URB 처리 방식을 바꿉니다.

snps,dis_u3_susphy_quirk:
  description: When set core will disable USB3 suspend phy
  type: boolean

snps,dis_u2_susphy_quirk:
  description: When set core will disable USB2 suspend phy
  type: boolean

snps,dis_enblslpm_quirk:
  description:
    When set clears the enblslpm in GUSB2PHYCFG, disabling the suspend signal
    to the PHY.
  type: boolean

snps,dis-u1-entry-quirk:
  description: Set if link entering into U1 needs to be disabled
  type: boolean

snps,dis-u2-entry-quirk:
  description: Set if link entering into U2 needs to be disabled
  type: boolean

snps,dis_rxdet_inp3_quirk:
  description:
    When set core will disable receiver detection in PHY P3 power state.
  type: boolean

snps,dis-u2-freeclk-exists-quirk:
  description:
    When set, clear the u2_freeclk_exists in GUSB2PHYCFG, specify that USB2
    PHY doesn't provide a free-running PHY clock.
  type: boolean

snps,dis-del-phy-power-chg-quirk:
  description:
    When set core will change PHY power from P0 to P1/P2/P3 without delay.
  type: boolean

snps,dis-tx-ipgap-linecheck-quirk:
  description: When set, disable u2mac linestate check during HS transmit
  type: boolean

snps,parkmode-disable-ss-quirk:
  description:
    When set, all SuperSpeed bus instances in park mode are disabled.
  type: boolean

snps,parkmode-disable-hs-quirk:
  description:
    When set, all HighSpeed bus instances in park mode are disabled.
  type: boolean

snps,dis_metastability_quirk:
  description:
    When set, disable metastability workaround. CAUTION! Use only if you are
    absolutely sure of it.
  type: boolean

snps,dis-split-quirk:
  description:
    When set, change the way URBs are handled by the driver. Needed to
    avoid -EPROTO errors with usbhid on some devices (Hikey 970).
  type: boolean

SOF clock, resume termination과 ULPI

`snps,gfladj-refclk-lpm-sel-quirk`는 SOF/ITP counter를 `ref_clk` 기준으로 동작시킵니다. `snps,resume-hs-terminations`는 resume 끝에 termsel·xcvrsel·opmode를 0으로 만들어 legacy ULPI PHY의 HS termination CRC 오류를 고칩니다.

내부 VBUS 공급을 지원하지 않는 ULPI PHY에서는 `snps,ulpi-ext-vbus-drv`가 DRVVBUSEXTERNAL을 설정해 USB2 PHY가 external supply로 VBUS를 구동하게 합니다. `snps,is-utmi-l1-suspend`는 `utmi_l1_suspend_n`과 `utmi_sleep_n` 중 어떤 output을 assert할지 정합니다.

`snps,hird-threshold`는 8-bit HIRD threshold이고 `snps,hsphy_interface`는 HSPHY interface 값 3일 때 UTMI+ 또는 ULPI를 선택합니다. frame-length adjustment는 GFLADJ_30MHZ에 0~0x3f를 쓰며, deprecated `snps,ref-clock-period-ns`는 실제 reference clock과 hardware default가 다를 때 GUCTL REFCLKPER에 8~62ns를 지정합니다. 대신 적절한 reference clock 제공이 권장됩니다.

snps,gfladj-refclk-lpm-sel-quirk:
  description:
    When set, run the SOF/ITP counter based on ref_clk.
  type: boolean

snps,resume-hs-terminations:
  description:
    Fix the issue of HS terminations CRC error on resume by enabling this
    quirk. When set, all the termsel, xcvrsel, opmode becomes 0 during end
    of resume. This option is to support certain legacy ULPI PHYs.
  type: boolean

snps,ulpi-ext-vbus-drv:
  description:
    Some ULPI USB PHY does not support internal VBUS supply, and driving
    the CPEN pin, requires the configuration of the ulpi DRVVBUSEXTERNAL
    bit. When set, the xhci host will configure the USB2 PHY drives VBUS
    with an external supply.
  type: boolean

snps,is-utmi-l1-suspend:
  description:
    True when DWC3 asserts output signal utmi_l1_suspend_n, false when
    asserts utmi_sleep_n.
  type: boolean

snps,hird-threshold:
  description: HIRD threshold
  $ref: /schemas/types.yaml#/definitions/uint8

snps,hsphy_interface:
  description:
    High-Speed PHY interface selection between UTMI+ and ULPI when the
    DWC_USB3_HSPHY_INTERFACE has value 3.
  $ref: /schemas/types.yaml#/definitions/string
  enum: [utmi, ulpi]

snps,quirk-frame-length-adjustment:
  description:
    Value for GFLADJ_30MHZ field of GFLADJ register for post-silicon frame
    length adjustment when the fladj_30mhz_sdbnd signal is invalid or
    incorrect.
  $ref: /schemas/types.yaml#/definitions/uint32
  minimum: 0
  maximum: 0x3f

snps,ref-clock-period-ns:
  description:
    Value for REFCLKPER field of GUCTL register for reference clock period in
    nanoseconds, when the hardware set default does not match the actual
    clock.

    This binding is deprecated. Instead, provide an appropriate reference clock.
  minimum: 8
  maximum: 62
  deprecated: true

일반 RX·TX threshold와 burst

`snps,rx-thr-num-pkt` 1~15는 host에서 RX transaction 시작 전 FIFO 여유 공간, device에서 flow-controlled endpoint가 ERDY를 보내기 전 공간을 정하며 SuperSpeed에서만 사용됩니다. `snps,rx-max-burst` 1~16은 host의 SS Bulk·Isochronous·Interrupt IN 최대 burst와 device OUT endpoint ERDY의 NUMP를 정합니다.

`snps,tx-thr-num-pkt` 1~15는 host와 device 모두에서 TXFIFO에 있어야 전송을 시작할 packet 수이며 SuperSpeed 전용입니다. `snps,tx-max-burst` 1~16은 느린 system bus에서 TX FIFO underrun을 피하도록 host SS Bulk·Isochronous·Interrupt OUT burst를 제한하며 device mode에서는 사용하지 않습니다.

snps,rx-thr-num-pkt:
  description:
    USB RX packet threshold count. In host mode, this field specifies
    the space that must be available in the RX FIFO before the core can
    start the corresponding USB RX transaction (burst).
    In device mode, this field specifies the space that must be
    available in the RX FIFO before the core can send ERDY for a
    flow-controlled endpoint. It is only used for SuperSpeed.
    The valid values for this field are from 1 to 15. (DWC3 SuperSpeed
    USB 3.0 Controller Databook)
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 15

snps,rx-max-burst:
  description:
    Max USB RX burst size. In host mode, this field specifies the
    Maximum Bulk IN burst the DWC_usb3 core can perform. When the system
    bus is slower than the USB, RX FIFO can overrun during a long burst.
    You can program a smaller value to this field to limit the RX burst
    size that the core can perform. It only applies to SS Bulk,
    Isochronous, and Interrupt IN endpoints in the host mode.
    In device mode, this field specifies the NUMP value that is sent in
    ERDY for an OUT endpoint.
    The valid values for this field are from 1 to 16. (DWC3 SuperSpeed
    USB 3.0 Controller Databook)
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 16

snps,tx-thr-num-pkt:
  description:
    USB TX packet threshold count. This field specifies the number of
    packets that must be in the TXFIFO before the core can start
    transmission for the corresponding USB transaction (burst).
    This count is valid in both host and device modes. It is only used
    for SuperSpeed operation.
    Valid values are from 1 to 15. (DWC3 SuperSpeed USB 3.0 Controller
    Databook)
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 15

snps,tx-max-burst:
  description:
    Max USB TX burst size. When the system bus is slower than the USB,
    TX FIFO can underrun during a long burst. Program a smaller value
    to this field to limit the TX burst size that the core can execute.
    In Host mode, it only applies to SS Bulk, Isochronous, and Interrupt
    OUT endpoints. This value is not used in device mode.
    Valid values are from 1 to 16. (DWC3 SuperSpeed USB 3.0 Controller
    Databook)
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 16

periodic ESS, TX FIFO resize와 INCR burst

host mode periodic ESS RX는 `snps,rx-thr-num-pkt-prd`와 `snps,rx-max-burst-prd`, TX는 `snps,tx-thr-num-pkt-prd`와 `snps,tx-max-burst-prd`를 함께 1~16의 non-zero 값으로 설정해야 활성화됩니다.

`tx-fifo-resize`는 사용 중인 IN endpoint 수와 bursting 지원에 따라 TX FIFO를 동적으로 조정해 높은 system latency에서 prefetch 공간과 bandwidth를 늘립니다. `tx-fifo-max-num`은 `bMaxBurst > 6`일 때 resizing logic이 고려할 최대 packet 수이며 최소 3입니다.

`snps,incr-burst-type-adjustment`는 GSBUSCFG0의 undefined-length INCR와 INCRx burst를 설정합니다. 단일 값이면 INCRX만, 여러 값이면 전달한 최대 길이까지 undefined-length INCR를 사용하며 허용값은 1, 4, 8, 16, 32, 64, 128, 256입니다.

snps,rx-thr-num-pkt-prd:
  description:
    Periodic ESS RX packet threshold count (host mode only). Set this and
    snps,rx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
    programming guide section 1.2.4) to enable periodic ESS RX threshold.
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 16

snps,rx-max-burst-prd:
  description:
    Max periodic ESS RX burst size (host mode only). Set this and
    snps,rx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
    programming guide section 1.2.4) to enable periodic ESS RX threshold.
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 16

snps,tx-thr-num-pkt-prd:
  description:
    Periodic ESS TX packet threshold count (host mode only). Set this and
    snps,tx-max-burst-prd to a valid, non-zero value 1-16 (DWC_usb31
    programming guide section 1.2.3) to enable periodic ESS TX threshold.
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 16

snps,tx-max-burst-prd:
  description:
    Max periodic ESS TX burst size (host mode only). Set this and
    snps,tx-thr-num-pkt-prd to a valid, non-zero value 1-16 (DWC_usb31
    programming guide section 1.2.3) to enable periodic ESS TX threshold.
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 1
  maximum: 16

tx-fifo-resize:
  description: Determines if the TX fifos can be dynamically resized depending
    on the number of IN endpoints used and if bursting is supported.  This
    may help improve bandwidth on platforms with higher system latencies, as
    increased fifo space allows for the controller to prefetch data into its
    internal memory.
  type: boolean

tx-fifo-max-num:
  description: Specifies the max number of packets the txfifo resizing logic
    can account for when higher endpoint bursting is used. (bMaxBurst > 6) The
    higher the number, the more fifo space the txfifo resizing logic will
    allocate for that endpoint.
  $ref: /schemas/types.yaml#/definitions/uint8
  minimum: 3

snps,incr-burst-type-adjustment:
  description:
    Value for INCR burst type of GSBUSCFG0 register, undefined length INCR
    burst type enable and INCRx type. A single value means INCRX burst mode
    enabled. If more than one value specified, undefined length INCR burst
    type will be enabled with burst lengths utilized up to the maximum
    of the values passed in this property.
  $ref: /schemas/types.yaml#/definitions/uint32-array
  minItems: 1
  maxItems: 8
  uniqueItems: true
  items:
    enum: [1, 4, 8, 16, 32, 64, 128, 256]

interrupter, Type-C connector와 graph port

`num-hc-interrupters`는 최대 8이고 기본값은 1입니다. dual-role switch용 `connector`는 공통 USB connector schema를 따릅니다.

단일 `port`는 `usb-role-switch`와 함께 DWC3를 Type-C connector에 연결합니다. 여러 data bus connector는 `ports` OF graph를 사용하며 `port@0`은 High Speed, `port@1`은 Super Speed bus입니다. `wakeup-source` flag는 USB remote wakeup을 활성화합니다.

num-hc-interrupters:
  maximum: 8
  default: 1

connector:
  $ref: /schemas/connector/usb-connector.yaml#
  description: Connector for dual role switch
  type: object
  unevaluatedProperties: false

port:
  $ref: /schemas/graph.yaml#/properties/port
  description:
    This port is used with the 'usb-role-switch' property  to connect the
    dwc3 to type C connector.

ports:
  $ref: /schemas/graph.yaml#/properties/ports
  description:
    Those ports should be used with any connector to the data bus of this
    controller using the OF graph bindings specified if the "usb-role-switch"
    property is used.

  properties:
    port@0:
      $ref: /schemas/graph.yaml#/properties/port
      description: High Speed (HS) data bus.

    port@1:
      $ref: /schemas/graph.yaml#/properties/port
      description: Super Speed (SS) data bus.

wakeup-source:
  $ref: /schemas/types.yaml#/definitions/flag
  description:
    Enable USB remote wakeup.

필수 속성과 확장 허용

필수 속성은 `compatible`과 `reg`입니다. vendor wrapper와 standalone 구현이 공통 정의를 확장할 수 있도록 추가 속성은 허용됩니다.

required:
  - compatible
  - reg

additionalProperties: true
...