docs: dt: convert writing-bindings.txt to ReST

- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>

diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
index 6b87875a049c9d5361173b5baa31e25f89bebe41..3837b17c234f466858b91a414ef9e30a33c34a9d 100644 (file)
--- a/Documentation/devicetree/bindings/index.rst
+++ b/Documentation/devicetree/bindings/index.rst
@@ -9,3 +9,4 @@ Device Tree
 
    ABI
    submitting-patches
+   writing-bindings

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
new file mode 100644 (file)
index 0000000..45ff426
--- /dev/null
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================================
+DOs and DON'Ts for designing and writing Devicetree bindings
+============================================================
+
+This is a list of common review feedback items focused on binding design. With
+every rule, there are exceptions and bindings have many gray areas.
+
+For guidelines related to patches, see
+Documentation/devicetree/bindings/submitting-patches.rst
+
+
+Overall design
+==============
+
+- DO attempt to make bindings complete even if a driver doesn't support some
+  features. For example, if a device has an interrupt, then include the
+  'interrupts' property even if the driver is only polled mode.
+
+- DON'T refer to Linux or "device driver" in bindings. Bindings should be
+  based on what the hardware has, not what an OS and driver currently support.
+
+- DO use node names matching the class of the device. Many standard names are
+  defined in the DT Spec. If there isn't one, consider adding it.
+
+- DO check that the example matches the documentation especially after making
+  review changes.
+
+- DON'T create nodes just for the sake of instantiating drivers. Multi-function
+  devices only need child nodes when the child nodes have their own DT
+  resources. A single node can be multiple providers (e.g. clocks and resets).
+
+- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
+  hardware block should have a compatible string unique enough to infer the
+  register layout of the entire block (at a minimum).
+
+
+Properties
+==========
+
+- DO make 'compatible' properties specific. DON'T use wildcards in compatible
+  strings. DO use fallback compatibles when devices are the same as or a subset
+  of prior implementations. DO add new compatibles in case there are new
+  features or bugs.
+
+- DO use a vendor prefix on device specific property names. Consider if
+  properties could be common among devices of the same class. Check other
+  existing bindings for similar devices.
+
+- DON'T redefine common properties. Just reference the definition and define
+  constraints specific to the device.
+
+- DO use common property unit suffixes for properties with scientific units.
+  See property-units.txt.
+
+- DO define properties in terms of constraints. How many entries? What are
+  possible values? What is the order?
+
+
+Board/SoC .dts Files
+====================
+
+- DO put all MMIO devices under a bus node and not at the top-level.
+
+- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
+  platforms don't need all devices to have 64-bit address and size.

diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.txt
deleted file mode 100644 (file)
index ca024b9..0000000
--- a/Documentation/devicetree/bindings/writing-bindings.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-DOs and DON'Ts for designing and writing Devicetree bindings
-
-This is a list of common review feedback items focused on binding design. With
-every rule, there are exceptions and bindings have many gray areas.
-
-For guidelines related to patches, see
-Documentation/devicetree/bindings/submitting-patches.rst
-
-
-Overall design
-
-- DO attempt to make bindings complete even if a driver doesn't support some
-  features. For example, if a device has an interrupt, then include the
-  'interrupts' property even if the driver is only polled mode.
-
-- DON'T refer to Linux or "device driver" in bindings. Bindings should be
-  based on what the hardware has, not what an OS and driver currently support.
-
-- DO use node names matching the class of the device. Many standard names are
-  defined in the DT Spec. If there isn't one, consider adding it.
-
-- DO check that the example matches the documentation especially after making
-  review changes.
-
-- DON'T create nodes just for the sake of instantiating drivers. Multi-function
-  devices only need child nodes when the child nodes have their own DT
-  resources. A single node can be multiple providers (e.g. clocks and resets).
-
-- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
-  hardware block should have a compatible string unique enough to infer the
-  register layout of the entire block (at a minimum).
-
-
-Properties
-
-- DO make 'compatible' properties specific. DON'T use wildcards in compatible
-  strings. DO use fallback compatibles when devices are the same as or a subset
-  of prior implementations. DO add new compatibles in case there are new
-  features or bugs.
-
-- DO use a vendor prefix on device specific property names. Consider if
-  properties could be common among devices of the same class. Check other
-  existing bindings for similar devices.
-
-- DON'T redefine common properties. Just reference the definition and define
-  constraints specific to the device.
-
-- DO use common property unit suffixes for properties with scientific units.
-  See property-units.txt.
-
-- DO define properties in terms of constraints. How many entries? What are
-  possible values? What is the order?
-
-
-Board/SoC .dts Files
-
-- DO put all MMIO devices under a bus node and not at the top-level.
-
-- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
-  platforms don't need all devices to have 64-bit address and size.