github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-27 08:33:17 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: dt-bindings: Specify ordering for properties within groups

Browse Source 
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@manjaro.org>
Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Link: https://lore.kernel.org/r/6468619098f94d8acb00de0431c414c5fcfbbdbf.1742532899.git.dsimic@manjaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
This commit is contained in:
Dragan Simic 2025-03-21 05:57:09 +01:00 committed by Rob Herring (Arm)
parent d47bdcbc55
commit 18d00558e8
1 changed files with 7 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Documentation/devicetree/bindings/dts-coding-style.rst
View File

@ -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";
}