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

[David Gibson]

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.

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