[PATCH V3 1/2] dt-bindings: pinctrl: support specifying pins, groups & functions

[Rafał Miłecki <zajec5@xxxxxxxxx>]

From: Rafał Miłecki <rafal@xxxxxxxxxx>

This binding change is meant to introduce a generic way of describing
pinctrl blocks details. Every pinmux block is expected to have:
1. Named pins
2. Named groups containing one or more pins
3. Named functions referencing one or more groups

It doesn't describe how hw should be programmed. That remains binding
and driver specific.

This commit describes a common syntax for "pins", "groups" & "functions"
nodes. Every node allows specifying its entries.

That design is meant to be extendable and minimalistic enough to be
generic (matching any hardware). Relations between pins, groups and
functions are expected to be the same for every hardware.

Using subnode objects allows extending this binding to cover hardware
specific needs (e.g. custom values). Example to consider:

pins {
    foo: foo {
        vendor,magic = <0xc0fe>;
    };
}

groups {
    bar {
        pins = <&foo>;
        vendor,secret = <0xbeaf>;
    };
};

Signed-off-by: Rafał Miłecki <rafal@xxxxxxxxxx>
---
 .../devicetree/bindings/pinctrl/pinctrl.yaml  | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml
index d471563119a9..e36662cb1f3b 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl.yaml
@@ -42,4 +42,38 @@ properties:
       This property can be set either globally for the pin controller or in
       child nodes for individual pin group control.
 
+  pins:
+    type: object
+
+    patternProperties:
+      "^.*$":
+        type: object
+        description: Pin named by node name
+
+  groups:
+    type: object
+
+    patternProperties:
+      "^.*$":
+        type: object
+        description: Group named by node name
+
+        properties:
+          pins:
+            $ref: /schemas/types.yaml#/definitions/phandle-array
+            description: Array of pins belonging to this group
+
+  functions:
+    type: object
+
+    patternProperties:
+      "^.*$":
+        type: object
+        description: Function named by node name
+
+        properties:
+          groups:
+            $ref: /schemas/types.yaml#/definitions/phandle-array
+            description: Array of groups used by this function
+
 additionalProperties: true
-- 
2.31.1