[PATCH 8/9 V3] Add documentation for the new DTS language.

[Grant Likely]

On Mon, Mar 1, 2010 at 3:26 PM, Stephen Neuendorffer
<stephen.neuendorffer at xilinx.com> wrote:
>
>
>> -----Original Message-----
>> From: glikely at secretlab.ca [mailto:glikely at secretlab.ca] On Behalf Of Grant Likely
>> Sent: Monday, March 01, 2010 2:19 PM
>> To: Scott Wood
>> Cc: Stephen Neuendorffer; Yoder Stuart-B08248; Wood Scott-B07421; devicetree-discuss at ozlabs.org; John
>> Williams; Jeremy Kerr
>> Subject: Re: [PATCH 8/9 V3] Add documentation for the new DTS language.
>>
>> On Mon, Mar 1, 2010 at 2:06 PM, Scott Wood <scottwood at freescale.com> wrote:
>> > Stephen Neuendorffer wrote:
>> >>
>> >> One thing I've seen in the past is that there is a sequentialization
>> >> question in this, which becomes
>> >> more apparent once deletion is allowed.
>> >>
>> >> First off, my assumption is that each node name is always unique in a
>> >> tree, even when overrides are allowed.
>> >> Otherwise the sub-node and property ordering becomes important.
>> >>
>> >> foo {
>> >>        bar = 2;
>> >>        bar = 3; // Illegal
>> >> } ;
>> >>
>> >>
>> >> foo {
>> >>        bar = 2;
>> >> } foo {
>> >>        bar = 3; // Legal
>> >> };
>> >>
>> >>
>> >> So, essentially, sequentialization of operation is forced by the
>> >> concatenation of trees.
>> >
>> > Hmm, I'd think it would be useful to e.g. include a template and
>> > subsequently modify it within the same node, rather than a more verbose and
>> > error-prone process of referencing labels later.
>> >
>> > If sequential operations within a tree are supported, I'm not sure that
>> > there's any remaining need for separate top-level trees -- you could express
>> > the same thing as top-level property/node redefinitions.
>> >
>> > What are the problems with supporting this?
>>
>> The main problem is that it doesn't fit the use cases I need to solve.
>>  I need to start with a 'stock' or 'vanilla' tree, and then add into
>> it board details.  ie. lay down a generic MPC5200 tree (include a .dts
>> file), and then fill it in with i2c and spi devices.  Or include the
>> .dts file generated by the XIlinx FPGA toolchain, and then populate it
>> with board details.  Sequential operations within the tree doesn't do
>> anything to support this use case because the board level fixups will
>> be applied all over the tree.
>
> Aside: I always pictured this the other way round, where the DTS for an
> FPGA design includes the DTS for the board.  Then again, as long as they
> are independent, it probably doesn't matter.

Heh, interesting.  Yeah, I suppose it could be done that way too.  The
/include/ directive works pretty much anywhere in the input file, so a
file could either lay down a structure and then include a modifer, or
include a structure and then modify it.  I was thinking in terms of
the board file including the FPGA file because it matches the pattern
for say an SoC where there would be a common SoC .dts file and all the
boards using that SoC would include it.

Also, I was thinking that the SoC or FPGA structure needs to be layed
down first so that the board file has nodes in the tree to anchor new
nodes to.  For example, the FPGA's i2c controller needs to be in place
so that i2c devices can be grafted onto it.

>> > There may be cases where a dts fragment A doesn't know whether
>> > fragment B will have defined something, and fragment A wants to make sure it
>> > ends up undefined one way or another.
>>
>> Later fragments should always override earlier ones.  So if A is
>> defined before B, then B can override anything that A does.
>
> So the idiom to do this safely would be:
>
> foo {
>        bar {} // Ensure that bar exists.
> }
> foo {
>        delete(bar);
> }
>
> Seems baroque, but OK...

Just to make sure I understand you, what bit is striking you as
baroque?  The bit about the node needing to exist before it can be
deleted?

Scott does make a good point in one of his emails, especially within
the 'stack of overlays' model.  Maybe it should be perfectly fine to
mask a node or property, regardless of whether or not it exists in the
previous tree.  Maybe this should be just fine:
foo {
};
foo {
       mask-node(bar);
};


>> following the 'stack of overlays' model to its logical conclusion.  In
>> a sense, properties and nodes are getting masked out of the earlier
>> tree, not deleted.  It is more of an operation (mask) than a command
>> (delete) being applied.  delete-node() may give the misleading
>> impression that something is being executed at that point in the tree.
>
> Regardless of what the syntax is, if the *semantics* is overlay, then there
> doesn't seem to be any reason to disallow undeletion, and in fact, this semantics
> gives a way to implement it.  I'll defer whether this is *needed*: In the case
> of device trees it's not clear that it is.

The only reason is a practical one.  The way the node redefinitions
are currently processed makes this difficult.  dtc fully processes and
resolves a node definition before moving on to the next one.  The data
is already gone by the time any kind of undelete occurs (but a new
node which the same name can certainly be created).

With my current love affair of wanting to know the use-case before
committing to a feature, I'd like to know where undelete would be used
before doing the rework required to implement it.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.