[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <CAGb2v64Vf5dDwq=KTrxwc=+w+0KUD2KVPMjmHg68Y_yukES5dQ@mail.gmail.com>
Date: Wed, 22 Nov 2023 16:09:00 +0800
From: Chen-Yu Tsai <wens@...nel.org>
To: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
Cc: Rafał Miłecki <zajec5@...il.com>,
Rob Herring <robh+dt@...nel.org>,
Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
Conor Dooley <conor+dt@...nel.org>,
Matthias Brugger <matthias.bgg@...il.com>,
AngeloGioacchino Del Regno
<angelogioacchino.delregno@...labora.com>,
devicetree@...r.kernel.org, linux-kernel@...r.kernel.org,
linux-arm-kernel@...ts.infradead.org,
linux-mediatek@...ts.infradead.org, Andrew Davis <afd@...com>,
Arnd Bergmann <arnd@...db.de>,
Bjorn Andersson <andersson@...nel.org>,
Geert Uytterhoeven <geert+renesas@...der.be>,
Heiko Stuebner <heiko@...ech.de>,
Konrad Dybcio <konrad.dybcio@...aro.org>,
Michal Simek <michal.simek@....com>,
Neil Armstrong <neil.armstrong@...aro.org>,
Nishanth Menon <nm@...com>, Olof Johansson <olof@...om.net>,
linux-rockchip@...ts.infradead.org,
linux-samsung-soc@...r.kernel.org,
linux-amlogic@...ts.infradead.org, linux-arm-msm@...r.kernel.org
Subject: Re: [PATCH v2] docs: dt-bindings: add DTS Coding Style document
On Wed, Nov 22, 2023 at 4:05 PM Krzysztof Kozlowski
<krzysztof.kozlowski@...aro.org> wrote:
>
> On 21/11/2023 14:50, Rafał Miłecki wrote:
> >> +Order of Nodes
> >> +--------------
> >> +
> >> +1. Nodes within any bus, thus using unit addresses for children, shall be
> >> + ordered incrementally by unit address.
> >> + Alternatively for some sub-architectures, nodes of the same type can be
> >> + grouped together (e.g. all I2C controllers one after another even if this
> >> + breaks unit address ordering).
> >> +
> >> +2. Nodes without unit addresses should be ordered alpha-numerically by the node
> >> + name. For a few types of nodes, they can be ordered by the main property
> >> + (e.g. pin configuration states ordered by value of "pins" property).
> >> +
> >> +3. When extending nodes in the board DTS via &label, the entries should be
> >> + ordered alpha-numerically.
> >
> > Just an idea. Would that make (more) sense to make &label-like entries
> > match order of nodes in included .dts(i)?
> >
> > Adventages:
> > 1. We keep unit address incremental order that is unlikely to change
> >
> > Disadventages:
> > 1. More difficult to verify
>
> Rob also proposed this and I believe above disadvantage here is crucial.
> If you add new SoC with board DTS you are fine. But if you add only new
> board, the order of entries look random in the diff hunk. Reviewer must
> open SoC DTSI to be able to review the patch with board DTS.
>
> If review is tricky and we do not have tool to perform it automatically,
> I am sure submissions will have disordered board DTS.
>
> >
> >
> >> +Example::
> >> +
> >> + // SoC DTSI
> >> +
> >> + / {
> >> + cpus {
> >> + // ...
> >> + };
> >> +
> >> + psci {
> >> + // ...
> >> + };
> >> +
> >> + soc@ {
> >> + dma: dma-controller@...00 {
> >> + // ...
> >> + };
> >> +
> >> + clk: clock-controller@...00 {
> >> + // ...
> >> + };
> >> + };
> >> + };
> >> +
> >> + // Board DTS
> >> +
> >> + &clk {
> >> + // ...
> >> + };
> >> +
> >> + &dma {
> >> + // ...
> >> + };
> >> +
> >> +
> >> +Order of Properties in Device Node
> >> +----------------------------------
> >> +
> >> +Following order of properties in device nodes is preferred:
> >> +
> >> +1. compatible
> >> +2. reg
> >> +3. ranges
> >> +4. Standard/common properties (defined by common bindings, e.g. without
> >> + vendor-prefixes)
> >> +5. Vendor-specific properties
> >> +6. status (if applicable)
> >> +7. Child nodes, where each node is preceded with a blank line
> >> +
> >> +The "status" property is by default "okay", thus it can be omitted.
> >
> > I think it would really help to include position of #address-cells and
> > #size-cells here. In some files I saw them above "compatible" that seems
> > unintuitive. Some prefer putting them at end which I think makes sense
> > as they affect children nodes.
> >
> > Whatever you choose it'd be just nice to have things consistent.
>
> This is a standard/common property, thus it goes to (4) above.
It's probably a mix, but AFAIK a lot of the device trees in tree have
#*-cells after "status". In some cases they are added in the board
.dts files, not the chip/module .dtsi files.
+1 that it makes sense at the end as they affect child nodes.
ChenYu
Powered by blists - more mailing lists