[PATCH v3] docs: dt-bindings: add DTS Coding Style document

[Rob Herring]

On Sun, Nov 26, 2023 at 04:53:40PM +0200, Laurent Pinchart wrote:
> Hi Krzysztof,
> 
> On Sun, Nov 26, 2023 at 11:32:17AM +0100, Krzysztof Kozlowski wrote:
> > On 25/11/2023 20:37, Laurent Pinchart wrote:
> > > On Sat, Nov 25, 2023 at 07:44:22PM +0100, Krzysztof Kozlowski wrote:
> > >> Document preferred coding style for Devicetree sources (DTS and DTSI),
> > >> to bring consistency among all (sub)architectures and ease in reviews.


> > >> +
> > >> +Naming and Valid Characters
> > >> +---------------------------
> > >> +
> > >> +Devicetree specification allows broader range of characters in node and
> > > 
> > > s/Devicetree specification/The Devicetree specification/
> > > s/broader range/a broad range/
> > 
> > Ack, but I really expect people finish with grammar and style fixes at
> > v3. Please point the language things now or just let it go.
> 
> v3 is the first version that ended up in my inbox. I haven't noticed any
> other spelling or grammar error in this patch, but I can't guarantee I
> won't see any in new text that gets introduced in a future version :-)
> 
> > >> +property names, but for code readability the choice shall be narrowed.
> > >> +
> > >> +1. Node and property names are allowed to use only:
> > >> +
> > >> +   * lowercase characters: [a-z]
> > >> +   * digits: [0-9]
> > >> +   * dash: -
> > >> +
> > >> +2. Labels are allowed to use only:
> > >> +
> > >> +   * lowercase characters: [a-z]
> > >> +   * digits: [0-9]
> > >> +   * underscore: _
> > >> +
> > >> +3. Unit addresses shall use lowercase hex, without leading zeros (padding).

Unless a bus defines differently, unit addresses shall ...

> > > 
> > > I'm curious, what's the reason for this ? I think it makes the sources
> > > less readable. If the rule is "just" because that's how DT sources are
> > > written today and it would be too complicated to change that, that's
> > > fine with me.
> > 
> > Warning (unit_address_format): /cpus/cpu at 0100: unit name should not have
> > leading 0s
> > 
> > And we fixed all or most of DTS some time ago.
> 
> It's the current practice in DT sources and I understand it won't get
> changed, but I was more curious about the rationale behind that.

I put the dtc check in, but the rational predates me. The OF PCI bus 
supplement from the 1990s defines that. My only rationale to check it 
was to be consistent. We don't check "the unit-address is lowercase hex"
because technically the bus defines the format. Leading 0s was as much 
as I could get David G to agree to check without regard to bus type.

Rob