In booting-without-of.txt, clarify that properties must precede subnodes

In booting-without-of.txt, clarify that properties must precede subnodes

[David Gibson]

A strict reading of the flattened device tree format defined in
booting-without-of.txt does in fact require that all the tags defining
properties for a node go before any definitions of subnodes, however
it's not particularly emphasised.  Although allowing intermingled
properties and subnodes would not be ambiguous in meaning, the kernel
parser does currently require that properties precede subnodes.
Furthermore, keeping this constraint makes life easier for various
device tree scanning tools.

Therefore, re-emphasise in booting-without-of.txt that this is a
strict requirement of the flattened device tree format.

Signed-off-by: David Gibson <david@gibson.dropbear.id.au>

Index: working-2.6/Documentation/powerpc/booting-without-of.txt
===================================================================
--- working-2.6.orig/Documentation/powerpc/booting-without-of.txt	2007-06-28 15:47:47.000000000 +1000
+++ working-2.6/Documentation/powerpc/booting-without-of.txt	2007-06-28 15:51:56.000000000 +1000
@@ -626,6 +626,14 @@
 a list of properties, a list of child nodes, and an end token. Every
 child node is a full node structure itself as defined above.
 
+NOTE: The above definition requires that all property definitions for
+a particular node MUST precede any subnode definitions for that node.
+Although the structure would not be ambiguous if properties and
+subnodes were intermingled, the kernel parser requires that the
+properties come first (up until at least 2.6.22).  Any tools
+manipulating a flattened tree must take care to preserve this
+constraint.
+
 4) Device tree "strings" block
 
 In order to save space, property names, which are generally redundant,

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

Re: In booting-without-of.txt, clarify that properties must precede subnodes

[Segher Boessenkool]

> A strict reading of the flattened device tree format defined in
> booting-without-of.txt does in fact require that all the tags defining
> properties for a node go before any definitions of subnodes, however
> it's not particularly emphasised.  Although allowing intermingled
> properties and subnodes would not be ambiguous in meaning, the kernel
> parser does currently require that properties precede subnodes.
> Furthermore, keeping this constraint makes life easier for various
> device tree scanning tools.
>
> Therefore, re-emphasise in booting-without-of.txt that this is a
> strict requirement of the flattened device tree format.

Do you want to require this for device tree source files,
too?  I think that's how the tools work right now but that's
not made explicit anywhere afaik.


Segher