doc/*.rst: fix ReSTructured text syntax

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

15 files changed, 634 insertions, 563 deletions

diff --git a/doc/bmc.rst b/doc/bmc.rst
index 78c3b29..bbb390a 100644
--- a/doc/bmc.rst
+++ b/doc/bmc.rst
@@ -21,13 +21,11 @@ FW Boot Progress: assertion type. During boot, skiboot will update this sensor
 to one of the IPMI-defined progress codes. The codes use by skiboot are:
 
   * PCI Resource configuration (0x01)
-     - asserted as the PCI devices have been probed and resources allocated
-
+     * asserted as the PCI devices have been probed and resources allocated
   * Motherboard init (0x14)
-     - asserted as the platform-specific components have been initialised
-
+     * asserted as the platform-specific components have been initialised
   * OS boot (0x13)
-     - asserted after skiboot has loaded the PAYLOAD image, and is about to
+     * asserted after skiboot has loaded the PAYLOAD image, and is about to
        boot it.
 
 Chassis control messages
diff --git a/doc/console-log.rst b/doc/console-log.rst
index fbdd33b..9802418 100644
--- a/doc/console-log.rst
+++ b/doc/console-log.rst
@@ -1,5 +1,5 @@
 SkiBoot Console Log
--------------------
+===================
 
 Skiboot maintains a circular textual log buffer in memory.
 
@@ -20,17 +20,22 @@ with prlog() calls.
 See timebase.h for full timebase explanation.
 
 Log level from skiboot.h:
-#define PR_EMERG        0
-#define PR_ALERT        1
-#define PR_CRIT         2
-#define PR_ERR          3
-#define PR_WARNING      4
-#define PR_NOTICE       5
-#define PR_PRINTF       PR_NOTICE
-#define PR_INFO         6
-#define PR_DEBUG        7
-#define PR_TRACE        8
-#define PR_INSANE       9
+
+=============== ==========
+Define          Value
+=============== ==========
+PR_EMERG        0
+PR_ALERT        1
+PR_CRIT         2
+PR_ERR          3
+PR_WARNING      4
+PR_NOTICE       5
+PR_PRINTF       PR_NOTICE
+PR_INFO         6
+PR_DEBUG        7
+PR_TRACE        8
+PR_INSANE       9
+=============== ==========
 
 The console_log_levels byte in the debug_descriptor controls what
 messages are written to any console drivers (e.g. fsp, uart) and
@@ -40,21 +45,21 @@ This enables (advanced) users to vary what level of output they want
 at runtime in the memory console and through console drivers (fsp/uart)
 
 You can vary two things by poking in the debug descriptor:
-a) what log level is printed at all
-  e.g. only turn on PR_TRACE at specific points during runtime
-b) what log level goes out the fsp/uart console
-   defaults to PR_PRINTF
-    
+
+1. what log level is printed at all
+   e.g. only turn on PR_TRACE at specific points during runtime
+2. what log level goes out the fsp/uart console, defaults to PR_PRINTF
+
 We use two 4bit numbers (1 byte) for this in debug descriptor (saving
 some space, not needlessly wasting space that we may want in future).
-    
+
 The default is 0x75 (7=PR_DEBUG to in memory console, 5=PR_PRINTF to drivers
-    
+
 If you write 0x77 you will get debug info on uart/fsp console as
 well as in memory. If you write 0x95 you get PR_INSANE in memory but
 still only PR_NOTICE through drivers.
-    
+
 People who write something like 0x1f will get a very quiet boot indeed.
- 
+
 
 
diff --git a/doc/device-tree.rst b/doc/device-tree.rst
index 742ff43..0597194 100644
--- a/doc/device-tree.rst
+++ b/doc/device-tree.rst
@@ -1,77 +1,54 @@
-/*
- * Sapphire device-tree requirements
- *
- * Version: 0.2.1
- *
- * This documents the generated device-tree requirements, this is based on
- * a commented device-tree dump obtained from a DT generated by Sapphire
- * itself from an HDAT.
- */
-
-/*
- * General comments:
- *
- *  - skiboot does not require nodes to have phandle properties, but
- *    if you have them then *all* nodes must have them including the
- *    root of the device-tree (currently a HB bug !). It is recommended
- *    to have them since they are needed to represent the cache levels.
- *
- *    NOTE: The example tree below only has phandle properties for
- *    nodes that are referenced by other nodes. This is *not* correct
- *    and is purely done for keeping this document smaller, make sure
- *    to follow the rule above.
- *
- *  - Only the "phandle" property is required. Sapphire also generates
- *    a "linux,phandle" for backward compatibility but doesn't require
- *    it as an input
- *
- *  - Any property not specifically documented must be put in "as is"
- *
- *  - All ibm,chip-id properties contain a HW chip ID which correspond
- *    on P8 to the PIR value shifted right by 7 bits, ie. it's a 6-bit
- *    value made of a 3-bit node number and a 3-bit chip number.
- *
- *  - Unit addresses (@xxxx part of node names) should if possible use
- *    lower case hexadecimal to be consistent with what skiboot does
- *    and to help some stupid parsers out there...
- */
-
-/*
- * Version history
- *
- * 2013/10/08 : Version 0.1
- *
- * 2013/10/09 : Version 0.2
- *
- *    - Add comment about case of unit addresses
- *    - Add missing lpc node definition
- *    - Add example UART node on LPC
- *    - Remove "status" property from PSI xsco nodes
- *
- * 2014/03/26 : Version 0.2.1
- *
- *    - Fix cpus/xxx/ibm,pa-features to be a byte array
- */
-
-/dts-v1/;
-
-
-/*
- * Here are the reserve map entries. They should exactly match the
- * reserved-ranges property of the root node (see documentation
- * of that property)
- */
-
-/memreserve/	0x00000007fe600000 0x0000000000100000;
-/memreserve/	0x00000007fe200000 0x0000000000100000;
-/memreserve/	0x0000000031e00000 0x00000000003e0000;
-/memreserve/	0x0000000031000000 0x0000000000e00000;
-/memreserve/	0x0000000030400000 0x0000000000c00000;
-/memreserve/	0x0000000030000000 0x0000000000400000;
-/memreserve/	0x0000000400000000 0x0000000000600450;
-
-/* Root node */
-/ {
+Device Tree
+===========
+
+General notes on the Device Tree produced by skiboot. This chapter
+**needs updating**.
+
+
+General comments
+----------------
+
+* skiboot does not require nodes to have phandle properties, but
+  if you have them then *all* nodes must have them including the
+  root of the device-tree (currently a HB bug !). It is recommended
+  to have them since they are needed to represent the cache levels.
+* **NOTE**: The example tree below only has phandle properties for
+  nodes that are referenced by other nodes. This is *not* correct
+  and is purely done for keeping this document smaller, make sure
+  to follow the rule above.
+* Only the "phandle" property is required. Sapphire also generates
+  a "linux,phandle" for backward compatibility but doesn't require
+  it as an input
+* Any property not specifically documented must be put in "as is"
+* All ibm,chip-id properties contain a HW chip ID which correspond
+  on P8 to the PIR value shifted right by 7 bits, ie. it's a 6-bit
+  value made of a 3-bit node number and a 3-bit chip number.
+* Unit addresses (@xxxx part of node names) should if possible use
+  lower case hexadecimal to be consistent with what skiboot does
+  and to help some stupid parsers out there...
+
+
+Reserve Map
+-----------
+
+Here are the reserve map entries. They should exactly match the
+reserved-ranges property of the root node (see documentation
+of that property)::
+
+  /memreserve/	0x00000007fe600000 0x0000000000100000;
+  /memreserve/	0x00000007fe200000 0x0000000000100000;
+  /memreserve/	0x0000000031e00000 0x00000000003e0000;
+  /memreserve/	0x0000000031000000 0x0000000000e00000;
+  /memreserve/	0x0000000030400000 0x0000000000c00000;
+  /memreserve/	0x0000000030000000 0x0000000000400000;
+  /memreserve/	0x0000000400000000 0x0000000000600450;
+
+Root Node
+---------
+
+Root node of device tree::
+
+ / {
   	/*
 	 * "compatible" properties are string lists (ASCII strings separated by
 	 * \0 characters) indicating the overall compatibility from the more
@@ -512,4 +489,4 @@
 			}
                 };
 	};
-};
+ };
diff --git a/doc/error-logging.rst b/doc/error-logging.rst
index 7c62520..02261e8 100644
--- a/doc/error-logging.rst
+++ b/doc/error-logging.rst
@@ -1,4 +1,4 @@
-How to log errors on Sapphire and POWERNV:
+How to log errors on Sapphire and POWERNV
 =========================================
 
 Currently the errors reported by POWERNV/Sapphire (OPAL) interfaces
@@ -14,8 +14,8 @@ passed by user using the error-logging interfaces outlined below.
 Following which, PEL structure is generated based on the input and
 then passed on to FSP.
 
-Error logging interfaces in Sapphire:
-====================================
+Error logging interfaces in Sapphire
+------------------------------------
 
 Interfaces are provided for the user to log/report an error in Sapphire.
 Using these interfaces relevant error information is collected and later
@@ -23,29 +23,30 @@ converted to PEL format and then pushed to FSP.
 
 Step 1: To report an error, invoke opal_elog_create() with required argument.
 
-	struct errorlog *opal_elog_create(struct opal_err_info *e_info,
-					  uint32_t tag);
+	``struct errorlog *opal_elog_create(struct opal_err_info *e_info, uint32_t tag);``
 
-	Parameters:
-
-	struct opal_err_info *e_info: Struct to hold information identifying
-                       error/event source.
+Parameters:
 
-	uint32_t tag: Unique value to identify the data.
+	* ``struct opal_err_info *e_info``
+	  Struct to hold information identifying error/event source.
+        * ``uint32_t tag:`` Unique value to identify the data.
                        Ideal to have ASCII value for 4-byte string.
 
 	The opal_err_info struct holds several pieces of information to help
 	identify the error/event. The struct can be obtained via the
-	DEFINE_LOG_ENTRY macro as below - it only needs to be called once.
+	``DEFINE_LOG_ENTRY`` macro as below - it only needs to be called once.
 
-	DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_CHIP,
+        ::
+
+	 DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_CHIP,
 			OPAL_PLATFORM_FIRMWARE, OPAL_PREDICTIVE_ERR_GENERAL,
 			OPAL_NA);
 
 	The various attributes set by this macro are described below.
 
-	uint8_t opal_error_event_type: Classification of error/events
-					type reported on OPAL
+	``uint8_t opal_error_event_type``: Classification of error/events
+	type reported on OPAL::
+
 		/* Platform Events/Errors: Report Machine Check Interrupt */
 		#define OPAL_PLATFORM_ERR_EVT           0x01
 		/* INPUT_OUTPUT: Report all I/O related events/errors */
@@ -55,10 +56,11 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
 		/* MISC: Miscellaneous error */
 		#define OPAL_MISC_ERR_EVT               0x04
 
-	uint16_t component_id: Component ID of Sapphire component as
+	``uint16_t component_id``: Component ID of Sapphire component as
 				listed in include/errorlog.h
 
-	uint8_t subsystem_id: ID of the sub-system reporting error.
+	  ``uint8_t subsystem_id``: ID of the sub-system reporting error.::
+
 		/* OPAL Subsystem IDs listed for reporting events/errors */
 			#define OPAL_PROCESSOR_SUBSYSTEM        0x10
 			#define OPAL_MEMORY_SUBSYSTEM           0x20
@@ -72,7 +74,8 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
 			#define OPAL_SOFTWARE                   0x90
 			#define OPAL_EXTERNAL_ENV               0xA0
 
-	uint8_t event_severity: Severity of the event/error to be reported
+	``uint8_t event_severity``: Severity of the event/error to be reported ::
+
 		#define OPAL_INFO                                   0x00
 		#define OPAL_RECOVERED_ERR_GENERAL                  0x10
 
@@ -105,83 +108,84 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
 
 		#define OPAL_ERROR_PANIC				    0x50
 
-	uint8_t  event_subtype: Event Sub-type
-			#define OPAL_NA                                         0x00
-			#define OPAL_MISCELLANEOUS_INFO_ONLY                    0x01
-			#define OPAL_PREV_REPORTED_ERR_RECTIFIED                0x10
-			#define OPAL_SYS_RESOURCES_DECONFIG_BY_USER             0x20
-			#define OPAL_SYS_RESOURCE_DECONFIG_PRIOR_ERR            0x21
-			#define OPAL_RESOURCE_DEALLOC_EVENT_NOTIFY              0x22
-			#define OPAL_CONCURRENT_MAINTENANCE_EVENT               0x40
-			#define OPAL_CAPACITY_UPGRADE_EVENT                     0x60
-			#define OPAL_RESOURCE_SPARING_EVENT                     0x70
-			#define OPAL_DYNAMIC_RECONFIG_EVENT                     0x80
-			#define OPAL_NORMAL_SYS_PLATFORM_SHUTDOWN               0xD0
-			#define OPAL_ABNORMAL_POWER_OFF                         0xE0
-
-	uint8_t opal_srctype: SRC type, value should be OPAL_SRC_TYPE_ERROR.
+		``uint8_t  event_subtype``: Event Sub-type ::
+
+		  #define OPAL_NA                                         0x00
+		  #define OPAL_MISCELLANEOUS_INFO_ONLY                    0x01
+		  #define OPAL_PREV_REPORTED_ERR_RECTIFIED                0x10
+		  #define OPAL_SYS_RESOURCES_DECONFIG_BY_USER             0x20
+		  #define OPAL_SYS_RESOURCE_DECONFIG_PRIOR_ERR            0x21
+		  #define OPAL_RESOURCE_DEALLOC_EVENT_NOTIFY              0x22
+		  #define OPAL_CONCURRENT_MAINTENANCE_EVENT               0x40
+		  #define OPAL_CAPACITY_UPGRADE_EVENT                     0x60
+		  #define OPAL_RESOURCE_SPARING_EVENT                     0x70
+		  #define OPAL_DYNAMIC_RECONFIG_EVENT                     0x80
+		  #define OPAL_NORMAL_SYS_PLATFORM_SHUTDOWN               0xD0
+		  #define OPAL_ABNORMAL_POWER_OFF                         0xE0
+
+
+	``uint8_t opal_srctype``: SRC type, value should be OPAL_SRC_TYPE_ERROR.
 			SRC refers to System Reference Code.
 			It is 4 byte hexa-decimal number that reflects the
 			current system state.
 			Eg: BB821010,
-				1st byte -> BB -> SRC Type
-				2nd byte -> 82 -> Subsystem
-				3rd, 4th byte -> Component ID and Reason Code
+
+			* 1st byte -> BB -> SRC Type
+			* 2nd byte -> 82 -> Subsystem
+			* 3rd, 4th byte -> Component ID and Reason Code
+
 			SRC needs to be generated on the fly depending on the state
 			of the system. All the parameters needed to generate a SRC
 			should be provided during reporting of an event/error.
 
 
-	 uint32_t reason_code: Reason for failure as stated in include/errorlog.h
-				for Sapphire
+	``uint32_t reason_code``: Reason for failure as stated in include/errorlog.h for Sapphire.
 			Eg: Reason code for code-update failures can be
-				OPAL_RC_CU_INIT  -> Initialisation failure
-				OPAL_RC_CU_FLASH -> Flash failure
+
+			* ``OPAL_RC_CU_INIT``  -> Initialisation failure
+			* ``OPAL_RC_CU_FLASH`` -> Flash failure
 
 
 Step 2: Data can be appended to the user data section using the either of
-        the below two interfaces:
+        the below two interfaces: ::
 
-	void log_append_data(struct errorlog *buf, unsigned char *data,
+	  void log_append_data(struct errorlog *buf, unsigned char *data,
 			     uint16_t size)
 
 	Parameters:
-	struct opal_errorlog *buf:
-		struct opal_errorlog *buf: struct opal_errorlog pointer returned
-		by opal_elog_create() call.
+	  ``struct opal_errorlog *buf``: ``struct opal_errorlog`` pointer
+	  returned by opal_elog_create() call.
 
-	unsigned char *data: Pointer to the dump data
+	``unsigned char *data``: Pointer to the dump data
 
-	uint16_t size: Size of the dump data.
+	``uint16_t size``: Size of the dump data.
 
-	void log_append_msg(struct errorlog *buf, const char *fmt, ...)
+	``void log_append_msg(struct errorlog *buf, const char *fmt, ...)``
 
 	Parameters:
-	struct opal_errorlog *buf:
-		struct opal_errorlog *buf: struct opal_errorlog pointer returned
-		by opal_elog_create() call.
+	  ``struct opal_errorlog *buf``: pointer returned by opal_elog_create()
+	  call.
 
-	const char *fmt: Formatted error log string.
+	``const char *fmt``: Formatted error log string.
 
 	Additional user data sections can be added to the error log to
 	separate data (eg. readable text vs binary data) by calling
 	log_add_section(). The interfaces in Step 2 operate on the 'last'
 	user data section of the error log.
 
-	void log_add_section(struct errorlog *buf, uint32_t tag);
+	``void log_add_section(struct errorlog *buf, uint32_t tag);``
 
 	Parameters:
-	struct opal_errorlog *buf:
-		struct opal_errorlog *buf: struct opal_errorlog pointer returned
-		by opal_elog_create() call.
+	  ``struct opal_errorlog *buf``: pointer returned by opal_elog_create() call.
 
-	uint32_t tag: Unique value to identify the data.
+	  ``uint32_t tag``: Unique value to identify the data.
                        Ideal to have ASCII value for 4-byte string.
 
 Step 3: Once all the data for an error is logged in, the error needs to be
-	committed in FSP.
+	committed in FSP. ::
+
+	  rc = elog_fsp_commit(buf);
 
-	rc = elog_fsp_commit(buf);
 	Value of 0 is returned on success.
 
 In the process of committing an error to FSP, log info is first internally
@@ -191,11 +195,13 @@ reported by Sapphire and POWERNV are logged in FSP.
 
 If the user does not intend to dump various user data sections, but just
 log the error with some amount of description around that error, they can do
-so using just the simple error logging interface
+so using just the simple error logging interface ::
+
+  log_simple_error(uint32_t reason_code, char *fmt, ...);
 
-log_simple_error(uint32_t reason_code, char *fmt, ...);
+For example: ::
 
-Eg: log_simple_error(OPAL_RC_SURVE_STATUS,
+  log_simple_error(OPAL_RC_SURVE_STATUS,
 			"SURV: Error retreiving surveillance status: %d\n",
                        						err_len);
 
@@ -203,8 +209,8 @@ Using the reason code, an error log is generated with the information derived
 from the look-up table, populated and committed to FSP. All of it
 is done with just one call.
 
-Note:
-====
+Note
+----
 * For more information regarding error logging and PEL format
   refer to PAPR doc and P7 PEL and SRC PLDD document.
 
@@ -212,15 +218,17 @@ Note:
   interface parameters and include/pel.h for PEL
   structures.
 
-Sample error logging:
-===================
+Sample error logging
+--------------------
 
-DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_ATTN,
+::
+
+  DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_ATTN,
 		 OPAL_PLATFORM_FIRMWARE, OPAL_PREDICTIVE_ERR_GENERAL,
 		 OPAL_NA);
 
-void report_error(int index)
-{
+  void report_error(int index)
+  {
 	struct errorlog *buf;
 	char data1[] = "This is a sample user defined data section1";
 	char data2[] = "Error logging sample. These are dummy errors. Section 2";
@@ -258,138 +266,141 @@ void report_error(int index)
 	/* Once all info is updated, ready to be sent to FSP */
 	printf("ELOG:commit to FSP\n");
 	log_commit(buf);
-}
+ }
+
+Sample output PEL dump got from FSP
+-----------------------------------
 
- Sample output PEL dump got from FSP:
- ===================================
+::
+   
  $ errl -d -x 0x533C9B37
-|   00000000     50480030  01004154  20150728  02000500     PH.0..AT ..(....   |
-|   00000010     20150728  02000566  4B000107  00000000      ..(...fK.......   |
-|   00000020     00000000  00000000  B0000002  533C9B37     ............S..7   |
-|   00000030     55480018  01004154  80002000  00000000     UH....AT.. .....   |
-|   00000040     00002000  01005300  50530050  01004154     .. ...S.PS.P..AT   |
-|   00000050     02000008  00000048  00000080  00000000     .......H........   |
-|   00000060     00000000  00000000  00000000  00000000     ................   |
-|   00000070     00000000  00000000  42423832  31343130     ........BB821410   |
-|   00000080     20202020  20202020  20202020  20202020                        |
-|   00000090     20202020  20202020  4548004C  01004154             EH.L..AT   |
-|   000000A0     38323836  2D343241  31303738  34415400     8286-42A10784AT.   |
-|   000000B0     00000000  00000000  00000000  00000000     ................   |
-|   000000C0     00000000  00000000  00000000  00000000     ................   |
-|   000000D0     00000000  00000000  20150728  02000500     ........ ..(....   |
-|   000000E0     00000000  4D54001C  01004154  38323836     ....MT....AT8286   |
-|   000000F0     2D343241  31303738  34415400  00000000     -42A10784AT.....   |
-|   00000100     5544003C  01004154  4B4B4B4B  00340000     UD....ATKKKK.4..   |
-|   00000110     54686973  20697320  61207361  6D706C65     This is a sample   |
-|   00000120     20757365  72206465  66696E65  64206461      user defined da   |
-|   00000130     74612073  65637469  6F6E3100  554400A7     ta section1.UD..   |
-|   00000140     01004154  4C4C4C4C  009F0000  4572726F     ..ATLLLL....Erro   |
-|   00000150     72206C6F  6767696E  67207361  6D706C65     r logging sample   |
-|   00000160     2E205468  65736520  61726520  64756D6D     . These are dumm   |
-|   00000170     79206572  726F7273  2E205365  6374696F     y errors. Sectio   |
-|   00000180     6E203200  53616D70  6C652065  72726F72     n 2.Sample error   |
-|   00000190     2053616D  706C6520  6572726F  72205361      Sample error Sa   |
-|   000001A0     6D706C65  20657272  6F722053  616D706C     mple error Sampl   |
-|   000001B0     65206572  726F7220  09090953  616D706C     e error ...Sampl   |
-|   000001C0     65206572  726F7220  61626364  65666768     e error abcdefgh   |
-|   000001D0     696A6B6C  6D6E6F70  71727374  75767778     ijklmnopqrstuvwx   |
-|   000001E0     797A00                                     yz.                |
-|------------------------------------------------------------------------------|
-|                       Platform Event Log - 0x533C9B37                        |
-|------------------------------------------------------------------------------|
-|                                Private Header                                |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Created by               : 4154                                              |
-| Created at               : 07/28/2015 02:00:05                               |
-| Committed at             : 07/28/2015 02:00:05                               |
-| Creator Subsystem        : OPAL                                              |
-| CSSVER                   :                                                   |
-| Platform Log Id          : 0xB0000002                                        |
-| Entry Id                 : 0x533C9B37                                        |
-| Total Log Size           : 483                                               |
-|------------------------------------------------------------------------------|
-|                                 User Header                                  |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Log Committed by         : 4154                                              |
-| Subsystem                : Platform Firmware                                 |
-| Event Scope              : Unknown - 0x00000000                              |
-| Event Severity           : Predictive Error                                  |
-| Event Type               : Not Applicable                                    |
-| Return Code              : 0x00000000                                        |
-| Action Flags             : Report Externally                                 |
-| Action Status            : Sent to Hypervisor                                |
-|------------------------------------------------------------------------------|
-|                        Primary System Reference Code                         |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Created by               : 4154                                              |
-| SRC Format               : 0x80                                              |
-| SRC Version              : 0x02                                              |
-| Virtual Progress SRC     : False                                             |
-| I5/OS Service Event Bit  : False                                             |
-| Hypervisor Dump Initiated: False                                             |
-| Power Control Net Fault  : False                                             |
-|                                                                              |
-| Valid Word Count         : 0x08                                              |
-| Reference Code           : BB821410                                          |
-| Hex Words 2 - 5          : 00000080 00000000 00000000 00000000               |
-| Hex Words 6 - 9          : 00000000 00000000 00000000 00000000               |
-|                                                                              |
-|------------------------------------------------------------------------------|
-|                             Extended User Header                             |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Created by               : 4154                                              |
-| Reporting Machine Type   : 8286-42A                                          |
-| Reporting Serial Number  : 10784AT                                           |
-| FW Released Ver          :                                                   |
-| FW SubSys Version        :                                                   |
-| Common Ref Time          : 07/28/2015 02:00:05                               |
-| Symptom Id Len           : 0                                                 |
-| Symptom Id               :                                                   |
-|------------------------------------------------------------------------------|
-|                      Machine Type/Model & Serial Number                      |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Created by               : 4154                                              |
-| Machine Type Model       : 8286-42A                                          |
-| Serial Number            : 10784AT                                           |
-|------------------------------------------------------------------------------|
-|                              User Defined Data                               |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Created by               : 4154                                              |
-|                                                                              |
-|   00000000     4B4B4B4B  00340000  54686973  20697320     KKKK.4..This is    |
-|   00000010     61207361  6D706C65  20757365  72206465     a sample user de   |
-|   00000020     66696E65  64206461  74612073  65637469     fined data secti   |
-|   00000030     6F6E3100                                   on1.               |
-|                                                                              |
-|------------------------------------------------------------------------------|
-|                              User Defined Data                               |
-|------------------------------------------------------------------------------|
-| Section Version          : 1                                                 |
-| Sub-section type         : 0                                                 |
-| Created by               : 4154                                              |
-|                                                                              |
-|   00000000     4C4C4C4C  009F0000  4572726F  72206C6F     LLLL....Error lo   |
-|   00000010     6767696E  67207361  6D706C65  2E205468     gging sample. Th   |
-|   00000020     65736520  61726520  64756D6D  79206572     ese are dummy er   |
-|   00000030     726F7273  2E205365  6374696F  6E203200     rors. Section 2.   |
-|   00000040     53616D70  6C652065  72726F72  2053616D     Sample error Sam   |
-|   00000050     706C6520  6572726F  72205361  6D706C65     ple error Sample   |
-|   00000060     20657272  6F722053  616D706C  65206572      error Sample er   |
-|   00000070     726F7220  09090953  616D706C  65206572     ror ...Sample er   |
-|   00000080     726F7220  61626364  65666768  696A6B6C     ror abcdefghijkl   |
-|   00000090     6D6E6F70  71727374  75767778  797A00       mnopqrstuvwxyz.    |
-|                                                                              |
-|------------------------------------------------------------------------------|
+ |   00000000     50480030  01004154  20150728  02000500     PH.0..AT ..(....   |
+ |   00000010     20150728  02000566  4B000107  00000000      ..(...fK.......   |
+ |   00000020     00000000  00000000  B0000002  533C9B37     ............S..7   |
+ |   00000030     55480018  01004154  80002000  00000000     UH....AT.. .....   |
+ |   00000040     00002000  01005300  50530050  01004154     .. ...S.PS.P..AT   |
+ |   00000050     02000008  00000048  00000080  00000000     .......H........   |
+ |   00000060     00000000  00000000  00000000  00000000     ................   |
+ |   00000070     00000000  00000000  42423832  31343130     ........BB821410   |
+ |   00000080     20202020  20202020  20202020  20202020                        |
+ |   00000090     20202020  20202020  4548004C  01004154             EH.L..AT   |
+ |   000000A0     38323836  2D343241  31303738  34415400     8286-42A10784AT.   |
+ |   000000B0     00000000  00000000  00000000  00000000     ................   |
+ |   000000C0     00000000  00000000  00000000  00000000     ................   |
+ |   000000D0     00000000  00000000  20150728  02000500     ........ ..(....   |
+ |   000000E0     00000000  4D54001C  01004154  38323836     ....MT....AT8286   |
+ |   000000F0     2D343241  31303738  34415400  00000000     -42A10784AT.....   |
+ |   00000100     5544003C  01004154  4B4B4B4B  00340000     UD....ATKKKK.4..   |
+ |   00000110     54686973  20697320  61207361  6D706C65     This is a sample   |
+ |   00000120     20757365  72206465  66696E65  64206461      user defined da   |
+ |   00000130     74612073  65637469  6F6E3100  554400A7     ta section1.UD..   |
+ |   00000140     01004154  4C4C4C4C  009F0000  4572726F     ..ATLLLL....Erro   |
+ |   00000150     72206C6F  6767696E  67207361  6D706C65     r logging sample   |
+ |   00000160     2E205468  65736520  61726520  64756D6D     . These are dumm   |
+ |   00000170     79206572  726F7273  2E205365  6374696F     y errors. Sectio   |
+ |   00000180     6E203200  53616D70  6C652065  72726F72     n 2.Sample error   |
+ |   00000190     2053616D  706C6520  6572726F  72205361      Sample error Sa   |
+ |   000001A0     6D706C65  20657272  6F722053  616D706C     mple error Sampl   |
+ |   000001B0     65206572  726F7220  09090953  616D706C     e error ...Sampl   |
+ |   000001C0     65206572  726F7220  61626364  65666768     e error abcdefgh   |
+ |   000001D0     696A6B6C  6D6E6F70  71727374  75767778     ijklmnopqrstuvwx   |
+ |   000001E0     797A00                                     yz.                |
+ |------------------------------------------------------------------------------|
+ |                       Platform Event Log - 0x533C9B37                        |
+ |------------------------------------------------------------------------------|
+ |                                Private Header                                |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Created by               : 4154                                              |
+ | Created at               : 07/28/2015 02:00:05                               |
+ | Committed at             : 07/28/2015 02:00:05                               |
+ | Creator Subsystem        : OPAL                                              |
+ | CSSVER                   :                                                   |
+ | Platform Log Id          : 0xB0000002                                        |
+ | Entry Id                 : 0x533C9B37                                        |
+ | Total Log Size           : 483                                               |
+ |------------------------------------------------------------------------------|
+ |                                 User Header                                  |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Log Committed by         : 4154                                              |
+ | Subsystem                : Platform Firmware                                 |
+ | Event Scope              : Unknown - 0x00000000                              |
+ | Event Severity           : Predictive Error                                  |
+ | Event Type               : Not Applicable                                    |
+ | Return Code              : 0x00000000                                        |
+ | Action Flags             : Report Externally                                 |
+ | Action Status            : Sent to Hypervisor                                |
+ |------------------------------------------------------------------------------|
+ |                        Primary System Reference Code                         |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Created by               : 4154                                              |
+ | SRC Format               : 0x80                                              |
+ | SRC Version              : 0x02                                              |
+ | Virtual Progress SRC     : False                                             |
+ | I5/OS Service Event Bit  : False                                             |
+ | Hypervisor Dump Initiated: False                                             |
+ | Power Control Net Fault  : False                                             |
+ |                                                                              |
+ | Valid Word Count         : 0x08                                              |
+ | Reference Code           : BB821410                                          |
+ | Hex Words 2 - 5          : 00000080 00000000 00000000 00000000               |
+ | Hex Words 6 - 9          : 00000000 00000000 00000000 00000000               |
+ |                                                                              |
+ |------------------------------------------------------------------------------|
+ |                             Extended User Header                             |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Created by               : 4154                                              |
+ | Reporting Machine Type   : 8286-42A                                          |
+ | Reporting Serial Number  : 10784AT                                           |
+ | FW Released Ver          :                                                   |
+ | FW SubSys Version        :                                                   |
+ | Common Ref Time          : 07/28/2015 02:00:05                               |
+ | Symptom Id Len           : 0                                                 |
+ | Symptom Id               :                                                   |
+ |------------------------------------------------------------------------------|
+ |                      Machine Type/Model & Serial Number                      |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Created by               : 4154                                              |
+ | Machine Type Model       : 8286-42A                                          |
+ | Serial Number            : 10784AT                                           |
+ |------------------------------------------------------------------------------|
+ |                              User Defined Data                               |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Created by               : 4154                                              |
+ |                                                                              |
+ |   00000000     4B4B4B4B  00340000  54686973  20697320     KKKK.4..This is    |
+ |   00000010     61207361  6D706C65  20757365  72206465     a sample user de   |
+ |   00000020     66696E65  64206461  74612073  65637469     fined data secti   |
+ |   00000030     6F6E3100                                   on1.               |
+ |                                                                              |
+ |------------------------------------------------------------------------------|
+ |                              User Defined Data                               |
+ |------------------------------------------------------------------------------|
+ | Section Version          : 1                                                 |
+ | Sub-section type         : 0                                                 |
+ | Created by               : 4154                                              |
+ |                                                                              |
+ |   00000000     4C4C4C4C  009F0000  4572726F  72206C6F     LLLL....Error lo   |
+ |   00000010     6767696E  67207361  6D706C65  2E205468     gging sample. Th   |
+ |   00000020     65736520  61726520  64756D6D  79206572     ese are dummy er   |
+ |   00000030     726F7273  2E205365  6374696F  6E203200     rors. Section 2.   |
+ |   00000040     53616D70  6C652065  72726F72  2053616D     Sample error Sam   |
+ |   00000050     706C6520  6572726F  72205361  6D706C65     ple error Sample   |
+ |   00000060     20657272  6F722053  616D706C  65206572      error Sample er   |
+ |   00000070     726F7220  09090953  616D706C  65206572     ror ...Sample er   |
+ |   00000080     726F7220  61626364  65666768  696A6B6C     ror abcdefghijkl   |
+ |   00000090     6D6E6F70  71727374  75767778  797A00       mnopqrstuvwxyz.    |
+ |                                                                              |
+ |------------------------------------------------------------------------------|
 
diff --git a/doc/gcov.rst b/doc/gcov.rst
index 956c5c8..d50fbe5 100644
--- a/doc/gcov.rst
+++ b/doc/gcov.rst
@@ -1,11 +1,11 @@
 GCOV for skiboot
-----------------
+================
 
 Unit tests
 ----------
-All unit tests are built+run with gcov enabled.
+All unit tests are built+run with gcov enabled. ::
 
-make coverage-report
+ make coverage-report
 
 will generate a unit test coverage report like:
 http://open-power.github.io/skiboot/coverage-report/
@@ -18,10 +18,11 @@ from real hardware (or a simulator).
 
 Building Skiboot with GCOV
 --------------------------
+::
 
-SKIBOOT_GCOV=1 make
+  SKIBOOT_GCOV=1 make
 
-You may need to "make clean" first.
+You may need to ``make clean`` first.
 
 This will build a skiboot lid roughly *twice* the size.
 
@@ -33,28 +34,36 @@ The way we extract the gcov data from a system is by dumping the contents
 of skiboot memory and then parsing the data structures in user space with
 the extract-gcov utility in the skiboot repo.
 
-mambo:
+mambo: ::
+
   mysim memory fwrite 0x30000000 0x240000 skiboot.dump
-FSP:
+
+FSP: ::
+
   getmemproc 30000000 3407872 -fb skiboot.dump
-linux (e.g. petitboot environment):
+
+linux (e.g. petitboot environment): ::
+
   dd if=/proc/kcore skip=1572864 count=6656  of=skiboot.dump
 
 You basically need to dump out the first 3MB of skiboot memory.
 
-Then you need to find out where the gcov data structures are:
-perl -e "printf '0x%x', 0x30000000 + 0x`grep gcov_info_list skiboot.map|cut -f 1 -d ' '`"
+Then you need to find out where the gcov data structures are: ::
+
+  perl -e "printf '0x%x', 0x30000000 + 0x`grep gcov_info_list skiboot.map|cut -f 1 -d ' '`"
 
-That address needs to be supplied to the extract-gcov utility:
-./extract-gcov skiboot.dump 0x3023ec40
+That address needs to be supplied to the extract-gcov utility: ::
+
+  ./extract-gcov skiboot.dump 0x3023ec40
 
 Once you've run extract-gcov, it will have extracted the gcda files
 from the skiboot memory image.
 
-You can then run lcov:
-lcov -b . -q -c -d . -o skiboot-boot.info \
---gcov-tool
-/opt/cross/gcc-4.8.0-nolibc/powerpc64-linux/bin/powerpc64-linux-gcov
+You can then run lcov: ::
+
+  lcov -b . -q -c -d . -o skiboot-boot.info
+  --gcov-tool
+  /opt/cross/gcc-4.8.0-nolibc/powerpc64-linux/bin/powerpc64-linux-gcov
 
 *IMPORTANT* you should point lcov to the gcov for the compiler you used
 to build skiboot, otherwise you're likely to get errors.
diff --git a/doc/index.rst b/doc/index.rst
index 5630004..bd40ad8 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,21 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   overview
+   opal-spec
+   console-log
+   device-tree
+   error-logging
+   bmc
+   gcov
+   memory
+   nvlink
+   stable-skiboot-rules
+   versioning
+   pci
+   pci-slot
+   xscom-node-bindings
+
 Indices and tables
 ==================
 
diff --git a/doc/memory.rst b/doc/memory.rst
index 002d460..923509d 100644
--- a/doc/memory.rst
+++ b/doc/memory.rst
@@ -1,5 +1,5 @@
 Memory in skiboot
------------------
+=================
 
 There are regions of memory we statically allocate for firmware as well as
 a HEAP region for boot and runtime allocations.
@@ -25,20 +25,23 @@ all the heap once skiboot became 2MB with GCOV.
 
 Heap usage is printed before running the payload.
 
-For example, as of writing, on a dual socket Tuleta:
-[45215870591,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
-[3680939340,5] CUPD: T side MI Keyword = SV830_027
-[3680942658,5] CUPD: T side ML Keyword = FW830.00
-[15404383291,5] Region ibm,firmware-heap free: 5378072
+For example, as of writing, on a dual socket Tuleta: ::
 
-and on a palmetto:
-[24748502575,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
-[9870429550,5] Region ibm,firmware-heap free: 10814856
+  [45215870591,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
+  [3680939340,5] CUPD: T side MI Keyword = SV830_027
+  [3680942658,5] CUPD: T side ML Keyword = FW830.00
+  [15404383291,5] Region ibm,firmware-heap free: 5378072
 
-Our memory allocator is simple, a use pattern of:
-A = malloc();
-B = malloc();
-free(A);
+and on a palmetto: ::
+
+  [24748502575,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
+  [9870429550,5] Region ibm,firmware-heap free: 10814856
+
+Our memory allocator is simple, a use pattern of: ::
+
+  A = malloc();
+  B = malloc();
+  free(A);
 
 is likely to generate fragmentation, so it should generally be avoided
 where possible.
diff --git a/doc/nvlink.rst b/doc/nvlink.rst
index 5aef539..981cf11 100644
--- a/doc/nvlink.rst
+++ b/doc/nvlink.rst
@@ -1,9 +1,8 @@
 OPAL/Skiboot Nvlink Interface Documentation
-----------------------------------------------------------------------
+===========================================
 
-========
 Overview
-========
+--------
 
 NV-Link is a high speed interconnect that is used in conjunction with
 a PCI-E connection to create an interface between chips that provides
@@ -22,9 +21,8 @@ Presently the NV-Link is only capable of data transfers initiated by
 the target, thus the emulated PCI device will only handle registers
 for link initialisation, DMA transfers and error reporting (EEH).
 
-====================
 Emulated PCI Devices
-====================
+--------------------
 
 Each link will be exported as an emulated PCI device with a minimum of
 two emulated PCI devices per GPU. Emulated PCI devices are grouped per
@@ -36,38 +34,42 @@ necessary device parameters. The only functionality available is
 related to the setup of DMA windows.
 
 Configuration Space Parameters
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Vendor ID = 0x1014         (IBM)
-Device ID = 0x04ea
-Revision ID = 0x00
-Class = 0x068000	   (Bridge Device Other, ProgIf = 0x0)
-BAR0/1 = TL/DL Registers
+============ =============== =====
+============ =============== =====
+Vendor ID    0x1014          (IBM)
+Device ID    0x04ea
+Revision ID  0x00
+Class        0x068000        (Bridge Device Other, ProgIf = 0x0)
+BAR0/1       TL/DL Registers
+============ =============== =====
 
 TL/DL Registers
----------------
+^^^^^^^^^^^^^^^
 
 Each link has 128KB of TL/DL registers. These will always be mapped
-to 64-bit BAR#0 of the emulated PCI device configuration space.
+to 64-bit BAR#0 of the emulated PCI device configuration space. ::
 
-BAR#0 + 128K +-----------+
-      	     | NTL (64K) |
-BAR#0 + 64K  +-----------+
+ BAR#0 + 128K +-----------+
+       	     | NTL (64K) |
+ BAR#0 + 64K  +-----------+
       	     | DL (64K)  |
-BAR#0	     +-----------+
+ BAR#0	     +-----------+
 
 Vendor Specific Capabilities
-----------------------------
-
-+-----------------+----------------+----------------+----------------+
-|  Version (0x02) |   Cap Length   |  Next Cap Ptr  |  Cap ID (0x09) |
-+-----------------+----------------+----------------+----------------+
-|                      Procedure Status Register                     |
-+--------------------------------------------------------------------+
-|                      Procedure Control Register                    |
-+---------------------------------------------------+----------------+
-|             Reserved            |   PCI Dev Flag  |   Link Number  |
-+---------------------------------------------------+----------------+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+ +-----------------+----------------+----------------+----------------+
+ |  Version (0x02) |   Cap Length   |  Next Cap Ptr  |  Cap ID (0x09) |
+ +-----------------+----------------+----------------+----------------+
+ |                      Procedure Status Register                     |
+ +--------------------------------------------------------------------+
+ |                      Procedure Control Register                    |
+ +---------------------------------------------------+----------------+
+ |             Reserved            |   PCI Dev Flag  |   Link Number  |
+ +---------------------------------------------------+----------------+
 
 Version
 
@@ -88,19 +90,20 @@ Procedure Control Register
    procedure number depending on the procedure status field.
 
    Procedure Numbers:
-    0  - Abort in-progress procedure
-    1  - NOP
-    2  - Unsupported procedure
-    3  - Unsupported procedure
-    4  - Naples PHY - RESET
-    5  - Naples PHY - TX_ZCAL
-    6  - Naples PHY - RX_DCCAL
-    7  - Naples PHY - TX_RXCAL_ENABLE
-    8  - Naples PHY - TX_RXCAL_DISABLE
-    9  - Naples PHY - RX_TRAINING
-    10 - Naples NPU - RESET
-    11 - Naples PHY - PHY preterminate
-    12 - Naples PHY - PHY terminated
+
+    0. Abort in-progress procedure
+    1. NOP
+    2. Unsupported procedure
+    3. Unsupported procedure
+    4. Naples PHY - RESET
+    5. Naples PHY - TX_ZCAL
+    6. Naples PHY - RX_DCCAL
+    7. Naples PHY - TX_RXCAL_ENABLE
+    8. Naples PHY - TX_RXCAL_DISABLE
+    9. Naples PHY - RX_TRAINING
+    10. Naples NPU - RESET
+    11. Naples PHY - PHY preterminate
+    12. Naples PHY - PHY terminated
 
    Procedure 5 (TX_ZCAL) should only be run once. System firmware will
    ensure this so device drivers may call this procedure mutiple
@@ -142,7 +145,7 @@ Reserved
    These fields must be ignored and no value should be assumed.
 
 Interrupts
-----------
+^^^^^^^^^^
 
 Each link has a single DL/TL interrupt assigned to it. These will be
 exposed as an LSI via the emulated PCI device. There are 4 links
@@ -150,8 +153,7 @@ consuming 4 LSI interrupts. The 4 remaining interrupts supported by the
 corresponding PHB will be routed to OS platform for the purpose of error
 reporting.
 
-====================
 Device Tree Bindings
-====================
+--------------------
 
 See doc/device-tree/nvlink.txt
diff --git a/doc/opal-spec.rst b/doc/opal-spec.rst
index ea76e59..eca8472 100644
--- a/doc/opal-spec.rst
+++ b/doc/opal-spec.rst
@@ -1,9 +1,9 @@
 OPAL Specification
 ==================
 
-DRAFT - VERSION 0.0.1 AT BEST.
+**DRAFT - VERSION 0.0.1 AT BEST.**
 
-COMMENTS ARE WELCOME - and indeed, needed.
+**COMMENTS ARE WELCOME** - and indeed, needed.
 
 If you are reading this, congratulations: you're now reviewing it!
 
@@ -34,21 +34,27 @@ POWER systems. There are several components to what makes up a firmware
 image for OpenPower machines.
 
 For example, there may be:
-- BMC firmware
-  - Firmware that runs purely on the BMC.
-  - On IBM systems that have an FSP rather than a BMC, there is FSP firmware
-  - While essential to having the machine function, this firmware is not
+
+* BMC firmware
+
+  * Firmware that runs purely on the BMC.
+  * On IBM systems that have an FSP rather than a BMC, there is FSP firmware
+  * While essential to having the machine function, this firmware is not
     part of the OPAL Specification.
-- HostBoot
-  - HostBoot ( https://github.com/open-power/hostboot ) performs all
+* HostBoot
+
+  * HostBoot ( https://github.com/open-power/hostboot ) performs all
     processor, bus and memory initialization within IBM POWER based systems.
-- OCC Firmware
-  - On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
+* OCC Firmware
+
+  * On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
     POWER8 in charge of keeping the system thermally and power safe ).
-- SkiBoot
-  - Boot and runtime services.
-- A linux kernel and initramfs incorporating petitboot
-  - The bootloader. This is where a user chooses what OS to boot, and
+* SkiBoot
+
+  * Boot and runtime services.
+* A linux kernel and initramfs incorporating petitboot
+
+  * The bootloader. This is where a user chooses what OS to boot, and
     petitboot will use kexec to switch to the host Operating System
     (for example, PowerKVM).
 
@@ -66,15 +72,17 @@ Operating System. It does not dictate that any specific pieces of firmware
 code be used, although re-inventing the wheel is strongly discouraged.
 
 The OPAL Specification explicitly allows for:
-- A conforming implementation to not use any of the reference implementation
+
+* A conforming implementation to not use any of the reference implementation
   code.
-- A conforming implementation to use any 64bit POWER ISA conforming processor,
+* A conforming implementation to use any 64bit POWER ISA conforming processor,
   and not be limited to the IBM POWER8.
-- A conforming implementation to be a simulator, emulator or virtual environment
-- A host OS other than Linux
+* A conforming implementation to be a simulator, emulator or virtual environment
+* A host OS other than Linux
 
 Explicitly not covered in this specification:
-- A 32bit OPAL Specification
+
+* A 32bit OPAL Specification
   There is no reason this couldn't exist but the current specification is for
   64bit POWER systems only.
 
@@ -93,32 +101,38 @@ The OPAL Specification explicitly allows variation in this payload.
 
 A requirement of the payload is that it MUST support loading and booting
 an uncomppressed vmlinux Linux kernel.
-[TODO: expand on what this actually means]
+[**TODO**: expand on what this actually means]
 
 An OPAL system MUST pass a device tree to the host kernel.
-[TODO: expand the details, add device-tree section and spec]
+[**TODO**: expand the details, add device-tree section and spec]
 
 An OPAL system MUST provide the host kernel with enough information to
 know how to call OPAL runtime services.
-[TODO: expand on this. ]
+[**TODO**: expand on this. ]
 
 Explicitly not covered by the OPAL Specification:
-- Kernel module ABI for skiroot kernel
-- Userspace environment of skiroot
-- That skiroot is Linux.
+
+* Kernel module ABI for skiroot kernel
+* Userspace environment of skiroot
+* That skiroot is Linux.
 
 Explicitly allowed:
-- Replacing the payload with something of equal/similar functionality
+
+* Replacing the payload with something of equal/similar functionality
   (weather replacing skiroot with an implementation of Zork would be compliant
-   is left as an exercise for the reader)
+  is left as an exercise for the reader)
 
 Payload Environment
 -------------------
 The payload is started with:
-r3 = address of flattened device-tree (fdt)
-r8 = OPAL base
-r9 = OPAL entry
 
+======== =====
+Register Value
+======== =====
+r3       address of flattened device-tree (fdt)
+r8       OPAL base
+r9       OPAL entry
+======== =====
 
 Runtime Services
 ----------------
@@ -143,12 +157,13 @@ All parameters to OPAL calls are big endian. Little endian hosts MUST
 appropriately convert parameters before passing them to OPAL.
 
 Machine state across OPAL calls:
-- r1 is preserved
-- r12 is scratch
-- r13 - 31 preserved
-- 64bit HV real mode
-- big endian
-- external interrupts disabled
+
+* r1 is preserved
+* r12 is scratch
+* r13 - 31 preserved
+* 64bit HV real mode
+* big endian
+* external interrupts disabled
 
 Detecting OPAL Support
 ----------------------
@@ -165,14 +180,14 @@ The presence of the "/ibm,opal" entry in the device tree signifies running
 under OPAL. Additionally, the "/ibm,opal" node MUST have a compatibile property
 listing "ibm,opal-v3".
 
-The "/ibm,opal" node MUST have the following properties:
+The "/ibm,opal" node MUST have the following properties: ::
 
-ibm,opal {
+ ibm,opal {
 	  compatible = "ibm,opal-v3";
 	  opal-base-address = <>;
 	  opal-entry-address = <>;
 	  opal-runtime-size = <>;
-}
+ }
 
 The compatible property MAY have other strings, such as a future "ibm,opal-v4".
 These are reserved for future use.
@@ -182,11 +197,11 @@ contain "ibm,opal-v2" as well as "ibm,opal-v3". Host operating systems MUST
 NOT rely on "ibm,opal-v2", this is a relic from early OPAL history.
 
 The "ibm,opal" node MUST have a child node named "firmware". It MUST contain
-the following:
+the following: ::
 
-firmware {
+ firmware {
 	 compatible = "ibm,opal-firmware";
-}
+ }
 
 It MUST contain one of the following two properties: git-id, version.
 The git-id property is deprecated, and version SHOULD be used. These
diff --git a/doc/overview.rst b/doc/overview.rst
index 760f391..e324ca2 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -6,6 +6,10 @@ it provides some runtime services to the OS (typically Linux).
 
 Source layout
 -------------
+
+========= ===================================
+Directory Content
+========= ===================================
 asm/	  small amount, mainly entry points
 ccan/	  bits from CCAN
 core/	  common code among machines.
@@ -17,6 +21,7 @@ include/  headers!
 libc/ 	  tiny libc, from SLOF
 libfdt/   straight device tree lib
 libpore/  to manipulate PORE engine.
+========= ===================================
 
 We have a spinlock implementation in asm/lock.S
 Entry points are detailed in asm/head.S
@@ -26,9 +31,13 @@ Binaries
 --------
 The following binaries are built:
 
-skiboot.lid: is the actual lid. objdump out
-skiboot.elf: is the elf binary of it, lid comes from this
-skiboot.map: plain map of symbols
+=========== ============================================
+File        Purpose
+=========== ============================================
+skiboot.lid is the actual lid. objdump out
+skiboot.elf is the elf binary of it, lid comes from this
+skiboot.map plain map of symbols
+=========== ============================================
 
 Booting
 -------
@@ -65,7 +74,7 @@ At the bottom of each stack area is a per CPU data structure, which we
 can get to by chopping off the LSBs of the stack pointer.
 
 The OPAL interface is a generic message queue. The Linux side of things
-can be found in linux/arch/powerpc/platform/powernv/opal-*.c
+can be found in linux/arch/powerpc/platform/powernv/
 
 Interrupts
 ----------
@@ -99,11 +108,12 @@ should be used sparingly though.
 
 Important memory locations:
 
-SKIBOOT_BASE - where we sit
-
-HEAP_BASE,
-HEAP_SIZE - the location and size for heap. We reserve 4MB for
-	    initial allocations.
+============= ============================================================
+Location      What's there
+============= ============================================================
+SKIBOOT_BASE  where skiboot lives, of SKIBOOT_SIZE
+HEAP_BASE     Where skiboot heap starts, of HEAP_SIZE
+============= ============================================================
 
 There is also SKIBOOT_SIZE (manually calculated) and DEVICE_TREE_MAX_SIZE,
 which is largely historical.
diff --git a/doc/pci-slot.rst b/doc/pci-slot.rst
index 1b64f69..e76fba1 100644
--- a/doc/pci-slot.rst
+++ b/doc/pci-slot.rst
@@ -1,5 +1,5 @@
-Overview
-========
+PCI Slots
+=========
 
 The PCI slots are instantiated to represent their associated properties and
 operations. The slot properties are exported to OS through the device tree
@@ -26,11 +26,14 @@ The operation set supplied by the template might be overrided and reimplemented,
 partially. It's usually done according to the VPD figured out by individual platforms.
 
 PCI Slot Operations
-===================
+-------------------
 
 The following operations are supported to one particular PCI slot. More details
 could be found from the definition of struct pci_slot_ops:
 
+===================== ==========
+Operation             Definition
+===================== ==========
 get_presence_state    Check if any adapter connected to slot
 get_link_state        Retrieve PCIE link status: up, down, link width
 get_power_state       Retrieve the power status: on, off
@@ -48,6 +51,7 @@ hreset                Hot reset
 poll                  Interface for OPAL API to drive internal state machine
 
 add_properties        Additional PCI slot properties seen by platform
+===================== ==========
 
 PCI Slot Properties
 ===================
@@ -57,16 +61,19 @@ node for a root port, a PCIE switch port, or a PCIE to PCIx bridge. If the
 individual platforms (e.g. Firenze and Apollo) have VPD for the PCI slot, they
 should extract the PCI slot properties from VPD and export them accordingly.
 
-ibm,reset-by-firmware  Boolean indicating whether the slot reset should be
-                       done in firmware
+====================== ==========
+Property               Definition
+====================== ==========
+ibm,reset-by-firmware  Boolean indicating whether the slot reset should be done in firmware
 ibm,slot-pluggable     Boolean indicating whether the slot is pluggable
 ibm,slot-power-ctl     Boolean indicating whether the slot has power control
 ibm,slot-wired-lanes   The number of hardware lanes that are wired
 ibm,slot-pwr-led-ctl   Presence of slot power led, and controlling entity
 ibm,slot-attn-led-ctl  Presence of slot ATTN led, and controlling entity
+====================== ==========
 
 PCI Hotplug
-===========
+-----------
 
 The implementation of PCI slot hotplug heavily relies on its power state.
 Initially, the slot is powered off if there are no adapters behind it.
@@ -98,7 +105,7 @@ The API call will return OPAL_SUCCESS immediately and no further asynchronous
 message will be sent.
 
 PCI Slot on Apollo and Firenze
-==============================
+------------------------------
 
 On IBM's Apollo and Firenze platform, the PCI VPD is fetched from dedicated LID,
 which is organized in so-called 1004, 1005, or 1006 format. 1006 mapping format
@@ -115,5 +122,9 @@ power management entity doesn't exist.
 For Apollo and Firenze platform, following PCI slot properties are exported through
 PCI device tree node except those generic properties (as above):
 
+======================= ==========
+Property                Definition
+======================= ==========
 ibm,slot-location-code  System location code string for the slot connector
 ibm,slot-label          Slot label, part of "ibm,slot-location-code"
+======================= ==========
diff --git a/doc/pci.rst b/doc/pci.rst
index a139176..5ccfd6e 100644
--- a/doc/pci.rst
+++ b/doc/pci.rst
@@ -1,71 +1,61 @@
+PCI
+===
+
+**WARNING**: This documentation **urgently needs updating** and is *woefully* incomplete.
+
 IODA PE Setup Sequences
 -----------------------
 
-(WARNING: this was rescued from old internal documentation. Needs verification)
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
 
 To setup basic PE mappings, the host performs this basic sequence:
 
-    For ibm,opal-ioda2, prior to allocating PHB resources to PEs, the host must
-    allocate memory for PE structures and then calls
-    opal_pci_set_phb_table_memory( phb_id, rtt_addr, ivt_addr, ivt_len,
-    rrba_addr, peltv_addr) to define them to the PHB. OPAL returns
-    OPAL_UNSUPPORTED status for ibm,opal-ioda PHBs.
+For ibm,opal-ioda2, prior to allocating PHB resources to PEs, the host must
+allocate memory for PE structures and then calls
+``opal_pci_set_phb_table_memory( phb_id, rtt_addr, ivt_addr, ivt_len, rrba_addr, peltv_addr)`` to define them to the PHB. OPAL returns ``OPAL_UNSUPPORTED`` status for ``ibm,opal-ioda`` PHBs.
 
-    The host calls opal_pci_set_pe( phb_id, pe_number, bus, dev, func,
-    validate_mask, bus_mask, dev_mask, func mask) to map a PE to a PCI RID or
-    range of RIDs in the same PE domain.
+The host calls ``opal_pci_set_pe( phb_id, pe_number, bus, dev, func, validate_mask, bus_mask, dev_mask, func mask)`` to map a PE to a PCI RID or range of RIDs in the same PE domain.
 
-    The host calls opal_pci_set_peltv(phb_id, parent_pe, child_pe, state) to
-    set a parent PELT vector bit for the child PE argument to 1 (a child of the
-    parent) or 0 (not in the parent PE domain).
+The host calls ``opal_pci_set_peltv(phb_id, parent_pe, child_pe, state)`` to
+set a parent PELT vector bit for the child PE argument to 1 (a child of the
+parent) or 0 (not in the parent PE domain).
 
 IODA MMIO Setup Sequences
 -------------------------
 
-(WARNING: this was rescued from old internal documentation. Needs verification)
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
 
 
-    The host calls opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x0) to disable the MMIO window.
+The host calls ``opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x0)`` to disable the MMIO window.
 
-    The host calls opal_pci_set_phb_mmio_window( phb_id, mmio_window, starting_real_address, starting_pci_address, segment_size) to change the MMIO window location in PCI and/or processor real address space, or to change the size -- and corresponding window size -- of a particular MMIO window.
+The host calls ``opal_pci_set_phb_mmio_window( phb_id, mmio_window, starting_real_address, starting_pci_address, segment_size)`` to change the MMIO window location in PCI and/or processor real address space, or to change the size -- and corresponding window size -- of a particular MMIO window.
 
-    The host calls opal_pci_map_pe_mmio_window( pe_number, mmio_window, segment_number) to map PEs to window segments, for each segment mapped to each PE.
+The host calls ``opal_pci_map_pe_mmio_window( pe_number, mmio_window, segment_number)`` to map PEs to window segments, for each segment mapped to each PE.
 
-    The host calls opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x1) to enable the MMIO window.
+The host calls ``opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x1)`` to enable the MMIO window.
 
 IODA MSI Setup Sequences
 ------------------------
 
-(WARNING: this was rescued from old internal documentation. Needs verification)
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
 
 To setup MSIs:
 
+1. For ibm,opal-ioda PHBs, the host chooses an MVE for a PE to use and calls ``opal_pci_set_mve( phb_id, mve_number, pe_number,)`` to setup the MVE for the PE number. HAL treats this call as a NOP and returns hal_success status for ibm,opal-ioda2 PHBs.
+2. The host chooses an XIVE to use with a PE and calls
+   a. ``opal_pci_set_xive_pe( phb_id, xive_number, pe_number)`` to authorize that PE to signal that XIVE as an interrupt. The host must call this function for each XIVE assigned to a particular PE, but may use this call for all XIVEs prior to calling ``opel_pci_set_mve()`` to bind the PE XIVEs to an MVE. For MSI conventional, the host must bind a unique MVE for each sequential set of 32 XIVEs.
+   b. The host forms the interrupt_source_number from the combination of the device tree MSI property base BUID and XIVE number, as an input to ``opal_set_xive(interrupt_source_number, server_number, priority)`` and ``opal_get_xive(interrupt_source_number, server_number, priority)`` to set or return the server and priority numbers within an XIVE.
+   c. ``opal_get_msi_64[32](phb_id, mve_number, xive_num, msi_range, msi_address, message_data)`` to determine the MSI DMA address (32 or 64 bit) and message data value for that xive.
 
-1.    For ibm,opal-ioda PHBs, the host chooses an MVE for a PE to use and calls opal_pci_set_mve( phb_id, mve_number, pe_number,) to setup the MVE for the PE number. HAL treats this call as a NOP and returns hal_success status for ibm,opal-ioda2 PHBs.
-
-2.    the host chooses an XIVE to use with a PE and calls
-
-      a. opal_pci_set_xive_pe( phb_id, xive_number, pe_number) to authorize that PE to signal that XIVE as an interrupt. The host must call this function for each XIVE assigned to a particular PE, but may use this call for all XIVEs prior to calling opel_pci_set_mve() to bind the PE XIVEs to an MVE.For MSI conventional, the host must bind a unique MVE for each sequential set of 32 XIVEs.
-
-      b. The host forms the interrupt_source_number from the combination of the device tree MSI property base BUID and XIVE number, as an input to opal_set_xive(interrupt_source_number, server_number, priority) and opal_get_xive(interrupt_source_number, server_number, priority) to set or return the server and priority numbers within an XIVE.
-
-      c. opal_get_msi_64[32](phb_id, mve_number, xive_num, msi_range, msi_address, message_data) to determine the MSI DMA address (32 or 64 bit) and message data value for that xive.
-
-        For MSI conventional, the host uses this for each sequential power of 2 set of 1 to 32 MSIs, to determine the MSI DMA address and starting message data value for that MSI range. For MSI-X, the host calls this uniquely for each MSI interrupt with an msi_range input value of 1.
-
-
-3.    For ibm,opal-ioda PHBs, once the MVE and XIVRs are setup for a PE, the host calls opal_pci_set_mve_enable( phb_id, mve_number, state)to enable that MVE to be a valid target of MSI DMAs. The host may also call this function to disable an MVE when changing PE domains or states.
+      For MSI conventional, the host uses this for each sequential power of 2 set of 1 to 32 MSIs, to determine the MSI DMA address and starting message data value for that MSI range. For MSI-X, the host calls this uniquely for each MSI interrupt with an msi_range input value of 1.
+3. For ``ibm,opal-ioda`` PHBs, once the MVE and XIVRs are setup for a PE, the host calls ``opal_pci_set_mve_enable( phb_id, mve_number, state)`` to enable that MVE to be a valid target of MSI DMAs. The host may also call this function to disable an MVE when changing PE domains or states.
 
 IODA DMA Setup Sequences
 ------------------------
 
-(WARNING: this was rescued from old internal documentation. Needs verification)
-
-
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
 
 To Manage DMA Windows :
 
-
-1.    The host calls opal_pci_map_pe_dma_window( phb_id, dma_window_number, pe_number, tce_levels, tce_table_addr, tce_table_size, tce_page_size, utin64_t* pci_start_addr ) to setup a DMA window for a PE to translate through a TCE table structure in KVM memory.
-
-2.    The host calls opal_pci_map_pe_dma_window_real( phb_id, dma_window_number, pe_number, mem_low_addr, mem_high_addr) to setup a DMA window for a PE that is translated (but validated by the PHB as an untranlsated address space authorized to this PE).
+1. The host calls ``opal_pci_map_pe_dma_window( phb_id, dma_window_number, pe_number, tce_levels, tce_table_addr, tce_table_size, tce_page_size, utin64_t* pci_start_addr )`` to setup a DMA window for a PE to translate through a TCE table structure in KVM memory.
+2. The host calls ``opal_pci_map_pe_dma_window_real( phb_id, dma_window_number, pe_number, mem_low_addr, mem_high_addr)`` to setup a DMA window for a PE that is translated (but validated by the PHB as an untranlsated address space authorized to this PE).
diff --git a/doc/stable-skiboot-rules.rst b/doc/stable-skiboot-rules.rst
index 1db47a3..bf4f5f0 100644
--- a/doc/stable-skiboot-rules.rst
+++ b/doc/stable-skiboot-rules.rst
@@ -1,5 +1,5 @@
 Stable Skiboot tree/releases
-----------------------------
+============================
 
 If you're at all familiar with the Linux kernel stable trees, this should
 seem fairly familiar.
@@ -15,48 +15,64 @@ with my IBMer hat on, we'll maintain branches that we ship in products.
 What patches are accepted?
 --------------------------
 
-- Patches must be obviously correct and tested
-  - A Tested-by signoff is *important*
-- A patch must fix a real bug
-- No trivial patches, such fixups belong in main branch
-- Not fix a purely theoretical problem unless you can prove how
+* Patches must be obviously correct and tested
+
+  * A Tested-by signoff is *important*
+* A patch must fix a real bug
+* No trivial patches, such fixups belong in main branch
+* Not fix a purely theoretical problem unless you can prove how
   it's exploitable
-- The patch, or an equivalent one, must already be in master
-  - Submitting to both at the same time is okay, but backporting is better
+* The patch, or an equivalent one, must already be in master
+
+  * Submitting to both at the same time is okay, but backporting is better
 
 HOWTO submit to stable
 ----------------------
 Two ways:
-1) Send patch to the skiboot@ list with "[PATCH stable]" in subject
-   - This targets the patch *ONLY* to the stable branch.
-      - Such commits will *NOT* be merged into master.
-   - Use this when:
-     a) cherry-picking a fix from master
-     b) fixing something that is only broken in stable
-     c) fix in stable needs to be completely different than in master
+1. Send patch to the skiboot@ list with "[PATCH stable]" in subject
+
+   * This targets the patch *ONLY* to the stable branch.
+
+     * Such commits will *NOT* be merged into master.
+   * Use this when:
+
+     a. cherry-picking a fix from master
+     b. fixing something that is only broken in stable
+     c. fix in stable needs to be completely different than in master
+
      If b or c: explain why.
-   - If cherry-picking, include the following at the top of your
-     commit message:
-        commit <sha1> upstream.
-   - If the patch has been modified, explain why in description.
-
-2) Add "Cc: stable" above your Signed-off-by line when sending to skiboot@
-   - This targets the patch to master and stable.
-   - You can target a patch to a specific stable tree with:
-       Cc: stable # 5.1.x
+   * If cherry-picking, include the following at the top of your
+     commit message: ::
+
+       commit <sha1> upstream.
+   * If the patch has been modified, explain why in description.
+
+2. Add "Cc: stable" above your Signed-off-by line when sending to skiboot@
+
+   * This targets the patch to master and stable.
+   * You can target a patch to a specific stable tree with: ::
+
+      Cc: stable # 5.1.x
+
      and that will target it to the 5.1.x branch.
-   - You can ask for prerequisites to be cherry-picked:
-       Cc: stable # 5.1.x 55ae15b Ensure we run pollers in cpu_wait_job()
-       Cc: stable # 5.1.x
+   * You can ask for prerequisites to be cherry-picked: ::
+
+        Cc: stable # 5.1.x 55ae15b Ensure we run pollers in cpu_wait_job()
+        Cc: stable # 5.1.x
+
      Which means:
-       1) please git cherry-pick 55ae15b
-       2) then apply this patch to 5.1.x".
+
+       1. please ``git cherry-pick 55ae15b``
+       2. then apply this patch to 5.1.x".
 
 Trees
 -----
-- https://github.com/open-power/skiboot/tree/stable
-  git@github.com:open-power/skiboot.git (branches are skiboot-X.Y.x - e.g. skiboot-5.1.x)
 
-- Some stable versions may last longer than others
-  - So there may be skiboot-5.1.x and skiboot-5.2.x actively maintained
+* https://github.com/open-power/skiboot/tree/stable (or via ssh at ``git@github.com:open-power/skiboot.git`` )
+
+  * (branches are skiboot-X.Y.x - e.g. skiboot-5.1.x)
+
+* Some stable versions may last longer than others
+
+  * So there may be skiboot-5.1.x and skiboot-5.2.x actively maintained
     and skiboot-5.1.x could possibly outlast skiboot-5.2.x
diff --git a/doc/versioning.rst b/doc/versioning.rst
index 2bbad69..64ccc2c 100644
--- a/doc/versioning.rst
+++ b/doc/versioning.rst
@@ -5,10 +5,11 @@ History
 -------
 For roughly the first six months of public life, skiboot just presented a
 git SHA1 as a version "number". This was "user visible" in two places:
-1) /sys/firmware/opal/msglog
-   the familiar "SkiBoot 71664fd-dirty starting..." message
-2) device tree:
-   /proc/device-tree/ibm,opal/firmware/git-id
+
+1. ``/sys/firmware/opal/msglog``
+   the familiar ``SkiBoot 71664fd-dirty starting...`` message
+2. device tree:
+   ``/proc/device-tree/ibm,opal/firmware/git-id``
 
 Builds were also referred to by date and by corresponding PowerKVM release.
 Clearly, this was unlikely to be good practice going forward.
