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