[Skiboot] [RFC PATCH 16/23] opal-api/: Fix ReStructured Text syntax
Stewart Smith
stewart at linux.vnet.ibm.com
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
More information about the Skiboot
mailing list