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

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

Posted by Dragan Simic 11 months, 1 week ago

When it comes to ordering of the individual properties inside each property
group, applying natural sort order to multi-digit numbers [1] found inside
the property names can result 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.  Also expand the
provided example a bit, to actually show the 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>
---

Notes:
    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
    
    [5] https://lore.kernel.org/linux-kernel/20250305-defiant-serious-newt-b7c5ea@krzk-bin/

 .../devicetree/bindings/dts-coding-style.rst          | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
index 8a68331075a0..15de3ede2d9c 100644
--- a/Documentation/devicetree/bindings/dts-coding-style.rst
+++ b/Documentation/devicetree/bindings/dts-coding-style.rst
@@ -133,6 +133,12 @@ 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 use natural
+sort order by the property name.  More specifically, natural sort order shall
+apply to multi-digit numbers found inside the property names, while alpha-
+numerical ordering shall apply otherwise.
+
 Example::
 
 	/* SoC DTSI */
@@ -158,7 +164,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 v2] docs: dt-bindings: Specify ordering for properties within groups

Posted by Krzysztof Kozlowski 11 months, 1 week ago

On 05/03/2025 09:45, Dragan Simic wrote:
> 
> diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
> index 8a68331075a0..15de3ede2d9c 100644
> --- a/Documentation/devicetree/bindings/dts-coding-style.rst
> +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
> @@ -133,6 +133,12 @@ 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 use natural
> +sort order by the property name.  More specifically, natural sort order shall
> +apply to multi-digit numbers found inside the property names, while alpha-
> +numerical ordering shall apply otherwise.


The last sentence was not here and I don't get the point. Natural sort
order should be always preferred over alpha-numerical for properties.
About which other case ("...apply otherwise.") are you thinking?

Best regards,
Krzysztof

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

Posted by Dragan Simic 11 months, 1 week ago

Hello Krzysztof,

On 2025-03-05 10:36, Krzysztof Kozlowski wrote:
> On 05/03/2025 09:45, Dragan Simic wrote:
>> 
>> diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst 
>> b/Documentation/devicetree/bindings/dts-coding-style.rst
>> index 8a68331075a0..15de3ede2d9c 100644
>> --- a/Documentation/devicetree/bindings/dts-coding-style.rst
>> +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
>> @@ -133,6 +133,12 @@ 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 use 
>> natural
>> +sort order by the property name.  More specifically, natural sort 
>> order shall
>> +apply to multi-digit numbers found inside the property names, while 
>> alpha-
>> +numerical ordering shall apply otherwise.
> 
> The last sentence was not here and I don't get the point. Natural sort
> order should be always preferred over alpha-numerical for properties.
> About which other case ("...apply otherwise.") are you thinking?

Yes, I added that sentence in the v2 to, hopefully, clarify the natural
sort order itself a bit.  I've researched the natural sort order a bit
further, and it technically applies only to the multi-digit numbers 
found
inside the sorted strings.  That's what I wanted to explain, and "shall
apply otherwise" refers to applying the alpha-numerical sort order to 
the
remainders of the sorted strings, i.e. to everything but the multi-digit
numbers found in the property names.

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

Posted by Krzysztof Kozlowski 11 months, 1 week ago

On Wed, Mar 05, 2025 at 10:53:48AM +0100, Dragan Simic wrote:
> Hello Krzysztof,
> 
> On 2025-03-05 10:36, Krzysztof Kozlowski wrote:
> > On 05/03/2025 09:45, Dragan Simic wrote:
> > > 
> > > diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst
> > > b/Documentation/devicetree/bindings/dts-coding-style.rst
> > > index 8a68331075a0..15de3ede2d9c 100644
> > > --- a/Documentation/devicetree/bindings/dts-coding-style.rst
> > > +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
> > > @@ -133,6 +133,12 @@ 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 use
> > > natural
> > > +sort order by the property name.  More specifically, natural sort
> > > order shall
> > > +apply to multi-digit numbers found inside the property names, while
> > > alpha-
> > > +numerical ordering shall apply otherwise.
> > 
> > The last sentence was not here and I don't get the point. Natural sort
> > order should be always preferred over alpha-numerical for properties.
> > About which other case ("...apply otherwise.") are you thinking?
> 
> Yes, I added that sentence in the v2 to, hopefully, clarify the natural
> sort order itself a bit.  I've researched the natural sort order a bit
> further, and it technically applies only to the multi-digit numbers found
> inside the sorted strings.  That's what I wanted to explain, and "shall

Natural sort applies to everywhere. It's just the same as
alpha-numerical sort for single digits.

> apply otherwise" refers to applying the alpha-numerical sort order to the
> remainders of the sorted strings, i.e. to everything but the multi-digit
> numbers found in the property names.

Sorry, still don't get. What would be the difference if for remainders
of properties you would also apply natural sort instead of
alphanumerical sort?

Best regards,
Krzysztof

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

Posted by Dragan Simic 11 months, 1 week ago

Hello Krzysztof,

