USB2 ChipIdea USB Controller Common Properties

USB2 ChipIdea 공통 속성

GPL-2.0-only 또는 BSD-2-Clause 라이선스의 이 schema는 USB2 ChipIdea controller의 공통 속성을 정의합니다. 관리자는 Xu Yang입니다.

Register, interrupt, clock와 reset

`reg`와 `interrupts`는 각각 1~2개, `clocks`와 `clock-names`는 각각 1~3개입니다. `dr_mode`를 지원하며 `power-domains`, `resets`, `reset-names`, `iommus`는 각각 최대 한 항목입니다.

Reset controller로 동작할 때 `#reset-cells = 1`입니다. `phy_type`을 지원합니다.

properties:
  reg:
    minItems: 1
    maxItems: 2

  interrupts:
    minItems: 1
    maxItems: 2

  clocks:
    minItems: 1
    maxItems: 3

  clock-names:
    minItems: 1
    maxItems: 3

  dr_mode: true

  power-domains:
    maxItems: 1

  resets:
    maxItems: 1

  reset-names:
    maxItems: 1

  "#reset-cells":
    const: 1

  phy_type: true

  iommus:
    maxItems: 1

ITC와 AHB TX·RX burst

`itc-setting`은 USBCMD register의 ITC bit와 일치해야 하는 interrupt threshold control uint32 값입니다. `ahb-burst-config`는 SBUSCFG의 AHBBRST와 일치하는 vendor별 값으로 범위는 0x0~0x7입니다. 값의 의미는 ChipIdea 사양을 따르며 속성이 없으면 hardware reset 값을 사용합니다.

`tx-burst-size-dword`는 system memory에서 USB bus로 이동할 때, `rx-burst-size-dword`는 USB bus에서 system memory로 이동할 때의 최대 burst 길이를 32-bit word, 즉 4-byte 단위로 지정합니다. 둘 다 범위는 0x0~0x20이고 `ahb-burst-config = 0`일 때만 적용되며, 생략하면 구현의 reset 기본값을 사용합니다.

itc-setting:
  description:
    interrupt threshold control register control, the setting should be
    aligned with ITC bits at register USBCMD.
  $ref: /schemas/types.yaml#/definitions/uint32

ahb-burst-config:
  description:
    it is vendor dependent, the required value should be aligned with
    AHBBRST at SBUSCFG, the range is from 0x0 to 0x7. This property is
    used to change AHB burst configuration, check the chipidea spec for
    meaning of each value. If this property is not existed, it will use
    the reset value.
  $ref: /schemas/types.yaml#/definitions/uint32
  minimum: 0x0
  maximum: 0x7

tx-burst-size-dword:
  description:
    it is vendor dependent, the tx burst size in dword (4 bytes), This
    register represents the maximum length of a the burst in 32-bit
    words while moving data from system memory to the USB bus, the value
    of this property will only take effect if property "ahb-burst-config"
    is set to 0, if this property is missing the reset default of the
    hardware implementation will be used.
  $ref: /schemas/types.yaml#/definitions/uint32
  minimum: 0x0
  maximum: 0x20

rx-burst-size-dword:
  description:
    it is vendor dependent, the rx burst size in dword (4 bytes), This
    register represents the maximum length of a the burst in 32-bit words
    while moving data from the USB bus to system memory, the value of
    this property will only take effect if property "ahb-burst-config"
    is set to 0, if this property is missing the reset default of the
    hardware implementation will be used.
  $ref: /schemas/types.yaml#/definitions/uint32
  minimum: 0x0
  maximum: 0x20

Extcon 순서와 PHY clock gate 지연

`extcon` phandle 배열의 첫 항목은 `USB` cable event를 제공하는 VBUS extcon이고, 두 번째 항목은 `USB-HOST` event를 제공하는 ID extcon입니다. 어느 connector가 필요하지 않으면 그 위치에 빈 `<0>` phandle을 넣어 순서를 보존합니다.

`phy-clkgate-delay-us`는 PHY를 low-power mode로 전환한 뒤 PHY clock을 gate하기까지의 지연 시간을 microsecond 단위로 지정합니다.

extcon:
  description:
    Phandles to external connector devices. First phandle should point
    to external connector, which provide "USB" cable events, the second
    should point to external connector device, which provide "USB-HOST"
    cable events. If one of the external connector devices is not
    required, empty <0> phandle should be specified.
  $ref: /schemas/types.yaml#/definitions/phandle-array
  minItems: 1
  items:
    - description: vbus extcon
    - description: id extcon

phy-clkgate-delay-us:
  description:
    The delay time (us) between putting the PHY into low power mode and
    gating the PHY clock.

TTCTRL TTHA의 transaction trade-off

