diff mbox series

[07/18] dt-bindings: usb: Convert xHCI bindings to DT schema

Message ID 20201010224121.12672-8-Sergey.Semin@baikalelectronics.ru
State Superseded
Headers show
Series dt-bindings: usb: Add generic USB HCD, xHCI, DWC USB3 DT schema | expand

Commit Message

Serge Semin Oct. 10, 2020, 10:41 p.m. UTC
Currently the DT bindings of Generic xHCI Controllers are described by means
of the legacy text file. Since such format is deprecated in favor of the
DT schema, let's convert the Generic xHCI Controllers bindings file to the
corresponding yaml files. There will be two of them: a DT schema for the
xHCI controllers on a generic platform and a DT schema validating a generic
xHCI controllers properties. The later will be used to validate the xHCI
controllers, which aside from some vendor-specific features support the
basic xHCI functionality.

An xHCI-compatible DT node shall support the standard USB HCD properties
and custom ones like: usb2-lpm-disable, usb3-lpm-capable,
quirk-broken-port-ped and imod-interval-ns. In addition if a generic xHCI
controller is being validated against the DT schema it is also supposed to
be equipped with mandatory compatible string, single registers range,
single interrupts source, and is supposed to optionally contain up to two
reference clocks for the controller core and CSRs.

Signed-off-by: Serge Semin <Sergey.Semin@baikalelectronics.ru>
---
 .../devicetree/bindings/usb/generic-xhci.yaml | 63 +++++++++++++++++++
 .../devicetree/bindings/usb/usb-xhci.txt      | 41 ------------
 .../devicetree/bindings/usb/usb-xhci.yaml     | 40 ++++++++++++
 3 files changed, 103 insertions(+), 41 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/usb/generic-xhci.yaml
 delete mode 100644 Documentation/devicetree/bindings/usb/usb-xhci.txt
 create mode 100644 Documentation/devicetree/bindings/usb/usb-xhci.yaml

Comments

