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

[Stephen Neuendorffer]

> -----Original Message-----
> From: devicetree-discuss-bounces+stephen.neuendorffer=xilinx.com at lists.ozlabs.org [mailto:devicetree-
> discuss-bounces+stephen.neuendorffer=xilinx.com at lists.ozlabs.org] On Behalf Of Grant Likely
> Sent: Monday, March 01, 2010 11:16 AM
> To: Yoder Stuart-B08248
> Cc: 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, 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.

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.

Similarly:

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

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
}

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.

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
}

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

Which brings up the question 'undeletion question'.  Can you do:

d-label: delete(bar);
delete(&d-label);

Steve




This email and any attachments are intended for the sole use of the named recipient(s) and contain(s) confidential information that may be proprietary, privileged or copyrighted under applicable law. If you are not the intended recipient, do not read, copy, or forward this email message or any attachments. Delete this email message and any attachments immediately.