@@ -27,10 +28,11 @@ only times you need to do something is if you are a) making an upstream
 skiboot release or b) building firmware to release for your platform(s).
 
 OPAL/skiboot has several consumers, for example:
-- IBM shipping POWER8 systems with an FSP (FW810.XX and future)
-- OpenPower
-- OpenPower partners manufacturing OpenPower systems
-- developers, test and support needing to understand what code a system
+
+* IBM shipping POWER8 systems with an FSP (FW810.XX and future)
+* OpenPower
+* OpenPower partners manufacturing OpenPower systems
+* developers, test and support needing to understand what code a system
   is running
 
 and there are going to be several concurrent maintained releases in the wild,
@@ -38,38 +40,39 @@ likely build by different teams of people at different companies.
 
 tl;dr; is you're likely going to see version numbers like this (for the
 hypothetical platforms 'ketchup' and 'mustard'):
-skiboot-4.0-ketchup-0
-skiboot-4.0-ketchup-1
-skiboot-4.1-mustard-4
-skiboot-4.1-ketchup-0
+
+* ``skiboot-4.0-ketchup-0``
+* ``skiboot-4.0-ketchup-1``
+* ``skiboot-4.1-mustard-4``
+* ``skiboot-4.1-ketchup-0``
 
 If you see *extra* things on the end of the version, then you're running
 a custom build from a developer
