xref: /linux/Documentation/devicetree/bindings/example-schema.yaml (revision bd628c1bed7902ec1f24ba0fe70758949146abbe) 
1# SPDX-License-Identifier: (GPL-2.0 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 idenifier 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 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
83
84  clock-names:
85    items:
86      - const: bus
87
88  interrupts:
89    # Either 1 or 2 interrupts can be present
90    minItems: 1
91    maxItems: 2
92    items:
93      - description: tx or combined interrupt
94      - description: rx interrupt
95    description:
96      A variable number of interrupts warrants a description of what conditions
97      affect the number of interrupts. Otherwise, descriptions on standard
98      properties are not necessary.
99
100  interrupt-names:
101    # minItems must be specified here because the default would be 2
102    minItems: 1
103    maxItems: 2
104    items:
105      - const: tx irq
106      - const: rx irq
107
108  # Property names starting with '#' must be quoted
109  '#interrupt-cells':
110    # A simple case where the value must always be '2'.
111    # The core schema handles that this must be a single integer.
112    const: 2
113
114  interrupt-controller: true
115    # The core checks this is a boolean, so just have to list it here to be
116    # valid for this binding.
117
118  clock-frequency:
119    # The type is set in the core schema. Per device schema only need to set
120    # constraints on the possible values.
121    minimum: 100
122    maximum: 400000
123    # The value that should be used if the property is not present
124    default: 200
125
126  foo-gpios:
127    maxItems: 1
128    description: A connection of the 'foo' gpio line.
129
130  vendor,int-property:
131    description: Vendor specific properties must have a description
132    # 'allOf' is the json-schema way of subclassing a schema. Here the base
133    # type schema is referenced and then additional constraints on the values
134    # are added.
135    allOf:
136      - $ref: /schemas/types.yaml#/definitions/uint32
137      - enum: [2, 4, 6, 8, 10]
138
139  vendor,bool-property:
140    description: Vendor specific properties must have a description
141    # boolean properties is one case where the json-schema 'type' keyword
142    # can be used directly
143    type: boolean
144
145  vendor,string-array-property:
146    description: Vendor specific properties should reference a type in the
147      core schema.
148    allOf:
149      - $ref: /schemas/types.yaml#/definitions/string-array
150      - items:
151          - enum: [ foo, bar ]
152          - enum: [ baz, boo ]
153
154required:
155  - compatible
156  - reg
157  - interrupts
158  - interrupt-controller
159
160examples:
161  # Examples are now compiled with dtc
162  - |
163    node@1000 {
164          compatible = "vendor,soc4-ip", "vendor,soc1-ip";
165          reg = <0x1000 0x80>,
166                <0x3000 0x80>;
167          reg-names = "core", "aux";
168          interrupts = <10>;
169          interrupt-controller;
170    };
171