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

[Grant Likely]

On Mon, Feb 22, 2010 at 2:59 PM, Grant Likely <grant.likely at secretlab.ca> wrote:
> On Mon, Feb 22, 2010 at 9:13 AM, Yoder Stuart-B08248
> <B08248 at freescale.com> wrote:
>>
>>> > That still leaves node and property deletion to cover.  In keeping
>>> > with the above approach, I'd like to do that in the form of
>>> "negative
>>> > redefinitions" of properties or nodes.  A neat syntax for
>>> that doesn't
>>> > immediately occur to be for that yet, though.
>>>
>>> hmmm.  I'll think more about it too.  I agree that a negative
>>> redefinition sounds like a reasonable approach.  I do want the ability
>>> to drop nodes easily.  It would make it easy to handle SoC or FPGA
>>> design variants.
>>
>> We had a similar problem in the Freescale Embedded Hypervisor
>> to control the generation of guest device trees.   We defined
>> several 'magic' properties that had special meaning in
>> the context of a node update.
>
> heh, so the functionality is definitely needed, but boy is that ugly!
> :-)  I really do think there needs to be a syntactically distinct
> method of deleting nodes and properties.  Magic property names that
> look like normal properties worry me.
>
> What about something like this:  Right now nodes are defined by <name>
> { [<property>|<node>]; ... }; and properties are defined by <name>; or
> <name> = <value>;  To differentiate a command from either a node or
> property definition, perhaps round braces could be used:
>
> so for the definition:
> a-node {
>        property-1;
>        property-2 = "blah";
>        child-1 {
>                ...
>        };
> };
>
> you could delete property-2 and node-1 with:
> a-node {
>        delete-node(child-1);
>        delete-property(property-2);
> };

Okay.  So the redefinition of nodes feature got implemented far faster
than I expected it would.  Woohoo!  :-)

That leaves the last bit that I really care about; deleting nodes and
properties.  I can probably find the time to implement the C code for
this, but have no idea how to do the grammer, and I don't think we've
got a consensus on syntax.

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.