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

[David Gibson]

On Mon, Feb 22, 2010 at 02:59:25PM -0700, Grant Likely 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.

Ah, yeah.  However, as Stuart said, the magic properties need to be
interpreted at runtime, so in that case it kind of makes sense.  What
we're discussing here, does have the interesting possibility that we
could extend it so that with the right flag set from command line
option and/or a special directive in the .dts we could have a mode
where instead of immediately processing node and property
redefinitions in our new syntax, we instead build them into magic
properties in the FEH format.  Doubtless there would be some
complications, but it's something to think about later, maybe.

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

Hrm.  I don't particularly like it, but I guess it's an option.

> > We also had the need to prepend to a <stringlist> so that
> > compatible properties could be updated.
> >
> >   prepend-stringlist  <stringlist> The value is a string list that
> >                                    specifies on or more property name/value
> >                                    pairs.
> 
> This is a bit of a harder problem.  I've go no ideas on how to handle
> this in a syntactically elegant way.

Actually, that I think we can handle relatively neatly.  We define a
special symbol which can be used in property definitions and expands
to the property's previous value.  So you could do:
	compatible = "newthing", /prev/;
(I don't particularly like '/prev/' as the symbol, but you get the
basic idea).


Actually, here's one thought.  At present, a reference to a node label
expands to the node's full path.  I don't think it's too far out of
keeping with that for a reference to a property label to expand to the
property's value.  Then we could have a special form of that which
means reference to this property's previous value, instead of
explicitly giving a property label.  Still not sure what to make the
actual symbols.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson