diff options
Diffstat (limited to 'Documentation/devicetree/bindings/example-schema.yaml')
-rw-r--r-- | Documentation/devicetree/bindings/example-schema.yaml | 108 |
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; }; |