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

[Grant Likely]

Hi Stephen, good comments...

On Mon, Mar 1, 2010 at 1:30 PM, Stephen Neuendorffer
<stephen.neuendorffer at xilinx.com> wrote:
>> Given the following tree...
>>
>> / {
>>         child-label: child {
>>                 prop = <0xbad>;
>>                 grandchild-label: grandchild {
>>                 };
>>         };
>> };
>>
>> ...here are the use cases that I see as important (plus some suggested
>> syntax.  I'm not happy with it though, and I'm open to better ideas).
>>
>> 1) Deleting a property from a node:
>> &child-label {
>>         /* syntax to delete "prop" property */
>>         delete-prop("prop");
>>         ^prop;  /* this isn't very good, hard to differentiate from
>> node deletion */
>>         __delete_property = "prop";
>> };
>>
>> 2) Delete a child node:
>> &child-label {
>>         /* syntax to delete "grandchild" node */
>>         delete-node("grandchild");
>>         ^grandchild;
>>         __delete_node = "grandchild";
>>         grandchild = ^{};
>> };
>>
>> 3) Delete a labelled node from the top level:
>> delete-node(&grandchild-label);
>>
>> Comments?  Suggestions?  Better ideas?  Please?  Don't inflict pain on
>> yourself by letting me decide the syntax.
>>
>> g.
>
> 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.

Yes, multiple sibling nodes with the same name are not allowed by dtc.
 I believe multiple siblings of the same name is legal with
OpenFirmware, but that is at least partially because in OpenFirmware
the @<addr> portion isn't necessarily part of the name.  (Imagine
having triplets and naming them Sally at 1, Sally at 2 and Sally at 3!)

However, the same name can be used by non-siblings.  For example, the
following is totally legal:

/ {
    foo {
        foo {
        };
    };
};

> 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.

Yes, you are exactly correct.  The model is to fully form 2 trees, and
then overlay the latter on the former.

> Similarly:
>
> foo {
>        bar-label: bar = 2;
> }
> &bar-label = 3;

This actually isn't legal, but for an entirely different reason.  Even
though labels can be applied to properties, property labels aren't
actually used for anything unless asm output is selected.  All tree
modification as of now is done from the context of nodes.
Redefinition can start from the root node, or it can start from a
labelled node, but there is no syntax defined for modifying a labelled
property.

It is possible to add redefinition of labelled properties, but I'd
like to see a use case first, and why it is better than the current
form (similar to the arguments I put forth for node redefinition by
label).

So, if I rework your example to use nodes...

foo {
        bar-label: bar {
                prop = 2;
        };
};
&bar-label {
        prop = 3;
};

So, yes, prop in the second tree overrides the prop in the first tree
because it is the same property name in the 'bar' node.

> delete has the similar problem.
>
> foo {
>        bar = 2;
>        delete(bar); // Should be illegal
> }
>
> foo {
>        bar-label: bar = 2;
> }
> delete(&bar-label);  // Legal.
> foo {
>        bar-label: bar = 4;  // Legal, even though previously deleted
> }

reworked to use nodes:
foo {
        bar-label: bar {
                prop = 2;
                delete(bar); // should be illegal
        };
};
foo {
        bar-label: bar {  /* legal, adds label to node */
                prop = 3;  /* legal, changes prop */
        };
};
delete-node(&bar-label};  // legal
foo {
        bar-label: bar {  /* Legal, even though previously deleted */
                prop = 4;
        };
};

> So, regardless of the syntax, I think it's important to ensure the above checks and sequentiality.
> There's also a canonicalization question, because you can spit out the original source, or the 'reduction'
> which results in all the overrides and deletions.   I think from looking at Grant's patch, this is already
> the way things work, but I don't think anyone had really explicitly stated that.

Hmmm, perhaps nobody has.  Yes, each node redefinition is fully
processed before going on to the next one.  Think: a stack of
transparencies where each new sheet masks/changed/adds to the one
below it.

> One trick is that the below is problematic, or at least hard to verify statically.
>
> foo {
>        delete(&bar-label); // Legal.

This is never legal.  If deleting by label, it must be at the top
level.  It doesn't make sense to use a label reference inside a node
block, since the node block is already supposed to define where you
are working in the tree.

>        delete(bar); // May or may not be Illegal, since don't know what bar-label references

No longer an issue since the previous line is illegal.

Also, must be either delete-node() or delete-prop() since nodes and
properties can use the same names.

> }
>
> 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 !;

That's an interesting point.  Perhaps it would be better to use a
syntax that enforces the concept of overlays, and talk about masking
out instead of deleting nodes and properties from the earlier tree.

I kind of like the ^ syntax, but there would have to be syntax
variations for both node and property masking.  I'm not sure it's a
good idea to dedicate otherwise valid node name characters to the
purpose of masking.

>
> Which brings up the question 'undeletion question'.  Can you do:
>
> d-label: delete(bar);
> delete(&d-label);

Not sure I follow.  It certainly isn't be valid to apply a label to a
command like delete().

g.

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