dt-bindings: pinctrl: brcm: Ensure all child node properties are documented

PATCH In review Rob Herring 2 participants 2 messages Oct 20, 2023 – Oct 23, 2023

Subsystems (4)

Device tree bindings GPIO Multifunction devices (MFD) Pin control

lore

Share & tools

lore

Rob Herring

author maintainer

2023-10-20 18:59 UTC #0 lore raw

PATCH v2 1/1 dt-bindings: pinctrl: brcm: Ensure all child node properties are documented

The Broadcom pinctrl bindings are incomplete for child nodes as they are missing 'unevaluatedProperties: false' to prevent unknown properties. Fixing this reveals many warnings including having grandchild nodes in some cases. Many cases in the examples use 'group' property which is undocumented and not used by the driver. As the schemas define 'pins', I assume that is the correct name except for the one case, 6358, using 'groups' which is documented.

Signed-off-by Rob Herring <[email protected]>

---
Well, it's been a year[1] and no one else has stepped up to fix these bindings. I'm still not certain where "pins" vs. "groups" is correct or whether it even matters (to the driver). As there are no .dts files to go by, I went with the schema being correct unless the example was the complete opposite (6358).

This is about the last thing blocking enabling checks that child node schemas have unevaluatedProperties or additionalProperties. If no one wants to fix this correctly, then apply this or we should remove the bindings.

[1] https://lore.kernel.org/all/[email protected]/

---
 .../mfd/brcm,bcm63268-gpio-sysctl.yaml        | 18 ++++++-------
 .../mfd/brcm,bcm6362-gpio-sysctl.yaml         |  2 +-
 .../mfd/brcm,bcm6368-gpio-sysctl.yaml         |  2 +-
 .../pinctrl/brcm,bcm6318-pinctrl.yaml         |  5 ++++
 .../pinctrl/brcm,bcm63268-pinctrl.yaml        | 25 +++++++++++--------
 .../pinctrl/brcm,bcm6328-pinctrl.yaml         |  5 ++++
 .../pinctrl/brcm,bcm6358-pinctrl.yaml         |  5 ++--
 .../pinctrl/brcm,bcm6362-pinctrl.yaml         |  7 +++++-
 .../pinctrl/brcm,bcm6368-pinctrl.yaml         |  7 +++++-
 9 files changed, 51 insertions(+), 25 deletions(-)

Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml +9 -9

index c14def1b2ad2..9c2a04829da5 100644
@@ -148,47 +148,47 @@ examples:
 
         pinctrl_nand: nand-pins {
           function = "nand";
-          group = "nand_grp";
+          pins = "nand_grp";
         };
 
         pinctrl_gpio35_alt: gpio35_alt-pins {
           function = "gpio35_alt";
-          pin = "gpio35";
+          pins = "gpio35";
         };
 
         pinctrl_dectpd: dectpd-pins {
           function = "dectpd";
-          group = "dectpd_grp";
+          pins = "dectpd_grp";
         };
 
         pinctrl_vdsl_phy_override_0: vdsl_phy_override_0-pins {
           function = "vdsl_phy_override_0";
-          group = "vdsl_phy_override_0_grp";
+          pins = "vdsl_phy_override_0_grp";
         };
 
         pinctrl_vdsl_phy_override_1: vdsl_phy_override_1-pins {
           function = "vdsl_phy_override_1";
-          group = "vdsl_phy_override_1_grp";
+          pins = "vdsl_phy_override_1_grp";
         };
 
         pinctrl_vdsl_phy_override_2: vdsl_phy_override_2-pins {
           function = "vdsl_phy_override_2";
-          group = "vdsl_phy_override_2_grp";
+          pins = "vdsl_phy_override_2_grp";
         };
 
         pinctrl_vdsl_phy_override_3: vdsl_phy_override_3-pins {
           function = "vdsl_phy_override_3";
-          group = "vdsl_phy_override_3_grp";
+          pins = "vdsl_phy_override_3_grp";
         };
 
         pinctrl_dsl_gpio8: dsl_gpio8-pins {
           function = "dsl_gpio8";
-          group = "dsl_gpio8";
+          pins = "dsl_gpio8";
         };
 
         pinctrl_dsl_gpio9: dsl_gpio9-pins {
           function = "dsl_gpio9";
-          group = "dsl_gpio9";
+          pins = "dsl_gpio9";
         };
       };
     };

Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml +1 -1

