MediaTek USB3 DRD Controller

MediaTek USB3 DRD controller

GPL-2.0-only 또는 BSD-2-Clause로 배포되는 이 schema는 MediaTek USB3 Dual-Role Device controller를 정의하고 공통 `usb-drd.yaml`을 상속합니다. DRD controller에는 IP Port Control(IPPC) glue layer가 있으며 host 기능은 xHCI를 기반으로 합니다. 관리자는 Chunfeng Yun입니다.

Compatible, MAC·IPPC와 interrupt

MT2712, MT8173, MT8183, MT8186, MT8188, MT8192, MT8195, MT8365 중 하나를 첫 compatible로 두고 `mediatek,mtu3` fallback을 이어서 지정합니다.

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

properties:
  compatible:
    items:
      - enum:
          - mediatek,mt2712-mtu3
          - mediatek,mt8173-mtu3
          - mediatek,mt8183-mtu3
          - mediatek,mt8186-mtu3
          - mediatek,mt8188-mtu3
          - mediatek,mt8192-mtu3
          - mediatek,mt8195-mtu3
          - mediatek,mt8365-mtu3
      - const: mediatek,mtu3

  reg:
    items:
      - description: the registers of device MAC
      - description: the registers of IP Port Control

  reg-names:
    items:
      - const: mac
      - const: ippc

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

  interrupt-names:
    items:
      - const: device
      - const: wakeup

Power, 여섯 clock과 PHY

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

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

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: DRD controller clock
    - description: Frame count clock

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

phys:
  description:
    List of all the USB PHYs used, it's better to keep the sequence
    as the hardware layout.
  minItems: 1
  items:
    - description: USB2/HS PHY    # required, others are optional
    - description: USB3/SS(P) PHY
    - description: USB2/HS PHY    # the following for backward compatible
    - 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

Supply, DRD mode와 role switch

`vusb33-supply`는 USB AVDD 3.3 V regulator입니다. `vbus-supply`는 dual-role VBUS 5 V용이지만 deprecated 상태입니다. GPIO로 VBUS regulator를 제어한다면 fixed regulator로 모델링해야 하며, 새 binding에서는 이 속성을 쓰지 않고 USB connector node에 둡니다.

`dr_mode`는 `host`, `peripheral`, `otg` 중 하나이며 기본값은 `otg`입니다. maximum speed는 SuperSpeedPlus부터 Full-Speed까지 선택할 수 있고 reset은 하나만 허용합니다. address cell과 size cell 수는 각각 1 또는 2이며 `ranges`를 사용합니다.

IDDIG 상태를 감지하는 `extcon` phandle도 호환성 목적으로만 남은 deprecated 속성입니다. 새 binding은 대신 `usb-role-switch`를 사용합니다. role switch 기본 mode는 `host`이며 `peripheral`로 바꿀 수 있습니다.

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

vbus-supply:
  deprecated: true
  description: |
    Regulator of USB VBUS5v, needed when supports dual-role mode.
    Particularly, if use an output GPIO to control a VBUS regulator, should
    model it as a regulator. See bindings/regulator/fixed-regulator.yaml
    It's considered valid for compatibility reasons, not allowed for
    new bindings, and put into a usb-connector node.

dr_mode:
  enum: [host, peripheral, otg]
  default: otg

maximum-speed:
  enum: [super-speed-plus, super-speed, high-speed, full-speed]

resets:
  maxItems: 1

"#address-cells":
  enum: [1, 2]

"#size-cells":
  enum: [1, 2]

ranges: true

extcon:
  deprecated: true
  description: |
    Phandle to the extcon device detecting the IDDIG state, needed
    when supports dual-role mode.
    It's considered valid for compatibility reasons, not allowed for
    new bindings, and use "usb-role-switch" property instead.

usb-role-switch:
  $ref: /schemas/types.yaml#/definitions/flag
  description: Support role switch.
  type: boolean

Connector graph와 manual DRD

`connector`는 dual-role switch용 USB connector이며 특히 `gpio-usb-b-connector`에 사용합니다. `usb-role-switch`를 쓰면 controller data bus의 connector를 OF graph `port`로 모델링해야 합니다.

