xref: /freebsd/sys/contrib/device-tree/Bindings/example-schema.yaml (revision d4eeb02986980bf33dd56c41ceb9fc5f180c0d47) 
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      The items should have a fixed order, so pattern matching names are
85      discouraged.
86
87  clock-names:
88    items:
89      - const: bus
90
91  interrupts:
92    # Either 1 or 2 interrupts can be present
93    minItems: 1
94    items:
95      - description: tx or combined interrupt
96      - description: rx interrupt
97    description:
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
102      discouraged.
103
104  interrupt-names:
105    # minItems must be specified here because the default would be 2
106    minItems: 1
107    items:
108      - const: tx irq
109      - const: rx irq
110
111  # Property names starting with '#' must be quoted
112  '#interrupt-cells':
113    # A simple case where the value must always be '2'.
114    # The core schema handles that this must be a single integer.
115    const: 2
116
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.
120
121  clock-frequency:
122    # The type is set in the core schema. Per-device schema only need to set
123    # constraints on the possible values.
124    minimum: 100
125    maximum: 400000
126    # The value that should be used if the property is not present
127    default: 200
128
129  foo-gpios:
130    maxItems: 1
131    description: A connection of the 'foo' gpio line.
132
133  # *-supply is always a single phandle, so nothing more to define.
134  foo-supply: true
135
136  # Vendor-specific properties
137  #
138  # Vendor-specific properties have slightly different schema requirements than
139  # common properties. They must have at least a type definition and
140  # 'description'.
141  vendor,int-property:
142    description: Vendor-specific properties must have a description
143    $ref: /schemas/types.yaml#/definitions/uint32
144    enum: [2, 4, 6, 8, 10]
145
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
149      directly.
150    type: boolean
151
152  vendor,string-array-property:
153    description: Vendor-specific properties should reference a type in the
154      core schema.
155    $ref: /schemas/types.yaml#/definitions/string-array
156    items:
157      - enum: [foo, bar]
158      - enum: [baz, boo]
159
160  vendor,property-in-standard-units-microvolt:
161    description: Vendor-specific properties having a standard unit suffix
162      don't need a type.
163    enum: [ 100, 200, 300 ]
164
165  vendor,int-array-variable-length-and-constrained-values:
166    description: Array might define what type of elements might be used (e.g.
167      their range).
168    $ref: /schemas/types.yaml#/definitions/uint32-array
169    minItems: 2
170    maxItems: 3
171    items:
172      minimum: 0
173      maximum: 8
174
175  child-node:
176    description: Child nodes are just another property from a json-schema
177      perspective.
178    type: object  # DT nodes are json objects
179    properties:
180      vendor,a-child-node-property:
181        description: Child node properties have all the same schema
182          requirements.
183        type: boolean
184
185    required:
186      - vendor,a-child-node-property
187
188# Describe the relationship between different properties
189dependencies:
190  # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
191  # is present
192  vendor,bool-property: [ 'vendor,string-array-property' ]
193  # Expressing 2 properties in both orders means all of the set of properties
194  # must be present or none of them.
195  vendor,string-array-property: [ 'vendor,bool-property' ]
196
197required:
198  - compatible
199  - reg
200  - interrupts
201  - interrupt-controller
202
203# if/then schema can be used to handle conditions on a property affecting
204# another property. A typical case is a specific 'compatible' value changes the
205# constraints on other properties.
206#
207# For multiple 'if' schema, group them under an 'allOf'.
208#
209# If the conditionals become too unweldy, then it may be better to just split
210# the binding into separate schema documents.
211allOf:
212  - if:
213      properties:
214        compatible:
215          contains:
216            const: vendor,soc2-ip
217    then:
218      required:
219        - foo-supply
220    else:
221      # If otherwise the property is not allowed:
222      properties:
223        foo-supply: false
224  # Altering schema depending on presence of properties is usually done by
225  # dependencies (see above), however some adjustments might require if:
226  - if:
227      required:
228        - vendor,bool-property
229    then:
230      properties:
231        vendor,int-property:
232          enum: [2, 4, 6]
233
234# Ideally, the schema should have this line otherwise any other properties
235# present are allowed. There's a few common properties such as 'status' and
236# 'pinctrl-*' which are added automatically by the tooling.
237#
238# This can't be used in cases where another schema is referenced
239# (i.e. allOf: [{$ref: ...}]).
240# If and only if another schema is referenced and arbitrary children nodes can
241# appear, "unevaluatedProperties: false" could be used.  A typical example is
242# an I2C controller where no name pattern matching for children can be added.
243additionalProperties: false
244
245examples:
246  # Examples are now compiled with dtc and validated against the schemas
247  #
248  # Examples have a default #address-cells and #size-cells value of 1. This can
249  # be overridden or an appropriate parent bus node should be shown (such as on
250  # i2c buses).
251  #
252  # Any includes used have to be explicitly included.
253  - |
254    node@1000 {
255          compatible = "vendor,soc4-ip", "vendor,soc1-ip";
256          reg = <0x1000 0x80>,
257                <0x3000 0x80>;
258          reg-names = "core", "aux";
259          interrupts = <10>;
260          interrupt-controller;
261    };
262