doc: device-tree snippets should be dts code-blocks

This gets us syntax highlighting of device tree snippets.

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

12 files changed, 165 insertions, 114 deletions

diff --git a/doc/device-tree/ibm,opal.rst b/doc/device-tree/ibm,opal.rst
index 03f540c..c951603 100644
--- a/doc/device-tree/ibm,opal.rst
+++ b/doc/device-tree/ibm,opal.rst
@@ -8,31 +8,33 @@ ibm,opal
    ibm,opal/*
 
 
-::
+.. code-block:: dts
 
    ibm,opal {
 		#address-cells = <0x0>;
 		#size-cells = <0x0>;
 		compatible = "ibm,opal-v2", "ibm,opal-v3";
 
-   ; v2 is maintained for possible compatibility with very, very old kernels
-   ; it will go away at some point in the future. Detect and rely on ibm,opal-v3
-   ; ibm,opal-v2 is *NOT* present on POWER9 and above.
+   /* v2 is maintained for possible compatibility with very, very old kernels
+    * it will go away at some point in the future. Detect and rely on ibm,opal-v3
+    * ibm,opal-v2 is *NOT* present on POWER9 and above.
+    */
 
 		ibm,associativity-reference-points = <0x4 0x3>;
 		ibm,heartbeat-ms = <0x7d0>;
 
-   ; how often any OPAL call needs to be made to avoid a watchdog timer on BMC
-   ; from kicking in
+   /* how often any OPAL call needs to be made to avoid a watchdog timer on BMC
+    * from kicking in
+    */
 
 		ibm,opal-memcons = <0x0 0x3007a000>;
 
-   ; location of in memory OPAL console buffer.
+   /* location of in memory OPAL console buffer. */
 
 		ibm,opal-trace-mask = <0x0 0x3008c3f0>;
 		ibm,opal-traces = <0x0 0x3007b010 0x0 0x10077 0x0 0x3b001010 0x0 0x1000a7 0x0 0x3b103010 0x0 0x1000a7 0x0 0x3b205010 0x0 0x1000a7 0x0 0x3b307010 0x0 0x1000a7 0x0 0x3b409010 0x0 0x1000a7 0x10 0x1801010 0x0 0x1000a7 0x10 0x1903010 0x0 0x1000a7 0x10 0x1a05010 0x0 0x1000a7 0x10 0x1b07010 0x0 0x1000a7 0x10 0x1c09010 0x0 0x1000a7 0x10 0x1d0b010 0x0 0x1000a7 0x10 0x1e0d010 0x0 0x1000a7 0x10 0x1f0f010 0x0 0x1000a7 0x10 0x2011010 0x0 0x1000a7 0x10 0x2113010 0x0 0x1000a7 0x10 0x2215010 0x0 0x1000a7 0x10 0x2317010 0x0 0x1000a7 0x10 0x2419010 0x0 0x1000a7 0x10 0x251b010 0x0 0x1000a7 0x10 0x261d010 0x0 0x1000a7>;
 
-   ; see docs on tracing
+   /* see docs on tracing */
 
 		linux,phandle = <0x10000003>;
 		opal-base-address = <0x0 0x30000000>;
diff --git a/doc/device-tree/ibm,opal/diagnostics.rst b/doc/device-tree/ibm,opal/diagnostics.rst
index 0314706..001ce25 100644
--- a/doc/device-tree/ibm,opal/diagnostics.rst
+++ b/doc/device-tree/ibm,opal/diagnostics.rst
@@ -4,6 +4,15 @@ ibm,opal/diagnostics device tree entries
 The diagnostics node under ibm,opal describes a userspace-to-firmware
 interface, supporting the runtime processor recovery diagnostics functions.
 
-The properties of a prd node are: ::
+The properties of a prd node are:
+
+.. code-block:: dts
+
+   / {
+      ibm,opal {
+        diagnostics {
+          compatible = "ibm,opal-prd";
+      };
+     };
+   };
 
- compatible = "ibm,opal-prd"
diff --git a/doc/device-tree/ibm,opal/firmware.rst b/doc/device-tree/ibm,opal/firmware.rst
index c936fce..ae84100 100644
--- a/doc/device-tree/ibm,opal/firmware.rst
+++ b/doc/device-tree/ibm,opal/firmware.rst
@@ -1,7 +1,9 @@
 System Firmware
 ===============
 
