[v7,03/22] dt-bindings: add BCM63XX GPIO binding documentation

Message ID 20210315114214.3096-4-noltari@gmail.com
State New
Headers show
Series
  • pinctrl: add BCM63XX pincontrol support
Related show

Commit Message

Álvaro Fernández Rojas March 15, 2021, 11:41 a.m.
Add binding documentation for the GPIO controller found in BCM6318, BCM6328,
BCM6358, BCM6362, BCM6368 and BCM63268 SoCs.

Co-developed-by: Jonas Gorski <jonas.gorski@gmail.com>
Signed-off-by: Jonas Gorski <jonas.gorski@gmail.com>
Signed-off-by: Álvaro Fernández Rojas <noltari@gmail.com>
---
 v7: new patch, splitted from pinctrl documentation

 .../bindings/gpio/brcm,bcm63xx-gpio.yaml      | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml

Comments

Rob Herring March 16, 2021, 8:54 p.m. | #1
On Mon, Mar 15, 2021 at 12:41:55PM +0100, Álvaro Fernández Rojas wrote:
> Add binding documentation for the GPIO controller found in BCM6318, BCM6328,
> BCM6358, BCM6362, BCM6368 and BCM63268 SoCs.
> 
> Co-developed-by: Jonas Gorski <jonas.gorski@gmail.com>
> Signed-off-by: Jonas Gorski <jonas.gorski@gmail.com>
> Signed-off-by: Álvaro Fernández Rojas <noltari@gmail.com>
> ---
>  v7: new patch, splitted from pinctrl documentation
> 
>  .../bindings/gpio/brcm,bcm63xx-gpio.yaml      | 83 +++++++++++++++++++
>  1 file changed, 83 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
> 
> diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
> new file mode 100644
> index 000000000000..94a4f00ae2c7
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
> @@ -0,0 +1,83 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/gpio/brcm,bcm63xx-gpio.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Broadcom BCM63xx GPIO controller
> +
> +maintainers:
> +  - Álvaro Fernández Rojas <noltari@gmail.com>
> +  - Jonas Gorski <jonas.gorski@gmail.com>
> +
> +description: |+
> +  The GPIO controller node should be the child of a syscon node.
> +
> +  Refer to the the bindings described in
> +  Documentation/devicetree/bindings/mfd/syscon.yaml

The above description is not too useful because it should hopefully 
later on in the series be expressed as a schema. IOW, the syscon schema 
should have a gpio child node with a $ref to this schema.

What would be useful is to say something about the GPIO block.

> +
> +properties:
> +  compatible:
> +    enum:
> +      - brcm,bcm6318-gpio
> +      - brcm,bcm6328-gpio
> +      - brcm,bcm6358-gpio
> +      - brcm,bcm6362-gpio
> +      - brcm,bcm6368-gpio
> +      - brcm,bcm63268-gpio
> +
> +  data:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: |
> +      Offset in the register map for the data register (in bytes).
> +
> +  dirout:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: |
> +      Offset in the register map for the dirout register (in bytes).

As I said earlier, copy what brcm,bcm6345-gpio.txt did and use reg 
instead of data and dirout properties.

That binding says it is for bcm63xx SoCs, too. So that should be 
resolved. It looks like it should be 1 binding IMO. The only difference 
I see is the number of GPIO lines and register size. The fact that the 
parent is a syscon in some cases is irrelevant.

> +
> +  gpio-controller: true
> +
> +  "#gpio-cells":
> +    const: 2
> +
> +  gpio-ranges:
> +    maxItems: 1
> +
> +  reg:
> +    maxItems: 1
> +
> +required:
> +  - compatible
> +  - gpio-controller
> +  - gpio-ranges
> +  - '#gpio-cells'
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    gpio@0 {
> +      compatible = "brcm,bcm6328-gpio";
> +      reg = <0x0 0x10>;
> +
> +      data = <0xc>;
> +      dirout = <0x4>;
> +
> +      gpio-controller;
> +      gpio-ranges = <&pinctrl 0 0 32>;
> +      #gpio-cells = <2>;
> +    };
> +
> +  - |
> +    gpio@0 {
> +      compatible = "brcm,bcm63268-gpio";
> +      reg = <0x0 0x10>;
> +
> +      data = <0xc>;
> +      dirout = <0x4>;
> +
> +      gpio-controller;
> +      gpio-ranges = <&pinctrl 0 0 52>;
> +      #gpio-cells = <2>;
> +    };
> -- 
> 2.20.1
>
Álvaro Fernández Rojas March 17, 2021, 10:46 a.m. | #2
Hi Rob,

