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

[Stephen Neuendorffer]

> -----Original Message-----
> From: glikely at secretlab.ca [mailto:glikely at secretlab.ca] On Behalf Of Grant Likely
> Sent: Monday, March 01, 2010 1:49 PM
> To: Stephen Neuendorffer
> Cc: 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.
> 
> 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.

Ah, OK.
 
> 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).

Ah, right, they have separate namespaces.  When I implemented this
in the past, properties and hierarchy shared a single namespace.

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

Um, my original intent was:
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.

I think this makes alot of sense. 

> > 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, is it true that a tree which is overlayed on another tree can be independently verified to
be independent of internal ordering?  This would be nice if so.

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

I'm not necessarily wild about these syntax options either, BTW...

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

But the best thing of the above is that there is no longer a distinction between commands and data!
delete is just a tag which gets interpreted during 'reduction' or 'overlay'.

For instance, deleting a subnode could be:

foo {
	bar {
		delete;
	}
}

I guess this ends up conflicting with a property named 'delete' though.

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.