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

[Grant Likely]

On Mon, Mar 1, 2010 at 3:50 PM, Scott Wood <scottwood at freescale.com> wrote:
> 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.

Right.  I thought about that too, and came to the conclusion that
while it might be nice to have templates and the like, it isn't as big
a deal as handling all the crazy board files duplicating the SoC bits
and subtly changing bits all through the tree.  At least after the SoC
.dts is written, even if it has a lot of similar nodes, it doesn't
really need to have bits added or removed from it on a regular basis.
And on the FPGA, we've got a real programming language (well, TCL) to
do complex tree generation with.

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

yes

>  What happens to previous references?

They are either already resolved (in the case of node redefines at the
top level), or they will fail.

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

All phandles are resolved after the tree is fully parsed.  This could
probably use more thought/discussion to think about the implications.

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

This is a good argument.  Let me think about it for a bit, but I think
you're probably right.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.