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

[Grant Likely]

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.

To reverse the question, what is the use case that is best solved with
sequential operations within the root tree?

>> foo {
>>        bar-label: bar = 2;
>> }
>> delete(&bar-label);  // Legal.
>> foo {
>>        bar-label: bar = 4;  // Legal, even though previously deleted
>> }
>
> Is it legal to reuse the label, even though it sort of points to the same
> spot?

In the overlay model that is currently being approached.  Yes.

> If you don't reuse the label, but bar is redefined, where does bar-label
> point?

It doesn't point to anything because when a property is deleted, the
label also goes away.

> Do all labels to nodes in separate trees that end up referring to the same
> node in the final tree have the same phandle?  Are they interchangeable in
> subsequent delete commands?

Yes.

>> One trick is that the below is problematic, or at least hard to verify
>> statically.
>>
>> foo {
>>        delete(&bar-label); // Legal.
>>        delete(bar); // May or may not be Illegal, since don't know what
>> bar-label references
>> }
>
> That raises the question of whether it's legal to delete things that aren't
> there.

It isn't currently, which seems sane to me.

> 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, to syntax: the sequentialization property may be more syntactically
>> obvious if deletion resembles
>> setting a property or node like:
>>
>>  ^bar
>>  !bar
>> or even
>>  bar = !;
>>  bar !;
>
> What specifically is made more obvious?  Using symbols rather than names
> seems more cryptic to me.
>
> Only the "bar = !" form seems to clearly indicate that, for the purposes of
> this particular tree, you're assigning some special placeholder to bar
> rather than performing an immediate action.  That could just as well be done
> with something like "bar = /delete-prop/".
>
> I'd rather make them actually behave like immediate commands, though.
>
>> Which brings up the question 'undeletion question'.  Can you do:
>>
>> d-label: delete(bar);
>> delete(&d-label);
>
> I'd say no -- delete operates on data, not commands.

Yes, I agree.  However, the command() syntax may be a bad idea if
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.

g.

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