[Skiboot] [PATCH 3/6] doc/device-tree: improve root node doc

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
 doc/device-tree.rst | 49 +++++++++++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 20 deletions(-)

diff --git a/doc/device-tree.rst b/doc/device-tree.rst
index fe527c65a226..e15394f4c51f 100644
--- a/doc/device-tree.rst
+++ b/doc/device-tree.rst
@@ -51,31 +51,40 @@ of that property)
 Root Node
 ---------
 
-Root node of device tree
+Root node of device tree. There are a few required and a few optional properties
+that sit in the root node. They're described here.
+
+compatible
+^^^^^^^^^^
+
+The "compatible" properties are string lists indicating the overall
+compatibility from the more specific to the least specific.
+
+The root node compatible property *must* contain "ibm,powernv" for
+Linux to have the powernv platform match the machine.
+
+Each distinct platform *MUST* also add a more precise property (first
+in order) indicating the board type.
+
+The standard naming is "vendor,name". For example: `compatible = "goog,rhesus","ibm,powernv";`
+would work. Or even better: `compatible = "goog,rhesus-v1","goog,rhesus","ibm,powernv";`.
+
+The bare `ibm,powernv` should be reserved for bringup/testing:
+
+.. code-block:: dts
+
+ /dts-v1/;
+ / {
+	compatible = "ibm,powernv";
+   };
+
+Example
+^^^^^^^
 
 .. code-block:: dts
 
  /dts-v1/;
  / {
-  	/*
-	 * "compatible" properties are string lists (ASCII strings separated by
-	 * \0 characters) indicating the overall compatibility from the more
-	 * specific to the least specific.
-	 *
-	 * The root node compatible property *must* contain "ibm,powernv" for
-	 * Linux to have the powernv platform match the machine. It is recommended
-	 * to add a slightly more precise property (first in order) indicating more
-	 * precisely the board type. We don't currently do that in HDAT based
-	 * setups but will.
-	 *
-	 * The standard naming is "vendor,name" so in your case, something like
-	 *
-	 * compatible = "goog,rhesus","ibm,powernv";
-	 *
-	 * would work. Or even better:
-         *
-	 * compatible = "goog,rhesus-v1","goog,rhesus","ibm,powernv";
-	 */
 	compatible = "ibm,powernv";
 
 	/* mandatory */
-- 
2.9.4