Boolean `non-zero-ttctrl-ttha`를 설정하면 `ttctrl.ttha`가 0x7f가 되고, 설정하지 않으면 기본값 0x0입니다. 대부분의 ChipIdea platform에서 RTL `usage_tt` flag가 0이므로 이 속성은 siTD에만 영향을 줍니다. 설정 전 IC engineer와 협의하는 것이 권장됩니다.

설정하지 않으면 최대 packet 크기는 1023 byte이며 이전 transaction packet 합계가 256 byte를 넘으면 같은 frame에서 추가 transaction을 받을 수 없습니다. 이는 transaction 수가 하나인 대신 frame rate가 높은 경우입니다.

설정하면 최대 packet 크기는 188 byte이고 frame의 남은 공간이 188 byte보다 작다고 판단할 때까지 더 많은 transaction을 처리할 수 있습니다. Software는 `maximum_periodic_data_per_frame`의 90%를 넘겨 보내지 않아야 하며, 여러 transaction을 처리하는 대신 frame rate가 낮은 경우입니다.

non-zero-ttctrl-ttha:
  description:
    After setting this property, the value of register ttctrl.ttha
    will be 0x7f; if not, the value will be 0x0, this is the default
    value. It needs to be very carefully for setting this property, it
    is recommended that consult with your IC engineer before setting
    this value.  On the most of chipidea platforms, the "usage_tt" flag
    at RTL is 0, so this property only affects siTD.

    If this property is not set, the max packet size is 1023 bytes, and
    if the total of packet size for previous transactions are more than
    256 bytes, it can't accept any transactions within this frame. The
    use case is single transaction, but higher frame rate.

    If this property is set, the max packet size is 188 bytes, it can
    handle more transactions than above case, it can accept transactions
    until it considers the left room size within frame is less than 188
    bytes, software needs to make sure it does not send more than 90%
    maximum_periodic_data_per_frame. The use case is multiple
    transactions, but less frame rate.
  type: boolean

Host/device mux와 pinctrl mode

`mux-controls`는 controller의 host/device 출력을 전환합니다. Mux state 0은 device mode, state 1은 host mode여야 하며 최대 한 항목입니다. 이름은 `usb_switch`입니다.

선택적인 pin mode는 `default`, `host`, `device` 조합을 사용할 수 있습니다. HSIC mode에서는 `idle`, `active`가 필수이며 idle state는 data와 strobe pin을 pull-down하고 active state는 strobe pin을 pull-up해야 합니다. `pinctrl-0`과 `pinctrl-1`은 각각 최대 한 항목입니다.

mux-controls:
  description:
    The mux control for toggling host/device output of this controller.
    It's expected that a mux state of 0 indicates device mode and a mux
    state of 1 indicates host mode.
  maxItems: 1

mux-control-names:
  const: usb_switch

pinctrl-names:
  description:
    Names for optional pin modes in "default", "host", "device".
    In case of HSIC-mode, "idle" and "active" pin modes are mandatory.
    In this case, the "idle" state needs to pull down the data and
    strobe pin and the "active" state needs to pull up the strobe pin.
  oneOf:
    - items:
        - const: idle
        - const: active
    - items:
        - const: default
        - const: host
        - const: device
    - items:
        - const: default
        - enum:
            - host
            - device
    - items:
        - const: default

pinctrl-0:
  maxItems: 1

pinctrl-1:
  maxItems: 1

PHY, VBUS, role-switch port와 reset GPIO

`phys`는 최대 한 항목이고 `phy-names`는 `usb-phy`입니다. `vbus-supply`는 VBUS regulator를 참조합니다. 예전 `usb-phy` phandle 속성은 폐기되었으므로 대신 `phys`를 사용해야 합니다.

`usb-role-switch`를 사용하면 controller data bus의 connector를 OF graph binding에 따라 `port`로 모델링해야 합니다. `reset-gpios`는 최대 한 항목입니다.

phys:
  maxItems: 1

phy-names:
  const: usb-phy

vbus-supply:
  description: reference to the VBUS regulator.

usb-phy:
  description: phandle for the PHY device. Use "phys" instead.
  maxItems: 1
  deprecated: true

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

reset-gpios:
  maxItems: 1

Dependency와 공통 USB schema

`port`에는 `usb-role-switch`가 필요하고 `mux-controls`에는 `mux-control-names`가 필요합니다. 필수 속성은 `reg`, `interrupts`입니다. Host와 dual-role 공통 속성을 위해 `usb-hcd.yaml`과 `usb-drd.yaml`을 모두 참조하며 vendor 확장을 위해 추가 속성을 허용합니다.

dependencies:
  port: [ usb-role-switch ]
  mux-controls: [ mux-control-names ]

required:
  - reg
  - interrupts

allOf:
  - $ref: usb-hcd.yaml#
  - $ref: usb-drd.yaml#

additionalProperties: true