]> www.infradead.org Git - users/jedix/linux-maple.git/commit
docs: dt-bindings: Specify ordering for properties within groups
authorDragan Simic <dsimic@manjaro.org>
Fri, 21 Mar 2025 04:57:09 +0000 (05:57 +0100)
committerRob Herring (Arm) <robh@kernel.org>
Fri, 21 Mar 2025 16:27:56 +0000 (11:27 -0500)
commit18d00558e89239e5c9a676341568b1ed6ecd4235
treeb11d786aacaf39156681e63f85fd42f384a8b7eb
parentd47bdcbc55e7969f0196192c44d0f39ec321d2cc
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@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>
Documentation/devicetree/bindings/dts-coding-style.rst