diff mbox series

[v3,1/2] dt-bindings: gpio: gpio-mvebu: convert txt binding to YAML

Message ID 20220512094125.3748197-1-chris.packham@alliedtelesis.co.nz
State Changes Requested, archived
Headers show
Series [v3,1/2] dt-bindings: gpio: gpio-mvebu: convert txt binding to YAML | expand

Checks

Context Check Description
robh/checkpatch warning total: 0 errors, 2 warnings, 167 lines checked
robh/patch-applied success
robh/dtbs-check warning build log
robh/dt-meta-schema success

Commit Message

Chris Packham May 12, 2022, 9:41 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.

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

Notes:
    Changes in v3:
    - Correct indent in example
    - Move offset and marvell,pwm-offset to separate patch
    - Correct some documentation cross references
    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

 .../arm/marvell/ap80x-system-controller.txt   |   2 +-
 .../arm/marvell/cp110-system-controller.txt   |   2 +-
 .../devicetree/bindings/gpio/gpio-mvebu.txt   |  93 ------------
 .../devicetree/bindings/gpio/gpio-mvebu.yaml  | 143 ++++++++++++++++++
 MAINTAINERS                                   |   2 +-
 5 files changed, 146 insertions(+), 96 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
 create mode 100644 Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml

Comments

Krzysztof Kozlowski May 13, 2022, 8:38 a.m. UTC | #1
On 12/05/2022 11:41, 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.
> 
> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> Reviewed-by: Andrew Lunn <andrew@lunn.ch>
> ---
> 
> Notes:
>     Changes in v3:
>     - Correct indent in example
>     - Move offset and marvell,pwm-offset to separate patch
>     - Correct some documentation cross references

Thank you for your patch. There is something to discuss/improve.

> diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
> new file mode 100644
> index 000000000000..2d95ef707f53
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
> @@ -0,0 +1,143 @@
> +# 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>

These should be rather platform or driver maintainers, not subsystem
folks. Unless it happens that Thierry and Lee are for platform?

> +
> +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
> +
> +  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
> +
> +  "#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

one blank line please

> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: marvell,armadaxp-gpio

Original bindings are saying that second reg is optional for
marvell,armada-370-gpio. What about other cases, e.g. mv78200-gpio? Is
it also allowed (and optional) there?

> +    then:
> +      properties:
> +        reg:
> +          minItems: 2

Then you also should require two reg-names.


Best regards,
Krzysztof
Chris Packham May 14, 2022, 2:20 a.m. UTC | #2
On 13/05/22 20:38, Krzysztof Kozlowski wrote:
> On 12/05/2022 11:41, 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.
>>
>> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
>> Reviewed-by: Andrew Lunn <andrew@lunn.ch>
>> ---
>>
>> Notes:
>>      Changes in v3:
>>      - Correct indent in example
>>      - Move offset and marvell,pwm-offset to separate patch
>>      - Correct some documentation cross references
> Thank you for your patch. There is something to discuss/improve.
>
>> diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
>> new file mode 100644
>> index 000000000000..2d95ef707f53
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
>> @@ -0,0 +1,143 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://scanmail.trustwave.com/?c=20988&d=rJn-4g1s6Eg0HzmHuA8bPCoTV-chhtJg5SGZN2xCmw&u=http%3a%2f%2fdevicetree%2eorg%2fschemas%2fgpio%2fgpio-mvebu%2eyaml%23
>> +$schema: http://scanmail.trustwave.com/?c=20988&d=rJn-4g1s6Eg0HzmHuA8bPCoTV-chhtJg5SXKYz9BlA&u=http%3a%2f%2fdevicetree%2eorg%2fmeta-schemas%2fcore%2eyaml%23
>> +
>> +title: Marvell EBU GPIO controller
>> +
>> +maintainers:
>> +  - Thierry Reding <thierry.reding@gmail.com>
>> +  - Lee Jones <lee.jones@linaro.org>
> These should be rather platform or driver maintainers, not subsystem
> folks. Unless it happens that Thierry and Lee are for platform?

Based on lines authored that would be Thomas and Andrew. But perhaps 
someone from Marvell or PLVision have an interest in adopting the driver 
and it's binding?

For now I'll put Thomas and Andrew until someone else steps up.

>
>> +
>> +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
>> +
>> +  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
>> +
>> +  "#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
> one blank line please
>
>> +  - if:
>> +      properties:
>> +        compatible:
>> +          contains:
>> +            const: marvell,armadaxp-gpio
> Original bindings are saying that second reg is optional for
> marvell,armada-370-gpio. What about other cases, e.g. mv78200-gpio? Is
> it also allowed (and optional) there?
This is where things get interesting. The armadaxp (and only the 
armadaxp) requires a second register value for some per-cpu registers. 
All of the other SoCs can have an optional 2nd register value if they 
want to use the PWM function. I guess that implies that the armadaxp 
can't do PWM.
>> +    then:
>> +      properties:
>> +        reg:
>> +          minItems: 2
> Then you also should require two reg-names.

Simple enough to add. But currently we've said that the reg-names are 
"gpio" and "pwm" but on the armadaxp the 2nd one is not "pwm" but 
something else ("per-cpu" perhaps?)

On the other hand this is all completely moot because the 
armada-xp-mv78*.dtsi actually use the "marvell,armada-370-gpio" 
compatible so this appears to be documenting something that is no longer 
used. Indeed it appears that the armadaxp specific usage was remove in 
5f79c651e81e ("arm: mvebu: use global interrupts for GPIOs on Armada XP").

