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

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

[Dragan Simic]

When it comes to ordering the individual properties inside each property
group, applying alphanumerical ordering can result in more logical and more
usable lists of properties, just like it's already the case with the
alphanumerical ordering of the nodes without unit addresses.

Let's have this clearly specified in the DTS coding style.  Also expand the
provided example a bit, to actually show the alphanumerical ordering.

Applying strict alphabetical ordering can result in property lists that are
far from optimal from the usability standpoint.  For the provided example,
which stems from a real-world DT, [1][2][3] applying the strict alphabetical
ordering produces this undesirable result:

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

Obviously, having the properties sorted by their associated voltages in the
ascending order, which the alphanumerical ordering produces, is more logical,
more usable and more consistent.

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

Signed-off-by: Dragan Simic <dsimic@manjaro.org>
---
 Documentation/devicetree/bindings/dts-coding-style.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
index 8a68331075a0..079d079f1ad9 100644
--- a/Documentation/devicetree/bindings/dts-coding-style.rst
+++ b/Documentation/devicetree/bindings/dts-coding-style.rst
@@ -133,6 +133,10 @@ 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 above-described ordering specifies the preferred ordering of property
+groups, while the individual properties inside each group shall be ordered
+alpha-numerically by the property name.
+
 Example::
 
 	/* SoC DTSI */
@@ -158,7 +162,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";
 	}
 

Re: [PATCH] docs: dt-bindings: Specify ordering for properties within groups

[Krzysztof Kozlowski]

On Tue, Mar 04, 2025 at 07:54:42AM +0100, Dragan Simic wrote:
> When it comes to ordering the individual properties inside each property
> group, applying alphanumerical ordering can result in more logical and more
> usable lists of properties, just like it's already the case with the
> alphanumerical ordering of the nodes without unit addresses.
> 
> Let's have this clearly specified in the DTS coding style.  Also expand the
> provided example a bit, to actually show the alphanumerical ordering.
> 
> Applying strict alphabetical ordering can result in property lists that are
> far from optimal from the usability standpoint.  For the provided example,
> which stems from a real-world DT, [1][2][3] applying the strict alphabetical
> ordering produces this undesirable result:
> 
>   vdd-0v9-supply = <&board_vreg1>;
>   vdd-12v-supply = <&board_vreg3>;
>   vdd-1v8-supply = <&board_vreg4>;
>   vdd-3v3-supply = <&board_vreg2>;

Depending on interpretation (of which StackOverflow or Google answer you
read), that is actual alphanumerical order. What you want to achieve is
"natural order", so to remove ambiguity just use commonly used natural
order.

> 
> Obviously, having the properties sorted by their associated voltages in the
> ascending order, which the alphanumerical ordering produces, is more logical,
> more usable and more consistent.
> 
> [1] https://lore.kernel.org/linux-rockchip/b39cfd7490d8194f053bf3971f13a43472d1769e.1740941097.git.dsimic@manjaro.org/
> [2] https://lore.kernel.org/linux-rockchip/174104113599.8946.16805724674396090918.b4-ty@sntech.de/
> [3] https://lore.kernel.org/linux-rockchip/757afa87255212dfa5abf4c0e31deb08@manjaro.org/
> 
> Signed-off-by: Dragan Simic <dsimic@manjaro.org>
> ---
>  Documentation/devicetree/bindings/dts-coding-style.rst | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
> index 8a68331075a0..079d079f1ad9 100644
> --- a/Documentation/devicetree/bindings/dts-coding-style.rst
> +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
> @@ -133,6 +133,10 @@ 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 above-described ordering specifies the preferred ordering of property
> +groups, while the individual properties inside each group shall be ordered

...shall use natural order by the property name.

Best regards,
Krzysztof