diff mbox series

[v2] dt-bindings: gpio: gpio-mvebu: convert txt binding to YAML

Message ID 20220511013737.1194344-1-chris.packham@alliedtelesis.co.nz
State Superseded
Headers show
Series [v2] dt-bindings: gpio: gpio-mvebu: convert txt binding to YAML | expand

Commit Message

Chris Packham May 11, 2022, 1:37 a.m. UTC 
Convert the existing device tree binding to YAML format.

The old binding listed the interrupt-controller and related properties
as required but there are sufficiently many existing usages without it
that the YAML binding does not make the interrupt properties required.

The offset and marvell,pwm-offset properties weren't in the old binding
and are added to the YAML binding. The offset property is required when
the marvell,armada-8k-gpio compatible is used.

Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
---

Notes:
    Changes in v2:
    - Collect review from Andrew
    - Remove unnecessary/obvious property descriptions
    - Clarify reg property requirements for armadaxp vs the rest. Enforce
      these with a variant specific constraint.
    - Update compatible property requirements. marvell,orion-gpio and
      marvell,armada-8k-gpio can be used on their own. Everything else needs
      marvell,orion-gpio as a fallback.
    - Correct example to include marvell,orion-gpio fallback

 .../devicetree/bindings/gpio/gpio-mvebu.txt   |  93 -----------
 .../devicetree/bindings/gpio/gpio-mvebu.yaml  | 151 ++++++++++++++++++
 MAINTAINERS                                   |   2 +-
 3 files changed, 152 insertions(+), 94 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
 create mode 100644 Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml

Comments

Uwe Kleine-König May 11, 2022, 7:52 a.m. UTC | #1 
Hello,

On Wed, May 11, 2022 at 01:37:37PM +1200, Chris Packham wrote:
> +  "#pwm-cells":
> +    description:
> +      The first cell is the GPIO line number. The second cell is the period
> +      in nanoseconds.
> +    const: 2

I wonder if the binding [cs]hould allow 3, too. After a quick look in
the driver code I think 3 would be supported out of the box.
That's a low prio thing though (the driver doesn't support polarity
anyhow) and this is orthogonal to this 1:1 conversion patch.

Best regards
Uwe
Rob Herring May 11, 2022, 1:36 p.m. UTC | #2 
On Wed, 11 May 2022 13:37:37 +1200, Chris Packham wrote:
> Convert the existing device tree binding to YAML format.
> 
> The old binding listed the interrupt-controller and related properties
> as required but there are sufficiently many existing usages without it
> that the YAML binding does not make the interrupt properties required.
> 
> The offset and marvell,pwm-offset properties weren't in the old binding
> and are added to the YAML binding. The offset property is required when
> the marvell,armada-8k-gpio compatible is used.
> 
> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> Reviewed-by: Andrew Lunn <andrew@lunn.ch>
> ---
> 
> Notes:
>     Changes in v2:
>     - Collect review from Andrew
>     - Remove unnecessary/obvious property descriptions
>     - Clarify reg property requirements for armadaxp vs the rest. Enforce
>       these with a variant specific constraint.
>     - Update compatible property requirements. marvell,orion-gpio and
>       marvell,armada-8k-gpio can be used on their own. Everything else needs
>       marvell,orion-gpio as a fallback.
>     - Correct example to include marvell,orion-gpio fallback
> 
>  .../devicetree/bindings/gpio/gpio-mvebu.txt   |  93 -----------
>  .../devicetree/bindings/gpio/gpio-mvebu.yaml  | 151 ++++++++++++++++++
>  MAINTAINERS                                   |   2 +-
>  3 files changed, 152 insertions(+), 94 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
>  create mode 100644 Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:

doc reference errors (make refcheckdocs):
Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt: Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt: Documentation/devicetree/bindings/gpio/gpio-mvebu.txt

See https://patchwork.ozlabs.org/patch/

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.
Krzysztof Kozlowski May 11, 2022, 3:55 p.m. UTC | #3 
On 11/05/2022 03:37, Chris Packham wrote:
> Convert the existing device tree binding to YAML format.
> 
> The old binding listed the interrupt-controller and related properties
> as required but there are sufficiently many existing usages without it
> that the YAML binding does not make the interrupt properties required.
> 
> The offset and marvell,pwm-offset properties weren't in the old binding
> and are added to the YAML binding. The offset property is required when
> the marvell,armada-8k-gpio compatible is used.

These properties do not look correct. It's some hacky design. As I see
in the driver, there is no reason to model the gpio under the syscon at
all. The GPIO has its own address space, which is for example in
armada-ap80x.dtsi 0x6f4000+0x1040.

