[Skiboot] [PATCH 031/110] doc: Make OPAL_CEC_POWER_DOWN docs pretty
stewart at linux.ibm.com
Fri May 31 16:12:32 AEST 2019
Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
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
@@ -1,6 +1,9 @@
+.. code-block:: c
#define OPAL_CEC_POWER_DOWN 5
@@ -8,11 +11,13 @@ OPAL_CEC_POWER_DOWN
- uint64 request values as follows:
- 0 - Power down normally
- 1 - Power down immediately
+`uint64 request` values as follows:
+ Power down normally
+ 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.
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.
unable to power down, try again later.
- Unable to power down, call `opal_run_pollers` and try again.
+ Unable to power down, call :ref:`OPAL_POLL_EVENTS` and try again.
a parameter was incorrect
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
- this platform does not support being powered off.
+ 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.
More information about the Skiboot