diff mbox series

[031/110] doc: Make OPAL_CEC_POWER_DOWN docs pretty

Message ID 20190531061351.22973-32-stewart@linux.ibm.com
State Accepted
Headers show
Series Big documentation cleanup/expansion | expand

Commit Message

Stewart Smith May 31, 2019, 6:12 a.m. UTC
Signed-off-by: Stewart Smith <stewart@linux.ibm.com>
---
 doc/opal-api/opal-cec-power-down-5.rst | 37 +++++++++++++++-----------
 1 file changed, 22 insertions(+), 15 deletions(-)
diff mbox series

Patch

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.