[Skiboot] [PATCH 001/110] doc: flesh out OPAL return codes documentation
Stewart Smith
stewart at linux.ibm.com
Fri May 31 16:12:02 AEST 2019
Ensure we can link to each return code, as well as document when each
one was introduced.
Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
doc/opal-api/return-codes.rst | 314 ++++++++++++++++++++++++++--
doc/release-notes/skiboot-5.1.0.rst | 2 +
2 files changed, 295 insertions(+), 21 deletions(-)
diff --git a/doc/opal-api/return-codes.rst b/doc/opal-api/return-codes.rst
index 8378ee1b6b0c..296675d5aed7 100644
--- a/doc/opal-api/return-codes.rst
+++ b/doc/opal-api/return-codes.rst
@@ -10,22 +10,116 @@ by a negative return code.
Conforming host Operating Systems MUST handle return codes other than those
listed here. In future OPAL versions, additional return codes may be added.
-In the reference implementation (skiboot) these are all in include/opal.h.
+In the reference implementation (skiboot) these are all in `include/opal-api.h`_
+
+.. _include/opal-api.h: https://github.com/open-power/skiboot/blob/master/include/opal-api.h
+
+There have been additions to the return codes from OPAL over time. A conforming
+host OS should gracefully handle receiving a new error code for existing calls.
+
+An OS running on a POWER8 system only has to know about error codes that existed
+when POWER8 with OPAL was introduced (indicated by YES in the POWER8 column below).
+Additional OPAL error codes *may be returned on POWER8 systems* and as such OSs
+need to gracefully handle unknown error codes.
+
+An OS running on POWER9 or above must handle all error codes as they were when
+POWER9 was introduced. We use the placeholder "v1.0" version for
+"since the dawn of time" even though there never was a skiboot v1.0
+
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| Name | Return Code | POWER8 GA | POWER9 GA | skiboot version where introduced |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_SUCCESS` | 0 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_PARAMETER` | -1 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_BUSY` | -2 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_PARTIAL` | -3 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_CONSTRAINED` | -4 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_CLOSED` | -5 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_HARDWARE` | -6 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_UNSUPPORTED` | -7 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_PERMISSION` | -8 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_NO_MEM` | -9 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_RESOURCE` | -10 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_INTERNAL_ERROR` | -11 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_BUSY_EVENT` | -12 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_HARDWARE_FROZEN` | -13 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_WRONG_STATE` | -14 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_ASYNC_COMPLETION` | -15 | YES | YES | v1.0 (initial release) |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_EMPTY` | -16 | NO | YES | v4.0 |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_TIMEOUT` | -17 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_INVALID_CMD` | -18 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_LBUS_PARITY` | -19 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_BKEND_OVERRUN` | -20 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_BKEND_ACCESS` | -21 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_ARBT_LOST` | -22 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_NACK_RCVD` | -23 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_I2C_STOP_ERR` | -24 | NO | YES | :ref:`skiboot-5.1.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_BUSY` | OPAL_BUSY | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_CHIPLET_OFF` | OPAL_WRONG_STATE | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_PARTIAL_GOOD` | -25 | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_ADDR_ERROR` | -26 | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_CLOCK_ERROR` | -27 | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_PARITY_ERROR` | -28 | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_TIMEOUT` | -29 | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XSCOM_CTR_OFFLINED` | -30 | NO | YES | :ref:`skiboot-5.4.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XIVE_PROVISIONING` | -31 | NO | YES | :ref:`skiboot-5.5.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_XIVE_FREE_ACTIVE` | -32 | NO | YES | :ref:`skiboot-5.5.0` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
+| :ref:`OPAL_TIMEOUT` | -33 | NO | YES | :ref:`skiboot-5.8` |
++--------------------------------+------------------+-----------+-----------+----------------------------------+
The core set of return codes are:
+.. _OPAL_SUCCESS:
+
OPAL_SUCCESS
------------
-::
+.. code-block:: c
#define OPAL_SUCCESS 0
Success!
+.. _OPAL_PARAMETER:
+
OPAL_PARAMETER
--------------
-::
+.. code-block:: c
#define OPAL_PARAMETER -1
@@ -34,66 +128,82 @@ 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.
+.. _OPAL_BUSY:
+
OPAL_BUSY
---------
-::
+.. code-block:: c
#define OPAL_BUSY -2
Try again later. Related to `OPAL_BUSY_EVENT`, but `OPAL_BUSY` indicates that the
caller need not call `OPAL_POLL_EVENTS` itself. **TODO** Clarify current situation.
+.. _OPAL_PARTIAL:
+
OPAL_PARTIAL
------------
-::
+.. code-block:: c
#define OPAL_PARTIAL -3
The operation partially succeeded.
+.. _OPAL_CONSTRAINED:
+
OPAL_CONSTRAINED
----------------
-::
+.. code-block:: c
#define OPAL_CONSTRAINED -4
**FIXME**
+.. _OPAL_CLOSED:
+
OPAL_CLOSED
-----------
-::
+.. code-block:: c
#define OPAL_CLOSED -5
**FIXME** document these
+.. _OPAL_HARDWARE:
+
OPAL_HARDWARE
-------------
-::
+.. code-block:: c
#define OPAL_HARDWARE -6
**FIXME** document these
+.. _OPAL_UNSUPPORTED:
+
OPAL_UNSUPPORTED
----------------
-::
+.. code-block:: c
#define OPAL_UNSUPPORTED -7
Unsupported operation. Non-fatal.
+.. _OPAL_PERMISSION:
+
OPAL_PERMISSION
---------------
-::
+.. code-block:: c
#define OPAL_PERMISSION -8
Inadequate permission to perform the operation.
+.. _OPAL_NO_MEM:
+
OPAL_NO_MEM
-----------
-::
+.. code-block:: c
#define OPAL_NO_MEM -9
@@ -104,10 +214,11 @@ from this heap.
If this is ever hit, you should likely file a bug.
+.. _OPAL_RESOURCE:
OPAL_RESOURCE
-------------
-::
+.. code-block:: c
#define OPAL_RESOURCE -10
@@ -116,33 +227,41 @@ While OPAL_BUSY indicates that OPAL may soon be able to proces the requent,
OPAL_RESOURCE is a more permanent error and while the resource *may* become
available again in the future, it is not certain that it will.
+.. _OPAL_INTERNAL_ERROR:
+
OPAL_INTERNAL_ERROR
-------------------
-::
+.. code-block:: c
#define OPAL_INTERNAL_ERROR -11
Something has gone wrong inside OPAL. This is likely a bug somewhere and we
return OPAL_INTERNAL_ERROR for safety.
+.. _OPAL_BUSY_EVENT:
+
OPAL_BUSY_EVENT
---------------
-::
+.. code-block:: c
#define OPAL_BUSY_EVENT -12
The same as `OPAL_BUSY` but signals that the OS should call `OPAL_POLL_EVENTS` as
that may be required to get into a state where the call will succeed.
+.. _OPAL_HARDWARE_FROZEN:
+
OPAL_HARDWARE_FROZEN
--------------------
-::
+.. code-block:: c
#define OPAL_HARDWARE_FROZEN -13
+.. _OPAL_WRONG_STATE:
+
OPAL_WRONG_STATE
----------------
-::
+.. code-block:: c
#define OPAL_WRONG_STATE -14
@@ -150,9 +269,11 @@ The requested operation requires a (hardware or software) component to be in
a different state. For example, you cannot call OPAL_START_CPU on a CPU that
is not currently in OPAL.
+.. _OPAL_ASYNC_COMPLETION:
+
OPAL_ASYNC_COMPLETION
---------------------
-::
+.. code-block:: c
#define OPAL_ASYNC_COMPLETION -15
@@ -167,9 +288,11 @@ pseudo-code for an async call: ::
rc = opal_async_wait(token);
// handle result here
+.. _OPAL_EMPTY:
+
OPAL_EMPTY
----------
-::
+.. code-block:: c
#define OPAL_EMPTY -16
@@ -177,17 +300,166 @@ The call was successful and the correct result is empty. For example, the
OPAL_IPMI_RECV call can succeed and return that there is no waiting IPMI
message.
-I2C Calls
----------
-Added for I2C, only applicable to I2C calls: ::
+.. _OPAL_I2C_TIMEOUT:
+
+OPAL_I2C_TIMEOUT
+----------------
+.. code-block:: c
#define OPAL_I2C_TIMEOUT -17
+
+
+.. _OPAL_I2C_INVALID_CMD:
+
+OPAL_I2C_INVALID
+----------------
+.. code-block:: c
+
#define OPAL_I2C_INVALID_CMD -18
+
+
+.. _OPAL_I2C_LBUS_PARITY:
+
+OPAL_I2C_LBUS_PARITY
+--------------------
+.. code-block:: c
+
#define OPAL_I2C_LBUS_PARITY -19
+
+
+.. _OPAL_I2C_BKEND_OVERRUN:
+
+OPAL_I2C_BKEND_OVERRUN
+----------------------
+.. code-block:: c
+
#define OPAL_I2C_BKEND_OVERRUN -20
+
+
+.. _OPAL_I2C_BKEND_ACCESS:
+
+OPAL_I2C_BKEND_ACCESS
+---------------------
+.. code-block:: c
+
#define OPAL_I2C_BKEND_ACCESS -21
+
+.. _OPAL_I2C_ARBT_LOST:
+
+OPAL_I2C_ARBT_LOST
+------------------
+.. code-block:: c
+
#define OPAL_I2C_ARBT_LOST -22
+
+.. _OPAL_I2C_NACK_RCVD:
+
+OPAL_I2C_NACK_RCVD
+------------------
+.. code-block:: c
+
#define OPAL_I2C_NACK_RCVD -23
+
+.. _OPAL_I2C_STOP_ERR:
+
+OPAL_I2C_STOP_ERR
+-----------------
+.. code-block:: c
+
#define OPAL_I2C_STOP_ERR -24
+.. _OPAL_XSCOM_BUSY:
+
+OPAL_XSCOM_BUSY
+---------------
+
+An alias for :ref:`OPAL_BUSY`
+
+.. _OPAL_XSCOM_CHIPLET_OFF:
+
+OPAL_XSCOM_CHIPLET_OFF
+----------------------
+
+An alias for :ref:`OPAL_WRONG_STATE`
+
+.. _OPAL_XSCOM_PARTIAL_GOOD:
+
+OPAL_XSCOM_PARTIAL_GOOD
+-----------------------
+
+.. code-block:: c
+
+ #define OPAL_XSCOM_PARTIAL_GOOD -25
+
+.. _OPAL_XSCOM_ADDR_ERROR:
+
+OPAL_XSCOM_ADDR_ERROR
+---------------------
+
+.. code-block:: c
+
+ #define OPAL_XSCOM_ADDR_ERROR -26
+
+.. _OPAL_XSCOM_CLOCK_ERROR:
+
+OPAL_XSCOM_CLOCK_ERROR
+----------------------
+
+.. code-block:: c
+
+ #define OPAL_XSCOM_CLOCK_ERROR -27
+
+.. _OPAL_XSCOM_PARITY_ERROR:
+
+OPAL_XSCOM_PARITY_ERROR
+-----------------------
+
+.. code-block:: c
+
+ #define OPAL_XSCOM_PARITY_ERROR -28
+
+.. _OPAL_XSCOM_TIMEOUT:
+
+OPAL_XSCOM_TIMEOUT
+------------------
+
+.. code-block:: c
+
+ #define OPAL_XSCOM_TIMEOUT -29
+
+.. _OPAL_XSCOM_CTR_OFFLINED:
+
+OPAL_XSCOM_CTR_OFFLINED
+-----------------------
+
+.. code-block:: c
+
+ #define OPAL_XSCOM_CTR_OFFLINED -30
+
+.. _OPAL_XIVE_PROVISIONING:
+
+OPAL_XIVE_PROVISIONING
+----------------------
+
+.. code-block:: c
+
+ #define OPAL_XIVE_PROVISIONING -31
+
+.. _OPAL_XIVE_FREE_ACTIVE:
+
+OPAL_XIVE_FREE_ACTIVE
+---------------------
+
+.. code-block:: c
+
+ #define OPAL_XIVE_FREE_ACTIVE -32
+
+.. _OPAL_TIMEOUT:
+
+OPAL_TIMEOUT
+------------
+
+.. code-block:: c
+
+ #define OPAL_TIMEOUT -33
diff --git a/doc/release-notes/skiboot-5.1.0.rst b/doc/release-notes/skiboot-5.1.0.rst
index d48dc0b3ae86..d7e65792e931 100644
--- a/doc/release-notes/skiboot-5.1.0.rst
+++ b/doc/release-notes/skiboot-5.1.0.rst
@@ -1,3 +1,5 @@
+.. _skiboot-5.1.0:
+
skiboot-5.1.0
=============
--
2.21.0
More information about the Skiboot
mailing list