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

[Michal Simek]

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 at ti.com>
>>> Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno at collabora.com>
>>> Cc: Arnd Bergmann <arnd at arndb.de>
>>> Cc: Bjorn Andersson <andersson at kernel.org>
>>> Cc: Geert Uytterhoeven <geert+renesas at glider.be>
>>> Cc: Heiko Stuebner <heiko at sntech.de>
>>> Cc: Konrad Dybcio <konrad.dybcio at linaro.org>
>>> Cc: Matthias Brugger <matthias.bgg at gmail.com>
>>> Cc: Michal Simek <michal.simek at amd.com>
>>> Cc: Neil Armstrong <neil.armstrong at linaro.org>
>>> Cc: Nishanth Menon <nm at ti.com>
>>> Cc: Olof Johansson <olof at lixom.net>
>>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski at linaro.org>
>>>
>>> ---
>>>
>>> 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 at lists.infradead.org
>>> Cc: linux-mediatek at lists.infradead.org
>>> Cc: linux-samsung-soc at vger.kernel.org
>>> Cc: linux-amlogic at lists.infradead.org
>>> Cc: linux-arm-kernel at lists.infradead.org
>>> Cc: linux-arm-msm at vger.kernel.org
>>> ---
>>>    .../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