Rob Herring Oct. 13, 2020, 12:30 p.m. UTC | #1
On Sun, Oct 11, 2020 at 01:41:10AM +0300, Serge Semin wrote:
> Currently the DT bindings of Generic xHCI Controllers are described by means
> of the legacy text file. Since such format is deprecated in favor of the
> DT schema, let's convert the Generic xHCI Controllers bindings file to the
> corresponding yaml files. There will be two of them: a DT schema for the
> xHCI controllers on a generic platform and a DT schema validating a generic
> xHCI controllers properties. The later will be used to validate the xHCI
> controllers, which aside from some vendor-specific features support the
> basic xHCI functionality.
> 
> An xHCI-compatible DT node shall support the standard USB HCD properties
> and custom ones like: usb2-lpm-disable, usb3-lpm-capable,
> quirk-broken-port-ped and imod-interval-ns. In addition if a generic xHCI
> controller is being validated against the DT schema it is also supposed to
> be equipped with mandatory compatible string, single registers range,
> single interrupts source, and is supposed to optionally contain up to two
> reference clocks for the controller core and CSRs.
> 
> Signed-off-by: Serge Semin <Sergey.Semin@baikalelectronics.ru>
> ---
>  .../devicetree/bindings/usb/generic-xhci.yaml | 63 +++++++++++++++++++
>  .../devicetree/bindings/usb/usb-xhci.txt      | 41 ------------
>  .../devicetree/bindings/usb/usb-xhci.yaml     | 40 ++++++++++++
>  3 files changed, 103 insertions(+), 41 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/usb/generic-xhci.yaml
>  delete mode 100644 Documentation/devicetree/bindings/usb/usb-xhci.txt
>  create mode 100644 Documentation/devicetree/bindings/usb/usb-xhci.yaml
> 
> diff --git a/Documentation/devicetree/bindings/usb/generic-xhci.yaml b/Documentation/devicetree/bindings/usb/generic-xhci.yaml
> new file mode 100644
> index 000000000000..1ea1d49a8175
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/generic-xhci.yaml
> @@ -0,0 +1,63 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/usb/generic-xhci.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: USB xHCI Controller Device Tree Bindings
> +
> +maintainers:
> +  - Mathias Nyman <mathias.nyman@intel.com>
> +
> +allOf:
> +  - $ref: "usb-xhci.yaml#"
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - description: Generic xHCI device
> +        const: generic-xhci
> +      - description: Armada 37xx/375/38x/8k SoCs
> +        items:
> +          - enum:
> +              - marvell,armada3700-xhci
> +              - marvell,armada-375-xhci
> +              - marvell,armada-380-xhci
> +              - marvell,armada-8k-xhci
> +          - const: generic-xhci
> +      - description: Broadcom STB SoCs with xHCI
> +        const: brcm,bcm7445-xhci
> +      - description: Generic xHCI device
> +        const: xhci-platform
> +        deprecated: true
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    minItems: 1
> +    maxItems: 2
> +
> +  clock-names:
> +    minItems: 1
> +    items:
> +      - const: core
> +      - const: reg
> +
> +unevaluatedProperties: false
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +examples:
> +  - |
> +    usb@f0931000 {
> +      compatible = "generic-xhci";
> +      reg = <0xf0931000 0x8c8>;
> +      interrupts = <0x0 0x4e 0x0>;
> +    };
> diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt
> deleted file mode 100644
> index 0c5cff84a969..000000000000
> --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt
> +++ /dev/null
> @@ -1,41 +0,0 @@
> -USB xHCI controllers
> -
> -Required properties:
> -  - compatible: should be one or more of
> -
> -    - "generic-xhci" for generic XHCI device
> -    - "marvell,armada3700-xhci" for Armada 37xx SoCs
> -    - "marvell,armada-375-xhci" for Armada 375 SoCs
> -    - "marvell,armada-380-xhci" for Armada 38x SoCs
> -    - "brcm,bcm7445-xhci" for Broadcom STB SoCs with XHCI
> -    - "xhci-platform" (deprecated)
> -
> -    When compatible with the generic version, nodes must list the
> -    SoC-specific version corresponding to the platform first
> -    followed by the generic version.
> -
> -  - reg: should contain address and length of the standard XHCI
> -    register set for the device.
> -  - interrupts: one XHCI interrupt should be described here.
> -
> -Optional properties:
> -  - clocks: reference to the clocks
> -  - clock-names: mandatory if there is a second clock, in this case
> -    the name must be "core" for the first clock and "reg" for the
> -    second one
> -  - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM
> -  - usb3-lpm-capable: determines if platform is USB3 LPM capable
> -  - quirk-broken-port-ped: set if the controller has broken port disable mechanism
> -  - imod-interval-ns: default interrupt moderation interval is 5000ns
> -  - phys : see usb-hcd.yaml in the current directory
> -
> -additionally the properties from usb-hcd.yaml (in the current directory) are
> -supported.
> -
> -
> -Example:
> -	usb@f0931000 {
> -		compatible = "generic-xhci";
> -		reg = <0xf0931000 0x8c8>;
> -		interrupts = <0x0 0x4e 0x0>;
> -	};
> diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.yaml b/Documentation/devicetree/bindings/usb/usb-xhci.yaml
> new file mode 100644
> index 000000000000..c5c177f2e055
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/usb-xhci.yaml
> @@ -0,0 +1,40 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/usb/usb-xhci.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic USB xHCI Controller Device Tree Bindings
> +
> +maintainers:
> +  - Mathias Nyman <mathias.nyman@intel.com>
> +
> +allOf:
> +  - $ref: "usb-hcd.yaml#"
> +
> +properties:
> +  usb2-lpm-disable:
> +    description: Indicates if we don't want to enable USB2 HW LPM
> +    type: boolean
> +
> +  usb3-lpm-capable:
> +    description: Determines if platform is USB3 LPM capable
> +    type: boolean
> +
> +  quirk-broken-port-ped:
> +    description: Set if the controller has broken port disable mechanism
> +    type: boolean
> +
> +  imod-interval-ns:
> +    description: Interrupt moderation interval
> +    default: 5000

