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 <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
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 3837b17c234f466858b91a414ef9e30a33c34a9d..d9002a3a0abb369dbaad2da74f09250d9e3b618d 100644 (file)
--- 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 (file)
index 0000000..23d6579
--- /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 <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
+
+.. _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 32509e8de8daeadc77e98e4e15ce84aaab9e8ed4..70b5dcdbcf07b65113cafe8bc53110a819fe445b 100644 (file)
--- 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 (file)
index 23d6579..0000000
--- 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 <http://json-schema.org/>`_
-
-`Using JSON Schema Book <http://usingjsonschema.com/>`_
-
-.. _example-schema:
-
-Annotated Example Schema
-------------------------
-
-Also available as a separate file: :download:`example-schema.yaml`
-
-.. literalinclude:: example-schema.yaml