Request review of device tree documentation

[Benjamin Herrenschmidt]

On Fri, 2010-06-11 at 16:47 -0700, Dan Malek wrote:
> Hi Grant.
> 
> On Jun 11, 2010, at 3:59 PM, Grant Likely wrote:
> 
> > I've been doing a bit of work on some introductory level documentation
> > of the flattened device tree.
> 
> Wow, I feel empowered to create device trees now :-)
> Seriously, I never understood this well and this is a
> great document.
> 
> I have one source of confusion.  Your first Initial structure
> example uses 'compatible' to describe the machine, the
> paragraph below then mentions the 'model' property,
> and all subsequent examples use model.
> 
> Does this mean if I use just the single line in the dts,
> using 'compatible' implies the ARM machine ID?  If I
> have more description I use 'model'?

Normally, "compatible" is what is used for code to match,
and model is more like a user-visible thingy.

It's possible to peek at 'model' tho, in some cases, I've seen the case
for example where things are -supposed- to be identical from an arch
point of view, have the same compatible, but later on, a quirk is found
and a test against model is used to differentiate. But that's something
to avoid in general. Better off having multiple strings in "compatible"
then, one more "generic" to have the BSP match against, and one more
"specific" that can be used if a quirk is needed.

Of course, it doesn't help that all pseries have "chrp" and nothing else
as compatible :-) But then, both IBM and Apple have been quite lax with
their (ab)use of the DT.

Cheers,
Ben.