MediaTek USB3 xHCI

MediaTek USB3 xHCI의 두 시나리오

GPL-2.0-only 또는 BSD-2-Clause로 배포되는 이 schema는 MediaTek USB3 xHCI controller를 정의하고 공통 `usb-xhci.yaml`을 상속합니다. 관리자는 Chunfeng Yun입니다.

두 동작 시나리오를 지원합니다. case 1은 xHCI driver만 사용하는 host 전용 구성이고, case 2는 xHCI 기반 host를 포함하는 dual-role 구성입니다.

SoC compatible, register와 interrupt

MT2701, MT2712, MT7622, MT7623, MT7629, MT7986, MT7988, MT8173, MT8183, MT8186, MT8188, MT8192, MT8195, MT8365 중 하나를 첫 compatible로 두고 `mediatek,mtk-xhci` fallback을 이어서 지정합니다.

register는 xHCI MAC용 `mac`이 필수이고 IP Port Control용 `ippc`는 case 1에서만 필요합니다. interrupt는 host interrupt가 필수이고 runtime PM wakeup interrupt는 선택적이며, 서로 다른 interrupt controller에 연결되면 `interrupts-extended`를 사용합니다. 이름은 `host`, `wakeup` 순서입니다.

properties:
  # common properties for both case 1 and case 2
  compatible:
    items:
      - enum:
          - mediatek,mt2701-xhci
          - mediatek,mt2712-xhci
          - mediatek,mt7622-xhci
          - mediatek,mt7623-xhci
          - mediatek,mt7629-xhci
          - mediatek,mt7986-xhci
          - mediatek,mt7988-xhci
          - mediatek,mt8173-xhci
          - mediatek,mt8183-xhci
          - mediatek,mt8186-xhci
          - mediatek,mt8188-xhci
          - mediatek,mt8192-xhci
          - mediatek,mt8195-xhci
          - mediatek,mt8365-xhci
      - const: mediatek,mtk-xhci

  reg:
    minItems: 1
    items:
      - description: the registers of xHCI MAC
      - description: the registers of IP Port Control

  reg-names:
    minItems: 1
    items:
      - const: mac
      - const: ippc  # optional, only needed for case 1.

  interrupts:
    description:
      use "interrupts-extended" when the interrupts are connected to the
      separate interrupt controllers
    minItems: 1
    items:
      - description: xHCI host controller interrupt
      - description: optional, wakeup interrupt used to support runtime PM

  interrupt-names:
    minItems: 1
    items:
      - const: host
      - const: wakeup

Power, 여섯 clock, PHY와 LPM

`power-domains`는 USB MTCMOS를 제어하는 power domain 하나를 가리킵니다. clock은 normal-mode controller, low-power reference, MCU bus, DMA bus, controller, frame-count 순서이며 이름은 `sys_ck`, `ref_ck`, `mcu_ck`, `dma_ck`, `xhci_ck`, `frmcnt_ck`입니다. 첫 `sys_ck`만 필수입니다.

PHY 목록은 hardware 배치 순서를 따르는 것이 좋으며 첫 USB2/HS PHY가 필수입니다. 그 뒤 USB3/SSP와 USB2/HS PHY를 번갈아 최대 아홉 항목까지 둘 수 있습니다.

`port`는 Type-C connector로 향하는 SuperSpeed output endpoint입니다. AVDD 3.3 V와 VBUS 5 V regulator, reset 하나를 지원합니다. USB3 LPM 지원과 USB2 LPM 비활성화를 표시할 수 있습니다.

`imod-interval-ns`는 MediaTek controller에서 xHCI 규격 값의 8배로 해석되는 interrupt moderation interval이며 기본값은 5,000 ns입니다.

power-domains:
  description: A phandle to USB power domain node to control USB's MTCMOS
  maxItems: 1

clocks:
  minItems: 1
  items:
    - description: Controller clock used by normal mode
    - description: Reference clock used by low power mode etc
    - description: Mcu bus clock for register access
    - description: DMA bus clock for data transfer
    - description: controller clock
    - description: frame count clock

clock-names:
  minItems: 1
  items:
    - const: sys_ck  # required, the following ones are optional
    - const: ref_ck
    - const: mcu_ck
    - const: dma_ck
    - const: xhci_ck
    - const: frmcnt_ck

phys:
  description:
    List of all PHYs used on this HCD, it's better to keep PHYs in order
    as the hardware layout
  minItems: 1
  items:
    - description: USB2/HS PHY    # required, others are optional
    - description: USB3/SS(P) PHY
    - description: USB2/HS PHY
    - description: USB3/SS(P) PHY
    - description: USB2/HS PHY
    - description: USB3/SS(P) PHY
    - description: USB2/HS PHY
    - description: USB3/SS(P) PHY
    - description: USB2/HS PHY

port:
  $ref: /schemas/graph.yaml#/properties/port
  description: Super Speed (SS) Output endpoint to a Type-C connector

vusb33-supply:
  description: Regulator of USB AVDD3.3v

vbus-supply:
  description: Regulator of USB VBUS5v

resets:
  maxItems: 1

usb3-lpm-capable: true

usb2-lpm-disable: true

imod-interval-ns:
  description:
    Interrupt moderation interval value, it is 8 times as much as that
    defined in the xHCI spec on MTK's controller.
  default: 5000

Gen1 isoc-in FIFO workaround

`rx-fifo-depth`는 약 IPM v1.6.0 이전 controller에서 Gen1 isochronous IN endpoint가 short packet으로 burst를 끝낸 뒤 예기치 않은 ACK를 보내 exception을 일으키는 문제를 우회합니다. 특히 4K camera에서 나타날 수 있습니다.

