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

[Scott Wood]

Grant Likely wrote:
> On Mon, Feb 22, 2010 at 9:13 AM, Yoder Stuart-B08248
>> 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!
> :-)

And we haven't even mentioned node-update-phandle yet. :-)

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

The problem in our case is that the updates have to be done at runtime 
(modifications contained in a config tree are applied to a hardware 
devtree node (or hv-generated node) to produce a guest devtree node), so 
to use something that doesn't look like a normal property would require 
dtb format changes.

The whole node-update subtree in such a case could be considered magic.

The problem domain of this thread has no such requirement, of course.

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

As long as we're talking about dts-level static manipulation (i.e. not 
magic properties), we're not limited to one instance of each command 
name, so we could just do:

prepend-stringlist("compatible", "foo,bar");
prepend-stringlist("compatible", "foo,bar-X.Y");
prepend-stringlist("something-else", "aoeuhtns");

We need the quotes around node/property names since comma is a legal 
character in them.

-Scott