lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <CAL_JsqLxKWXVXp6+-yNxvHifZHEDvMdQChR7AHD9STJw_S9UiA@mail.gmail.com>
Date:   Thu, 16 Nov 2023 14:44:44 -0600
From:   Rob Herring <robh+dt@...nel.org>
To:     Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
Cc:     Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
        Conor Dooley <conor+dt@...nel.org>, devicetree@...r.kernel.org,
        linux-kernel@...r.kernel.org,
        AngeloGioacchino Del Regno 
        <angelogioacchino.delregno@...labora.com>,
        Arnd Bergmann <arnd@...db.de>,
        Bjorn Andersson <andersson@...nel.org>,
        Geert Uytterhoeven <geert+renesas@...der.be>,
        Heiko Stuebner <heiko@...ech.de>,
        Konrad Dybcio <konrad.dybcio@...aro.org>,
        Matthias Brugger <matthias.bgg@...il.com>,
        Michal Simek <michal.simek@....com>,
        Neil Armstrong <neil.armstrong@...aro.org>,
        Nishanth Menon <nm@...com>, Olof Johansson <olof@...om.net>
Subject: Re: [PATCH] docs: dt-bindings: add DTS Coding Style document

On Thu, Nov 16, 2023 at 12:12 PM Krzysztof Kozlowski
<krzysztof.kozlowski@...aro.org> wrote:
>
> Document preferred coding style for Devicetree sources (DTS and DTSI),
> to bring consistency among all (sub)architectures and ease in reviews.

Thanks for doing this.

>
> Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno@...labora.com>
> Cc: Arnd Bergmann <arnd@...db.de>
> Cc: Bjorn Andersson <andersson@...nel.org>
> Cc: Geert Uytterhoeven <geert+renesas@...der.be>
> Cc: Heiko Stuebner <heiko@...ech.de>
> Cc: Konrad Dybcio <konrad.dybcio@...aro.org>
> Cc: Matthias Brugger <matthias.bgg@...il.com>
> Cc: Michal Simek <michal.simek@....com>
> Cc: Neil Armstrong <neil.armstrong@...aro.org>
> Cc: Nishanth Menon <nm@...com>
> Cc: Olof Johansson <olof@...om.net>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.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

Perhaps dts-coding-style.rst

After adding writing-schema, I realized the difference between
writing-schema and writing-bindings isn't all that clear. I never got
around to renaming things.

>
> 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).

Strictly speaking, the unit-address is whatever a bus defines, but
yes, by default, that is the format.

> +
> +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@...000 {
> +               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.

Or matching the original node definition order?

> +
> +Example::
> +
> +       // SoC DTSI
> +
> +       \ {

/ {

> +               cpus {
> +                       // ...
> +               };
> +
> +               psci {
> +                       // ...
> +               };
> +
> +               soc@ {
> +                       dma: dma-controller@...00 {
> +                               // ...
> +                       };
> +
> +                       clk: clock-controller@...00 {
> +                               // ...
> +                       };
> +               };
> +       };
> +
> +       // 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

I make this like schemas, standard/common properties first, then
vendor specific 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@...3000 {
> +               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@...1000 {
> +               compatible = "qcom,sm8550-tsens", "qcom,tsens-v2";
> +               reg = <0x0 0x0c271000 0x0 0x1000>,
> +                     <0x0 0x0c222000 0x0 0x1000>;

You should cover the <> style too, meaning <> around each logical entry.

> +       };
> --
> 2.34.1
>

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