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

[Grant Likely]

On Mon, Mar 1, 2010 at 7:10 PM, Grant Likely <grant.likely at secretlab.ca> wrote:
> On Mon, Mar 1, 2010 at 6:19 PM, David Gibson
> <david at gibson.dropbear.id.au> wrote:
>> On Mon, Mar 01, 2010 at 04:50:48PM -0600, Scott Wood 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?),
>>
>> m4 can do arithmetic, but it's pretty hideous.  But I still have
>> allowing expressions as a reasonable extension within dtc itself.
>> Macros or templates with parameters raise a lot more complex issues.
>>
>> [snip]
>>> >>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, node labels are attached to the node, so if the node is removed,
>> so is the label.
>>
>>> 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?
>>
>> References aren't resolved until the whole tree is built.  So
>> references will always resolve to the *last* definition of a label,
>> and if the last "definition" is an undefinition / deletion, then the
>> references will fail to resolve and give an error.
>
> ...except for when processing node redefinitions by label in the current patch.

In fact, I think this has to be the case, otherwise it would be
possible to create circular references in node redefiniton.

g.

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