From: Rob Herring Date: Thu, 25 Mar 2021 16:47:10 +0000 (-0600) Subject: docs: dt: Group DT docs into relevant sub-sections X-Git-Tag: Ubuntu-5.13.0-19.19~3428^2~12 X-Git-Url: https://git.proxmox.com/?a=commitdiff_plain;h=b83db5b8490073dfd27f4fd478b478f34e51bb36;p=mirror_ubuntu-jammy-kernel.git docs: dt: Group DT docs into relevant sub-sections The DT docs are currently all just lumped together in the doc build. Let's organize the documents by kernel specifics, overlays and bindings. As writing-schema.rst is about bindings, let's move it to the bindings directory. Cc: Frank Rowand Cc: Mauro Carvalho Chehab Signed-off-by: Rob Herring Reviewed-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/20210325164713.1296407-6-robh@kernel.org --- diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index 3837b17c234f..d9002a3a0abb 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -1,12 +1,9 @@ .. SPDX-License-Identifier: GPL-2.0 -=========== -Device Tree -=========== - .. toctree:: :maxdepth: 1 ABI - submitting-patches writing-bindings + writing-schema + submitting-patches diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst new file mode 100644 index 000000000000..23d6579aea2c --- /dev/null +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Writing Devicetree Bindings in json-schema +========================================== + +Devicetree bindings are written using json-schema vocabulary. Schema files are +written in a JSON compatible subset of YAML. YAML is used instead of JSON as it +is considered more human readable and has some advantages such as allowing +comments (Prefixed with '#'). + +Also see :ref:`example-schema`. + +Schema Contents +--------------- + +Each schema doc is a structured json-schema which is defined by a set of +top-level properties. Generally, there is one binding defined per file. The +top-level json-schema properties used are: + +$id + A json-schema unique identifier string. The string must be a valid + URI typically containing the binding's filename and path. For DT schema, it must + begin with "http://devicetree.org/schemas/". The URL is used in constructing + references to other files specified in schema "$ref" properties. A $ref value + with a leading '/' will have the hostname prepended. A $ref value a relative + path or filename only will be prepended with the hostname and path components + of the current schema file's '$id' value. A URL is used even for local files, + but there may not actually be files present at those locations. + +$schema + Indicates the meta-schema the schema file adheres to. + +title + A one line description on the contents of the binding schema. + +maintainers + A DT specific property. Contains a list of email address(es) + for maintainers of this binding. + +description + Optional. A multi-line text block containing any detailed + information about this binding. It should contain things such as what the block + or device does, standards the device conforms to, and links to datasheets for + more information. + +select + Optional. A json-schema used to match nodes for applying the + schema. By default without 'select', nodes are matched against their possible + compatible string values or node name. Most bindings should not need select. + +allOf + Optional. A list of other schemas to include. This is used to + include other schemas the binding conforms to. This may be schemas for a + particular class of devices such as I2C or SPI controllers. + +properties + A set of sub-schema defining all the DT properties for the + binding. The exact schema syntax depends on whether properties are known, + common properties (e.g. 'interrupts') or are binding/vendor specific properties. + +A property can also define a child DT node with child properties defined +under it. + +For more details on properties sections, see 'Property Schema' section. + +patternProperties + Optional. Similar to 'properties', but names are regex. + +required + A list of DT properties from the 'properties' section that + must always be present. + +examples + Optional. A list of one or more DTS hunks implementing the + binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. + +Unless noted otherwise, all properties are required. + +Property Schema +--------------- + +The 'properties' section of the schema contains all the DT properties for a +binding. Each property contains a set of constraints using json-schema +vocabulary for that property. The properties schemas are what is used for +validation of DT files. + +For common properties, only additional constraints not covered by the common +binding schema need to be defined such as how many values are valid or what +possible values are valid. + +Vendor specific properties will typically need more detailed schema. With the +exception of boolean properties, they should have a reference to a type in +schemas/types.yaml. A "description" property is always required. + +The Devicetree schemas don't exactly match the YAML encoded DT data produced by +dtc. They are simplified to make them more compact and avoid a bunch of +boilerplate. The tools process the schema files to produce the final schema for +validation. There are currently 2 transformations the tools perform. + +The default for arrays in json-schema is they are variable sized and allow more +entries than explicitly defined. This can be restricted by defining 'minItems', +'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed +size is desired in most cases, so these properties are added based on the +number of entries in an 'items' list. + +The YAML Devicetree format also makes all string values an array and scalar +values a matrix (in order to define groupings) even when only a single value +is present. Single entries in schemas are fixed up to match this encoding. + +Testing +------- + +Dependencies +~~~~~~~~~~~~ + +The DT schema project must be installed in order to validate the DT schema +binding documents and validate DTS files using the DT schema. The DT schema +project can be installed with pip:: + + pip3 install git+https://github.com/devicetree-org/dt-schema.git@master + +Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be +installed. Ensure they are in your PATH (~/.local/bin by default). + +dtc must also be built with YAML output support enabled. This requires that +libyaml and its headers be installed on the host system. For some distributions +that involves installing the development package, such as: + +Debian:: + + apt-get install libyaml-dev + +Fedora:: + + dnf -y install libyaml-devel + +Running checks +~~~~~~~~~~~~~~ + +The DT schema binding documents must be validated using the meta-schema (the +schema for the schema) to ensure they are both valid json-schema and valid +binding schema. All of the DT binding documents can be validated using the +``dt_binding_check`` target:: + + make dt_binding_check + +In order to perform validation of DT source files, use the ``dtbs_check`` target:: + + make dtbs_check + +Note that ``dtbs_check`` will skip any binding schema files with errors. It is +necessary to use ``dt_binding_check`` to get all the validation errors in the +binding schema files. + +It is possible to run both in a single command:: + + make dt_binding_check dtbs_check + +It is also possible to run checks with a single schema file by setting the +``DT_SCHEMA_FILES`` variable to a specific schema file. + +:: + + make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml + make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml + + +json-schema Resources +--------------------- + + +`JSON-Schema Specifications `_ + +`Using JSON Schema Book `_ + +.. _example-schema: + +Annotated Example Schema +------------------------ + +Also available as a separate file: :download:`example-schema.yaml` + +.. literalinclude:: example-schema.yaml diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 32509e8de8da..70b5dcdbcf07 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -4,14 +4,26 @@ Open Firmware and Devicetree ============================= +Kernel Devicetree Usage +======================= .. toctree:: :maxdepth: 1 usage-model - writing-schema + of_unittest + +Devicetree Overlays +=================== +.. toctree:: + :maxdepth: 1 + changesets dynamic-resolution-notes - of_unittest overlay-notes +Devicetree Bindings +=================== +.. toctree:: + :maxdepth: 1 + bindings/index diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst deleted file mode 100644 index 23d6579aea2c..000000000000 --- a/Documentation/devicetree/writing-schema.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Writing Devicetree Bindings in json-schema -========================================== - -Devicetree bindings are written using json-schema vocabulary. Schema files are -written in a JSON compatible subset of YAML. YAML is used instead of JSON as it -is considered more human readable and has some advantages such as allowing -comments (Prefixed with '#'). - -Also see :ref:`example-schema`. - -Schema Contents ---------------- - -Each schema doc is a structured json-schema which is defined by a set of -top-level properties. Generally, there is one binding defined per file. The -top-level json-schema properties used are: - -$id - A json-schema unique identifier string. The string must be a valid - URI typically containing the binding's filename and path. For DT schema, it must - begin with "http://devicetree.org/schemas/". The URL is used in constructing - references to other files specified in schema "$ref" properties. A $ref value - with a leading '/' will have the hostname prepended. A $ref value a relative - path or filename only will be prepended with the hostname and path components - of the current schema file's '$id' value. A URL is used even for local files, - but there may not actually be files present at those locations. - -$schema - Indicates the meta-schema the schema file adheres to. - -title - A one line description on the contents of the binding schema. - -maintainers - A DT specific property. Contains a list of email address(es) - for maintainers of this binding. - -description - Optional. A multi-line text block containing any detailed - information about this binding. It should contain things such as what the block - or device does, standards the device conforms to, and links to datasheets for - more information. - -select - Optional. A json-schema used to match nodes for applying the - schema. By default without 'select', nodes are matched against their possible - compatible string values or node name. Most bindings should not need select. - -allOf - Optional. A list of other schemas to include. This is used to - include other schemas the binding conforms to. This may be schemas for a - particular class of devices such as I2C or SPI controllers. - -properties - A set of sub-schema defining all the DT properties for the - binding. The exact schema syntax depends on whether properties are known, - common properties (e.g. 'interrupts') or are binding/vendor specific properties. - -A property can also define a child DT node with child properties defined -under it. - -For more details on properties sections, see 'Property Schema' section. - -patternProperties - Optional. Similar to 'properties', but names are regex. - -required - A list of DT properties from the 'properties' section that - must always be present. - -examples - Optional. A list of one or more DTS hunks implementing the - binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. - -Unless noted otherwise, all properties are required. - -Property Schema ---------------- - -The 'properties' section of the schema contains all the DT properties for a -binding. Each property contains a set of constraints using json-schema -vocabulary for that property. The properties schemas are what is used for -validation of DT files. - -For common properties, only additional constraints not covered by the common -binding schema need to be defined such as how many values are valid or what -possible values are valid. - -Vendor specific properties will typically need more detailed schema. With the -exception of boolean properties, they should have a reference to a type in -schemas/types.yaml. A "description" property is always required. - -The Devicetree schemas don't exactly match the YAML encoded DT data produced by -dtc. They are simplified to make them more compact and avoid a bunch of -boilerplate. The tools process the schema files to produce the final schema for -validation. There are currently 2 transformations the tools perform. - -The default for arrays in json-schema is they are variable sized and allow more -entries than explicitly defined. This can be restricted by defining 'minItems', -'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed -size is desired in most cases, so these properties are added based on the -number of entries in an 'items' list. - -The YAML Devicetree format also makes all string values an array and scalar -values a matrix (in order to define groupings) even when only a single value -is present. Single entries in schemas are fixed up to match this encoding. - -Testing -------- - -Dependencies -~~~~~~~~~~~~ - -The DT schema project must be installed in order to validate the DT schema -binding documents and validate DTS files using the DT schema. The DT schema -project can be installed with pip:: - - pip3 install git+https://github.com/devicetree-org/dt-schema.git@master - -Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be -installed. Ensure they are in your PATH (~/.local/bin by default). - -dtc must also be built with YAML output support enabled. This requires that -libyaml and its headers be installed on the host system. For some distributions -that involves installing the development package, such as: - -Debian:: - - apt-get install libyaml-dev - -Fedora:: - - dnf -y install libyaml-devel - -Running checks -~~~~~~~~~~~~~~ - -The DT schema binding documents must be validated using the meta-schema (the -schema for the schema) to ensure they are both valid json-schema and valid -binding schema. All of the DT binding documents can be validated using the -``dt_binding_check`` target:: - - make dt_binding_check - -In order to perform validation of DT source files, use the ``dtbs_check`` target:: - - make dtbs_check - -Note that ``dtbs_check`` will skip any binding schema files with errors. It is -necessary to use ``dt_binding_check`` to get all the validation errors in the -binding schema files. - -It is possible to run both in a single command:: - - make dt_binding_check dtbs_check - -It is also possible to run checks with a single schema file by setting the -``DT_SCHEMA_FILES`` variable to a specific schema file. - -:: - - make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml - make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml - - -json-schema Resources ---------------------- - - -`JSON-Schema Specifications `_ - -`Using JSON Schema Book `_ - -.. _example-schema: - -Annotated Example Schema ------------------------- - -Also available as a separate file: :download:`example-schema.yaml` - -.. literalinclude:: example-schema.yaml