From 24e7fd3aa79697c019f215e1dd1a270b1b014e89 Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Wed, 27 Jul 2016 17:43:17 +1000 Subject: opal-api/: Fix ReStructured Text syntax Signed-off-by: Stewart Smith --- 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@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 + + -- cgit v1.1