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

[David Gibson]

On Mon, Mar 01, 2010 at 04:33:29PM -0700, Grant Likely wrote:
> On Mon, Mar 1, 2010 at 3:15 PM, Mitch Bradley <wmb at firmworks.com> wrote:
[snip]
> Thanks for the clarification.  The flat tree does stay with the Open
> Firmware standard, however it does have the quirk that the name value
> in the flat tree includes the reg address.  This is mostly because
> when Linux on PowerPC reads the tree out of Open Firmware and creates
> the flat representation it stores the full path including the reg
> address.  The dts representation duplicates that behaviour.

Well, it's more that in the flat tree we treat the "node name" as a
separate entity to the node's name property, and containing the
equivalent of both the name property and unit address as they'd be
treated in real OF.  And having done that, we typically omit the name
property entirely, and just generate it on the fly from the node name
when we need to.

> I haven't entirely decided whether or not wildcard nodes are a good
> idea in the flat representation, but I am leaning in that direction.
> You already know about the discussion on how to handle Ethernet PHYs
> at an unknown address.  That may very well be the way we decide to
> handle it.

Well.. the difficulty with wildcard nodes in a flat tree is that we
have a number of cases where we already use nodes with no reg property
to represent things that aren't really wildcards.  The common use is
for things which are addressable only on a sideband bus which doesn't
form part of the normal reg address space hierarchy, such as DCR
devices on 4xx.

> However, the node name issue does raise a question about dtc.  Right
> now it doesn't do any checks in this regard, but an argument could be
> made that dtc should warn or fail if a dts file sets the @<reg>
> component in a way inconsistent with the first entry in the reg
> property.  Perhaps dtc should also automatically add @<reg> when the
> node name string omits it.  (again, this only applies to the flat
> representation).

I've been intending that for ages.  The complication is that the way
the reg property is formatted into the unit address string is
dependent on the parent bus.  There's no inherent barrier to
implementing this, and indeed the infrastructure in checks.c was
created with this in mind amongst other things, but it's just a
moderately large amount of coding because we need per-bus hooks to
supply unit address formatting functions.

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