index 4d594739b382..c2941638c8f2 100644
@@ -230,7 +230,7 @@ examples:
 
         pinctrl_nand: nand-pins {
           function = "nand";
-          group = "nand_grp";
+          pins = "nand_grp";
         };
       };
     };

Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml +1 -1

index aae83d432880..44e77d77d314 100644
@@ -240,7 +240,7 @@ examples:
 
         pinctrl_uart1: uart1-pins {
           function = "uart1";
-          group = "uart1_grp";
+          pins = "uart1_grp";
         };
       };
     };

Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml +5 -0

index 4478a76171f7..62890a0aead1 100644
@@ -24,6 +24,7 @@ patternProperties:
   '-pins$':
     type: object
     $ref: pinmux-node.yaml#
+    additionalProperties: false
 
     properties:
       function:

@@ -37,6 +38,10 @@ patternProperties:
         enum: [ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7,
                 gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio40 ]
 
+    patternProperties:
+      '-pins$':
+        $ref: '#/patternProperties/-pins$'
+
 allOf:
   - $ref: pinctrl.yaml#

Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml +15 ~~-10~~

index 73e1caa7c011..7cc0e1650835 100644
@@ -24,6 +24,7 @@ patternProperties:
   '-pins$':
     type: object
     $ref: pinmux-node.yaml#
+    unevaluatedProperties: false
 
     properties:
       function:

@@ -36,11 +37,15 @@ patternProperties:
 
       pins:
         enum: [ gpio0, gpio1, gpio16, gpio17, gpio8, gpio9, gpio18, gpio19,
-                gpio22, gpio23, gpio30, gpio31, nand_grp, gpio35
+                gpio22, gpio23, gpio30, gpio31, nand_grp, gpio35,
                 dectpd_grp, vdsl_phy_override_0_grp,
                 vdsl_phy_override_1_grp, vdsl_phy_override_2_grp,
                 vdsl_phy_override_3_grp, dsl_gpio8, dsl_gpio9 ]
 
+    patternProperties:
+      '-pins$':
+        $ref: '#/patternProperties/-pins$'
+
 allOf:
   - $ref: pinctrl.yaml#

@@ -122,46 +127,46 @@ examples:
 
       pinctrl_nand: nand-pins {
         function = "nand";
-        group = "nand_grp";
+        pins = "nand_grp";
       };
 
       pinctrl_gpio35_alt: gpio35_alt-pins {
         function = "gpio35_alt";
-        pin = "gpio35";
+        pins = "gpio35";
       };
 
       pinctrl_dectpd: dectpd-pins {
         function = "dectpd";
-        group = "dectpd_grp";
+        pins = "dectpd_grp";
       };
 
       pinctrl_vdsl_phy_override_0: vdsl_phy_override_0-pins {
         function = "vdsl_phy_override_0";
-        group = "vdsl_phy_override_0_grp";
+        pins = "vdsl_phy_override_0_grp";
       };
 
       pinctrl_vdsl_phy_override_1: vdsl_phy_override_1-pins {
         function = "vdsl_phy_override_1";
-        group = "vdsl_phy_override_1_grp";
+        pins = "vdsl_phy_override_1_grp";
       };
 
       pinctrl_vdsl_phy_override_2: vdsl_phy_override_2-pins {
         function = "vdsl_phy_override_2";
-        group = "vdsl_phy_override_2_grp";
+        pins = "vdsl_phy_override_2_grp";
       };
 
       pinctrl_vdsl_phy_override_3: vdsl_phy_override_3-pins {
         function = "vdsl_phy_override_3";
-        group = "vdsl_phy_override_3_grp";
+        pins = "vdsl_phy_override_3_grp";
       };
 
       pinctrl_dsl_gpio8: dsl_gpio8-pins {
         function = "dsl_gpio8";
-        group = "dsl_gpio8";
+        pins = "dsl_gpio8";
       };
 
       pinctrl_dsl_gpio9: dsl_gpio9-pins {
         function = "dsl_gpio9";
-        group = "dsl_gpio9";
+        pins = "dsl_gpio9";
       };
     };

Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml +5 -0

