From: Dragan Simic Date: Fri, 21 Mar 2025 04:57:09 +0000 (+0100) Subject: docs: dt-bindings: Specify ordering for properties within groups X-Git-Tag: v6.15-rc1~115^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=18d00558e89239e5c9a676341568b1ed6ecd4235;p=thirdparty%2Fkernel%2Flinux.git 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 Reviewed-by: Krzysztof Kozlowski Link: https://lore.kernel.org/r/6468619098f94d8acb00de0431c414c5fcfbbdbf.1742532899.git.dsimic@manjaro.org Signed-off-by: Rob Herring (Arm) --- diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst index 4772ded8a9872..202acac0507ab 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"; }