Having additionalProperties or unevaluatedProperties is going to be 
mandatory, so for this add:

additionalProperties: true

> +
> +examples:
> +  - |
> +    usb@f0930000 {
> +      compatible = "generic-xhci";
> +      reg = <0xf0930000 0x8c8>;
> +      interrupts = <0x0 0x4e 0x0>;
> +      usb2-lpm-disable;
> +      usb3-lpm-capable;
> +    };
> -- 
> 2.27.0
>
Serge Semin Oct. 13, 2020, 2:29 p.m. UTC | #2
On Tue, Oct 13, 2020 at 07:30:04AM -0500, Rob Herring wrote:
> On Sun, Oct 11, 2020 at 01:41:10AM +0300, Serge Semin wrote:
> > Currently the DT bindings of Generic xHCI Controllers are described by means
> > of the legacy text file. Since such format is deprecated in favor of the
> > DT schema, let's convert the Generic xHCI Controllers bindings file to the
> > corresponding yaml files. There will be two of them: a DT schema for the
> > xHCI controllers on a generic platform and a DT schema validating a generic
> > xHCI controllers properties. The later will be used to validate the xHCI
> > controllers, which aside from some vendor-specific features support the
> > basic xHCI functionality.
> > 
> > An xHCI-compatible DT node shall support the standard USB HCD properties
> > and custom ones like: usb2-lpm-disable, usb3-lpm-capable,
> > quirk-broken-port-ped and imod-interval-ns. In addition if a generic xHCI
> > controller is being validated against the DT schema it is also supposed to
> > be equipped with mandatory compatible string, single registers range,
> > single interrupts source, and is supposed to optionally contain up to two
> > reference clocks for the controller core and CSRs.
> > 
> > Signed-off-by: Serge Semin <Sergey.Semin@baikalelectronics.ru>
> > ---
> >  .../devicetree/bindings/usb/generic-xhci.yaml | 63 +++++++++++++++++++
> >  .../devicetree/bindings/usb/usb-xhci.txt      | 41 ------------
> >  .../devicetree/bindings/usb/usb-xhci.yaml     | 40 ++++++++++++
> >  3 files changed, 103 insertions(+), 41 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/usb/generic-xhci.yaml
> >  delete mode 100644 Documentation/devicetree/bindings/usb/usb-xhci.txt
> >  create mode 100644 Documentation/devicetree/bindings/usb/usb-xhci.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/usb/generic-xhci.yaml b/Documentation/devicetree/bindings/usb/generic-xhci.yaml
> > new file mode 100644
> > index 000000000000..1ea1d49a8175
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/usb/generic-xhci.yaml
> > @@ -0,0 +1,63 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/usb/generic-xhci.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: USB xHCI Controller Device Tree Bindings
> > +
> > +maintainers:
> > +  - Mathias Nyman <mathias.nyman@intel.com>
> > +
> > +allOf:
> > +  - $ref: "usb-xhci.yaml#"
> > +
> > +properties:
> > +  compatible:
> > +    oneOf:
> > +      - description: Generic xHCI device
> > +        const: generic-xhci
> > +      - description: Armada 37xx/375/38x/8k SoCs
> > +        items:
> > +          - enum:
> > +              - marvell,armada3700-xhci
> > +              - marvell,armada-375-xhci
> > +              - marvell,armada-380-xhci
> > +              - marvell,armada-8k-xhci
> > +          - const: generic-xhci
> > +      - description: Broadcom STB SoCs with xHCI
> > +        const: brcm,bcm7445-xhci
> > +      - description: Generic xHCI device
> > +        const: xhci-platform
> > +        deprecated: true
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  clocks:
> > +    minItems: 1
> > +    maxItems: 2
> > +
> > +  clock-names:
> > +    minItems: 1
> > +    items:
> > +      - const: core
> > +      - const: reg
> > +
> > +unevaluatedProperties: false
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +
> > +examples:
> > +  - |
> > +    usb@f0931000 {
> > +      compatible = "generic-xhci";
> > +      reg = <0xf0931000 0x8c8>;
> > +      interrupts = <0x0 0x4e 0x0>;
> > +    };
> > diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt
> > deleted file mode 100644
> > index 0c5cff84a969..000000000000
> > --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt
> > +++ /dev/null
> > @@ -1,41 +0,0 @@
> > -USB xHCI controllers
> > -
> > -Required properties:
> > -  - compatible: should be one or more of
> > -
> > -    - "generic-xhci" for generic XHCI device
> > -    - "marvell,armada3700-xhci" for Armada 37xx SoCs
> > -    - "marvell,armada-375-xhci" for Armada 375 SoCs
> > -    - "marvell,armada-380-xhci" for Armada 38x SoCs
> > -    - "brcm,bcm7445-xhci" for Broadcom STB SoCs with XHCI
> > -    - "xhci-platform" (deprecated)
> > -
> > -    When compatible with the generic version, nodes must list the
> > -    SoC-specific version corresponding to the platform first
> > -    followed by the generic version.
> > -
> > -  - reg: should contain address and length of the standard XHCI
> > -    register set for the device.
> > -  - interrupts: one XHCI interrupt should be described here.
> > -
> > -Optional properties:
> > -  - clocks: reference to the clocks
> > -  - clock-names: mandatory if there is a second clock, in this case
> > -    the name must be "core" for the first clock and "reg" for the
> > -    second one
> > -  - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM
> > -  - usb3-lpm-capable: determines if platform is USB3 LPM capable
> > -  - quirk-broken-port-ped: set if the controller has broken port disable mechanism
> > -  - imod-interval-ns: default interrupt moderation interval is 5000ns
> > -  - phys : see usb-hcd.yaml in the current directory
> > -
> > -additionally the properties from usb-hcd.yaml (in the current directory) are
> > -supported.
> > -
> > -
> > -Example:
> > -	usb@f0931000 {
> > -		compatible = "generic-xhci";
> > -		reg = <0xf0931000 0x8c8>;
> > -		interrupts = <0x0 0x4e 0x0>;
> > -	};
> > diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.yaml b/Documentation/devicetree/bindings/usb/usb-xhci.yaml
> > new file mode 100644
> > index 000000000000..c5c177f2e055
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/usb/usb-xhci.yaml
> > @@ -0,0 +1,40 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/usb/usb-xhci.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Generic USB xHCI Controller Device Tree Bindings
> > +
> > +maintainers:
> > +  - Mathias Nyman <mathias.nyman@intel.com>
> > +
> > +allOf:
> > +  - $ref: "usb-hcd.yaml#"
> > +
> > +properties:
> > +  usb2-lpm-disable:
> > +    description: Indicates if we don't want to enable USB2 HW LPM
> > +    type: boolean
> > +
> > +  usb3-lpm-capable:
> > +    description: Determines if platform is USB3 LPM capable
> > +    type: boolean
> > +
> > +  quirk-broken-port-ped:
> > +    description: Set if the controller has broken port disable mechanism
> > +    type: boolean
> > +
> > +  imod-interval-ns:
> > +    description: Interrupt moderation interval
> > +    default: 5000
> 