복수 `ports`에서는 port 0이 High-Speed data bus, port 1이 SuperSpeed data bus입니다. `enable-manual-drd`는 보통 Type-A receptacle에서 dual-role도 지원하려 할 때 debugfs를 통한 수동 role 전환을 활성화합니다.

`wakeup-source`는 USB remote wakeup을 활성화합니다.

role-switch-default-mode:
  enum: [host, peripheral]
  default: host

connector:
  $ref: /schemas/connector/usb-connector.yaml#
  description:
    Connector for dual role switch, especially for "gpio-usb-b-connector"
  type: object

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. See graph.txt
  $ref: /schemas/graph.yaml#/properties/port

ports:
  $ref: /schemas/graph.yaml#/properties/ports

  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.

enable-manual-drd:
  $ref: /schemas/types.yaml#/definitions/flag
  description:
    supports manual dual-role switch via debugfs; usually used when
    receptacle is TYPE-A and also wants to support dual-role mode.
  type: boolean

wakeup-source:
  description: enable USB remote wakeup, see power/wakeup-source.txt
  type: boolean

Wakeup glue와 USB port disable mask

`mediatek,syscon-wakeup`은 xHCI와 SPM 사이 USB wakeup glue layer register에 접근하는 세 cell phandle array입니다. 첫 cell은 syscon phandle, 둘째는 register base address, 셋째는 hardware version입니다.

version 1은 IPM 규칙 이전 MT8173 계열, 2는 IPM 규칙을 따르는 MT2712 계열이며 101, 102, 103, 105, 106은 각각 MT8183, MT8192와 MT8195 IP0·IP2·IP3의 1.01·1.02·1.03·1.05·1.06별 값입니다.

`mediatek,u3p-dis-msk`와 `mediatek,u2p-dis-msk`는 각각 USB3·USB2 port disable bit mask입니다. dual-role mode가 활성화된 경우 USB2 port 0은 끌 수 없으므로 해당 bit를 건너뜁니다.

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 with 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;
          105 - used by mt8195, IP2, specific 1.05;
          106 - used by mt8195, IP3, specific 1.06;
        enum: [1, 2, 101, 102, 103, 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; but can't disable u2port0 if dual role mode
    is enabled, so will be skipped in this case.

xHCI child, 의존성과 필수 속성

dual-role에서 host mode를 활성화하면 16진 주소를 가진 `usb@...` xHCI node를 MTU3 child로 추가하고 `mediatek,mtk-xhci.yaml`을 따라야 합니다.

`connector`, `port`, `role-switch-default-mode`는 각각 `usb-role-switch`에 의존합니다. `wakeup-source`를 쓰면 `mediatek,syscon-wakeup`도 필요합니다.

필수 속성은 `compatible`, `reg`, `reg-names`, `interrupts`, `clocks`, `clock-names`이며 정의되지 않은 추가 속성은 허용하지 않습니다.

# Required child node when support dual-role
patternProperties:
  "^usb@[0-9a-f]+$":
    type: object
    $ref: /schemas/usb/mediatek,mtk-xhci.yaml#
    description:
      The xhci should be added as subnode to mtu3 as shown in the following
      example if the host mode is enabled.

dependencies:
  connector: [ usb-role-switch ]
  port: [ usb-role-switch ]
  role-switch-default-mode: [ usb-role-switch ]
  wakeup-source: [ 'mediatek,syscon-wakeup' ]

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

additionalProperties: false

MT8173 extcon dual-role 예제

첫 예제 MT8173 MTU3는 MAC·IPPC register, level-low GIC SPI 64, USB3·USB2 PHY, USB power domain과 `sys_ck`를 사용합니다. 3.3 V와 deprecated VBUS supply, `extcon`, OTG mode, wakeup glue offset 0x400 version 1을 지정합니다.

child xHCI는 register 0x11270000, level-low GIC SPI 115, `sys_ck`·`ref_ck`와 3.3 V regulator를 사용합니다.

examples:
  # Dual role switch by extcon
  - |
    #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@11271000 {
        compatible = "mediatek,mt8173-mtu3", "mediatek,mtu3";
        reg = <0x11271000 0x3000>, <0x11280700 0x0100>;
        reg-names = "mac", "ippc";
        interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_LOW>;
        phys = <&phy_port0 PHY_TYPE_USB3>, <&phy_port1 PHY_TYPE_USB2>;
        power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>;
        clocks = <&topckgen CLK_TOP_USB30_SEL>;
        clock-names = "sys_ck";
        vusb33-supply = <&mt6397_vusb_reg>;
        vbus-supply = <&usb_p0_vbus>;
        extcon = <&extcon_usb>;
        dr_mode = "otg";
        wakeup-source;
        mediatek,syscon-wakeup = <&pericfg 0x400 1>;
        #address-cells = <1>;
        #size-cells = <1>;
        ranges;

        xhci: usb@11270000 {
            compatible = "mediatek,mt8173-xhci", "mediatek,mtk-xhci";
            reg = <0x11270000 0x1000>;
            reg-names = "mac";
            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";
            vusb33-supply = <&mt6397_vusb_reg>;
        };
    };

