devicetree.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] docs: dt-bindings: add DTS Coding Style document
@ 2023-11-16 18:12 Krzysztof Kozlowski
  2023-11-16 19:26 ` Heiko Stuebner
                   ` (5 more replies)
  0 siblings, 6 replies; 22+ messages in thread
From: Krzysztof Kozlowski @ 2023-11-16 18:12 UTC (permalink / raw)
  To: Rob Herring, Krzysztof Kozlowski, Conor Dooley, devicetree,
	linux-kernel
  Cc: Krzysztof Kozlowski, AngeloGioacchino Del Regno, Arnd Bergmann,
	Bjorn Andersson, Geert Uytterhoeven, Heiko Stuebner,
	Konrad Dybcio, Matthias Brugger, Michal Simek, Neil Armstrong,
	Nishanth Menon, Olof Johansson

Document preferred coding style for Devicetree sources (DTS and DTSI),
to bring consistency among all (sub)architectures and ease in reviews.

Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Bjorn Andersson <andersson@kernel.org>
Cc: Geert Uytterhoeven <geert+renesas@glider.be>
Cc: Heiko Stuebner <heiko@sntech.de>
Cc: Konrad Dybcio <konrad.dybcio@linaro.org>
Cc: Matthias Brugger <matthias.bgg@gmail.com>
Cc: Michal Simek <michal.simek@amd.com>
Cc: Neil Armstrong <neil.armstrong@linaro.org>
Cc: Nishanth Menon <nm@ti.com>
Cc: Olof Johansson <olof@lixom.net>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Merging idea: Rob/DT bindings
---
 Documentation/devicetree/bindings/index.rst   |   1 +
 .../devicetree/bindings/writing-dts.rst       | 137 ++++++++++++++++++
 2 files changed, 138 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/writing-dts.rst

diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
index d9002a3a0abb..975449be4862 100644
--- a/Documentation/devicetree/bindings/index.rst
+++ b/Documentation/devicetree/bindings/index.rst
@@ -5,5 +5,6 @@
 
    ABI
    writing-bindings
+   writing-dts
    writing-schema
    submitting-patches
diff --git a/Documentation/devicetree/bindings/writing-dts.rst b/Documentation/devicetree/bindings/writing-dts.rst
new file mode 100644
index 000000000000..10c477ec1eed
--- /dev/null
+++ b/Documentation/devicetree/bindings/writing-dts.rst
@@ -0,0 +1,137 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. _writingdts:
+
+===================================================
+Writing Devicetree Sources (DTS) - DTS Coding Style
+===================================================
+
+When writing Devicetree Sources (DTS) please observe below guidelines.  They
+should be considered complementary to any rules expressed already in Devicetree
+Specification and dtc compiler (including W=1 and W=2 builds).
+
+Individual architectures and sub-architectures can add additional rules, making
+the style stricter.
+
+Naming and Valid Characters
+---------------------------
+
+1. Node and property names are allowed to use only:
+
+   * lowercase characters:: [a-z]
+   * digits:: [0-9]
+   * dash:: -
+
+2. Labels are allowed to use only:
+
+   * lowercase characters:: [a-z]
+   * digits:: [0-9]
+   * underscore:: _
+
+3. Unit addresses should use lowercase hex, without leading zeros (padding).
+
+4. Hex values in properties, e.g. "reg", should use lowercase hex.  Any address
+   part can be padded with leading zeros.
+
+Example::
+
+	gpi_dma2: dma-controller@800000 {
+		compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma";
+		reg = <0x0 0x00800000 0x0 0x60000>;
+	}
+
+Order of Nodes
+--------------
+
+1. Nodes within any bus, thus using unit addresses for children, shall be
+   ordered incrementally by unit address.
+
+2. Nodes without unit addresses should be ordered alpha-numerically.
+
+3. When extending nodes in board DTS via &label, the entries should be ordered
+   alpha-numerically.
+
+Example::
+
+	// SoC DTSI
+
+	\ {
+		cpus {
+			// ...
+		};
+
+		psci {
+			// ...
+		};
+
+		soc@ {
+			dma: dma-controller@10000 {
+				// ...
+			};
+
+			clk: clock-controller@80000 {
+				// ...
+			};
+		};
+	};
+
+	// Board DTS
+
+	&clk {
+		// ...
+	};
+
+	&dma {
+		// ...
+	};
+
+
+Order of Properties in Device Node
+----------------------------------
+
+Following order of properties in device nodes is preferred:
+
+1. compatible
+2. reg
+3. ranges
+4. All properties with values
+5. Boolean properties
+6. status (if applicable)
+7. Child nodes
+
+The "status" property is by default "okay", thus it can be omitted.
+
+Example::
+
+	// SoC DTSI
+
+	usb_1_hsphy: phy@88e3000 {
+		compatible = "qcom,sm8550-snps-eusb2-phy";
+		reg = <0x0 0x088e3000 0x0 0x154>;
+		#phy-cells = <0>;
+		resets = <&gcc GCC_QUSB2PHY_PRIM_BCR>;
+		status = "disabled";
+	};
+
+	// Board DTS
+
+	&usb_1_hsphy {
+		clocks = <&tcsr TCSR_USB2_CLKREF_EN>;
+		clock-names = "ref";
+		status = "okay";
+	};
+
+
+Indentation
+-----------
+
+1. Use indentation according to :ref:`codingstyle`.
+2. For arrays spanning across lines, preferred is to align the continued
+   entries with opening < from first line.
+
+Example::
+
+	thermal-sensor@c271000 {
+		compatible = "qcom,sm8550-tsens", "qcom,tsens-v2";
+		reg = <0x0 0x0c271000 0x0 0x1000>,
+		      <0x0 0x0c222000 0x0 0x1000>;
+	};
-- 
2.34.1


^ permalink raw reply related	[flat|nested] 22+ messages in thread
end of thread, other threads:[~2023-11-20  7:19 UTC | newest]

Thread overview: 22+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-11-16 18:12 [PATCH] docs: dt-bindings: add DTS Coding Style document Krzysztof Kozlowski
2023-11-16 19:26 ` Heiko Stuebner
2023-11-16 19:51   ` Krzysztof Kozlowski
2023-11-16 20:03     ` Heiko Stuebner
2023-11-16 20:23       ` Krzysztof Kozlowski
2023-11-16 20:33         ` Heiko Stuebner
2023-11-17 14:03           ` Andrew Davis
2023-11-17 19:38             ` Heiko Stübner
2023-11-17 19:54               ` Andrew Davis
2023-11-17 20:04                 ` Heiko Stübner
2023-11-18 11:25               ` Geert Uytterhoeven
2023-11-20  7:12           ` Krzysztof Kozlowski
2023-11-16 20:44 ` Rob Herring
2023-11-17 23:55   ` Konrad Dybcio
2023-11-20  7:19   ` Krzysztof Kozlowski
2023-11-16 21:27 ` Conor Dooley
2023-11-20  7:14   ` Krzysztof Kozlowski
2023-11-16 21:32 ` Geert Uytterhoeven
2023-11-20  7:16   ` Krzysztof Kozlowski
2023-11-17 23:53 ` Konrad Dybcio
2023-11-20  7:15   ` Krzysztof Kozlowski
2023-11-17 23:58 ` Konrad Dybcio

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).