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