On 2025-03-06 09:38, Krzysztof Kozlowski wrote:
> On Wed, Mar 05, 2025 at 10:53:48AM +0100, Dragan Simic wrote:
>> On 2025-03-05 10:36, Krzysztof Kozlowski wrote:
>> > On 05/03/2025 09:45, Dragan Simic wrote:
>> > >
>> > > diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst
>> > > b/Documentation/devicetree/bindings/dts-coding-style.rst
>> > > index 8a68331075a0..15de3ede2d9c 100644
>> > > --- a/Documentation/devicetree/bindings/dts-coding-style.rst
>> > > +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
>> > > @@ -133,6 +133,12 @@ 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 use
>> > > natural
>> > > +sort order by the property name.  More specifically, natural sort
>> > > order shall
>> > > +apply to multi-digit numbers found inside the property names, while
>> > > alpha-
>> > > +numerical ordering shall apply otherwise.
>> >
>> > The last sentence was not here and I don't get the point. Natural sort
>> > order should be always preferred over alpha-numerical for properties.
>> > About which other case ("...apply otherwise.") are you thinking?
>> 
>> Yes, I added that sentence in the v2 to, hopefully, clarify the 
>> natural
>> sort order itself a bit.  I've researched the natural sort order a bit
>> further, and it technically applies only to the multi-digit numbers 
>> found
>> inside the sorted strings.  That's what I wanted to explain, and 
>> "shall
> 
> Natural sort applies to everywhere. It's just the same as
> alpha-numerical sort for single digits.

Technically, it depends on how one describes the natural sort order.
I'll get back to this below.

>> apply otherwise" refers to applying the alpha-numerical sort order to 
>> the
>> remainders of the sorted strings, i.e. to everything but the 
>> multi-digit
>> numbers found in the property names.
> 
> Sorry, still don't get. What would be the difference if for remainders
> of properties you would also apply natural sort instead of
> alphanumerical sort?

Oh, there are no differences in the results of the ordering, it's just
about the formal definition of the natural sort order.  In some places,
the natural sort order is described to apply to the multi-digit numbers
found in the sorted strings only.  Thus, the wording I proposed tries
to explain that further, but I do agree that it's somewhat confusing.

In other words, the way natural sort order is defined in some places,
it applies to the multi-digit parts of the sorted strings only, while
the remainders of the strings are sorted alpha-numerically.  I'll 
consult
some more sources and get back with some better wording in the v3, to
make it less confusing, while still describing the natural sort order
a bit, because the people who will be reading the DTS coding style may
not already be familiar with it.

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

Posted by Krzysztof Kozlowski 11 months, 1 week ago

On 06/03/2025 09:57, Dragan Simic wrote:
> Hello Krzysztof,
> 
> On 2025-03-06 09:38, Krzysztof Kozlowski wrote:
>> On Wed, Mar 05, 2025 at 10:53:48AM +0100, Dragan Simic wrote:
>>> On 2025-03-05 10:36, Krzysztof Kozlowski wrote:
>>>> On 05/03/2025 09:45, Dragan Simic wrote:
>>>>>
>>>>> diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst
>>>>> b/Documentation/devicetree/bindings/dts-coding-style.rst
>>>>> index 8a68331075a0..15de3ede2d9c 100644
>>>>> --- a/Documentation/devicetree/bindings/dts-coding-style.rst
>>>>> +++ b/Documentation/devicetree/bindings/dts-coding-style.rst
>>>>> @@ -133,6 +133,12 @@ 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 use
>>>>> natural
>>>>> +sort order by the property name.  More specifically, natural sort
>>>>> order shall
>>>>> +apply to multi-digit numbers found inside the property names, while
>>>>> alpha-
>>>>> +numerical ordering shall apply otherwise.
>>>>
>>>> The last sentence was not here and I don't get the point. Natural sort
>>>> order should be always preferred over alpha-numerical for properties.
>>>> About which other case ("...apply otherwise.") are you thinking?
>>>
>>> Yes, I added that sentence in the v2 to, hopefully, clarify the 
>>> natural
>>> sort order itself a bit.  I've researched the natural sort order a bit
>>> further, and it technically applies only to the multi-digit numbers 
>>> found
>>> inside the sorted strings.  That's what I wanted to explain, and 
>>> "shall
>>
>> Natural sort applies to everywhere. It's just the same as
>> alpha-numerical sort for single digits.
> 
> Technically, it depends on how one describes the natural sort order.
> I'll get back to this below.
> 
>>> apply otherwise" refers to applying the alpha-numerical sort order to 
>>> the
>>> remainders of the sorted strings, i.e. to everything but the 
>>> multi-digit
>>> numbers found in the property names.
>>
>> Sorry, still don't get. What would be the difference if for remainders
>> of properties you would also apply natural sort instead of
>> alphanumerical sort?
> 
> Oh, there are no differences in the results of the ordering, it's just
> about the formal definition of the natural sort order.  In some places,
> the natural sort order is described to apply to the multi-digit numbers


I am no language expert, so I rely on Wikipedia:

https://en.wikipedia.org/wiki/Natural_sort_order
"except that single- and multi-digit numbers are treated atomically,"

and anyway I don't really know how natural sort order would work for
single digits if it was applying to them differently.

> found in the sorted strings only.  Thus, the wording I proposed tries
> to explain that further, but I do agree that it's somewhat confusing.
> 
> In other words, the way natural sort order is defined in some places,
> it applies to the multi-digit parts of the sorted strings only, while
> the remainders of the strings are sorted alpha-numerically.  I'll 
> consult
> some more sources and get back with some better wording in the v3, to
> make it less confusing, while still describing the natural sort order
> a bit, because the people who will be reading the DTS coding style may
> not already be familiar with it.


Please drop the second sentence. The point is to be concise. If text
grows too long, people won't read it (just like they don't read
submitting-patches).


Best regards,
Krzysztof