[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 2:19 PM
> To: Scott Wood
> Cc: Stephen Neuendorffer; 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.
> 
> 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.

Aside: I always pictured this the other way round, where the DTS for an
FPGA design includes the DTS for the board.  Then again, as long as they
are independent, it probably doesn't matter.

 
> 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 the idiom to do this safely would be:

foo {
	bar {} // Ensure that bar exists.
}
foo {
	delete(bar);
}

Seems baroque, but OK...

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

Regardless of what the syntax is, if the *semantics* is overlay, then there
doesn't seem to be any reason to disallow undeletion, and in fact, this semantics
gives a way to implement it.  I'll defer whether this is *needed*: In the case
of device trees it's not clear that it is.

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.