Skip to contentSkip to conversation

dt-bindings: pinctrl: aspeed: Drop referenced nodes in examples

PATCH NAK Rob Herring 4 participants 5 messages Apr 22, 2022 – May 4, 2022

Subsystems (5)
lore
Share & tools
lore

Rob Herring

author maintainer
#0 lore raw

PATCH 1/1 dt-bindings: pinctrl: aspeed: Drop referenced nodes in examples

The additional nodes in the example referenced from the pinctrl node 'aspeed,external-nodes' properties are either incorrect (aspeed,ast2500-lpc) or not documented with a schema (aspeed,ast2500-gfx). There's no need to show these nodes as part of the pinctrl example, so just remove them.

---
 .../pinctrl/aspeed,ast2500-pinctrl.yaml       | 81 ++++---------------
 1 file changed, 16 insertions(+), 65 deletions(-)
Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml +16 -65
index 7c25c8d51116..9db904a528ee 100644
@@ -76,73 +76,24 @@ additionalProperties: false
 examples:
   - |
     #include <dt-bindings/clock/aspeed-clock.h>
-    apb {
-        compatible = "simple-bus";
-        #address-cells = <1>;
-        #size-cells = <1>;
-        ranges;
-
-        syscon: scu at 1e6e2000 {
-            compatible = "aspeed,ast2500-scu", "syscon", "simple-mfd";
-            reg = <0x1e6e2000 0x1a8>;
-            #clock-cells = <1>;
-            #reset-cells = <1>;
-
-            pinctrl: pinctrl {
-                compatible = "aspeed,ast2500-pinctrl";
-                aspeed,external-nodes = <&gfx>, <&lhc>;
-
-                pinctrl_i2c3_default: i2c3_default {
-                    function = "I2C3";
-                    groups = "I2C3";
-                };
-
-                pinctrl_gpioh0_unbiased_default: gpioh0 {
-                    pins = "A18";
-                    bias-disable;
-                };
+    scu at 1e6e2000 {
+        compatible = "aspeed,ast2500-scu", "syscon", "simple-mfd";
+        reg = <0x1e6e2000 0x1a8>;
+        #clock-cells = <1>;
+        #reset-cells = <1>;
+
+        pinctrl: pinctrl {
+            compatible = "aspeed,ast2500-pinctrl";
+            aspeed,external-nodes = <&gfx>, <&lhc>;
+
+            pinctrl_i2c3_default: i2c3_default {
+                function = "I2C3";
+                groups = "I2C3";
             };
-        };
-
-        gfx: display at 1e6e6000 {
-            compatible = "aspeed,ast2500-gfx", "syscon";
-            reg = <0x1e6e6000 0x1000>;
-            reg-io-width = <4>;
-            clocks = <&syscon ASPEED_CLK_GATE_D1CLK>;
-            resets = <&syscon ASPEED_RESET_CRT1>;
-            interrupts = <0x19>;
-            syscon = <&syscon>;
-            memory-region = <&gfx_memory>;
-        };
-    };
-
-    lpc: lpc at 1e789000 {
-        compatible = "aspeed,ast2500-lpc", "simple-mfd";
-        reg = <0x1e789000 0x1000>;
-
-        #address-cells = <1>;
-        #size-cells = <1>;
-        ranges = <0x0 0x1e789000 0x1000>;
-
-        lpc_host: lpc-host at 80 {
-            compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon";
-            reg = <0x80 0x1e0>;
-            reg-io-width = <4>;
 
-            #address-cells = <1>;
-            #size-cells = <1>;
-            ranges = <0x0 0x80 0x1e0>;
-
-            lhc: lhc at 20 {
-                   compatible = "aspeed,ast2500-lhc";
-                   reg = <0x20 0x24>, <0x48 0x8>;
+            pinctrl_gpioh0_unbiased_default: gpioh0 {
+                pins = "A18";
+                bias-disable;
             };
         };
     };
-
-    gfx_memory: framebuffer {
-        size = <0x01000000>;
-        alignment = <0x01000000>;
-        compatible = "shared-dma-pool";
-        reusable;
-    };
Signature · 1 line
2.32.0
maintainer NAK
#1 lore raw
Quoted 7 lines · Rob Herring

The additional nodes in the example referenced from the pinctrl node 'aspeed,external-nodes' properties are either incorrect (aspeed,ast2500-lpc) or not documented with a schema (aspeed,ast2500-gfx). There's no need to show these nodes as part of the pinctrl example, so just remove them.

Nak.

This removes the information on how to use the bindings. Surely we prefer to over document rather than under document?

Quoted 101 lines
---
 .../pinctrl/aspeed,ast2500-pinctrl.yaml       | 81 ++++---------------
 1 file changed, 16 insertions(+), 65 deletions(-)
Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml +16 -66
index 7c25c8d51116..9db904a528ee 100644
@@ -76,73 +76,24 @@ additionalProperties: false
 examples:
   - |
     #include <dt-bindings/clock/aspeed-clock.h>
-    apb {
-        compatible = "simple-bus";
-        #address-cells = <1>;
-        #size-cells = <1>;
-        ranges;
-
-        syscon: scu at 1e6e2000 {
-            compatible = "aspeed,ast2500-scu", "syscon", "simple-mfd";
-            reg = <0x1e6e2000 0x1a8>;
-            #clock-cells = <1>;
-            #reset-cells = <1>;
-
-            pinctrl: pinctrl {
-                compatible = "aspeed,ast2500-pinctrl";
-                aspeed,external-nodes = <&gfx>, <&lhc>;
-
-                pinctrl_i2c3_default: i2c3_default {
-                    function = "I2C3";
-                    groups = "I2C3";
-                };
-
-                pinctrl_gpioh0_unbiased_default: gpioh0 {
-                    pins = "A18";
-                    bias-disable;
-                };
+    scu at 1e6e2000 {
+        compatible = "aspeed,ast2500-scu", "syscon", "simple-mfd";
+        reg = <0x1e6e2000 0x1a8>;
+        #clock-cells = <1>;
+        #reset-cells = <1>;
+
+        pinctrl: pinctrl {
+            compatible = "aspeed,ast2500-pinctrl";
+            aspeed,external-nodes = <&gfx>, <&lhc>;
+
+            pinctrl_i2c3_default: i2c3_default {
+                function = "I2C3";
+                groups = "I2C3";
             };
-        };
-
-        gfx: display at 1e6e6000 {
-            compatible = "aspeed,ast2500-gfx", "syscon";
-            reg = <0x1e6e6000 0x1000>;
-            reg-io-width = <4>;
-            clocks = <&syscon ASPEED_CLK_GATE_D1CLK>;
-            resets = <&syscon ASPEED_RESET_CRT1>;
-            interrupts = <0x19>;
-            syscon = <&syscon>;
-            memory-region = <&gfx_memory>;
-        };
-    };
-
-    lpc: lpc at 1e789000 {
-        compatible = "aspeed,ast2500-lpc", "simple-mfd";
-        reg = <0x1e789000 0x1000>;
-
-        #address-cells = <1>;
-        #size-cells = <1>;
-        ranges = <0x0 0x1e789000 0x1000>;
-
-        lpc_host: lpc-host at 80 {
-            compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon";
-            reg = <0x80 0x1e0>;
-            reg-io-width = <4>;
 
-            #address-cells = <1>;
-            #size-cells = <1>;
-            ranges = <0x0 0x80 0x1e0>;
-
-            lhc: lhc at 20 {
-                   compatible = "aspeed,ast2500-lhc";
-                   reg = <0x20 0x24>, <0x48 0x8>;
+            pinctrl_gpioh0_unbiased_default: gpioh0 {
+                pins = "A18";
+                bias-disable;
             };
         };
     };
-
-    gfx_memory: framebuffer {
-        size = <0x01000000>;
-        alignment = <0x01000000>;
-        compatible = "shared-dma-pool";
-        reusable;
-    };
--

2.32.0

author maintainer
#2 lore raw
Quoted 10 lines · Joel Stanley
Quoted 7 lines · Rob Herring

The additional nodes in the example referenced from the pinctrl node 'aspeed,external-nodes' properties are either incorrect (aspeed,ast2500-lpc) or not documented with a schema (aspeed,ast2500-gfx). There's no need to show these nodes as part of the pinctrl example, so just remove them.

Nak.

I welcome patches that add schemas for the undocumented compatibles instead. Otherwise, I will be turning on this check by default and nagging people to fix them.

Quoted 2 lines

This removes the information on how to use the bindings. Surely we prefer to over document rather than under document?

How is what the 'gfx' and 'lpc' nodes contain relevant to how the pinctrl binding works? If a user wants to know, then they should go look at the aspeed,ast2500-lpc/aspeed,ast2500-gfx bindings and their examples. Which brings up my secondary issue which is having the same example multiple times. It is multiple chances for errors (that I end up fixing).

How do we know the example is even correct without any schema checks? The 'framebuffer' node is not in a valid location is the most obvious thing I see.

Rob

#3 lore raw
In reply to Joel Stanley
Quoted 7 lines · Joel Stanley
Quoted 6 lines · Rob Herring

The additional nodes in the example referenced from the pinctrl node 'aspeed,external-nodes' properties are either incorrect (aspeed,ast2500-lpc) or not documented with a schema (aspeed,ast2500-gfx). There's no need to show these nodes as part of the pinctrl example, so just remove them.

Quoted 6 lines
Quoted 1 line

Nak.

This removes the information on how to use the bindings. Surely we prefer to over document rather than under document?

There is no need to document consumers of generic providers, like syscon, clock or pinctrl. These are already well documented. The examples of consumers here do not bring any additional value.

Best regards,
Krzysztof

#4 lore raw
In reply to Rob Herring
Quoted 6 lines · Rob Herring

The additional nodes in the example referenced from the pinctrl node 'aspeed,external-nodes' properties are either incorrect (aspeed,ast2500-lpc) or not documented with a schema (aspeed,ast2500-gfx). There's no need to show these nodes as part of the pinctrl example, so just remove them.

Patch applied. Concerns about lost examples can be solved with incremental patches on top adding more schema.

Yours,
Linus Walleij