> El 16 mar 2021, a las 21:54, Rob Herring <robh@kernel.org> escribió:
> 
> On Mon, Mar 15, 2021 at 12:41:55PM +0100, Álvaro Fernández Rojas wrote:
>> Add binding documentation for the GPIO controller found in BCM6318, BCM6328,
>> BCM6358, BCM6362, BCM6368 and BCM63268 SoCs.
>> 
>> Co-developed-by: Jonas Gorski <jonas.gorski@gmail.com>
>> Signed-off-by: Jonas Gorski <jonas.gorski@gmail.com>
>> Signed-off-by: Álvaro Fernández Rojas <noltari@gmail.com>
>> ---
>> v7: new patch, splitted from pinctrl documentation
>> 
>> .../bindings/gpio/brcm,bcm63xx-gpio.yaml      | 83 +++++++++++++++++++
>> 1 file changed, 83 insertions(+)
>> create mode 100644 Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
>> 
>> diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
>> new file mode 100644
>> index 000000000000..94a4f00ae2c7
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
>> @@ -0,0 +1,83 @@
>> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/gpio/brcm,bcm63xx-gpio.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Broadcom BCM63xx GPIO controller
>> +
>> +maintainers:
>> +  - Álvaro Fernández Rojas <noltari@gmail.com>
>> +  - Jonas Gorski <jonas.gorski@gmail.com>
>> +
>> +description: |+
>> +  The GPIO controller node should be the child of a syscon node.
>> +
>> +  Refer to the the bindings described in
>> +  Documentation/devicetree/bindings/mfd/syscon.yaml
> 
> The above description is not too useful because it should hopefully 
> later on in the series be expressed as a schema. IOW, the syscon schema 
> should have a gpio child node with a $ref to this schema.

Is the following OK?
description:
  BCM63XX GPIO controller driver which supports the SoC system controller supplied GPIO registers.
  The BCM63XX GPIO controller node must be defined as a child node of the BCM63XX GPIO system controller node.

> 
> What would be useful is to say something about the GPIO block.

Something like…?

> 
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - brcm,bcm6318-gpio
>> +      - brcm,bcm6328-gpio
>> +      - brcm,bcm6358-gpio
>> +      - brcm,bcm6362-gpio
>> +      - brcm,bcm6368-gpio
>> +      - brcm,bcm63268-gpio
>> +
>> +  data:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description: |
>> +      Offset in the register map for the data register (in bytes).
>> +
>> +  dirout:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description: |
>> +      Offset in the register map for the dirout register (in bytes).
> 
> As I said earlier, copy what brcm,bcm6345-gpio.txt did and use reg 
> instead of data and dirout properties.

Ok, I will remove dirout and data properties.

> 
> That binding says it is for bcm63xx SoCs, too. So that should be 
> resolved. It looks like it should be 1 binding IMO. The only difference 
> I see is the number of GPIO lines and register size. The fact that the 
> parent is a syscon in some cases is irrelevant.

Please be more specific.
What do you want me to do with this? How should I handle that?

> 
>> +
>> +  gpio-controller: true
>> +
>> +  "#gpio-cells":
>> +    const: 2
>> +
>> +  gpio-ranges:
>> +    maxItems: 1
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +required:
>> +  - compatible
>> +  - gpio-controller
>> +  - gpio-ranges
>> +  - '#gpio-cells'
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    gpio@0 {
>> +      compatible = "brcm,bcm6328-gpio";
>> +      reg = <0x0 0x10>;
>> +
>> +      data = <0xc>;
>> +      dirout = <0x4>;
>> +
>> +      gpio-controller;
>> +      gpio-ranges = <&pinctrl 0 0 32>;
>> +      #gpio-cells = <2>;
>> +    };
>> +
>> +  - |
>> +    gpio@0 {
>> +      compatible = "brcm,bcm63268-gpio";
>> +      reg = <0x0 0x10>;
>> +
>> +      data = <0xc>;
>> +      dirout = <0x4>;
>> +
>> +      gpio-controller;
>> +      gpio-ranges = <&pinctrl 0 0 52>;
>> +      #gpio-cells = <2>;
>> +    };
>> -- 
>> 2.20.1

Patch

diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
new file mode 100644
index 000000000000..94a4f00ae2c7
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
@@ -0,0 +1,83 @@ 
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/brcm,bcm63xx-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM63xx GPIO controller
+
+maintainers:
+  - Álvaro Fernández Rojas <noltari@gmail.com>
+  - Jonas Gorski <jonas.gorski@gmail.com>
+
+description: |+
+  The GPIO controller node should be the child of a syscon node.
+
+  Refer to the the bindings described in
+  Documentation/devicetree/bindings/mfd/syscon.yaml
+
+properties:
+  compatible:
+    enum:
+      - brcm,bcm6318-gpio
+      - brcm,bcm6328-gpio
+      - brcm,bcm6358-gpio
+      - brcm,bcm6362-gpio
+      - brcm,bcm6368-gpio
+      - brcm,bcm63268-gpio
+
+  data:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: |
+      Offset in the register map for the data register (in bytes).
+
+  dirout:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: |
+      Offset in the register map for the dirout register (in bytes).
+
+  gpio-controller: true
+
+  "#gpio-cells":
+    const: 2
+
+  gpio-ranges:
+    maxItems: 1
+
+  reg:
+    maxItems: 1
+
+required:
+  - compatible
+  - gpio-controller
+  - gpio-ranges
+  - '#gpio-cells'
+
+additionalProperties: false
+
+examples:
+  - |
+    gpio@0 {
+      compatible = "brcm,bcm6328-gpio";
+      reg = <0x0 0x10>;
+
+      data = <0xc>;
+      dirout = <0x4>;
+
+      gpio-controller;
+      gpio-ranges = <&pinctrl 0 0 32>;
+      #gpio-cells = <2>;
+    };
+
+  - |
+    gpio@0 {
+      compatible = "brcm,bcm63268-gpio";
+      reg = <0x0 0x10>;
+
+      data = <0xc>;
+      dirout = <0x4>;
+
+      gpio-controller;
+      gpio-ranges = <&pinctrl 0 0 52>;
+      #gpio-cells = <2>;
+    };