Merge tag 'apparmor-pr-2019-03-12' of git://git.kernel.org/pub/scm/linux/kernel/git...
[linux-2.6-microblaze.git] / Documentation / devicetree / bindings / example-schema.yaml
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
14 title: An example schema annotated with jsonschema details
15
16 maintainers:
17   - Rob Herring <robh@kernel.org>
18
19 description: |
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
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.
32
33   # In this case, a 'false' schema will never match.
34
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
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
154 required:
155   - compatible
156   - reg
157   - interrupts
158   - interrupt-controller
159
160 examples:
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     };