Commit | Line | Data |
---|---|---|
d0793c3c | 1 | .. SPDX-License-Identifier: GPL-2.0 |
cdea0121 | 2 | |
7248213c | 3 | Writing Devicetree Bindings in json-schema |
cdea0121 MCC |
4 | ========================================== |
5 | ||
6 | Devicetree bindings are written using json-schema vocabulary. Schema files are | |
37ef2c34 | 7 | written in a JSON-compatible subset of YAML. YAML is used instead of JSON as it |
43647929 | 8 | is considered more human readable and has some advantages such as allowing |
cdea0121 MCC |
9 | comments (Prefixed with '#'). |
10 | ||
9be21f73 RH |
11 | Also see :ref:`example-schema`. |
12 | ||
cdea0121 MCC |
13 | Schema Contents |
14 | --------------- | |
15 | ||
16 | Each schema doc is a structured json-schema which is defined by a set of | |
17 | top-level properties. Generally, there is one binding defined per file. The | |
18 | top-level json-schema properties used are: | |
19 | ||
20 | $id | |
21 | A json-schema unique identifier string. The string must be a valid | |
22 | URI typically containing the binding's filename and path. For DT schema, it must | |
23 | begin with "http://devicetree.org/schemas/". The URL is used in constructing | |
43647929 | 24 | references to other files specified in schema "$ref" properties. A $ref value |
37ef2c34 SG |
25 | with a leading '/' will have the hostname prepended. A $ref value with only a |
26 | relative path or filename will be prepended with the hostname and path | |
27 | components of the current schema file's '$id' value. A URL is used even for | |
28 | local files, but there may not actually be files present at those locations. | |
cdea0121 MCC |
29 | |
30 | $schema | |
31 | Indicates the meta-schema the schema file adheres to. | |
32 | ||
33 | title | |
37ef2c34 | 34 | A one-line description on the contents of the binding schema. |
cdea0121 MCC |
35 | |
36 | maintainers | |
37 | A DT specific property. Contains a list of email address(es) | |
38 | for maintainers of this binding. | |
39 | ||
40 | description | |
41 | Optional. A multi-line text block containing any detailed | |
42 | information about this binding. It should contain things such as what the block | |
43 | or device does, standards the device conforms to, and links to datasheets for | |
44 | more information. | |
45 | ||
46 | select | |
47 | Optional. A json-schema used to match nodes for applying the | |
37ef2c34 SG |
48 | schema. By default, without 'select', nodes are matched against their possible |
49 | compatible-string values or node name. Most bindings should not need select. | |
cdea0121 | 50 | |
0d45f833 | 51 | allOf |
cdea0121 MCC |
52 | Optional. A list of other schemas to include. This is used to |
53 | include other schemas the binding conforms to. This may be schemas for a | |
54 | particular class of devices such as I2C or SPI controllers. | |
55 | ||
0d45f833 | 56 | properties |
cdea0121 MCC |
57 | A set of sub-schema defining all the DT properties for the |
58 | binding. The exact schema syntax depends on whether properties are known, | |
37ef2c34 SG |
59 | common properties (e.g. 'interrupts') or are binding/vendor-specific |
60 | properties. | |
cdea0121 MCC |
61 | |
62 | A property can also define a child DT node with child properties defined | |
63 | under it. | |
64 | ||
65 | For more details on properties sections, see 'Property Schema' section. | |
66 | ||
67 | patternProperties | |
68 | Optional. Similar to 'properties', but names are regex. | |
69 | ||
70 | required | |
71 | A list of DT properties from the 'properties' section that | |
72 | must always be present. | |
73 | ||
74 | examples | |
75 | Optional. A list of one or more DTS hunks implementing the | |
76 | binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. | |
77 | ||
78 | Unless noted otherwise, all properties are required. | |
79 | ||
80 | Property Schema | |
81 | --------------- | |
82 | ||
83 | The 'properties' section of the schema contains all the DT properties for a | |
84 | binding. Each property contains a set of constraints using json-schema | |
37ef2c34 | 85 | vocabulary for that property. The properties schemas are what are used for |
cdea0121 MCC |
86 | validation of DT files. |
87 | ||
37ef2c34 | 88 | For common properties, only additional constraints not covered by the common, |
cdea0121 MCC |
89 | binding schema need to be defined such as how many values are valid or what |
90 | possible values are valid. | |
91 | ||
37ef2c34 | 92 | Vendor-specific properties will typically need more detailed schema. With the |
cdea0121 MCC |
93 | exception of boolean properties, they should have a reference to a type in |
94 | schemas/types.yaml. A "description" property is always required. | |
95 | ||
37ef2c34 | 96 | The Devicetree schemas don't exactly match the YAML-encoded DT data produced by |
cdea0121 MCC |
97 | dtc. They are simplified to make them more compact and avoid a bunch of |
98 | boilerplate. The tools process the schema files to produce the final schema for | |
99 | validation. There are currently 2 transformations the tools perform. | |
100 | ||
37ef2c34 | 101 | The default for arrays in json-schema is they are variable-sized and allow more |
cdea0121 MCC |
102 | entries than explicitly defined. This can be restricted by defining 'minItems', |
103 | 'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed | |
104 | size is desired in most cases, so these properties are added based on the | |
105 | number of entries in an 'items' list. | |
106 | ||
107 | The YAML Devicetree format also makes all string values an array and scalar | |
108 | values a matrix (in order to define groupings) even when only a single value | |
109 | is present. Single entries in schemas are fixed up to match this encoding. | |
110 | ||
111 | Testing | |
112 | ------- | |
113 | ||
114 | Dependencies | |
115 | ~~~~~~~~~~~~ | |
116 | ||
117 | The DT schema project must be installed in order to validate the DT schema | |
118 | binding documents and validate DTS files using the DT schema. The DT schema | |
119 | project can be installed with pip:: | |
120 | ||
121 | pip3 install git+https://github.com/devicetree-org/dt-schema.git@master | |
122 | ||
7054c207 RH |
123 | Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be |
124 | installed. Ensure they are in your PATH (~/.local/bin by default). | |
125 | ||
cdea0121 | 126 | dtc must also be built with YAML output support enabled. This requires that |
7dcde0f3 LW |
127 | libyaml and its headers be installed on the host system. For some distributions |
128 | that involves installing the development package, such as: | |
129 | ||
d0793c3c MCC |
130 | Debian:: |
131 | ||
7dcde0f3 | 132 | apt-get install libyaml-dev |
d0793c3c MCC |
133 | |
134 | Fedora:: | |
135 | ||
7dcde0f3 | 136 | dnf -y install libyaml-devel |
cdea0121 MCC |
137 | |
138 | Running checks | |
139 | ~~~~~~~~~~~~~~ | |
140 | ||
141 | The DT schema binding documents must be validated using the meta-schema (the | |
142 | schema for the schema) to ensure they are both valid json-schema and valid | |
143 | binding schema. All of the DT binding documents can be validated using the | |
144 | ``dt_binding_check`` target:: | |
145 | ||
146 | make dt_binding_check | |
147 | ||
93512dad | 148 | In order to perform validation of DT source files, use the ``dtbs_check`` target:: |
cdea0121 MCC |
149 | |
150 | make dtbs_check | |
151 | ||
93512dad RH |
152 | Note that ``dtbs_check`` will skip any binding schema files with errors. It is |
153 | necessary to use ``dt_binding_check`` to get all the validation errors in the | |
154 | binding schema files. | |
cdea0121 | 155 | |
e10c4321 MY |
156 | It is possible to run both in a single command:: |
157 | ||
158 | make dt_binding_check dtbs_check | |
159 | ||
cdea0121 MCC |
160 | It is also possible to run checks with a single schema file by setting the |
161 | ``DT_SCHEMA_FILES`` variable to a specific schema file. | |
162 | ||
163 | :: | |
164 | ||
7aa8dd91 | 165 | make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml |
cdea0121 MCC |
166 | make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml |
167 | ||
168 | ||
169 | json-schema Resources | |
170 | --------------------- | |
171 | ||
172 | ||
173 | `JSON-Schema Specifications <http://json-schema.org/>`_ | |
174 | ||
175 | `Using JSON Schema Book <http://usingjsonschema.com/>`_ | |
9be21f73 RH |
176 | |
177 | .. _example-schema: | |
178 | ||
179 | Annotated Example Schema | |
180 | ------------------------ | |
181 | ||
182 | Also available as a separate file: :download:`example-schema.yaml` | |
183 | ||
184 | .. literalinclude:: example-schema.yaml |