aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/example-schema.yaml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/devicetree/bindings/example-schema.yaml')
-rw-r--r--Documentation/devicetree/bindings/example-schema.yaml108
1 files changed, 68 insertions, 40 deletions
diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml
index 62811a1b5058..a41f9b9a196b 100644
--- a/Documentation/devicetree/bindings/example-schema.yaml
+++ b/Documentation/devicetree/bindings/example-schema.yaml
@@ -11,7 +11,7 @@ $id: http://devicetree.org/schemas/example-schema.yaml#
# $schema is the meta-schema this schema should be validated with.
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: An example schema annotated with jsonschema details
+title: An Example Device
maintainers:
- Rob Herring <robh@kernel.org>
@@ -52,8 +52,7 @@ properties:
- vendor,soc4-ip
- vendor,soc3-ip
- vendor,soc2-ip
- - enum:
- - vendor,soc1-ip
+ - const: vendor,soc1-ip
# additionalItems being false is implied
# minItems/maxItems equal to 2 is implied
- items:
@@ -81,15 +80,19 @@ 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 have a fixed order, so pattern matching names are
+ discouraged.
clock-names:
+ # For single-entry lists in clocks, resets etc., the xxx-names often do not
+ # bring any value, especially if they copy the IP block name. In such case
+ # just skip the xxx-names.
items:
- const: bus
interrupts:
# Either 1 or 2 interrupts can be present
minItems: 1
- maxItems: 2
items:
- description: tx or combined interrupt
- description: rx interrupt
@@ -97,11 +100,12 @@ 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 have a fixed order, so pattern matching names are
+ discouraged.
interrupt-names:
# minItems must be specified here because the default would be 2
minItems: 1
- maxItems: 2
items:
- const: tx irq
- const: rx irq
@@ -117,7 +121,7 @@ properties:
# valid for this binding.
clock-frequency:
- # The type is set in the core schema. Per device schema only need to set
+ # The type is set in the core schema. Per-device schema only need to set
# constraints on the possible values.
minimum: 100
maximum: 400000
@@ -131,44 +135,51 @@ properties:
# *-supply is always a single phandle, so nothing more to define.
foo-supply: true
- # Vendor specific properties
+ # Vendor-specific properties
#
- # Vendor specific properties have slightly different schema requirements than
+ # Vendor-specific properties have slightly different schema requirements than
# common properties. They must have at least a type definition and
# 'description'.
vendor,int-property:
- description: Vendor specific properties must have a description
- # 'allOf' is the json-schema way of subclassing a schema. Here the base
- # type schema is referenced and then additional constraints on the values
- # are added.
- allOf:
- - $ref: /schemas/types.yaml#/definitions/uint32
- - enum: [2, 4, 6, 8, 10]
+ description: Vendor-specific properties must have a description
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [2, 4, 6, 8, 10]
vendor,bool-property:
- description: Vendor specific properties must have a description. Boolean
+ description: Vendor-specific properties must have a description. Boolean
properties are one case where the json-schema 'type' keyword can be used
directly.
type: boolean
vendor,string-array-property:
- description: Vendor specific properties should reference a type in the
+ description: Vendor-specific properties should reference a type in the
core schema.
- allOf:
- - $ref: /schemas/types.yaml#/definitions/string-array
- - items:
- - enum: [ foo, bar ]
- - enum: [ baz, boo ]
+ $ref: /schemas/types.yaml#/definitions/string-array
+ items:
+ - enum: [foo, bar]
+ - enum: [baz, boo]
vendor,property-in-standard-units-microvolt:
- description: Vendor specific properties having a standard unit suffix
+ description: Vendor-specific properties having a standard unit suffix
don't need a type.
enum: [ 100, 200, 300 ]
+ vendor,int-array-variable-length-and-constrained-values:
+ description: Array might define what type of elements might be used (e.g.
+ their range).
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 2
+ maxItems: 3
+ items:
+ minimum: 0
+ maximum: 8
+
child-node:
description: Child nodes are just another property from a json-schema
perspective.
type: object # DT nodes are json objects
+ # Child nodes also need additionalProperties or unevaluatedProperties
+ additionalProperties: false
properties:
vendor,a-child-node-property:
description: Child node properties have all the same schema
@@ -182,10 +193,10 @@ properties:
dependencies:
# 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
# is present
- vendor,bool-property: [ vendor,string-array-property ]
+ vendor,bool-property: [ 'vendor,string-array-property' ]
# Expressing 2 properties in both orders means all of the set of properties
# must be present or none of them.
- vendor,string-array-property: [ vendor,bool-property ]
+ vendor,string-array-property: [ 'vendor,bool-property' ]
required:
- compatible
@@ -201,14 +212,28 @@ 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
+ else:
+ # If otherwise the property is not allowed:
+ properties:
+ foo-supply: false
+ # 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
@@ -216,6 +241,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. A typical example is
+# an I2C controller where no name pattern matching for children can be added.
additionalProperties: false
examples:
@@ -225,13 +253,13 @@ examples:
# be overridden or an appropriate parent bus node should be shown (such as on
# i2c buses).
#
- # Any includes used have to be explicitly included.
+ # Any includes used have to be explicitly included. Use 4-space indentation.
- |
node@1000 {
- compatible = "vendor,soc4-ip", "vendor,soc1-ip";
- reg = <0x1000 0x80>,
- <0x3000 0x80>;
- reg-names = "core", "aux";
- interrupts = <10>;
- interrupt-controller;
+ compatible = "vendor,soc4-ip", "vendor,soc1-ip";
+ reg = <0x1000 0x80>,
+ <0x3000 0x80>;
+ reg-names = "core", "aux";
+ interrupts = <10>;
+ interrupt-controller;
};