index 2750ba42aeb8..f57bb34c3130 100644
@@ -24,6 +24,7 @@ patternProperties:
   '-pins$':
     type: object
     $ref: pinmux-node.yaml#
+    unevaluatedProperties: false
 
     properties:
       function:

@@ -36,6 +37,10 @@ patternProperties:
                 gpio20, gpio25, gpio26, gpio27, gpio28, hsspi_cs1,
                 usb_port1 ]
 
+    patternProperties:
+      '-pins$':
+        $ref: '#/patternProperties/-pins$'
+
 allOf:
   - $ref: pinctrl.yaml#

Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml +3 -2

index 2f6c540498bc..ce6fc5380c52 100644
@@ -24,15 +24,16 @@ patternProperties:
   '-pins$':
     type: object
     $ref: pinmux-node.yaml#
+    unevaluatedProperties: false
 
     properties:
       function:
         enum: [ ebi_cs, uart1, serial_led, legacy_led, led, spi_cs, utopia,
                 pwm_syn_clk, sys_irq ]
 
-      pins:
+      groups:
         enum: [ ebi_cs_grp, uart1_grp, serial_led_grp, legacy_led_grp,
-                led_grp, spi_cs_grp, utopia_grp, pwm_syn_clk, sys_irq_grp ]
+                led_grp, spi_cs_grp, utopia_grp, pwm_syn_clk_grp, sys_irq_grp ]
 
 allOf:
   - $ref: pinctrl.yaml#

Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml +6 -1

index b3044f805753..5f7ed7d3dd49 100644
@@ -24,6 +24,7 @@ patternProperties:
   '-pins$':
     type: object
     $ref: pinmux-node.yaml#
+    unevaluatedProperties: false
 
     properties:
       function:

@@ -41,6 +42,10 @@ patternProperties:
                 gpio15, gpio16, gpio17, gpio18, gpio19, gpio20, gpio21,
                 gpio22, gpio23, gpio24, gpio25, gpio26, gpio27, nand_grp ]
 
+    patternProperties:
+      '-pins$':
+        $ref: '#/patternProperties/-pins$'
+
 allOf:
   - $ref: pinctrl.yaml#

@@ -204,6 +209,6 @@ examples:
 
       pinctrl_nand: nand-pins {
         function = "nand";
-        group = "nand_grp";
+        pins = "nand_grp";
       };
     };

Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml +6 -1

index 3236871827df..d549e945505b 100644
@@ -24,6 +24,7 @@ patternProperties:
   '-pins$':
     type: object
     $ref: pinmux-node.yaml#
+    unevaluatedProperties: false
 
     properties:
       function:

@@ -42,6 +43,10 @@ patternProperties:
                 gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30,
                 gpio31, uart1_grp ]
 
+    patternProperties:
+      '-pins$':
+        $ref: '#/patternProperties/-pins$'
+
 allOf:
   - $ref: pinctrl.yaml#

@@ -215,6 +220,6 @@ examples:
 
       pinctrl_uart1: uart1-pins {
         function = "uart1";
-        group = "uart1_grp";
+        pins = "uart1_grp";
       };
     };

Signature · 1 line

2.42.0

Linus Walleij

2023-10-23 08:23 UTC #1 lore raw

Quoted 9 lines · Rob Herring

The Broadcom pinctrl bindings are incomplete for child nodes as they are missing 'unevaluatedProperties: false' to prevent unknown properties. Fixing this reveals many warnings including having grandchild nodes in some cases. Many cases in the examples use 'group' property which is undocumented and not used by the driver. As the schemas define 'pins', I assume that is the correct name except for the one case, 6358, using 'groups' which is documented.
Signed-off-by Rob Herring <[email protected]>

Patch applied!

Quoted 6 lines

Well, it's been a year[1] and no one else has stepped up to fix these bindings. I'm still not certain where "pins" vs. "groups" is correct or whether it even matters (to the driver). As there are no .dts files to go by, I went with the schema being correct unless the example was the complete opposite (6358).

Quoted 6 lines

This is about the last thing blocking enabling checks that child node schemas have unevaluatedProperties or additionalProperties. If no one wants to fix this correctly, then apply this or we should remove the bindings.
[1] https://lore.kernel.org/all/[email protected]/

AFAICT you did the right thing, thanks for your perseverance on this Rob!

Yours,
Linus Walleij