-The 'firmware' node under 'ibm,opal' lists system and OPAL firmware version. ::
+The 'firmware' node under 'ibm,opal' lists system and OPAL firmware version.
+
+.. code-block:: dts
 
   firmware {
 	symbol-map = <0x0 0x300ac650 0x0 0x1b3f5>;
diff --git a/doc/device-tree/ibm,opal/flash.rst b/doc/device-tree/ibm,opal/flash.rst
index 5bce76b..85e008c 100644
--- a/doc/device-tree/ibm,opal/flash.rst
+++ b/doc/device-tree/ibm,opal/flash.rst
@@ -33,3 +33,16 @@ flash partitions; the reg parameter contains the offset and size of the
 partition.
 
 
+Example:
+
+.. code-block:: dts
+
+ flash@0 {
+   reg = <0x0 0x4000000>;
+   compatible = "ibm,opal-flash";
+   ibm,opal-id = <0x0>;
+   ibm,flash-block-size = <0x1000>;
+   #address-cells = <0x1>;
+   phandle = <0x100002bf>;
+   #size-cells = <0x1>;
+ };
diff --git a/doc/device-tree/ibm,opal/led.rst b/doc/device-tree/ibm,opal/led.rst
index e7d80b7..7e062fe 100644
--- a/doc/device-tree/ibm,opal/led.rst
+++ b/doc/device-tree/ibm,opal/led.rst
@@ -4,7 +4,9 @@ Service Indicators (LEDS)
 =========================
 
 The 'leds' node under 'ibm,opal' lists service indicators available in the
-system and their capabilities. ::
+system and their capabilities.
+
+.. code-block:: dts
 
   leds {
 	compatible = "ibm,opal-v3-led";
@@ -17,8 +19,7 @@ system and their capabilities. ::
 		phandle = <0x1000006f>;
 		linux,phandle = <0x1000006f>;
 	};
-	...
-	...
+	/* Other LED nodes like the above one */
   };
 
 compatible
diff --git a/doc/device-tree/ibm,opal/oppanel.rst b/doc/device-tree/ibm,opal/oppanel.rst
index 76b6c6c..fd02e9b 100644
--- a/doc/device-tree/ibm,opal/oppanel.rst
+++ b/doc/device-tree/ibm,opal/oppanel.rst
@@ -1,6 +1,7 @@
 Operator Panel (oppanel)
 ========================