MT2712 GPIO USB-B connector 예제

둘째 예제 MT2712 MTU3는 USB2 PHY와 OTG mode, `usb-role-switch`를 사용하며 host xHCI child를 포함합니다.

`gpio-usb-b-connector`는 micro 타입이고 active-high GPIO 12로 ID를 감지하며 `usb_p0_vbus` regulator를 연결합니다.

# Dual role switch by gpio-usb-b-connector
- |
  #include <dt-bindings/gpio/gpio.h>
  #include <dt-bindings/power/mt2712-power.h>

  usb@112c1000 {
      compatible = "mediatek,mt2712-mtu3", "mediatek,mtu3";
      reg = <0x112c1000 0x3000>, <0x112d0700 0x0100>;
      reg-names = "mac", "ippc";
      interrupts = <GIC_SPI 248 IRQ_TYPE_LEVEL_LOW>;
      phys = <&u2port2 PHY_TYPE_USB2>;
      power-domains = <&scpsys MT2712_POWER_DOMAIN_USB2>;
      clocks = <&topckgen CLK_TOP_USB30_SEL>;
      clock-names = "sys_ck";
      dr_mode = "otg";
      usb-role-switch;
      #address-cells = <1>;
      #size-cells = <1>;
      ranges;

      host0: usb@11270000 {
          compatible = "mediatek,mt2712-xhci", "mediatek,mtk-xhci";
          reg = <0x11270000 0x1000>;
          reg-names = "mac";
          interrupts = <GIC_SPI 123 IRQ_TYPE_LEVEL_LOW>;
          power-domains = <&scpsys MT2712_POWER_DOMAIN_USB>;
          clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>;
          clock-names = "sys_ck", "ref_ck";
      };

      connector {
          compatible = "gpio-usb-b-connector", "usb-b-connector";
          type = "micro";
          id-gpios = <&pio 12 GPIO_ACTIVE_HIGH>;
          vbus-supply = <&usb_p0_vbus>;
      };
  };

MT8183 Type-C role switch 예제

셋째 예제 MT8183 MTU3는 USB2 PHY, 26 MHz system clock, wakeup glue offset 0x400 version 1, OTG mode와 role switch를 사용하며 기본 role을 `host`로 둡니다.

child xHCI는 level-low GIC SPI 73을 사용합니다. MTU3의 graph endpoint `usb_role_sw`는 Type-C 측 High-Speed endpoint `hs_ep`와 상호 연결됩니다.

  # Dual role switch with type-c
  - |
    usb@11201000 {
        compatible = "mediatek,mt8183-mtu3", "mediatek,mtu3";
        reg = <0x11201000 0x2e00>, <0x11203e00 0x0100>;
        reg-names = "mac", "ippc";
        interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_LOW>;
        phys = <&u2port0 PHY_TYPE_USB2>;
        clocks = <&clk26m>;
        clock-names = "sys_ck";
        mediatek,syscon-wakeup = <&pericfg 0x400 1>;
        wakeup-source;
        dr_mode = "otg";
        usb-role-switch;
        role-switch-default-mode = "host";
        #address-cells = <1>;
        #size-cells = <1>;
        ranges;

        host: usb@11200000 {
            compatible = "mediatek,mt8183-xhci", "mediatek,mtk-xhci";
            reg = <0x11200000 0x1000>;
            reg-names = "mac";
            interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_LOW>;
            clocks = <&clk26m>;
            clock-names = "sys_ck";
        };

        port {
            usb_role_sw: endpoint {
                remote-endpoint = <&hs_ep>;
            };
        };
    };

...