From 2c2c622d1dc2bced4101c33ddfb4a8489294159f Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Fri, 31 May 2019 16:12:32 +1000 Subject: [PATCH] doc: Make OPAL_CEC_POWER_DOWN docs pretty Signed-off-by: Stewart Smith --- doc/opal-api/opal-cec-power-down-5.rst | 37 +++++++++++++++----------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/doc/opal-api/opal-cec-power-down-5.rst b/doc/opal-api/opal-cec-power-down-5.rst index bdcb84e3b958..b4b236e2467c 100644 --- a/doc/opal-api/opal-cec-power-down-5.rst +++ b/doc/opal-api/opal-cec-power-down-5.rst @@ -1,6 +1,9 @@ +.. _OPAL_CEC_POWER_DOWN: + OPAL_CEC_POWER_DOWN =================== -:: + +.. code-block:: c #define OPAL_CEC_POWER_DOWN 5 @@ -8,11 +11,13 @@ OPAL_CEC_POWER_DOWN Arguments --------- -:: - uint64 request values as follows: - 0 - Power down normally - 1 - Power down immediately +`uint64 request` values as follows: + +0 + Power down normally +1 + Power down immediately This OPAL call requests OPAL to power down the system. The exact difference between a normal and immediate shutdown is platform specific. @@ -23,29 +28,31 @@ platform to only support some types of power down operations. Return Values ------------- -``OPAL_SUCCESS`` +:ref:`OPAL_SUCCESS` the power down request was successful. This may/may not result in immediate power down. An OS should - spin in a loop after getting `OPAL_SUCCESS` as it is likely that there + spin in a loop after getting :ref:`OPAL_SUCCESS` as it is likely that there will be a delay before instructions stop being executed. -``OPAL_BUSY`` +:ref:`OPAL_BUSY` unable to power down, try again later. -``OPAL_BUSY_EVENT`` - Unable to power down, call `opal_run_pollers` and try again. +:ref:`OPAL_BUSY_EVENT` + Unable to power down, call :ref:`OPAL_POLL_EVENTS` and try again. -``OPAL_PARAMETER`` +:ref:`OPAL_PARAMETER` a parameter was incorrect -``OPAL_INTERNAL_ERROR`` +:ref:`OPAL_INTERNAL_ERROR` Something went wrong, and waiting and trying again is unlikely to be successful. Although, considering that in a shutdown code path, there's unlikely to be any other valid option to take, retrying is perfectly valid. In older OPAL versions (prior to skiboot v5.9), on IBM FSP systems, this - return code was returned erroneously instead of OPAL_BUSY_EVENT during an + return code was returned erroneously instead of :ref:`OPAL_BUSY_EVENT` during an FSP Reset/Reload. -``OPAL_UNSUPPORTED`` - this platform does not support being powered off. +:ref:`OPAL_UNSUPPORTED` + this platform does not support being powered off. Practically speaking, this + should **never** be returned, but in various simulation or bring-up situations, + it's plausible it is, so code should handle this gracefully.