projects/linux·blob master · refs

279 lines · 9.4 KiB

1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2# Copyright 2018 Linaro Ltd.
3%YAML 1.2
4---
5# All the top-level keys are standard json-schema keywords except for
6# 'maintainers' and 'select'
7
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#
13
14title: An Example Device
15
16maintainers:
17 - Rob Herring <[email protected]>
18
19description: |
20 A more detailed multi-line description of the binding.
21
22 Details about the hardware device and any links to datasheets can go here.
23
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.
27
28select: false
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.
32
33 # In this case, a 'false' schema will never match.
34
35properties:
36 # A dictionary of DT properties for this binding schema
37 compatible:
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.
43 oneOf:
44 - items:
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
49 #
50 # Each element in items should be 'enum' or 'const'
51 - enum:
52 - vendor,soc4-ip
53 - vendor,soc3-ip
54 - vendor,soc2-ip
55 - const: vendor,soc1-ip
56 # additionalItems being false is implied
57 # minItems/maxItems equal to 2 is implied
58 - items:
59 # 'const' is just a special case of an enum with a single possible value
60 - const: vendor,soc1-ip
61
62 reg:
63 # The core schema already checks that reg values are numbers, so device
64 # specific schema don't need to do those checks.
65 # The description of each element defines the order and implicitly defines
66 # the number of reg entries.
67 items:
68 - description: core registers
69 - description: aux registers
70 # minItems/maxItems equal to 2 is implied
71
72 reg-names:
73 # The core schema enforces this (*-names) is a string array
74 items:
75 - const: core
76 - const: aux
77
78 clocks:
79 # Cases that have only a single entry just need to express that with maxItems
80 maxItems: 1
81 description: bus clock. A description is only needed for a single item if
82 there's something unique to add.
83 The items should have a fixed order, so pattern matching names are
84 discouraged.
85
86 clock-names:
87 # For single-entry lists in clocks, resets etc., the xxx-names often do not
88 # bring any value, especially if they copy the IP block name. In such case
89 # just skip the xxx-names.
90 items:
91 - const: bus
92
93 interrupts:
94 # Either 1 or 2 interrupts can be present
95 minItems: 1
96 items:
97 - description: tx or combined interrupt
98 - description: rx interrupt
99 description:
100 A variable number of interrupts warrants a description of what conditions
101 affect the number of interrupts. Otherwise, descriptions on standard
102 properties are not necessary.
103 The items should have a fixed order, so pattern matching names are
104 discouraged.
105
106 interrupt-names:
107 # minItems must be specified here because the default would be 2
108 minItems: 1
109 items:
110 - const: tx irq
111 - const: rx irq
112
113 # Property names starting with '#' must be quoted
114 '#interrupt-cells':
115 # A simple case where the value must always be '2'.
116 # The core schema handles that this must be a single integer.
117 const: 2
118
119 interrupt-controller: true
120 # The core checks this is a boolean, so just have to list it here to be
121 # valid for this binding.
122
123 clock-frequency:
124 # The type is set in the core schema. Per-device schema only need to set
125 # constraints on the possible values.
126 minimum: 100
127 maximum: 400000
128 # The value that should be used if the property is not present
129 default: 200
130
131 foo-gpios:
132 maxItems: 1
133 description: A connection of the 'foo' gpio line.
134
135 # *-supply is always a single phandle, so nothing more to define.
136 foo-supply: true
137
138 # Vendor-specific properties
139 #
140 # Vendor-specific properties have slightly different schema requirements than
141 # common properties. They must have at least a type definition and
142 # 'description'.
143 vendor,int-property:
144 description: Vendor-specific properties must have a description
145 $ref: /schemas/types.yaml#/definitions/uint32
146 enum: [2, 4, 6, 8, 10]
147
148 vendor,bool-property:
149 description: Vendor-specific properties must have a description. Boolean
150 properties are one case where the json-schema 'type' keyword can be used
151 directly.
152 type: boolean
153
154 vendor,string-array-property:
155 description: Vendor-specific properties should reference a type in the
156 core schema.
157 $ref: /schemas/types.yaml#/definitions/string-array
158 items:
159 - enum: [foo, bar]
160 - enum: [baz, boo]
161
162 vendor,property-in-standard-units-microvolt:
163 description: Vendor-specific properties having a standard unit suffix
164 don't need a type.
165 enum: [ 100, 200, 300 ]
166
167 vendor,int-array-variable-length-and-constrained-values:
168 description: Array might define what type of elements might be used (e.g.
169 their range).
170 $ref: /schemas/types.yaml#/definitions/uint32-array
171 minItems: 2
172 maxItems: 3
173 items:
174 minimum: 0
175 maximum: 8
176
177 child-node:
178 description: Child nodes are just another property from a json-schema
179 perspective.
180 type: object # DT nodes are json objects
181 # Child nodes also need additionalProperties or unevaluatedProperties, where
182 # 'false' should be used in most cases (see 'child-node-with-own-schema'
183 # below).
184 additionalProperties: false
185 properties:
186 vendor,a-child-node-property:
187 description: Child node properties have all the same schema
188 requirements.
189 type: boolean
190
191 required:
192 - vendor,a-child-node-property
193
194 child-node-with-own-schema:
195 description: |
196 Child node with their own compatible and device schema which ends in
197 'additionalProperties: false' or 'unevaluatedProperties: false' can
198 mention only the compatible and use here 'additionalProperties: true'.
199 type: object
200 additionalProperties: true
201 properties:
202 compatible:
203 const: vendor,sub-device
204
205# Describe the relationship between different properties
206dependencies:
207 # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
208 # is present
209 vendor,bool-property: [ 'vendor,string-array-property' ]
210 # Expressing 2 properties in both orders means all of the set of properties
211 # must be present or none of them.
212 vendor,string-array-property: [ 'vendor,bool-property' ]
213
214required:
215 - compatible
216 - reg
217 - interrupts
218 - interrupt-controller
219
220# if/then schema can be used to handle conditions on a property affecting
221# another property. A typical case is a specific 'compatible' value changes the
222# constraints on other properties.
223#
224# For multiple 'if' schema, group them under an 'allOf'.
225#
226# If the conditionals become too unwieldy, then it may be better to just split
227# the binding into separate schema documents.
228allOf:
229 - if:
230 properties:
231 compatible:
232 contains:
233 const: vendor,soc2-ip
234 then:
235 required:
236 - foo-supply
237 else:
238 # If otherwise the property is not allowed:
239 properties:
240 foo-supply: false
241 # Altering schema depending on presence of properties is usually done by
242 # dependencies (see above), however some adjustments might require if:
243 - if:
244 required:
245 - vendor,bool-property
246 then:
247 properties:
248 vendor,int-property:
249 enum: [2, 4, 6]
250
251# Ideally, the schema should have this line otherwise any other properties
252# present are allowed. There's a few common properties such as 'status' and
253# 'pinctrl-*' which are added automatically by the tooling.
254#
255# This can't be used in cases where another schema is referenced
256# (i.e. allOf: [{$ref: ...}]).
257# If and only if another schema is referenced and arbitrary children nodes can
258# appear, "unevaluatedProperties: false" could be used. A typical example is
259# an I2C controller where no name pattern matching for children can be added.
260additionalProperties: false
261
262examples:
263 # Examples are now compiled with dtc and validated against the schemas
264 #
265 # Examples have a default #address-cells and #size-cells value of 1. This can
266 # be overridden or an appropriate parent bus node should be shown (such as on
267 # i2c buses).
268 #
269 # Any includes used have to be explicitly included. Use 4-space indentation.
270 - |
271 node@1000 {
272 compatible = "vendor,soc4-ip", "vendor,soc1-ip";
273 reg = <0x1000 0x80>,
274 <0x3000 0x80>;
275 reg-names = "core", "aux";
276 interrupts = <10>;
277 interrupt-controller;
278 #interrupt-cells = <2>;
279 };