tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: writing-schema.md: convert from markdown to ReST
The documentation standard is ReST and not markdown.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Rob Herring
cdea0121
5f9040fd
+153
-130
-130
Documentation/devicetree/writing-schema.md
-130
Documentation/devicetree/writing-schema.md
···
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/devicetree-org/dt-schema.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/)
+153
Documentation/devicetree/writing-schema.rst
+153
Documentation/devicetree/writing-schema.rst
···
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
+
144
+
make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
145
+
146
+
147
+
json-schema Resources
148
+
---------------------
149
+
150
+
151
+
`JSON-Schema Specifications <http://json-schema.org/>`_
152
+
153
+
`Using JSON Schema Book <http://usingjsonschema.com/>`_