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

[Geert Uytterhoeven]

Hi Krzysztof,

On Sat, Nov 25, 2023 at 7:44 PM Krzysztof Kozlowski
<krzysztof.kozlowski at linaro.org> 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: Andrew Lunn <andrew at lunn.ch>
> Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno at collabora.com>
> Cc: Arnd Bergmann <arnd at arndb.de>
> Cc: Bjorn Andersson <andersson at kernel.org>
> Cc: Chen-Yu Tsai <wens at kernel.org>
> Cc: Dmitry Baryshkov <dmitry.baryshkov at linaro.org>
> Cc: Geert Uytterhoeven <geert+renesas at glider.be>
> Cc: Heiko Stuebner <heiko at sntech.de>
> Cc: Jonathan Corbet <corbet at lwn.net>
> 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>
> Cc: Rafał Miłecki <zajec5 at gmail.com>
> Acked-by: Neil Armstrong <neil.armstrong at linaro.org>
> Acked-by: Heiko Stuebner <heiko at sntech.de>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski at linaro.org>
>
> ---
>
> Merging idea: Rob/DT bindings
>
> Changes in v3
> =============
> 1. should->shall (Angelo)
> 2. Comments // -> /* (Angelo, Michal)
> 3. Use imaginary example in "Order of Properties in Device Node"
>    (Angelo)
> 4. Added paragraphs for three sections with justifications of chosen
>    style.
> 5. Allow two style of ordering overrides in board DTS: alphabetically or
>    by order of DTSI (Rob).
> 6. I did not incorporate feedback about, due to lack of consensus and my
>    disagreement:
>    a. SoM being DTS without DTSI in "Organizing DTSI and DTS"

Thanks for the update!

> --- /dev/null
> +++ b/Documentation/devicetree/bindings/dts-coding-style.rst

> +       /* SoC DTSI */
> +
> +       / {
> +               cpus {
> +                       /* ... */
> +               };
> +
> +               psci {
> +                       /* ... */
> +               };
> +
> +               soc@ {

"soc@" is invalid, that should be "soc".

As the "soc" node is special, you may want to elaborate:

                compatible = "simple-bus";
                #address-cells = <1>;
                #size-cells = <1>;
                ranges;

> +                       dma: dma-controller at 10000 {
> +                               /* ... */
> +                       };
> +
> +                       clk: clock-controller at 80000 {
> +                               /* ... */
> +                       };
> +               };
> +       };
> +
> +       /* Board DTS - alphabetical order */
> +
> +       &clk {
> +               /* ... */
> +       };
> +
> +       &dma {
> +               /* ... */
> +       };
> +
> +       /* Board DTS - alternative order, keep as DTSI */
> +
> +       &dma {
> +               /* ... */
> +       };
> +
> +       &clk {
> +               /* ... */
> +       };

IMO that alternative order is hard to review: you need to have multiple
files open.  It will also make validation hard, as you can only validate
the end result, not individual files.

Anyway, this is already quite usable so
Reviewed-by: Geert Uytterhoeven <geert+renesas at glider.be>

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert at linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds