Re: [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@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