linux-kernel - [PATCH v4] docs: dt-bindings: Specify ordering for properties within groups

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-next>] [day] [month] [year] [list]

Message-Id: <6468619098f94d8acb00de0431c414c5fcfbbdbf.1742532899.git.dsimic@manjaro.org>
Date: Fri, 21 Mar 2025 05:57:09 +0100
From: Dragan Simic <dsimic@...jaro.org>
To: robh@...nel.org,
	krzk+dt@...nel.org,
	conor+dt@...nel.org
Cc: heiko@...ech.de,
	dsimic@...jaro.org,
	devicetree@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: [PATCH v4] docs: dt-bindings: Specify ordering for properties within groups

Ordering of the individual properties inside each property group benefits
from applying natural sort order [1] by the property names, because it
results in more logical and more usable property lists, similarly to what's
already the case with the alpha-numerical ordering of the nodes without
unit addresses.

Let's have this clearly specified in the DTS coding style, and let's expand
the provided node example a bit, to actually show the results of applying
natural sort order.

Applying strict alpha-numerical ordering can result in property lists that
are suboptimal from the usability standpoint.  For the provided example,
which stems from a real-world DT, [2][3][4] applying strict alpha-numerical
ordering produces the following undesirable result:

  vdd-0v9-supply = <&board_vreg1>;
  vdd-12v-supply = <&board_vreg3>;
  vdd-1v8-supply = <&board_vreg4>;
  vdd-3v3-supply = <&board_vreg2>;

Having the properties sorted in natural order by their associated voltages
is more logical, more usable, and a bit more consistent.

[1] https://en.wikipedia.org/wiki/Natural_sort_order
[2] https://lore.kernel.org/linux-rockchip/b39cfd7490d8194f053bf3971f13a43472d1769e.1740941097.git.dsimic@manjaro.org/
[3] https://lore.kernel.org/linux-rockchip/174104113599.8946.16805724674396090918.b4-ty@sntech.de/
[4] https://lore.kernel.org/linux-rockchip/757afa87255212dfa5abf4c0e31deb08@manjaro.org/

Signed-off-by: Dragan Simic <dsimic@...jaro.org>
---

Notes:
    Changes in v4:
      - Compacted both the introduced additions to the DTS conding style
        and the patch description, as suggested by Krzysztof [7]
      - Reformatted the patch description to obey the 75-column-width
        rule, and adjusted the editor configuration accordingly, to avoid
        such issues in the future, as suggested by Krzysztof [7]
    
    Changes in v3:
      - Rewrote the part of the changes that describes natural sort order
        and its relation to "standard" alpha-numerical ordering, to make
        it more understandable, as suggested by Krzysztof [6]
      - Slightly expanded the patch description, to clarify the additional
        goal of explaining the natural sort order briefly
    
    Changes in v2:
      - Changed the additions to the coding style to specify natural sort
        order, which avoids amibguity, as suggested by Krzysztof [5]
      - Adjusted and expanded the patch description appropriately, together
        with including one more reference for the natural sort order
    
    Link to v1: https://lore.kernel.org/linux-kernel/09d6f2fc111b3d6e58987336944f93ec36b65118.1741071107.git.dsimic@manjaro.org/T/#u
    Link to v2: https://lore.kernel.org/linux-kernel/47c51c10098f089e52fb14c5c5527611dc8daf32.1741164239.git.dsimic@manjaro.org/T/#u
    Link to v3: https://lore.kernel.org/linux-kernel/7276139ea1f4a5f4db48c77f536a3638492e6c2f.1741321984.git.dsimic@manjaro.org/T/#u
    
    [5] https://lore.kernel.org/linux-kernel/20250305-defiant-serious-newt-b7c5ea@krzk-bin/
    [6] https://lore.kernel.org/linux-kernel/20250306-dexterous-goshawk-of-aptitude-e4f1f6@krzk-bin/
    [7] https://lore.kernel.org/linux-kernel/20250307-logical-nimble-okapi-3ba081@krzk-bin/

 Documentation/devicetree/bindings/dts-coding-style.rst | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
index 8a68331075a0..d8a2b11cab48 100644
--- a/Documentation/devicetree/bindings/dts-coding-style.rst
+++ b/Documentation/devicetree/bindings/dts-coding-style.rst
@@ -133,6 +133,9 @@ The above-described ordering follows this approach:
 3. Status is the last information to annotate that device node is or is not
    finished (board resources are needed).
 
+The individual properties inside each group shall use natural sort order by
+the property name.
+
 Example::
 
 	/* SoC DTSI */
@@ -158,7 +161,10 @@ Example::
 	/* Board DTS */
 
 	&device_node {
-		vdd-supply = <&board_vreg1>;
+		vdd-0v9-supply = <&board_vreg1>;
+		vdd-1v8-supply = <&board_vreg4>;
+		vdd-3v3-supply = <&board_vreg2>;
+		vdd-12v-supply = <&board_vreg3>;
 		status = "okay";
 	}