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