[PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[Paul Cercueil]

Convert the ingenic,pinctrl.txt doc file to ingenic,pinctrl.yaml.

In the process, some compatible strings now require a fallback, as the
corresponding SoCs are pin-compatible with their fallback variant.

Signed-off-by: Paul Cercueil <paul@crapouillou.net>
---

Notes:
    v2: - Use 'pinctrl' instead of 'pin-controller' as the node name
        - remove 'additionalProperties: false' since we will have pin conf nodes

 .../bindings/pinctrl/ingenic,pinctrl.txt      |  81 -----------
 .../bindings/pinctrl/ingenic,pinctrl.yaml     | 136 ++++++++++++++++++
 2 files changed, 136 insertions(+), 81 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
 create mode 100644 Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml

diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
deleted file mode 100644
index d9b2100c98e8..000000000000
--- a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
+++ /dev/null
@@ -1,81 +0,0 @@
-Ingenic XBurst pin controller
-
-Please refer to pinctrl-bindings.txt in this directory for details of the
-common pinctrl bindings used by client devices, including the meaning of the
-phrase "pin configuration node".
-
-For the XBurst SoCs, pin control is tightly bound with GPIO ports. All pins may
-be used as GPIOs, multiplexed device functions are configured within the
-GPIO port configuration registers and it is typical to refer to pins using the
-naming scheme "PxN" where x is a character identifying the GPIO port with
-which the pin is associated and N is an integer from 0 to 31 identifying the
-pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and
-PB31 is the last pin in GPIO port B. The jz4740, the x1000 and the x1830
-contains 4 GPIO ports, PA to PD, for a total of 128 pins. The jz4760, the
-jz4770 and the jz4780 contains 6 GPIO ports, PA to PF, for a total of 192 pins.
-
-
-Required properties:
---------------------
-
- - compatible: One of:
-    - "ingenic,jz4740-pinctrl"
-    - "ingenic,jz4725b-pinctrl"
-    - "ingenic,jz4760-pinctrl"
-    - "ingenic,jz4760b-pinctrl"
-    - "ingenic,jz4770-pinctrl"
-    - "ingenic,jz4780-pinctrl"
-    - "ingenic,x1000-pinctrl"
-    - "ingenic,x1000e-pinctrl"
-    - "ingenic,x1500-pinctrl"
-    - "ingenic,x1830-pinctrl"
- - reg: Address range of the pinctrl registers.
-
-
-Required properties for sub-nodes (GPIO chips):
------------------------------------------------
-
- - compatible: Must contain one of:
-    - "ingenic,jz4740-gpio"
-    - "ingenic,jz4760-gpio"
-    - "ingenic,jz4770-gpio"
-    - "ingenic,jz4780-gpio"
-    - "ingenic,x1000-gpio"
-    - "ingenic,x1830-gpio"
- - reg: The GPIO bank number.
- - interrupt-controller: Marks the device node as an interrupt controller.
- - interrupts: Interrupt specifier for the controllers interrupt.
- - #interrupt-cells: Should be 2. Refer to
-   ../interrupt-controller/interrupts.txt for more details.
- - gpio-controller: Marks the device node as a GPIO controller.
- - #gpio-cells: Should be 2. The first cell is the GPIO number and the second
-    cell specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. Only the
-    GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported.
- - gpio-ranges: Range of pins managed by the GPIO controller. Refer to
-   ../gpio/gpio.txt for more details.
-
-
-Example:
---------
-
-pinctrl: pin-controller@10010000 {
-	compatible = "ingenic,jz4740-pinctrl";
-	reg = <0x10010000 0x400>;
-	#address-cells = <1>;
-	#size-cells = <0>;
-
-	gpa: gpio@0 {
-		compatible = "ingenic,jz4740-gpio";
-		reg = <0>;
-
-		gpio-controller;
-		gpio-ranges = <&pinctrl 0 0 32>;
-		#gpio-cells = <2>;
-
-		interrupt-controller;
-		#interrupt-cells = <2>;
-
-		interrupt-parent = <&intc>;
-		interrupts = <28>;
-	};
-};
diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml
new file mode 100644
index 000000000000..5be2b1e95b36
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/ingenic,pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ingenic SoCs pin controller devicetree bindings
+
+description: >
+  Please refer to pinctrl-bindings.txt in this directory for details of the
+  common pinctrl bindings used by client devices, including the meaning of the
+  phrase "pin configuration node".
+
+  For the Ingenic SoCs, pin control is tightly bound with GPIO ports. All pins
+  may be used as GPIOs, multiplexed device functions are configured within the
+  GPIO port configuration registers and it is typical to refer to pins using the
+  naming scheme "PxN" where x is a character identifying the GPIO port with
+  which the pin is associated and N is an integer from 0 to 31 identifying the
+  pin within that GPIO port. For example PA0 is the first pin in GPIO port A,
+  and PB31 is the last pin in GPIO port B. The JZ4740, the X1000 and the X1830
+  contains 4 GPIO ports, PA to PD, for a total of 128 pins. The JZ4760, the
+  JZ4770 and the JZ4780 contains 6 GPIO ports, PA to PF, for a total of 192
+  pins.
+
+maintainers:
+  - Paul Cercueil <paul@crapouillou.net>
+
+properties:
+  nodename:
+    pattern: "^pinctrl@[0-9a-f]+$"
+
+  compatible:
+    oneOf:
+      - enum:
+        - ingenic,jz4740-pinctrl
+        - ingenic,jz4725b-pinctrl
+        - ingenic,jz4760-pinctrl
+        - ingenic,jz4770-pinctrl
+        - ingenic,jz4780-pinctrl
+        - ingenic,x1000-pinctrl
+        - ingenic,x1500-pinctrl
+        - ingenic,x1830-pinctrl
+      - items:
+        - const: ingenic,jz4760b-pinctrl
+        - const: ingenic,jz4760-pinctrl
+      - items:
+        - const: ingenic,x1000e-pinctrl
+        - const: ingenic,x1000-pinctrl
+
+  reg:
+    maxItems: 1
+
+  "#address-cells":
+    const: 1
+
+  "#size-cells":
+    const: 0
+
+patternProperties:
+  "^gpio@[0-9]$":
+    type: object
+    properties:
+      compatible:
+        enum:
+          - ingenic,jz4740-gpio
+          - ingenic,jz4725b-gpio
+          - ingenic,jz4760-gpio
+          - ingenic,jz4770-gpio
+          - ingenic,jz4780-gpio
+          - ingenic,x1000-gpio
+          - ingenic,x1500-gpio
+          - ingenic,x1830-gpio
+
+      reg:
+        items:
+          - description: The GPIO bank number
+
+      gpio-controller: true
+
+      "#gpio-cells":
+        const: 2
+
+      gpio-ranges:
+        maxItems: 1
+
+      interrupt-controller: true
+
+      "#interrupt-cells":
+        const: 2
+        description:
+          Refer to ../interrupt-controller/interrupts.txt for more details.
+
+      interrupts:
+        maxItems: 1
+
+    required:
+      - compatible
+      - reg
+      - gpio-controller
+      - "#gpio-cells"
+      - interrupts
+      - interrupt-controller
+      - "#interrupt-cells"
+
+    additionalProperties: false
+
+required:
+  - compatible
+  - reg
+  - "#address-cells"
+  - "#size-cells"
+
+examples:
+  - |
+    pin-controller@10010000 {
+      compatible = "ingenic,jz4770-pinctrl";
+      reg = <0x10010000 0x600>;
+
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      gpio@0 {
+        compatible = "ingenic,jz4770-gpio";
+        reg = <0>;
+
+        gpio-controller;
+        gpio-ranges = <&pinctrl 0 0 32>;
+        #gpio-cells = <2>;
+
+        interrupt-controller;
+        #interrupt-cells = <2>;
+
+        interrupt-parent = <&intc>;
+        interrupts = <17>;
+      };
+    };
-- 
2.26.2

Re: [PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[Linus Walleij]

On Mon, Jun 22, 2020 at 1:38 PM Paul Cercueil <paul@crapouillou.net> wrote:

> Convert the ingenic,pinctrl.txt doc file to ingenic,pinctrl.yaml.
>
> In the process, some compatible strings now require a fallback, as the
> corresponding SoCs are pin-compatible with their fallback variant.
>
> Signed-off-by: Paul Cercueil <paul@crapouillou.net>
> ---
>
> Notes:
>     v2: - Use 'pinctrl' instead of 'pin-controller' as the node name
>         - remove 'additionalProperties: false' since we will have pin conf nodes

Patch applied.

Yours,
Linus Walleij

Re: [PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[Rob Herring]

On Mon, Jun 22, 2020 at 01:37:40PM +0200, Paul Cercueil wrote:
> Convert the ingenic,pinctrl.txt doc file to ingenic,pinctrl.yaml.
> 
> In the process, some compatible strings now require a fallback, as the
> corresponding SoCs are pin-compatible with their fallback variant.
> 
> Signed-off-by: Paul Cercueil <paul@crapouillou.net>
> ---
> 
> Notes:
>     v2: - Use 'pinctrl' instead of 'pin-controller' as the node name
>         - remove 'additionalProperties: false' since we will have pin conf nodes

What do those look like? They need to be described, but that can be a 
follow-up. 

Rob

Re: [PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[Paul Cercueil]

Hi Rob,

Le lun. 13 juil. 2020 à 9:32, Rob Herring <robh@kernel.org> a écrit :
> On Mon, Jun 22, 2020 at 01:37:40PM +0200, Paul Cercueil wrote:
>>  Convert the ingenic,pinctrl.txt doc file to ingenic,pinctrl.yaml.
>> 
>>  In the process, some compatible strings now require a fallback, as 
>> the
>>  corresponding SoCs are pin-compatible with their fallback variant.
>> 
>>  Signed-off-by: Paul Cercueil <paul@crapouillou.net>
>>  ---
>> 
>>  Notes:
>>      v2: - Use 'pinctrl' instead of 'pin-controller' as the node name
>>          - remove 'additionalProperties: false' since we will have 
>> pin conf nodes
> 
> What do those look like? They need to be described, but that can be a
> follow-up.

These are generic conf nodes that are handled by the pinctrl core. 
Nothing specific to the hardware described here. The subnodes don't 
have any specific pattern so it is not possible to represent them in 
devicetree (we'd need a 'catch them all' wildcard pattern property).

Cheers,
-Paul

Re: [PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[Rob Herring]

On Mon, Jul 13, 2020 at 9:36 AM Paul Cercueil <paul@crapouillou.net> wrote:
>
> Hi Rob,
>
> Le lun. 13 juil. 2020 à 9:32, Rob Herring <robh@kernel.org> a écrit :
> > On Mon, Jun 22, 2020 at 01:37:40PM +0200, Paul Cercueil wrote:
> >>  Convert the ingenic,pinctrl.txt doc file to ingenic,pinctrl.yaml.
> >>
> >>  In the process, some compatible strings now require a fallback, as
> >> the
> >>  corresponding SoCs are pin-compatible with their fallback variant.
> >>
> >>  Signed-off-by: Paul Cercueil <paul@crapouillou.net>
> >>  ---
> >>
> >>  Notes:
> >>      v2: - Use 'pinctrl' instead of 'pin-controller' as the node name
> >>          - remove 'additionalProperties: false' since we will have
> >> pin conf nodes
> >
> > What do those look like? They need to be described, but that can be a
> > follow-up.
>
> These are generic conf nodes that are handled by the pinctrl core.

No such thing. There's a set of common properties, but that is all.
You still need to document which properties apply because it is
doubtful they all do.

> Nothing specific to the hardware described here. The subnodes don't
> have any specific pattern so it is not possible to represent them in
> devicetree (we'd need a 'catch them all' wildcard pattern property).

Ideally, the nodes should be named something we can match on like
"-pins$", but if not you can do:

additionalProperties:
  type: object
  $ref: pincfg-node.yaml#
  properties:
    bias-disable: true
    ...
  additionalProperties: false


Rob

Re: [PATCH RESEND v2] dt-bindings: pinctrl: Convert ingenic,pinctrl.txt to YAML

[Linus Walleij]

On Tue, Jul 14, 2020 at 4:05 PM Rob Herring <robh@kernel.org> wrote:
> On Mon, Jul 13, 2020 at 9:36 AM Paul Cercueil <paul@crapouillou.net> wrote:

> > >>  Notes:
> > >>      v2: - Use 'pinctrl' instead of 'pin-controller' as the node name
> > >>          - remove 'additionalProperties: false' since we will have
> > >> pin conf nodes
> > >
> > > What do those look like? They need to be described, but that can be a
> > > follow-up.
> >
> > These are generic conf nodes that are handled by the pinctrl core.
>
> No such thing. There's a set of common properties, but that is all.
> You still need to document which properties apply because it is
> doubtful they all do.

Paul can you make a follow-up patch to fix this?

Yours,
Linus Walleij