-(e.g. 'skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40' means something to
+(e.g. ``skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40`` means something to
 us - explained below).
 
-If you see less, for example 'skiboot-4.0', then you're running a build
+If you see less, for example ``skiboot-4.0``, then you're running a build
 directly out of the main git tree. Those producing OPAL builds for users
 must *not* ship like this, even if the tree is identical.
 
-Here are the components of the version string from master:
-
-skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40
-^       ^^^ ^  ^^^^^^^ ^-------^    ^      ^   ^^^^^^^
-|        |  |     |        |        |      |      |
-|        |  |     |        |         \    /        - 'git diff|sha1sum'
-|        |  |     |        |          \  /
-|        |  |     |        |            - built from a dirty tree of $USER
-|        |  |     |        |
-|        |  |     |         - $EXTRA_VERSION (optional)
-|        |  |     |
-|        |  |      - git SHA1 of commit built
-|        |  |
-|        |   - commits head of skiboot-4.0 tag
-|        |
-|         - skiboot version number ---\
-|                                      >--  from  the 'skiboot-4.0' git tag
- - product name (always skiboot)   ---/
+Here are the components of the version string from master: ::
+
+ skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40
+ ^       ^^^ ^  ^^^^^^^ ^-------^    ^      ^   ^^^^^^^
+ |        |  |     |        |        |      |      |
+ |        |  |     |        |         \    /        - 'git diff|sha1sum'
+ |        |  |     |        |          \  /
+ |        |  |     |        |            - built from a dirty tree of $USER
+ |        |  |     |        |
+ |        |  |     |         - $EXTRA_VERSION (optional)
+ |        |  |     |
+ |        |  |      - git SHA1 of commit built
+ |        |  |
+ |        |   - commits head of skiboot-4.0 tag
+ |        |
+ |         - skiboot version number ---\
+ |                                      >--  from  the 'skiboot-4.0' git tag
+  - product name (always skiboot)   ---/
 
 
 When doing a release for a particular platform, you are expected to create
@@ -77,19 +80,19 @@ and tag a branch from master. For the (hypothetical) ketchup platform which
 is going to do a release based on skiboot-4.0, you would create a tag
 'skiboot-4.0-ketchup-0' pointing to the same revision as the 'skiboot-4.0' tag
 and then make any additional modifications to skiboot that were not in the 4.0
-release. So, you could ship a skiboot with the following version string:
-
-skiboot-4.0-ketchup-1
-^       ^^^ ^       ^
-|        |  |       |
-|        |  |        - revision for this platform
-|        |  |      
-|        |  |
-|        |   - Platform name/version
-|        |
-|         - skiboot version number
-|
- - product name (always skiboot)
+release. So, you could ship a skiboot with the following version string: ::
+
+ skiboot-4.0-ketchup-1
+ ^       ^^^ ^       ^
+ |        |  |       |
+ |        |  |        - revision for this platform
+ |        |  |      
+ |        |  |
+ |        |   - Platform name/version
+ |        |
+ |         - skiboot version number
+ |
+  - product name (always skiboot)
 
 This version string tells your users to expect what is in skiboot-4.0 plus
 some revisions for your platform.
diff --git a/doc/xscom-node-bindings.rst b/doc/xscom-node-bindings.rst
index 0c2545e..0fd5e93 100644
--- a/doc/xscom-node-bindings.rst
+++ b/doc/xscom-node-bindings.rst
@@ -1,18 +1,22 @@
+XSCOM Bindings
+==============
+
 XSCOM regions
-=============
+-------------
 
 The top-level xscom nodes specify the mapping range from the 64-bit address
 space into the PCB address space.
 
 There's one mapping range per chip xscom, therefore one node per mapping range.
+::
 
-/
-/xscom@<chip-base-address-0>/
-/xscom@<chip-base-address-1>/
-…
-/xscom@<chip-base-address-n>/
+ /
+ /xscom@<chip-base-address-0>/
+ /xscom@<chip-base-address-1>/
+ …
+ /xscom@<chip-base-address-n>/
 
-- where <chip-base-address-n> is the xscom base address with the gcid-specific
+* where <chip-base-address-n> is the xscom base address with the gcid-specific
   bits (for chip n) OR-ed in.
 
 Each xscom node has the following properties:
@@ -25,17 +29,18 @@ Each xscom node has the following properties:
 
 
 Chiplet endpoints
-=================
+-----------------
 
 One sub-node per endpoint. Endpoints are defined by their (port,
 endpoint-address) data on the PCB, and are named according to their endpoint
 types:
+::
 
-/xscom@<chip-base-address>/
-/xscom@<chip-base-address>/chiptod@<endpoint-addr>
-/xscom@<chip-base-address>/lpc@<endpoint-addr>
+ /xscom@<chip-base-address>/
+ /xscom@<chip-base-address>/chiptod@<endpoint-addr>
+ /xscom@<chip-base-address>/lpc@<endpoint-addr>
 
-- where the <endpoint-addr> is a single address (as distinct from the current
+* where the <endpoint-addr> is a single address (as distinct from the current
   (gcid,base) format), consisting of the SCOM port and SCOM endpoint bits in
   their 31-bit address format.
 
@@ -46,12 +51,13 @@ Each endpoint node has the following properties:
 
 The endpoint address specifies the address on the PCB. So, to calculate the
 MMIO address for a PCB register:
+::
 
 	mmio_addr  = <xscom-base-addr> | (pcb_addr[1:27] << 4)
 				       | (pcb_addr[28:31] << 3)
 
 Where:
 
-  - xscom-base-addr is the address from the first two cells of the parent
+  * xscom-base-addr is the address from the first two cells of the parent
     node's reg property
-  - pcb_addr is the first cell of the endpoint's reg property 
+  * pcb_addr is the first cell of the endpoint's reg property