[Skiboot] [RFC PATCH 16/23] opal-api/: Fix ReStructured Text syntax

Wed Jul 27 17:43:17 AEST 2016

Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
 doc/opal-api/power9-changes.rst |  19 ++---
 doc/opal-api/return-codes.rst   | 156 ++++++++++++++++++++++++++++++++--------
 2 files changed, 137 insertions(+), 38 deletions(-)

diff --git a/doc/opal-api/power9-changes.rst b/doc/opal-api/power9-changes.rst
index 72c4885..838b84c 100644
--- a/doc/opal-api/power9-changes.rst
+++ b/doc/opal-api/power9-changes.rst
@@ -1,5 +1,5 @@
 POWER9 Changes to OPAL API
---------------------------
+==========================
 
 This document is a summary of POWER9 changes to the OPAL API over what it
 was for POWER7 and POWER8. As the POWER series of processors (at least up
@@ -17,17 +17,20 @@ POWER9, OPAL_UNSUPPORTED will be returned.
 
 Device Tree
 -----------
-- /ibm,opal/ compatible property now just lists ibm,opal-v3 and no longer
-  ibm,opal-v2 (power9 and above only)
+
+- ``/ibm,opal/`` compatible property now just lists ``ibm,opal-v3`` and no longer ``ibm,opal-v2`` (power9 and above only)
 
 
 TODO
 ----
 Things we still have to do for POWER9:
+
 - PCI to use async API rather than returning delays
 - deprecate/remove v1 APIs where there's a V2
-- Fix this FWTS warning:
-  FAILED [MEDIUM] DeviceTreeBaseDTCWarnings: Test 3, dtc reports warnings from
-  device tree: Warning (reg_format): "reg" property in /ibm,opal/flash at 0 has
-  invalid length (8 bytes) (#address-cells == 0, #size-cells == 0)
-- Remove mi-version / ml-version from /ibm,opal/firmware and replace with something better and more portable
+- Fix this FWTS warning: ::
+
+   FAILED [MEDIUM] DeviceTreeBaseDTCWarnings: Test 3, dtc reports warnings from
+   device tree: Warning (reg_format): "reg" property in /ibm,opal/flash at 0 has
+   invalid length (8 bytes) (#address-cells == 0, #size-cells == 0)
+
+- Remove mi-version / ml-version from ``/ibm,opal/firmware`` and replace with something better and more portable
diff --git a/doc/opal-api/return-codes.rst b/doc/opal-api/return-codes.rst
index e82c5a2..03ea5c1 100644
--- a/doc/opal-api/return-codes.rst
+++ b/doc/opal-api/return-codes.rst
@@ -1,5 +1,5 @@
 OPAL API Return Codes
----------------------
+=====================
 
 All OPAL calls return an integer relaying the success/failure of the OPAL
 call.
@@ -15,33 +15,87 @@ In the reference implementation (skiboot) these are all in include/opal.h.
 
 The core set of return codes are:
 
-#define OPAL_SUCCESS		0
+OPAL_SUCCESS
+------------
+::
+
+ #define OPAL_SUCCESS		0
+
 Success!
 
-#define OPAL_PARAMETER		-1
+OPAL_PARAMETER
+--------------
+::
+
+ #define OPAL_PARAMETER		-1
+
 A parameter was invalid. This will also be returned if you call an
 invalid OPAL call. To determine if a specific OPAL call is supported
 or not, OPAL_CHECK_TOKEN should be called rather than relying on
 OPAL_PARAMETER being returned for an invalid token.
 
-#define OPAL_BUSY		-2
+OPAL_BUSY
+---------
+::
+
+   #define OPAL_BUSY		-2
+
 Try again later.
 
-#define OPAL_PARTIAL		-3
+OPAL_PARTIAL
+------------
+::
+
+   #define OPAL_PARTIAL		-3
+
 The operation partially succeeded.
 
-#define OPAL_CONSTRAINED	-4
-#define OPAL_CLOSED		-5
-#define OPAL_HARDWARE		-6
+OPAL_CONSTRAINED
+----------------
+::
+
+   #define OPAL_CONSTRAINED	-4
+
+**FIXME**
+
+OPAL_CLOSED
+-----------
+::
+
+   #define OPAL_CLOSED		-5
+
+**FIXME** document these
+
+OPAL_HARDWARE
+-------------
+::
+
+   #define OPAL_HARDWARE		-6
+
+**FIXME** document these
+
+OPAL_UNSUPPORTED
+----------------
+::
+
+   #define OPAL_UNSUPPORTED	-7
 
-#define OPAL_UNSUPPORTED	-7
 Unsupported operation. Non-fatal.
 
-#define OPAL_PERMISSION		-8
+OPAL_PERMISSION
+---------------
+::
+
+   #define OPAL_PERMISSION		-8
+
 Inadequate permission to perform the operation.
 
+OPAL_NO_MEM
+-----------
+::
+
+   #define OPAL_NO_MEM		-9
 
-#define OPAL_NO_MEM		-9
 Indicates a temporary or permanent lack of adequate memory to perform the
 operation. Ideally, this should never happen. Skiboot reserves a small amount
 of memory for its heap and some operations (such as I2C requests) are allocated
@@ -50,16 +104,50 @@ from this heap.
 If this is ever hit, you should likely file a bug.
 
 
-#define OPAL_RESOURCE		-10
-#define OPAL_INTERNAL_ERROR	-11
-#define OPAL_BUSY_EVENT		-12
-#define OPAL_HARDWARE_FROZEN	-13
-#define OPAL_WRONG_STATE	-14
+OPAL_RESOURCE
+-------------
+::
+
+   #define OPAL_RESOURCE		-10
+
+**FIXME**
+
+OPAL_INTERNAL_ERROR
+-------------------
+::
+
+   #define OPAL_INTERNAL_ERROR	-11
+
+**FIXME**
+
+OPAL_BUSY_EVENT
+---------------
+::
+
+   #define OPAL_BUSY_EVENT		-12
+
+OPAL_HARDWARE_FROZEN
+--------------------
+::
+
+   #define OPAL_HARDWARE_FROZEN	-13
+
+OPAL_WRONG_STATE
+----------------
+::
+
+   #define OPAL_WRONG_STATE	-14
+
+OPAL_ASYNC_COMPLETION
+---------------------
+::
+
+   #define OPAL_ASYNC_COMPLETION	-15
 
-#define OPAL_ASYNC_COMPLETION	-15
 For asynchronous calls, successfully queueing/starting executing the
 command is indicated by the OPAL_ASYNC_COMPLETION return code.
-pseudo-code for an async call:
+pseudo-code for an async call: ::
+
   token = opal_async_get_token();
   rc = opal_async_example(foo, token);
   if (rc != OPAL_ASYNC_COMPLETION)
@@ -67,15 +155,23 @@ pseudo-code for an async call:
   rc = opal_async_wait(token);
   // handle result here
 
-#define OPAL_EMPTY		-16
-
-Added for I2C, only applicable to I2C calls:
-#define OPAL_I2C_TIMEOUT	-17
-#define OPAL_I2C_INVALID_CMD	-18
-#define OPAL_I2C_LBUS_PARITY	-19
-#define OPAL_I2C_BKEND_OVERRUN	-20
-#define OPAL_I2C_BKEND_ACCESS	-21
-#define OPAL_I2C_ARBT_LOST	-22
-#define OPAL_I2C_NACK_RCVD	-23
-#define OPAL_I2C_STOP_ERR	-24
- 
+OPAL_EMPTY
+----------
+::
+
+   #define OPAL_EMPTY		-16
+
+I2C Calls
+---------
+Added for I2C, only applicable to I2C calls: ::
+
+  #define OPAL_I2C_TIMEOUT	-17
+  #define OPAL_I2C_INVALID_CMD	-18
+  #define OPAL_I2C_LBUS_PARITY	-19
+  #define OPAL_I2C_BKEND_OVERRUN	-20
+  #define OPAL_I2C_BKEND_ACCESS	-21
+  #define OPAL_I2C_ARBT_LOST	-22
+  #define OPAL_I2C_NACK_RCVD	-23
+  #define OPAL_I2C_STOP_ERR	-24
+
+
-- 
2.7.4