Instead of describing it as a separate device under that address,
someone created a syscon node for entire address space, put the GPIO as
a fake child and added some new property "offset" indicating address
offset. Wait, what, why?

Why this cannot be a child of SoC, just like all other nodes are?

Since this is a conversion and offset was never previously accepted in
the bindings, it has to go to separate patch where you will need to get
Rob's ack on documenting offset.

(...)

> +    then:
> +      properties:
> +        reg:
> +          minItems: 2
> +
> +unevaluatedProperties: true
> +
> +examples:
> +  - |
> +      gpio@d0018100 {

Wrong indentation. See example schema.


> +        compatible = "marvell,armadaxp-gpio", "marvell,orion-gpio";
> +        reg = <0xd0018100 0x40>, <0xd0018800 0x30>;
> +        ngpios = <32>;
> +        gpio-controller;
> +        #gpio-cells = <2>;
> +        interrupt-controller;
> +        #interrupt-cells = <2>;
> +        interrupts = <16>, <17>, <18>, <19>;
> +      };
> +
> +  - |
> +      gpio@18140 {

Best regards,
Krzysztof
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
deleted file mode 100644
index 0fc6700ed800..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
+++ /dev/null
@@ -1,93 +0,0 @@ 
-* Marvell EBU GPIO controller
-
-Required properties:
-
-- compatible : Should be "marvell,orion-gpio", "marvell,mv78200-gpio",
-  "marvell,armadaxp-gpio" or "marvell,armada-8k-gpio".
-
-    "marvell,orion-gpio" should be used for Orion, Kirkwood, Dove,
-    Discovery (except MV78200) and Armada 370. "marvell,mv78200-gpio"
-    should be used for the Discovery MV78200.
-
-    "marvel,armadaxp-gpio" should be used for all Armada XP SoCs
-    (MV78230, MV78260, MV78460).
-
-    "marvell,armada-8k-gpio" should be used for the Armada 7K and 8K
-    SoCs (either from AP or CP), see
-    Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
-    for specific details about the offset property.
-
-- reg: Address and length of the register set for the device. Only one
-  entry is expected, except for the "marvell,armadaxp-gpio" variant
-  for which two entries are expected: one for the general registers,
-  one for the per-cpu registers. Not used for marvell,armada-8k-gpio.
-
-- interrupts: The list of interrupts that are used for all the pins
-  managed by this GPIO bank. There can be more than one interrupt
-  (example: 1 interrupt per 8 pins on Armada XP, which means 4
-  interrupts per bank of 32 GPIOs).
-
-- interrupt-controller: identifies the node as an interrupt controller
-
-- #interrupt-cells: specifies the number of cells needed to encode an
-  interrupt source. Should be two.
-  The first cell is the GPIO number.
-  The second cell is used to specify flags:
-    bits[3:0] trigger type and level flags:
-      1 = low-to-high edge triggered.
-      2 = high-to-low edge triggered.
-      4 = active high level-sensitive.
-      8 = active low level-sensitive.
-
-- gpio-controller: marks the device node as a gpio controller
-
-- ngpios: number of GPIOs this controller has
-
-- #gpio-cells: Should be two. The first cell is the pin number. The
-  second cell is reserved for flags, unused at the moment.
-
-Optional properties:
-
-In order to use the GPIO lines in PWM mode, some additional optional
-properties are required.
-
-- compatible: Must contain "marvell,armada-370-gpio"
-
-- reg: an additional register set is needed, for the GPIO Blink
-  Counter on/off registers.
-
-- reg-names: Must contain an entry "pwm" corresponding to the
-  additional register range needed for PWM operation.
-
-- #pwm-cells: Should be two. The first cell is the GPIO line number. The
-  second cell is the period in nanoseconds.
-
-- clocks: Must be a phandle to the clock for the GPIO controller.
-
-Example:
-
-		gpio0: gpio@d0018100 {
-			compatible = "marvell,armadaxp-gpio";
-			reg = <0xd0018100 0x40>,
-			    <0xd0018800 0x30>;
-			ngpios = <32>;
-			gpio-controller;
-			#gpio-cells = <2>;
-			interrupt-controller;
-			#interrupt-cells = <2>;
-			interrupts = <16>, <17>, <18>, <19>;
-		};
-
-		gpio1: gpio@18140 {
-			compatible = "marvell,armada-370-gpio";
-			reg = <0x18140 0x40>, <0x181c8 0x08>;
-			reg-names = "gpio", "pwm";
-			ngpios = <17>;
-			gpio-controller;
-			#gpio-cells = <2>;
-			#pwm-cells = <2>;
-			interrupt-controller;
-			#interrupt-cells = <2>;
-			interrupts = <87>, <88>, <89>;
-			clocks = <&coreclk 0>;
-		};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
new file mode 100644
index 000000000000..dad752a49bce
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
@@ -0,0 +1,151 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-mvebu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell EBU GPIO controller
+
+maintainers:
+  - Thierry Reding <thierry.reding@gmail.com>
+  - Lee Jones <lee.jones@linaro.org>
+
+properties:
+  compatible:
+    oneOf:
+      - enum:
+          - marvell,armada-8k-gpio
+          - marvell,orion-gpio
+
+      - items:
+          - enum:
+              - marvell,mv78200-gpio
+              - marvell,armada-370-gpio
+              - marvell,armadaxp-gpio
+          - const: marvell,orion-gpio
+
+  reg:
+    description: |
+      Address and length of the register set for the device. Not used for
+      marvell,armada-8k-gpio.
+
+      For the "marvell,armadaxp-gpio" variant a second entry is expected for
+      the per-cpu registers. For other variants second entry can be provided,
+      for the PWM function using the GPIO Blink Counter on/off registers.
+    minItems: 1
+    maxItems: 2
+
+  reg-names:
+    items:
+      - const: gpio
+      - const: pwm
+    minItems: 1
+
+  offset:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Offset in the register map for the gpio registers (in bytes)
+
+  interrupts:
+    description: |
+      The list of interrupts that are used for all the pins managed by this
+      GPIO bank. There can be more than one interrupt (example: 1 interrupt
+      per 8 pins on Armada XP, which means 4 interrupts per bank of 32
+      GPIOs).
+    minItems: 1
+    maxItems: 4
+
+  interrupt-controller: true
+
+  "#interrupt-cells":
+    const: 2
+
+  gpio-controller: true
+
+  ngpios:
+    minimum: 1
+    maximum: 32
+
+  "#gpio-cells":
+    const: 2
+
+  marvell,pwm-offset:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Offset in the register map for the pwm registers (in bytes)
+
+  "#pwm-cells":
+    description:
+      The first cell is the GPIO line number. The second cell is the period
+      in nanoseconds.
+    const: 2
+
+  clocks:
+    description:
+      Clock(s) used for PWM function.
+    items:
+      - description: Core clock
+      - description: AXI bus clock
+    minItems: 1
+
+  clock-names:
+    items:
+      - const: core
+      - const: axi
+    minItems: 1
+
+required:
+  - compatible
+  - gpio-controller
+  - ngpios
+  - "#gpio-cells"
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: marvell,armada-8k-gpio
+    then:
+      required:
+        - offset
+    else:
+      required:
+        - reg
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: marvell,armadaxp-gpio
+    then:
+      properties:
+        reg:
+          minItems: 2
+
+unevaluatedProperties: true
+
+examples:
+  - |
+      gpio@d0018100 {
+        compatible = "marvell,armadaxp-gpio", "marvell,orion-gpio";
+        reg = <0xd0018100 0x40>, <0xd0018800 0x30>;
+        ngpios = <32>;
+        gpio-controller;
+        #gpio-cells = <2>;
+        interrupt-controller;
+        #interrupt-cells = <2>;
+        interrupts = <16>, <17>, <18>, <19>;
+      };
+
+  - |
+      gpio@18140 {
+        compatible = "marvell,armada-370-gpio", "marvell,orion-gpio";
+        reg = <0x18140 0x40>, <0x181c8 0x08>;
+        reg-names = "gpio", "pwm";
+        ngpios = <17>;
+        gpio-controller;
+        #gpio-cells = <2>;
+        #pwm-cells = <2>;
+        interrupt-controller;
+        #interrupt-cells = <2>;
+        interrupts = <87>, <88>, <89>;
+        clocks = <&coreclk 0>;
+      };
diff --git a/MAINTAINERS b/MAINTAINERS
index e8c52d0192a6..6b1c80fd7611 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16019,7 +16019,7 @@  L:	linux-pwm@vger.kernel.org
 S:	Maintained
 Q:	https://patchwork.ozlabs.org/project/linux-pwm/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/thierry.reding/linux-pwm.git
-F:	Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
+F:	Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
 F:	Documentation/devicetree/bindings/pwm/
 F:	Documentation/driver-api/pwm.rst
 F:	drivers/gpio/gpio-mvebu.c