이 workaround는 bulk transfer를 포함해 성능을 약 10% 낮출 수 있으므로 3 KiB 사용을 권장합니다. byte 단위 허용값은 1,024, 2,048, 3,072, 4,096입니다.

rx-fifo-depth:
  $ref: /schemas/types.yaml#/definitions/uint32
  description:
    It is a quirk used to work around Gen1 isoc-in endpoint transfer issue
    that still send out unexpected ACK after device finishes the burst
    transfer with a short packet and cause an exception, specially on a 4K
    camera device, it happens on controller before about IPM v1.6.0;
    the side-effect is that it may cause performance drop about 10%,
    including bulk transfer, prefer to use 3k here. The size is in bytes.
  enum: [1024, 2048, 3072, 4096]

Case 1 wakeup glue와 port mask

case 1 전용 `wakeup-source`는 USB remote wakeup을 활성화합니다. `mediatek,syscon-wakeup`은 xHCI와 SPM 사이 USB wakeup glue layer register에 접근하는 세 cell phandle array입니다.

첫 cell은 syscon phandle, 둘째는 glue register base address, 셋째는 hardware version입니다. version 1은 IPM 규칙 이전 MT8173 계열, 2는 IPM 규칙을 따르는 MT2712 계열이며 101~106은 MT8183, MT8192, MT8195 IP0~IP3의 1.01~1.06별 값입니다.

`mediatek,u3p-dis-msk`와 `mediatek,u2p-dis-msk`는 각각 USB3·USB2 port를 끄는 bit mask이며 bit 0은 port 0, bit 1은 port 1에 대응합니다.

# the following properties are only used for case 1
wakeup-source:
  description: enable USB remote wakeup, see power/wakeup-source.txt
  type: boolean

mediatek,syscon-wakeup:
  $ref: /schemas/types.yaml#/definitions/phandle-array
  maxItems: 1
  description:
    A phandle to syscon used to access the register of the USB wakeup glue
    layer between xHCI and SPM, the field should always be 3 cells long.
  items:
    items:
      - description:
          The first cell represents a phandle to syscon
      - description:
          The second cell represents the register base address of the glue
          layer in syscon
      - description: |
          The third cell represents the hardware version of the glue layer,
          1 - used by mt8173 etc, revision 1 without following IPM rule;
          2 - used by mt2712 etc, revision 2 following IPM rule;
          101 - used by mt8183, specific 1.01;
          102 - used by mt8192, specific 1.02;
          103 - used by mt8195, IP0, specific 1.03;
          104 - used by mt8195, IP1, specific 1.04;
          105 - used by mt8195, IP2, specific 1.05;
          106 - used by mt8195, IP3, specific 1.06;
        enum: [1, 2, 101, 102, 103, 104, 105, 106]

mediatek,u3p-dis-msk:
  $ref: /schemas/types.yaml#/definitions/uint32
  description: The mask to disable u3ports, bit0 for u3port0,
    bit1 for u3port1, ... etc

mediatek,u2p-dis-msk:
  $ref: /schemas/types.yaml#/definitions/uint32
  description: The mask to disable u2ports, bit0 for u2port0,
    bit1 for u2port1, ... etc

Hard-wired device와 필수 속성

address cell 수는 1, size cell 수는 0입니다. 한 자리 16진 unit address 형태의 child는 hard-wired USB device를 나타냅니다.

`wakeup-source`를 쓰면 `mediatek,syscon-wakeup`도 반드시 필요합니다. 필수 속성은 `compatible`, `reg`, `reg-names`, `interrupts`, `clocks`, `clock-names`이며 정의되지 않은 추가 속성은 허용하지 않습니다.

  "#address-cells":
    const: 1

  "#size-cells":
    const: 0

patternProperties:
  "@[0-9a-f]{1}$":
    type: object
    description: The hard wired USB devices.

dependencies:
  wakeup-source: [ 'mediatek,syscon-wakeup' ]

required:
  - compatible
  - reg
  - reg-names
  - interrupts
  - clocks
  - clock-names

additionalProperties: false

MT8173 host 전용 xHCI 예제

예제 `usb@11270000`은 MT8173 및 generic MediaTek xHCI compatible, MAC·IPPC register, level-low GIC SPI 115, USB power domain을 사용합니다.

`sys_ck`와 `ref_ck`, USB3 port 0과 USB2 port 1 PHY, 3.3 V·VBUS regulator를 연결합니다. moderation interval은 10,000 ns이고 wakeup syscon은 offset 0x400과 hardware version 1을 사용하며 wakeup과 USB3 LPM을 활성화합니다.

examples:
  - |
    #include <dt-bindings/clock/mt8173-clk.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/phy/phy.h>
    #include <dt-bindings/power/mt8173-power.h>

    usb@11270000 {
        compatible = "mediatek,mt8173-xhci", "mediatek,mtk-xhci";
        reg = <0x11270000 0x1000>, <0x11280700 0x0100>;
        reg-names = "mac", "ippc";
        interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>;
        power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>;
        clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>;
        clock-names = "sys_ck", "ref_ck";
        phys = <&u3port0 PHY_TYPE_USB3>, <&u2port1 PHY_TYPE_USB2>;
        vusb33-supply = <&mt6397_vusb_reg>;
        vbus-supply = <&usb_p1_vbus>;
        imod-interval-ns = <10000>;
        mediatek,syscon-wakeup = <&pericfg 0x400 1>;
        wakeup-source;
        usb3-lpm-capable;
    };
...