WIP FPC-III support
[linux/fpc-iii.git] / Documentation / devicetree / bindings / example-schema.yaml
bloba97f39109f8d0414157a3391976ef73b86808b10
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'
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
16 maintainers:
17   - Rob Herring <robh@kernel.org>
19 description: |
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.
28 select: 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.
33   # In this case, a 'false' schema will never match.
35 properties:
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
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
73   reg-names:
74     # The core schema enforces this (*-names) is a string array
75     items:
76       - const: core
77       - const: aux
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       The items should have a fixed order, so pattern matching names are
85       discouraged.
87   clock-names:
88     items:
89       - const: bus
91   interrupts:
92     # Either 1 or 2 interrupts can be present
93     minItems: 1
94     maxItems: 2
95     items:
96       - description: tx or combined interrupt
97       - description: rx interrupt
98     description:
99       A variable number of interrupts warrants a description of what conditions
100       affect the number of interrupts. Otherwise, descriptions on standard
101       properties are not necessary.
102       The items should have a fixed order, so pattern matching names are
103       discouraged.
105   interrupt-names:
106     # minItems must be specified here because the default would be 2
107     minItems: 1
108     maxItems: 2
109     items:
110       - const: tx irq
111       - const: rx irq
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
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.
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
131   foo-gpios:
132     maxItems: 1
133     description: A connection of the 'foo' gpio line.
135   # *-supply is always a single phandle, so nothing more to define.
136   foo-supply: true
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]
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
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]
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 ]
167   child-node:
168     description: Child nodes are just another property from a json-schema
169       perspective.
170     type: object  # DT nodes are json objects
171     properties:
172       vendor,a-child-node-property:
173         description: Child node properties have all the same schema
174           requirements.
175         type: boolean
177     required:
178       - vendor,a-child-node-property
180 # Describe the relationship between different properties
181 dependencies:
182   # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
183   # is present
184   vendor,bool-property: [ 'vendor,string-array-property' ]
185   # Expressing 2 properties in both orders means all of the set of properties
186   # must be present or none of them.
187   vendor,string-array-property: [ 'vendor,bool-property' ]
189 required:
190   - compatible
191   - reg
192   - interrupts
193   - interrupt-controller
195 # if/then schema can be used to handle conditions on a property affecting
196 # another property. A typical case is a specific 'compatible' value changes the
197 # constraints on other properties.
199 # For multiple 'if' schema, group them under an 'allOf'.
201 # If the conditionals become too unweldy, then it may be better to just split
202 # the binding into separate schema documents.
203 allOf:
204   - if:
205       properties:
206         compatible:
207           contains:
208             const: vendor,soc2-ip
209     then:
210       required:
211         - foo-supply
212   # Altering schema depending on presence of properties is usually done by
213   # dependencies (see above), however some adjustments might require if:
214   - if:
215       required:
216         - vendor,bool-property
217     then:
218       properties:
219         vendor,int-property:
220           enum: [2, 4, 6]
222 # Ideally, the schema should have this line otherwise any other properties
223 # present are allowed. There's a few common properties such as 'status' and
224 # 'pinctrl-*' which are added automatically by the tooling.
226 # This can't be used in cases where another schema is referenced
227 # (i.e. allOf: [{$ref: ...}]).
228 # If and only if another schema is referenced and arbitrary children nodes can
229 # appear, "unevaluatedProperties: false" could be used.  A typical example is
230 # an I2C controller where no name pattern matching for children can be added.
231 additionalProperties: false
233 examples:
234   # Examples are now compiled with dtc and validated against the schemas
235   #
236   # Examples have a default #address-cells and #size-cells value of 1. This can
237   # be overridden or an appropriate parent bus node should be shown (such as on
238   # i2c buses).
239   #
240   # Any includes used have to be explicitly included.
241   - |
242     node@1000 {
243           compatible = "vendor,soc4-ip", "vendor,soc1-ip";
244           reg = <0x1000 0x80>,
245                 <0x3000 0x80>;
246           reg-names = "core", "aux";
247           interrupts = <10>;
248           interrupt-controller;
249     };