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

[Scott Wood]

Grant Likely wrote:
> On Mon, Mar 1, 2010 at 2:06 PM, Scott Wood <scottwood at freescale.com> wrote:
>> 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.
> 
> To reverse the question, what is the use case that is best solved with
> sequential operations within the root tree?

The case I had in mind was having includable templates for fragments of the 
tree, rather than starting with a generic full tree.  Though I'd probably end up 
wanting things like template arguments and math as well (is any existing macro 
language going to do cell arithmetic?), so the focus on that kind of use case at 
this point should probably be limited to not defining syntax that's going to 
make things harder on future language extensions.  The only thing that 
immediately comes to mind from that perspective is that symbols are a more 
limited resource than keywords.

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

Is it the same way with node labels?  What happens to previous references?  Is 
it detected by dtc, or does a bad phandle/path stick around to be found at 
runtime?  And what if the node is added back?

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

Sorry for the confusing enumeration -- A comes after B.

To put it in more concrete terms, suppose you're writing an update wrapper 
around the autogenerated FPGA dts.  In some configurations a given node/property 
will be autogenerated, in others not -- but you want the wrapper to make sure 
it's gone, because it doesn't work with the system the FPGA is connected to.

If it's an error to delete something that doesn't exist, you'd have to have two 
update trees, first adding/replacing the thing in question to make sure it's 
there, and the second to delete it.

Allowing such an operation also lines up better with your suggestion to think of 
it as masking, rather than deleting.

-Scott