Re: [PATCH v2] docs: dt-bindings: add DTS Coding Style document

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 





On 11/20/23 15:53, Krzysztof Kozlowski wrote:
On 20/11/2023 15:01, Michal Simek wrote:


On 11/20/23 09:40, Krzysztof Kozlowski wrote:
Document preferred coding style for Devicetree sources (DTS and DTSI),
to bring consistency among all (sub)architectures and ease in reviews.

Cc: Andrew Davis <afd@xxxxxx>
Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno@xxxxxxxxxxxxx>
Cc: Arnd Bergmann <arnd@xxxxxxxx>
Cc: Bjorn Andersson <andersson@xxxxxxxxxx>
Cc: Geert Uytterhoeven <geert+renesas@xxxxxxxxx>
Cc: Heiko Stuebner <heiko@xxxxxxxxx>
Cc: Konrad Dybcio <konrad.dybcio@xxxxxxxxxx>
Cc: Matthias Brugger <matthias.bgg@xxxxxxxxx>
Cc: Michal Simek <michal.simek@xxxxxxx>
Cc: Neil Armstrong <neil.armstrong@xxxxxxxxxx>
Cc: Nishanth Menon <nm@xxxxxx>
Cc: Olof Johansson <olof@xxxxxxxxx>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@xxxxxxxxxx>

---

Merging idea: Rob/DT bindings

Changes in v2
=============
1. Hopefully incorporate entire feedback from comments:
a. Fix \ { => / { (Rob)
b. Name: dts-coding-style (Rob)
c. Exceptions for ordering nodes by name for Renesas and pinctrl (Geert,
     Konrad)
d. Ordering properties by common/vendor (Rob)
e. Array entries in <> (Rob)

2. New chapter: Organizing DTSI and DTS

3. Several grammar fixes (missing articles)

Cc: linux-rockchip@xxxxxxxxxxxxxxxxxxx
Cc: linux-mediatek@xxxxxxxxxxxxxxxxxxx
Cc: linux-samsung-soc@xxxxxxxxxxxxxxx
Cc: linux-amlogic@xxxxxxxxxxxxxxxxxxx
Cc: linux-arm-kernel@xxxxxxxxxxxxxxxxxxx
Cc: linux-arm-msm@xxxxxxxxxxxxxxx
---
   .../devicetree/bindings/dts-coding-style.rst  | 163 ++++++++++++++++++
   Documentation/devicetree/bindings/index.rst   |   1 +
   2 files changed, 164 insertions(+)
   create mode 100644 Documentation/devicetree/bindings/dts-coding-style.rst

diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
new file mode 100644
index 000000000000..cc7e3b4d1b92
--- /dev/null
+++ b/Documentation/devicetree/bindings/dts-coding-style.rst
@@ -0,0 +1,163 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. _dtscodingstyle:
+
+=====================================
+Devicetree Sources (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: -

device-tree specification v0.4. Chapter 2.2.1/Table 2.1 is describing much more
valid characters for node names.
It means above description is not accurate or DT spec should be updated.

Spec allows way to much. dtc doesn't. One thing is the spec, second
thing is coding style.

From my point of view spec is primary source of truth. If spec is saying name can use upper case then I can use it. If upper case is not recommended/deprecated because of whatever reason spec should be updated to reflect it. I know that DTC is reporting other issues but isn't it the right way to reflect it back to the spec?

No doubt that it is nice to see to have guide like this.

Thanks,
Michal




[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]


  Powered by Linux