1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 # Copyright 2018 Linaro Ltd.
5 # All the top-level keys are standard json-schema keywords except for
6 # 'maintainers' and 'select'
8 # $id is a unique identifier based on the filename. There may or may not be a
9 # file present at the URL.
10 $id: http://devicetree.org/schemas/example-schema.yaml#
11 # $schema is the meta-schema this schema should be validated with.
12 $schema: http://devicetree.org/meta-schemas/core.yaml#
14 title: An example schema annotated with jsonschema details
17 - Rob Herring <robh@kernel.org>
20 A more detailed multi-line description of the binding.
22 Details about the hardware device and any links to datasheets can go here.
24 Literal blocks are marked with the '|' at the beginning. The end is marked by
25 indentation less than the first line of the literal block. Lines also cannot
26 begin with a tab character.
29 # 'select' is a schema applied to a DT node to determine if this binding
30 # schema should be applied to the node. It is optional and by default the
31 # possible compatible strings are extracted and used to match.
33 # In this case, a 'false' schema will never match.
36 # A dictionary of DT properties for this binding schema
38 # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND)
39 # to handle different conditions.
40 # In this case, it's needed to handle a variable number of values as there
41 # isn't another way to express a constraint of the last string value.
42 # The boolean schema must be a list of schemas.
45 # items is a list of possible values for the property. The number of
46 # values is determined by the number of elements in the list.
47 # Order in lists is significant, order in dicts is not
48 # Must be one of the 1st enums followed by the 2nd enum
50 # Each element in items should be 'enum' or 'const'
57 # additionalItems being false is implied
58 # minItems/maxItems equal to 2 is implied
60 # 'const' is just a special case of an enum with a single possible value
61 - const: vendor,soc1-ip
64 # The core schema already checks that reg values are numbers, so device
65 # specific schema don't need to do those checks.
66 # The description of each element defines the order and implicitly defines
67 # the number of reg entries.
69 - description: core registers
70 - description: aux registers
71 # minItems/maxItems equal to 2 is implied
74 # The core schema enforces this (*-names) is a string array
80 # Cases that have only a single entry just need to express that with maxItems
82 description: bus clock. A description is only needed for a single item if
83 there's something unique to add.
84 The items should have a fixed order, so pattern matching names are
92 # Either 1 or 2 interrupts can be present
95 - description: tx or combined interrupt
96 - description: rx interrupt
98 A variable number of interrupts warrants a description of what conditions
99 affect the number of interrupts. Otherwise, descriptions on standard
100 properties are not necessary.
101 The items should have a fixed order, so pattern matching names are
105 # minItems must be specified here because the default would be 2
111 # Property names starting with '#' must be quoted
113 # A simple case where the value must always be '2'.
114 # The core schema handles that this must be a single integer.
117 interrupt-controller: true
118 # The core checks this is a boolean, so just have to list it here to be
119 # valid for this binding.
122 # The type is set in the core schema. Per device schema only need to set
123 # constraints on the possible values.
126 # The value that should be used if the property is not present
131 description: A connection of the 'foo' gpio line.
133 # *-supply is always a single phandle, so nothing more to define.
136 # Vendor specific properties
138 # Vendor specific properties have slightly different schema requirements than
139 # common properties. They must have at least a type definition and
142 description: Vendor specific properties must have a description
143 $ref: /schemas/types.yaml#/definitions/uint32
144 enum: [2, 4, 6, 8, 10]
146 vendor,bool-property:
147 description: Vendor specific properties must have a description. Boolean
148 properties are one case where the json-schema 'type' keyword can be used
152 vendor,string-array-property:
153 description: Vendor specific properties should reference a type in the
155 $ref: /schemas/types.yaml#/definitions/string-array
160 vendor,property-in-standard-units-microvolt:
161 description: Vendor specific properties having a standard unit suffix
163 enum: [ 100, 200, 300 ]
166 description: Child nodes are just another property from a json-schema
168 type: object # DT nodes are json objects
170 vendor,a-child-node-property:
171 description: Child node properties have all the same schema
176 - vendor,a-child-node-property
178 # Describe the relationship between different properties
180 # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
182 vendor,bool-property: [ 'vendor,string-array-property' ]
183 # Expressing 2 properties in both orders means all of the set of properties
184 # must be present or none of them.
185 vendor,string-array-property: [ 'vendor,bool-property' ]
191 - interrupt-controller
193 # if/then schema can be used to handle conditions on a property affecting
194 # another property. A typical case is a specific 'compatible' value changes the
195 # constraints on other properties.
197 # For multiple 'if' schema, group them under an 'allOf'.
199 # If the conditionals become too unweldy, then it may be better to just split
200 # the binding into separate schema documents.
206 const: vendor,soc2-ip
210 # Altering schema depending on presence of properties is usually done by
211 # dependencies (see above), however some adjustments might require if:
214 - vendor,bool-property
220 # Ideally, the schema should have this line otherwise any other properties
221 # present are allowed. There's a few common properties such as 'status' and
222 # 'pinctrl-*' which are added automatically by the tooling.
224 # This can't be used in cases where another schema is referenced
225 # (i.e. allOf: [{$ref: ...}]).
226 # If and only if another schema is referenced and arbitrary children nodes can
227 # appear, "unevaluatedProperties: false" could be used. A typical example is
228 # an I2C controller where no name pattern matching for children can be added.
229 additionalProperties: false
232 # Examples are now compiled with dtc and validated against the schemas
234 # Examples have a default #address-cells and #size-cells value of 1. This can
235 # be overridden or an appropriate parent bus node should be shown (such as on
238 # Any includes used have to be explicitly included.
241 compatible = "vendor,soc4-ip", "vendor,soc1-ip";
244 reg-names = "core", "aux";
246 interrupt-controller;