> Having additionalProperties or unevaluatedProperties is going to be 
> mandatory, so for this add:
> 
> additionalProperties: true

Ok. I'll get to remember this.

-Sergey

> 
> > +
> > +examples:
> > +  - |
> > +    usb@f0930000 {
> > +      compatible = "generic-xhci";
> > +      reg = <0xf0930000 0x8c8>;
> > +      interrupts = <0x0 0x4e 0x0>;
> > +      usb2-lpm-disable;
> > +      usb3-lpm-capable;
> > +    };
> > -- 
> > 2.27.0
> >
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/usb/generic-xhci.yaml b/Documentation/devicetree/bindings/usb/generic-xhci.yaml
new file mode 100644
index 000000000000..1ea1d49a8175
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/generic-xhci.yaml
@@ -0,0 +1,63 @@ 
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/generic-xhci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: USB xHCI Controller Device Tree Bindings
+
+maintainers:
+  - Mathias Nyman <mathias.nyman@intel.com>
+
+allOf:
+  - $ref: "usb-xhci.yaml#"
+
+properties:
+  compatible:
+    oneOf:
+      - description: Generic xHCI device
+        const: generic-xhci
+      - description: Armada 37xx/375/38x/8k SoCs
+        items:
+          - enum:
+              - marvell,armada3700-xhci
+              - marvell,armada-375-xhci
+              - marvell,armada-380-xhci
+              - marvell,armada-8k-xhci
+          - const: generic-xhci
+      - description: Broadcom STB SoCs with xHCI
+        const: brcm,bcm7445-xhci
+      - description: Generic xHCI device
+        const: xhci-platform
+        deprecated: true
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    minItems: 1
+    maxItems: 2
+
+  clock-names:
+    minItems: 1
+    items:
+      - const: core
+      - const: reg
+
+unevaluatedProperties: false
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+examples:
+  - |
+    usb@f0931000 {
+      compatible = "generic-xhci";
+      reg = <0xf0931000 0x8c8>;
+      interrupts = <0x0 0x4e 0x0>;
+    };
diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt
deleted file mode 100644
index 0c5cff84a969..000000000000
--- a/Documentation/devicetree/bindings/usb/usb-xhci.txt
+++ /dev/null
@@ -1,41 +0,0 @@ 
-USB xHCI controllers
-
-Required properties:
-  - compatible: should be one or more of
-
-    - "generic-xhci" for generic XHCI device
-    - "marvell,armada3700-xhci" for Armada 37xx SoCs
-    - "marvell,armada-375-xhci" for Armada 375 SoCs
-    - "marvell,armada-380-xhci" for Armada 38x SoCs
-    - "brcm,bcm7445-xhci" for Broadcom STB SoCs with XHCI
-    - "xhci-platform" (deprecated)
-
-    When compatible with the generic version, nodes must list the
-    SoC-specific version corresponding to the platform first
-    followed by the generic version.
-
-  - reg: should contain address and length of the standard XHCI
-    register set for the device.
-  - interrupts: one XHCI interrupt should be described here.
-
-Optional properties:
-  - clocks: reference to the clocks
-  - clock-names: mandatory if there is a second clock, in this case
-    the name must be "core" for the first clock and "reg" for the
-    second one
-  - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM
-  - usb3-lpm-capable: determines if platform is USB3 LPM capable
-  - quirk-broken-port-ped: set if the controller has broken port disable mechanism
-  - imod-interval-ns: default interrupt moderation interval is 5000ns
-  - phys : see usb-hcd.yaml in the current directory
-
-additionally the properties from usb-hcd.yaml (in the current directory) are
-supported.
-
-
-Example:
-	usb@f0931000 {
-		compatible = "generic-xhci";
-		reg = <0xf0931000 0x8c8>;
-		interrupts = <0x0 0x4e 0x0>;
-	};
diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.yaml b/Documentation/devicetree/bindings/usb/usb-xhci.yaml
new file mode 100644
index 000000000000..c5c177f2e055
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/usb-xhci.yaml
@@ -0,0 +1,40 @@ 
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/usb/usb-xhci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic USB xHCI Controller Device Tree Bindings
+
+maintainers:
+  - Mathias Nyman <mathias.nyman@intel.com>
+
+allOf:
+  - $ref: "usb-hcd.yaml#"
+
+properties:
+  usb2-lpm-disable:
+    description: Indicates if we don't want to enable USB2 HW LPM
+    type: boolean
+
+  usb3-lpm-capable:
+    description: Determines if platform is USB3 LPM capable
+    type: boolean
+
+  quirk-broken-port-ped:
+    description: Set if the controller has broken port disable mechanism
+    type: boolean
+
+  imod-interval-ns:
+    description: Interrupt moderation interval
+    default: 5000
+
+examples:
+  - |
+    usb@f0930000 {
+      compatible = "generic-xhci";
+      reg = <0xf0930000 0x8c8>;
+      interrupts = <0x0 0x4e 0x0>;
+      usb2-lpm-disable;
+      usb3-lpm-capable;
+    };