example-schema.yaml

  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 <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          - 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    };