doc: prettify OPAL_QUIESCE
-.. _opal-quiesce:
+.. _OPAL_QUIESCE:
OPAL_QUIESCE
============
-The host OS can use OPAL_QUIESCE to ensure CPUs under host control are not
+.. code-block:: c
+
+ #define OPAL_QUIESCE 158
+
+ int64_t opal_quiesce(uint32_t quiesce_type, int32_t cpu_target);
+
+The host OS can use :ref:`OPAL_QUIESCE` to ensure CPUs under host control are not
executing OPAL. This is useful in crash or shutdown scenarios to try to
ensure that CPUs are not holding locks, and is intended to be used with
-OPAL_SIGNAL_SYSTEM_RESET, for example.
+:ref:`OPAL_SIGNAL_SYSTEM_RESET`, for example.
Arguments
---------
-::
- uint32_t quiesce_type
- QUIESCE_HOLD Wait for all target(s) currently executing OPAL to
+quiesce_type
+^^^^^^^^^^^^
+
+QUIESCE_HOLD
+ Wait for all target(s) currently executing OPAL to
return to the host. Any new OPAL call that is made
will be held off until QUIESCE_RESUME.
- QUIESCE_REJECT Wait for all target(s) currently executing OPAL to
+QUIESCE_REJECT
+ Wait for all target(s) currently executing OPAL to
return to the host. Any new OPAL call that is made
will fail with OPAL_BUSY until QUIESCE_RESUME.
- QUIESCE_LOCK_BREAK After QUIESCE_HOLD or QUIESCE_REJECT is successful,
+QUIESCE_LOCK_BREAK
+ After QUIESCE_HOLD or QUIESCE_REJECT is successful,
the CPU can call QUIESCE_LOCK_BREAK to skip all
locking in OPAL to give the best chance of making
progress in the crash/debug paths. The host should
ensure all other CPUs are stopped (e.g., with
OPAL_SIGNAL_SYSTEM_RESET) before this call is made, to
avoid concurrency.
- QUIESCE_RESUME Undo the effects of QUIESCE_HOLD/QUIESCE_REJECT and
+QUIESCE_RESUME
+ Undo the effects of QUIESCE_HOLD/QUIESCE_REJECT and
QUIESCE_LOCK_BREAK calls.
QUIESCE_RESUME_FAST_REBOOT
As above, but also reset the tracking of OS calls
@@ -34,25 +45,27 @@ Arguments
will never return to OS, but instead be released
into a new OS boot).
- int32_t target_cpu
- cpu_nr >= 0 The cpu server number of the target cpu to reset.
- -1 All cpus except the current one should be quiesced.
+target_cpu
+^^^^^^^^^^
+
+``cpu_nr >= 0``
+ The cpu server number of the target cpu to reset.
+``-1``
+ All cpus except the current one should be quiesced.
Returns
-------
-OPAL_SUCCESS
- The quiesce call was successful.
-OPAL_PARTIAL
+:ref:`OPAL_SUCCESS`
+ The quiesce call was successful.
+:ref:`OPAL_PARTIAL`
Some or all of the CPUs executing OPAL when the call was made did not
return to the host after a timeout of 1 second. This is a best effort
at quiescing OPAL, and QUIESCE_RESUME must be called to resume normal
firmware operation.
-
-OPAL_PARAMETER
+:ref:`OPAL_PARAMETER`
A parameter was incorrect.
-
-OPAL_BUSY
+:ref:`OPAL_BUSY`
This CPU was not able to complete the operation, either because another
has concurrently started quiescing the system, or because it has not
successfully called QUIESCE_HOLD or QUIESCE_REJECT before attempting
