Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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 schema annotated with jsonschema details
15
16maintainers:
17 - Rob Herring <robh@kernel.org>
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 - enum:
56 - vendor,soc1-ip
57 # additionalItems being false is implied
58 # minItems/maxItems equal to 2 is implied
59 - items:
60 # 'const' is just a special case of an enum with a single possible value
61 - const: vendor,soc1-ip
62
63 reg:
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.
68 items:
69 - description: core registers
70 - description: aux registers
71 # minItems/maxItems equal to 2 is implied
72
73 reg-names:
74 # The core schema enforces this (*-names) is a string array
75 items:
76 - const: core
77 - const: aux
78
79 clocks:
80 # Cases that have only a single entry just need to express that with maxItems
81 maxItems: 1
82 description: bus clock. A description is only needed for a single item if
83 there's something unique to add.
84
85 clock-names:
86 items:
87 - const: bus
88
89 interrupts:
90 # Either 1 or 2 interrupts can be present
91 minItems: 1
92 maxItems: 2
93 items:
94 - description: tx or combined interrupt
95 - description: rx interrupt
96 description:
97 A variable number of interrupts warrants a description of what conditions
98 affect the number of interrupts. Otherwise, descriptions on standard
99 properties are not necessary.
100
101 interrupt-names:
102 # minItems must be specified here because the default would be 2
103 minItems: 1
104 maxItems: 2
105 items:
106 - const: tx irq
107 - const: rx irq
108
109 # Property names starting with '#' must be quoted
110 '#interrupt-cells':
111 # A simple case where the value must always be '2'.
112 # The core schema handles that this must be a single integer.
113 const: 2
114
115 interrupt-controller: true
116 # The core checks this is a boolean, so just have to list it here to be
117 # valid for this binding.
118
119 clock-frequency:
120 # The type is set in the core schema. Per device schema only need to set
121 # constraints on the possible values.
122 minimum: 100
123 maximum: 400000
124 # The value that should be used if the property is not present
125 default: 200
126
127 foo-gpios:
128 maxItems: 1
129 description: A connection of the 'foo' gpio line.
130
131 # *-supply is always a single phandle, so nothing more to define.
132 foo-supply: true
133
134 # Vendor specific properties
135 #
136 # Vendor specific properties have slightly different schema requirements than
137 # common properties. They must have at least a type definition and
138 # 'description'.
139 vendor,int-property:
140 description: Vendor specific properties must have a description
141 # 'allOf' is the json-schema way of subclassing a schema. Here the base
142 # type schema is referenced and then additional constraints on the values
143 # are added.
144 allOf:
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 allOf:
158 - $ref: /schemas/types.yaml#/definitions/string-array
159 - items:
160 - enum: [ foo, bar ]
161 - enum: [ baz, boo ]
162
163 vendor,property-in-standard-units-microvolt:
164 description: Vendor specific properties having a standard unit suffix
165 don't need a type.
166 enum: [ 100, 200, 300 ]
167
168 child-node:
169 description: Child nodes are just another property from a json-schema
170 perspective.
171 type: object # DT nodes are json objects
172 properties:
173 vendor,a-child-node-property:
174 description: Child node properties have all the same schema
175 requirements.
176 type: boolean
177
178 required:
179 - vendor,a-child-node-property
180
181# Describe the relationship between different properties
182dependencies:
183 # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
184 # is present
185 vendor,bool-property: [ vendor,string-array-property ]
186 # Expressing 2 properties in both orders means all of the set of properties
187 # must be present or none of them.
188 vendor,string-array-property: [ vendor,bool-property ]
189
190required:
191 - compatible
192 - reg
193 - interrupts
194 - interrupt-controller
195
196# if/then schema can be used to handle conditions on a property affecting
197# another property. A typical case is a specific 'compatible' value changes the
198# constraints on other properties.
199#
200# For multiple 'if' schema, group them under an 'allOf'.
201#
202# If the conditionals become too unweldy, then it may be better to just split
203# the binding into separate schema documents.
204if:
205 properties:
206 compatible:
207 contains:
208 const: vendor,soc2-ip
209then:
210 required:
211 - foo-supply
212
213# Ideally, the schema should have this line otherwise any other properties
214# present are allowed. There's a few common properties such as 'status' and
215# 'pinctrl-*' which are added automatically by the tooling.
216#
217# This can't be used in cases where another schema is referenced
218# (i.e. allOf: [{$ref: ...}]).
219additionalProperties: false
220
221examples:
222 # Examples are now compiled with dtc and validated against the schemas
223 #
224 # Examples have a default #address-cells and #size-cells value of 1. This can
225 # be overridden or an appropriate parent bus node should be shown (such as on
226 # i2c buses).
227 #
228 # Any includes used have to be explicitly included.
229 - |
230 node@1000 {
231 compatible = "vendor,soc4-ip", "vendor,soc1-ip";
232 reg = <0x1000 0x80>,
233 <0x3000 0x80>;
234 reg-names = "core", "aux";
235 interrupts = <10>;
236 interrupt-controller;
237 };