From: Mauro Carvalho Chehab Date: Wed, 15 Apr 2020 14:45:26 +0000 (+0200) Subject: docs: dt: convert writing-bindings.txt to ReST X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=e7728fcf7dd7955dae7e6e9a14ab5faa392b8605;p=linux.git 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 Signed-off-by: Rob Herring --- diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index 6b87875a049c9..3837b17c234f4 100644 --- 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 index 0000000000000..45ff426d00196 --- /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 index ca024b9c7433b..0000000000000 --- 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.