Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

1 files changed, 465 insertions, 0 deletions

diff --git a/roms/skiboot/doc/opal-api/return-codes.rst b/roms/skiboot/doc/opal-api/return-codes.rst
new file mode 100644
index 000000000..296675d5a
--- /dev/null
+++ b/roms/skiboot/doc/opal-api/return-codes.rst
@@ -0,0 +1,465 @@
+OPAL API Return Codes
+=====================
+
+All OPAL calls return an integer relaying the success/failure of the OPAL
+call.
+
+Success is typically indicated by OPAL_SUCCESS. Failure is always indicated
+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-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
+
+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.
+
+.. _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
+
+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
+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
+
+When trying to use a limited resource, OPAL found that there were none free.
+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
+
+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
+
+For asynchronous calls, successfully queueing/starting executing the
+command is indicated by the OPAL_ASYNC_COMPLETION return code.
+pseudo-code for an async call: ::
+
+  token = opal_async_get_token();
+  rc = opal_async_example(foo, token);
+  if (rc != OPAL_ASYNC_COMPLETION)
+      handle_error(rc);
+  rc = opal_async_wait(token);
+  // handle result here
+
+.. _OPAL_EMPTY:
+
+OPAL_EMPTY
+----------
+.. code-block:: c
+
+   #define OPAL_EMPTY		-16
+
+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.
+
+.. _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