So perhaps the best course of action is to drop marvell,armadaxp-gpio 
from the new binding (noting that we've done so in the commit message).

>
>
> Best regards,
> Krzysztof
Krzysztof Kozlowski May 14, 2022, 8:28 p.m. UTC | #3
On 14/05/2022 04:20, Chris Packham wrote:
> 
>>> +
>>> +allOf:
>>> +  - if:
>>> +      properties:
>>> +        compatible:
>>> +          contains:
>>> +            const: marvell,armada-8k-gpio
>>> +    then:
>>> +      required:
>>> +        - offset
>>> +    else:
>>> +      required:
>>> +        - reg
>> one blank line please
>>
>>> +  - if:
>>> +      properties:
>>> +        compatible:
>>> +          contains:
>>> +            const: marvell,armadaxp-gpio
>> Original bindings are saying that second reg is optional for
>> marvell,armada-370-gpio. What about other cases, e.g. mv78200-gpio? Is
>> it also allowed (and optional) there?
> This is where things get interesting. The armadaxp (and only the 
> armadaxp) requires a second register value for some per-cpu registers. 
> All of the other SoCs can have an optional 2nd register value if they 
> want to use the PWM function. I guess that implies that the armadaxp 
> can't do PWM.
>>> +    then:
>>> +      properties:
>>> +        reg:
>>> +          minItems: 2
>> Then you also should require two reg-names.
> 
> Simple enough to add. But currently we've said that the reg-names are 
> "gpio" and "pwm" but on the armadaxp the 2nd one is not "pwm" but 
> something else ("per-cpu" perhaps?)

In such case they would be failing with current bindings, because they
expect "pwm" as second name, right?

> 
> On the other hand this is all completely moot because the 
> armada-xp-mv78*.dtsi actually use the "marvell,armada-370-gpio" 
> compatible so this appears to be documenting something that is no longer 
> used. Indeed it appears that the armadaxp specific usage was remove in 
> 5f79c651e81e ("arm: mvebu: use global interrupts for GPIOs on Armada XP").
> 
> So perhaps the best course of action is to drop marvell,armadaxp-gpio 
> from the new binding (noting that we've done so in the commit message).


That's fine, maybe in a separate patch (2nd one)?


Best regards,
Krzysztof
Chris Packham May 15, 2022, 9:20 p.m. UTC | #4
On 15/05/22 08:28, Krzysztof Kozlowski wrote:
> On 14/05/2022 04:20, Chris Packham wrote:
>>>> +
>>>> +allOf:
>>>> +  - if:
>>>> +      properties:
>>>> +        compatible:
>>>> +          contains:
>>>> +            const: marvell,armada-8k-gpio
>>>> +    then:
>>>> +      required:
>>>> +        - offset
>>>> +    else:
>>>> +      required:
>>>> +        - reg
>>> one blank line please
>>>
>>>> +  - if:
>>>> +      properties:
>>>> +        compatible:
>>>> +          contains:
>>>> +            const: marvell,armadaxp-gpio
>>> Original bindings are saying that second reg is optional for
>>> marvell,armada-370-gpio. What about other cases, e.g. mv78200-gpio? Is
>>> it also allowed (and optional) there?
>> This is where things get interesting. The armadaxp (and only the
>> armadaxp) requires a second register value for some per-cpu registers.
>> All of the other SoCs can have an optional 2nd register value if they
>> want to use the PWM function. I guess that implies that the armadaxp
>> can't do PWM.
>>>> +    then:
>>>> +      properties:
>>>> +        reg:
>>>> +          minItems: 2
>>> Then you also should require two reg-names.
>> Simple enough to add. But currently we've said that the reg-names are
>> "gpio" and "pwm" but on the armadaxp the 2nd one is not "pwm" but
>> something else ("per-cpu" perhaps?)
> In such case they would be failing with current bindings, because they
> expect "pwm" as second name, right?

The driver is alright because it checks for the 
"marvell,armada-370-gpio" compatible before using 
platform_get_resource_byname("pwm"). The unused (at least in theory) 
armadaxp code just calls devm_platform_ioremap_resource(pdev, 1) so it 
doesn't care about the name.

I'm tempted to leave the regName: minItems: 2 out because the armadaxp 
code doesn't care about them and setting the 2nd regname to "pwm" when 
the compatible is armadaxp would be misleading.

>> On the other hand this is all completely moot because the
>> armada-xp-mv78*.dtsi actually use the "marvell,armada-370-gpio"
>> compatible so this appears to be documenting something that is no longer
>> used. Indeed it appears that the armadaxp specific usage was remove in
>> 5f79c651e81e ("arm: mvebu: use global interrupts for GPIOs on Armada XP").
>>
>> So perhaps the best course of action is to drop marvell,armadaxp-gpio
>> from the new binding (noting that we've done so in the commit message).
>
> That's fine, maybe in a separate patch (2nd one)?
I'll add another patch on top that marks the compatible as deprecated 
including some of the above info in the commit message.
>
> Best regards,
> Krzysztof
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
index 052a967c1f28..c83245065d44 100644
--- a/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
@@ -72,7 +72,7 @@  mpp19	19	gpio, uart0(rxd), sdio(pw_off)
 GPIO:
 -----
 For common binding part and usage, refer to
-Documentation/devicetree/bindings/gpio/gpio-mvebu.txt.
+Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml.
 
 Required properties:
 
diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
index 0705e765f432..d84105c7c935 100644
--- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
+++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt
@@ -156,7 +156,7 @@  GPIO:
 -----
 
 For common binding part and usage, refer to
-Documentation/devicetree/bindings/gpio/gpio-mvebu.txt.
+Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml.
 
 Required properties:
 
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..2d95ef707f53
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
@@ -0,0 +1,143 @@ 
+# 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
+
+  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
+
+  "#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