diff options
author | Stewart Smith <stewart@linux.vnet.ibm.com> | 2016-07-27 17:43:17 +1000 |
---|---|---|
committer | Stewart Smith <stewart@linux.vnet.ibm.com> | 2016-08-02 18:12:48 +1000 |
commit | 24e7fd3aa79697c019f215e1dd1a270b1b014e89 (patch) | |
tree | 042dfc33ca690648456edc4fc25cfff2a82ef439 | |
parent | 925dff3660f9993e655ce45320ec294f8826f7cf (diff) | |
download | skiboot-24e7fd3aa79697c019f215e1dd1a270b1b014e89.zip skiboot-24e7fd3aa79697c019f215e1dd1a270b1b014e89.tar.gz skiboot-24e7fd3aa79697c019f215e1dd1a270b1b014e89.tar.bz2 |
opal-api/: Fix ReStructured Text syntax
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>
-rw-r--r-- | doc/opal-api/power9-changes.rst | 19 | ||||
-rw-r--r-- | 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@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@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 + + |