Skip to contentSkip to conversation

dt-bindings: example: Extend based on practice

PATCH Applied Krzysztof Kozlowski 2 participants 2 messages Sep 10, 2020 – Sep 15, 2020 Device tree bindings

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 dt-bindings: example: Extend based on practice

Extend the example schema with common rules which seems to be not that obvious:
1. Expecting arrays of phandles to be always ordered, regardless if "xxx-names" is provided (e.g. clocks),
2. Add example of altering a property based on presence of other property,
3. Document usage of unevaluatedProperties.

---
 .../devicetree/bindings/example-schema.yaml   | 33 ++++++++++++++-----
 1 file changed, 25 insertions(+), 8 deletions(-)
Documentation/devicetree/bindings/example-schema.yaml +25 -8
index 822975dbeafa..b381db1ae00a 100644
@@ -81,6 +81,8 @@ properties:
     maxItems: 1
     description: bus clock. A description is only needed for a single item if
       there's something unique to add.
+      The items should be have a fixed order, so pattern matching names are
+      discouraged.
 
   clock-names:
     items:
@@ -97,6 +99,8 @@ properties:
       A variable number of interrupts warrants a description of what conditions
       affect the number of interrupts. Otherwise, descriptions on standard
       properties are not necessary.
+      The items should be have a fixed order, so pattern matching names are
+      discouraged.
 
   interrupt-names:
     # minItems must be specified here because the default would be 2
@@ -196,14 +200,24 @@ required:
 #
 # If the conditionals become too unweldy, then it may be better to just split
 # the binding into separate schema documents.
-if:
-  properties:
-    compatible:
-      contains:
-        const: vendor,soc2-ip
-then:
-  required:
-    - foo-supply
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: vendor,soc2-ip
+    then:
+      required:
+        - foo-supply
+  # Altering schema depending on presence of properties is usually done by
+  # dependencies (see above), however some adjustments might require if:
+  - if:
+      required:
+        - vendor,bool-property
+    then:
+      properties:
+        vendor,int-property:
+          enum: [2, 4, 6]
 
 # Ideally, the schema should have this line otherwise any other properties
 # present are allowed. There's a few common properties such as 'status' and
@@ -211,6 +225,9 @@ then:
 #
 # This can't be used in cases where another schema is referenced
 # (i.e. allOf: [{$ref: ...}]).
+# If and only if another schema is referenced and arbitrary children nodes can
+# appear, "unevaluatedProperties: false" could be used.  Typical example is I2C
+# controller where no name pattern matching for childre can be added.
 additionalProperties: false
 
 examples:
Signature · 1 line
2.17.1
maintainer Applied
#1 lore raw
Quoted 8 lines · Krzysztof Kozlowski

Extend the example schema with common rules which seems to be not that obvious:
1. Expecting arrays of phandles to be always ordered, regardless if "xxx-names" is provided (e.g. clocks),
2. Add example of altering a property based on presence of other property,
3. Document usage of unevaluatedProperties.

Quoted 5 lines
---
 .../devicetree/bindings/example-schema.yaml   | 33 ++++++++++++++-----
 1 file changed, 25 insertions(+), 8 deletions(-)

Applied, thanks!

I keep meaning to go work on improving this...