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

[Mitch Bradley]

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