core: Add support for quiescing OPAL

Quiescing is ensuring all host controlled CPUs (except the current
one) are out of OPAL and prevented from entering. This can be use in
debug and shutdown paths, particularly with system reset sequences.

This patch adds per-CPU entry and exit tracking for OPAL calls, and
adds logic to "hold" or "reject" at entry time, if OPAL is quiesced.

An OPAL call is added, to expose the functionality to Linux, where it
can be used for shutdown, kexec, and before generating sreset IPIs for
debugging (so the debug code does not recurse into OPAL).

Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

2 files changed, 66 insertions, 0 deletions

diff --git a/doc/opal-api/opal-quiesce-158.rst b/doc/opal-api/opal-quiesce-158.rst
new file mode 100644
index 00000000..19604396
--- /dev/null
+++ b/doc/opal-api/opal-quiesce-158.rst
@@ -0,0 +1,59 @@
+.. _opal-quiesce:
+
+OPAL_QUIESCE
+============
+
+The host OS can use 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.
+
+Arguments
+---------
+::
+
+  uint32_t 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
+                        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,
+                        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_LOCK_BREAK calls.
+    QUIESCE_RESUME_FAST_REBOOT
+                        As above, but also reset the tracking of OS calls
+                        into firmware as part of fast reboot (secondaries
+                        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.
+
+Returns
+-------
+OPAL_SUCCESS
+  The quiesce call was successful.
+
+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
+  A parameter was incorrect.
+
+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
+  QUIESCE_LOCK_BREAK or QUIESCE_RESUME.
diff --git a/doc/opal-api/opal-signal-system-reset-145.rst b/doc/opal-api/opal-signal-system-reset-145.rst
index 28e5e2f4..98baef72 100644
--- a/doc/opal-api/opal-signal-system-reset-145.rst
+++ b/doc/opal-api/opal-signal-system-reset-145.rst
@@ -17,6 +17,13 @@ raised when the target has MSR[RI]=0), so it should not be used in
 normal operation, but only for crashing, debugging, and similar
 exceptional cases.
 
+OPAL_SIGNAL_SYSTEM_RESET can pull CPUs out of OPAL, which may be
+undesirable in a crash or shutdown situation (e.g., because they may
+hold locks which are required to access the console, or may be halfway
+through setting hardware registers), so OPAL_QUIESCE can be used
+before OPAL_SIGNAL_SYSTEM_RESET to (attempt to) ensure all CPUs are
+out of OPAL before being interrupted.
+
 Arguments
 ---------
 ::