doc: Make OPAL_CEC_POWER_DOWN docs pretty
+.. _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.