-::
+
+.. code-block:: dts
 
   oppanel {
         compatible = "ibm,opal-oppanel";
diff --git a/doc/device-tree/ibm,opal/power-mgt.rst b/doc/device-tree/ibm,opal/power-mgt.rst
index 5bc1fb4..275f92b 100644
--- a/doc/device-tree/ibm,opal/power-mgt.rst
+++ b/doc/device-tree/ibm,opal/power-mgt.rst
@@ -3,9 +3,15 @@ ibm,opal/power-mgt device tree entries
 
 All available CPU idle states are listed in ibm,cpu-idle-state-names
 
-For example: ::
+For example:
 
-  ibm,cpu-idle-state-names = "nap", "fastsleep_", "winkle";
+.. code-block:: dts
+
+  power-mgt {
+    ibm,cpu-idle-state-names = "nap", "fastsleep_", "winkle";
+    ibm,cpu-idle-state-residency-ns = <0x1 0x2 0x3>;
+    ibm,cpu-idle-state-latencies-ns = <0x1 0x2 0x3>;
+  };
 
 The idle states are characterized by latency and residency
 numbers which determine the breakeven point for entry into them. The
@@ -21,10 +27,33 @@ the measured latency numbers for the idle states. The residency numbers have
 been arrived at experimentally after ensuring that the performance of latency
 sensitive workloads do not regress while allowing deeper idle states to be
 entered into during low load situations. The kernel is expected to use these
-values for optimal power efficiency. ::
+values for optimal power efficiency.
+
+Example:
+
+.. code-block:: dts
+
+   / {
+     ibm,opal {
+       power-mgt {
+		ibm,pstate-frequencies-mhz = <0xda3 0xd82 0xd60 0xd3f 0xd1e 0xcfd 0xcdb 0xcba 0xc99 0xc78 0xc56 0xc35 0xc14 0xbf3 0xbd1 0xbb0 0xb8f 0xb6e 0xb4c 0xb2b 0xb0a 0xae9 0xac7 0xaa6 0xa85 0xa64 0xa42 0xa21 0xa00 0x9df 0x9bd 0x99c 0x97b 0x95a 0x938 0x917 0x8f6 0x8d5 0x8b3 0x892 0x871 0x850 0x82e 0x80d>;
+                ibm,cpu-idle-state-latencies-ns = <0xfa0 0x9c40 0x989680>;
+                ibm,cpu-idle-state-flags = <0x11000 0x81003 0x47003>;
+                ibm,cpu-idle-state-names = "nap", "fastsleep_", "winkle";
+                ibm,cpu-idle-state-pmicr = <0x0 0x0 0x20 0x0 0x0 0x0>;
+                ibm,pstate-vdds = <0x5758595a 0x5a5b5c5d 0x5e5e5f60 0x61626263 0x64656566 0x66676768 0x6869696a 0x6a6b6b6c 0x6c6d6d6e 0x6e6f6f70 0x70717272>;
+                ibm,pstate-vcss = <0x4d4e4f4f 0x50505152 0x52535354 0x55555657 0x57585859 0x59595a5a 0x5a5b5b5c 0x5c5c5d5d 0x5d5e5e5f 0x5f5f6060 0x60616162>;
+                ibm,pstate-nominal = <0xffffffef>;
+                ibm,cpu-idle-state-residency-ns = <0x186a0 0x11e1a300 0x3b9aca00>;
+                ibm,cpu-idle-state-pmicr-mask = <0x0 0x0 0x30 0x0 0x0 0x0>;
+                phandle = <0x100002a0>;
+                ibm,pstate-ids = <0x0 0xffffffff 0xfffffffe 0xfffffffd 0xfffffffc 0xfffffffb 0xfffffffa 0xfffffff9 0xfffffff8 0xfffffff7 0xfffffff6 0xfffffff5 0xfffffff4 0xfffffff3 0xfffffff2 0xfffffff1 0xfffffff0 0xffffffef 0xffffffee 0xffffffed 0xffffffec 0xffffffeb 0xffffffea 0xffffffe9 0xffffffe8 0xffffffe7 0xffffffe6 0xffffffe5 0xffffffe4 0xffffffe3 0xffffffe2 0xffffffe1 0xffffffe0 0xffffffdf 0xffffffde 0xffffffdd 0xffffffdc 0xffffffdb 0xffffffda 0xffffffd9 0xffffffd8 0xffffffd7 0xffffffd6 0xffffffd5>;
+                ibm,pstate-max = <0x0>;
+                ibm,pstate-min = <0xffffffd5>;
+       };
+     };
+   };
 
-  ibm,cpu-idle-state-residency-ns = <0x1 0x2 0x3>
-  ibm,cpu-idle-state-latencies-ns = <0x1 0x2 0x3>
 
 
 ibm,cpu-idle-state-pmicr ibm,cpu-idle-state-pmicr-mask
diff --git a/doc/device-tree/ibm,opal/sensors.rst b/doc/device-tree/ibm,opal/sensors.rst
index f92c298..cd30ffc 100644
--- a/doc/device-tree/ibm,opal/sensors.rst
+++ b/doc/device-tree/ibm,opal/sensors.rst
@@ -35,9 +35,12 @@ Each node has a minimum set of properties describing the sensor :
 - an optional "label" property
 
 Each node can have some extra properties depending on the resource
-they represent. See the tree below for more information. ::
+they represent. See the tree below for more information.
 
-  ibm,opal/sensors/ {
+.. code-block:: dts
+
+  ibm,opal {
+    sensors {
 
 	/*
 	 * Core temperatures (DTS) nodes.
@@ -88,5 +91,5 @@ they represent. See the tree below for more information. ::
 		ibm,chip-id = <0x80000001>;
 		label = "Centaur";
 	};
-
+    };
   };
diff --git a/doc/device-tree/ibm,secureboot.rst b/doc/device-tree/ibm,secureboot.rst
index 915ee13..948c7e0 100644
--- a/doc/device-tree/ibm,secureboot.rst
+++ b/doc/device-tree/ibm,secureboot.rst
@@ -24,7 +24,7 @@ For further information about secure boot and trusted boot please refer to
 Required properties
 -------------------
 
-::  
+.. code-block:: none
 
     compatible:         ibm,secureboot version. It is related to the ROM code version.
                 
@@ -44,7 +44,7 @@ Example
 For the first version ``ibm,secureboot-v1``, the ROM code expects the *hw-key-hash*
 to be a SHA512 hash.
 
-::
+.. code-block:: dts
 
     ibm,secureboot {
         compatible = "ibm,secureboot-v1";
diff --git a/doc/device-tree/nvlink.rst b/doc/device-tree/nvlink.rst
index a0aed4f..8375dc4 100644
--- a/doc/device-tree/nvlink.rst
+++ b/doc/device-tree/nvlink.rst
@@ -6,84 +6,73 @@ Nvlink Device Tree Bindings
 
 See :ref:`nvlink` for general Nvlink information.
 
-NPU bindings: ::
+NPU bindings:
+
+.. code-block:: dts
 
   xscom@3fc0000000000 {
-        npu@8013c00 {
-			reg = <0x8013c00 0x2c>;
-                        compatible = "ibm,power8-npu";
-                        ibm,npu-index = <0x0>;
-                        ibm,npu-links = <0x4>;
-
-  ; Number of links wired up to this npu.
-
-                        phandle = <0x100002bc>;
-                        linux,phandle = <0x100002bc>;
-
-                        link@0 {
-                                ibm,npu-pbcq = <0x1000000b>;
-
-  ; phandle to the pbcq which connects to the GPU.
-
-				ibm,npu-phy = <0x80000000 0x8010c3f>;
-
-  ; SCOM address of the IBM PHY controlling this link.
-
-				compatible = "ibm,npu-link";
-                                ibm,npu-lane-mask = <0xff>;
-
-  ; Mask specifying which IBM PHY lanes are used for this link.
-
-				phandle = <0x100002bd>;
-                                ibm,npu-link-index = <0x0>;
-
-  ; Hardware link index. Naples systems contain links at index 0,1,4 & 5.
-  ; Used to calculate various address offsets.
-
-				linux,phandle = <0x100002bd>;
-                        };
-
-                        link@1 {
-                                ibm,npu-pbcq = <0x1000000b>;
-                                ibm,npu-phy = <0x80000000 0x8010c3f>;
-                                compatible = "ibm,npu-link";
-                                ibm,npu-lane-mask = <0xff00>;
-                                phandle = <0x100002be>;
-                                ibm,npu-link-index = <0x1>;
-                                linux,phandle = <0x100002be>;
-                        };
-
-                        link@4 {
-                                ibm,npu-pbcq = <0x1000000a>;
-                                ibm,npu-phy = <0x80000000 0x8010c7f>;
-                                compatible = "ibm,npu-link";
-                                ibm,npu-lane-mask = <0xff00>;
-                                phandle = <0x100002bf>;
-                                ibm,npu-link-index = <0x4>;
-                                linux,phandle = <0x100002bf>;
-			};
-
-			link@5 {
-                                ibm,npu-pbcq = <0x1000000a>;
-                                ibm,npu-phy = <0x80000000 0x8010c7f>;
-                                compatible = "ibm,npu-link";
-                                ibm,npu-lane-mask = <0xff>;
-                                phandle = <0x100002c0>;
-                                ibm,npu-link-index = <0x5>;
-                                linux,phandle = <0x100002c0>;
-                        };
-	};
+    npu@8013c00 {
+      reg = <0x8013c00 0x2c>;
+      compatible = "ibm,power8-npu";
+      ibm,npu-index = <0x0>;
+      ibm,npu-links = <0x4>; /* Number of links wired up to this npu. */
+
+      phandle = <0x100002bc>;
+      linux,phandle = <0x100002bc>;
+
+      link@0 {
+        ibm,npu-pbcq = <0x1000000b>; /* phandle to the pbcq which connects to the GPU. */
+	ibm,npu-phy = <0x80000000 0x8010c3f>; /* SCOM address of the IBM PHY controlling this link. */
+	compatible = "ibm,npu-link";
+        ibm,npu-lane-mask = <0xff>; /* Mask specifying which IBM PHY lanes are used for this link. */
+
+	phandle = <0x100002bd>;
+        ibm,npu-link-index = <0x0>; /* Hardware link index. Naples systems
+		                     * contain links at index 0,1,4 & 5.
+                                     * Used to calculate various address offsets. */
+
+	linux,phandle = <0x100002bd>;
+      };
+
+      link@1 {
+        ibm,npu-pbcq = <0x1000000b>;
+        ibm,npu-phy = <0x80000000 0x8010c3f>;
+        compatible = "ibm,npu-link";
+        ibm,npu-lane-mask = <0xff00>;
+        phandle = <0x100002be>;
+        ibm,npu-link-index = <0x1>;
+        linux,phandle = <0x100002be>;
+      };
+
+      link@4 {
+        ibm,npu-pbcq = <0x1000000a>;
+        ibm,npu-phy = <0x80000000 0x8010c7f>;
+        compatible = "ibm,npu-link";
+        ibm,npu-lane-mask = <0xff00>;
+        phandle = <0x100002bf>;
+	ibm,npu-link-index = <0x4>;
+        linux,phandle = <0x100002bf>;
+      };
+
+      link@5 {
+        ibm,npu-pbcq = <0x1000000a>;
+        ibm,npu-phy = <0x80000000 0x8010c7f>;
+        compatible = "ibm,npu-link";
+        ibm,npu-lane-mask = <0xff>;
+        phandle = <0x100002c0>;
+        ibm,npu-link-index = <0x5>;
+        linux,phandle = <0x100002c0>;
+      };
+    };
   };
 
 Emulated PCI device bindings
 ----------------------------
-::
-
-       pciex@3fff000400000 {
-                ibm,npcq = <0x100002bc>;
 
-       ; phandle to the NPU node. Used to find associated PCI GPU devices.
+.. code-block:: dts
 
+       pciex@3fff000400000 {
+                ibm,npcq = <0x100002bc>; /* phandle to the NPU node. Used to find associated PCI GPU devices. */
                 compatible = "ibm,power8-npu-pciex", "ibm,ioda2-npu-phb";
 
 		pci@0 {
@@ -93,10 +82,7 @@ Emulated PCI device bindings
                         device-id = <0x4ea>;
                         ibm,pci-config-space-type = <0x1>;
                         vendor-id = <0x1014>;
-                        ibm,gpu = <0x100002f7>;
-
-       ; phandle pointing the associated GPU PCI device node
-
+                        ibm,gpu = <0x100002f7>; /* phandle pointing the associated GPU PCI device node */
   	  	        phandle = <0x100002fc>;
                 };
 
diff --git a/doc/device-tree/tpm.rst b/doc/device-tree/tpm.rst
index 2f1f6a5..d4e7667 100644
--- a/doc/device-tree/tpm.rst
+++ b/doc/device-tree/tpm.rst
@@ -33,7 +33,7 @@ Optional properties
 Example
 -------
 
-::
+.. code-block:: dts
 
     tpm@57 {
     	reg = <0x57>;
diff --git a/doc/device-tree/vpd.rst b/doc/device-tree/vpd.rst
index 65a1738..3e70d38 100644
--- a/doc/device-tree/vpd.rst
+++ b/doc/device-tree/vpd.rst
@@ -6,20 +6,23 @@ the system and each vpd node in the device tree represents a FRU. These node and
 their properties are specific to the FSP-based systems, passed to the skiboot in
 the form of FSP-defined HDAT structures. skiboot parses these structures and
 add respective nodes in the device tree.
-::
 
- /vpd			: VPD root node
- <fru-name>@<rsrc-id>	: Node name
- ibm,vpd			: VPD data binary blob
- ccin			: Customer Card Identification Number
- fru-type		: FRU type label (2 bytes ASCII character)
- fru-number		: FRU stocking part number
- ibm,loc-code		: Location code
- part-number		: Part number
- serial-number		: Serial number
- ibm,chip-id		: Processor Id
- size			: DIMM size (applicable for DIMM VPD only)
- ibm,memory-bus-frequency: DIMM frequency (applicable for DIMM VPD only)
+.. code-block:: dts
+
+ vpd {			   /* VPD root node */
+   fru-name@rsrc-id {	   /* Node name formatted as such */
+   ibm,vpd = <             /* VPD data binary blob */ >;
+     ccin = "524D";        /* Customer Card Identification Number */
+     fru-type = [ 41 56 ]; /* FRU type label (2 bytes ASCII character) */
+     fru-number    =       "FRU stocking part number";
+     ibm,loc-code  =       "Location code";
+     part-number   =       "ABC123456";
+     serial-number =       "ABC123456";
+     ibm,chip-id   = <0x0>; /* If part is a chip, Processor Id */
+     size = "0032768";      /* DIMM size (applicable for DIMM VPD only) */
+     ibm,memory-bus-frequency = <0x0 0x0>; /* DIMM frequency (applicable for DIMM VPD only) */
+   };
+ };
 
 The VPD tree in the device tree depicts the hierarchial structure of the
 FRUs having parent-child relationship. ::
@@ -53,7 +56,9 @@ FRUs having parent-child relationship. ::
     |-- root-node-vpd@a001
     `-- system-vpd@1c00
 
-Example vpd node: ::
+Example vpd node:
+
+.. code-block:: dts
 
  anchor-card@500 {
 	ccin = "52FE";