[PATCH v5 10/11] dt-bindings: usb: convert mediatek,mtu3.txt to YAML schema
From: Chunfeng Yun
Date: Fri Dec 25 2020 - 02:55:01 EST
Convert mediatek,mtu3.txt to YAML schema mediatek,mtu3.yaml
Signed-off-by: Chunfeng Yun <chunfeng.yun@xxxxxxxxxxxx>
---
v5: changes suggested by Rob
1. remove unnecessary maxItems
2. define all phys supported
v4:
1. refer to usb-drd.yaml insstead of usb/generic.txt
the following ones suggested by Rob:
2. add the number of phys supported
3. fix indentation of wakeup
4. add examples for port and connector
v3:
1. fix yamllint warning
2. remove pinctrl* properties
3. remove unnecessary '|'
4. drop unused labels in example
v2: new patch
---
.../devicetree/bindings/usb/mediatek,mtu3.txt | 108 -------
.../bindings/usb/mediatek,mtu3.yaml | 287 ++++++++++++++++++
2 files changed, 287 insertions(+), 108 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
create mode 100644 Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml
diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
deleted file mode 100644
index a82ca438aec1..000000000000
--- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt
+++ /dev/null
@@ -1,108 +0,0 @@
-The device node for Mediatek USB3.0 DRD controller
-
-Required properties:
- - compatible : should be "mediatek,<soc-model>-mtu3", "mediatek,mtu3",
- soc-model is the name of SoC, such as mt8173, mt2712 etc,
- when using "mediatek,mtu3" compatible string, you need SoC specific
- ones in addition, one of:
- - "mediatek,mt8173-mtu3"
- - reg : specifies physical base address and size of the registers
- - reg-names: should be "mac" for device IP and "ippc" for IP port control
- - interrupts : interrupt used by the device IP
- - power-domains : a phandle to USB power domain node to control USB's
- mtcmos
- - vusb33-supply : regulator of USB avdd3.3v
- - clocks : a list of phandle + clock-specifier pairs, one for each
- entry in clock-names
- - clock-names : must contain "sys_ck" for clock of controller,
- the following clocks are optional:
- "ref_ck", "mcu_ck" and "dma_ck";
- - phys : see usb-hcd.yaml in the current directory
- - dr_mode : should be one of "host", "peripheral" or "otg",
- refer to usb/generic.txt
-
-Optional properties:
- - #address-cells, #size-cells : should be '2' if the device has sub-nodes
- with 'reg' property
- - ranges : allows valid 1:1 translation between child's address space and
- parent's address space
- - extcon : external connector for vbus and idpin changes detection, 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.
- - vbus-supply : reference to the VBUS regulator, needed when supports
- dual-role mode.
- it's considered valid for compatibility reasons, not allowed for
- new bindings, and put into a usb-connector node.
- see connector/usb-connector.yaml.
- - pinctrl-names : a pinctrl state named "default" is optional, and need be
- defined if auto drd switch is enabled, that means the property dr_mode
- is set as "otg", and meanwhile the property "mediatek,enable-manual-drd"
- is not set.
- - pinctrl-0 : pin control group
- See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
-
- - maximum-speed : valid arguments are "super-speed", "high-speed" and
- "full-speed"; refer to usb/generic.txt
- - usb-role-switch : use USB Role Switch to support dual-role switch, but
- not extcon; see usb/generic.txt.
- - enable-manual-drd : supports manual dual-role switch via debugfs; usually
- used when receptacle is TYPE-A and also wants to support dual-role
- mode.
- - wakeup-source: enable USB remote wakeup of host mode.
- - mediatek,syscon-wakeup : phandle to syscon used to access the register
- of the USB wakeup glue layer between SSUSB and SPM; it depends on
- "wakeup-source", and has two arguments:
- - the first one : register base address of the glue layer in syscon;
- - the second one : hardware version of the glue layer
- - 1 : used by mt8173 etc
- - 2 : used by mt2712 etc
- - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0,
- bit1 for u3port1, ... etc;
-
-additionally the properties from usb-hcd.yaml (in the current directory) are
-supported.
-
-Sub-nodes:
-The xhci should be added as subnode to mtu3 as shown in the following example
-if host mode is enabled. The DT binding details of xhci can be found in:
-Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt
-
-The port would be added as subnode if use "usb-role-switch" property.
- see graph.txt
-
-Example:
-ssusb: usb@11271000 {
- compatible = "mediatek,mt8173-mtu3";
- reg = <0 0x11271000 0 0x3000>,
- <0 0x11280700 0 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>, <&clk26m>,
- <&pericfg CLK_PERI_USB0>,
- <&pericfg CLK_PERI_USB1>;
- clock-names = "sys_ck", "ref_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 = <2>;
- #size-cells = <2>;
- ranges;
-
- usb_host: xhci@11270000 {
- compatible = "mediatek,mt8173-xhci";
- reg = <0 0x11270000 0 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>;
- };
-};
diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml
new file mode 100644
index 000000000000..f5c04b9d2de9
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml
@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2020 MediaTek
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/mediatek,mtu3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek USB3 DRD Controller Device Tree Bindings
+
+maintainers:
+ - Chunfeng Yun <chunfeng.yun@xxxxxxxxxxxx>
+
+allOf:
+ - $ref: "usb-drd.yaml"
+
+description: |
+ The DRD controller has a glue layer IPPC (IP Port Control), and its host is
+ based on xHCI.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - mediatek,mt2712-mtu3
+ - mediatek,mt8173-mtu3
+ - mediatek,mt8183-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:
+ maxItems: 1
+
+ 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
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: sys_ck # required, others are optional
+ - const: ref_ck
+ - const: mcu_ck
+ - const: dma_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
+
+ 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]
+
+ "#address-cells":
+ enum: [1, 2]
+
+ "#size-cells":
+ enum: [1, 2]
+
+ ranges: true
+
+ extcon:
+ deprecated: true
+ description: |
+ Phandle to the extcon device detecting the IDDIG/VBUS state, neede
+ 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:
+ $ref: /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
+ type: object
+
+ 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
+
+ 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 is used by mt8173 etc, 2 is used by mt2712 etc
+ enum: [1, 2]
+
+ mediatek,u3p-dis-msk:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The mask to disable u3ports, bit0 for u3port0,
+ bit1 for u3port1, ... etc
+
+# Required child node when support dual-role
+patternProperties:
+ "^usb@[0-9a-f]+$":
+ type: object
+ $ref: /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' ]
+ wakeup-source: [ 'mediatek,syscon-wakeup' ]
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+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>;
+ };
+ };
+
+ # Enable/disable device by an input gpio for VBUS pin
+ - |
+ #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 = "peripheral";
+ usb-role-switch;
+
+ connector {
+ compatible = "gpio-usb-b-connector", "usb-b-connector";
+ type = "micro";
+ vbus-gpios = <&pio 13 GPIO_ACTIVE_HIGH>;
+ };
+ };
+
+ # 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;
+ #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>;
+ };
+ };
+ };
+
+...
--
2.18.0