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

[Grant Likely]

On Mon, Mar 1, 2010 at 3:15 PM, Mitch Bradley <wmb at firmworks.com> wrote:
>>
>> Yes, multiple sibling nodes with the same name are not allowed by dtc.
>>  I believe multiple siblings of the same name is legal with
>> OpenFirmware, but that is at least partially because in OpenFirmware
>> the @<addr> portion isn't necessarily part of the name.  (Imagine
>> having triplets and naming them Sally at 1, Sally at 2 and Sally at 3!)
>>
>>
>
> I'm not sure how to parse the above because the word "name" seems to be used
> somewhat informally.
>
> The Open Firmware situation is this:
>
> a) At a given level of the tree, there can be any number of nodes with the
> same value for the "name" property.  For example, you could plug in several
> PCI Ethernet adapters and each would have "ethernet" as the value of the
> "name" property.  In general, the "name" property is not intended as a
> unique identifier, but rather as a mnemonic for human convenience.  The
> unique identifier is the first component of the "reg" property (within the
> context of the parent node).  The whole schema for reg properties is driven
> by this uniqueness requirement, along with the observation that the computer
> hardware must have some physical means of addressing specific devices.  The
> "reg" properties mimic physical addresses on various bus domains.
>
> b) A fully-qualified device specifier component includes both the name
> property value and the reg property value (AKA the unit address), for
> example "ethernet at 5".
>
> c) It is possible to have a "wildcard" device node that contains an Open
> Firmware driver for a given device, but its bus has not been fully probed so
> you don't yet know the addresses (reg properties) for the actual devices.
>  In that case, you can have a "name" property but no "reg" property.  You
> can have a wildcard node "disk" and some explicit nodes "disk at 1", "disk at 2"
> as siblings.  When searching the device tree, nodes with reg properties take
> precedence over wildcard nodes, so the wildcard node is a "fallback" to use
> if you can't find an explicit "name at reg" match.  In principle, you could
> have several wildcard nodes with the same name at the same level of the
> tree, but if so, the search would find only the most recently defined one,
> so for all practical purposes it is as if only one exists.
>
> Wildcard nodes are useful for Open Firmware driver binding, and could
> potentially be used for OS driver binding for either hot-plugged or
> late-probed devices.  Whether or not they fit well into the dtc scheme, I
> can't say.

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.

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.

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

Cheers,
g.

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