From b83db5b8490073dfd27f4fd478b478f34e51bb36 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Thu, 25 Mar 2021 10:47:10 -0600 Subject: 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 --- Documentation/devicetree/writing-schema.rst | 183 ---------------------------- 1 file changed, 183 deletions(-) delete mode 100644 Documentation/devicetree/writing-schema.rst (limited to 'Documentation/devicetree/writing-schema.rst') 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 -- cgit