1.. _OPAL_QUIESCE:
2
3OPAL_QUIESCE
4============
5
6.. code-block:: c
7
8   #define OPAL_QUIESCE				158
9
10   int64_t opal_quiesce(uint32_t quiesce_type, int32_t cpu_target);
11
12The host OS can use :ref:`OPAL_QUIESCE` to ensure CPUs under host control are not
13executing OPAL. This is useful in crash or shutdown scenarios to try to
14ensure that CPUs are not holding locks, and is intended to be used with
15:ref:`OPAL_SIGNAL_SYSTEM_RESET`, for example.
16
17Arguments
18---------
19
20quiesce_type
21^^^^^^^^^^^^
22
23QUIESCE_HOLD
24  Wait for all target(s) currently executing OPAL to
25  return to the host. Any new OPAL call that is made
26  will be held off until QUIESCE_RESUME.
27QUIESCE_REJECT
28  Wait for all target(s) currently executing OPAL to
29  return to the host. Any new OPAL call that is made
30  will fail with OPAL_BUSY until QUIESCE_RESUME.
31QUIESCE_LOCK_BREAK
32  After QUIESCE_HOLD or QUIESCE_REJECT is successful,
33  the CPU can call QUIESCE_LOCK_BREAK to skip all
34  locking in OPAL to give the best chance of making
35  progress in the crash/debug paths. The host should
36  ensure all other CPUs are stopped (e.g., with
37  OPAL_SIGNAL_SYSTEM_RESET) before this call is made, to
38  avoid concurrency.
39QUIESCE_RESUME
40  Undo the effects of QUIESCE_HOLD/QUIESCE_REJECT and
41  QUIESCE_LOCK_BREAK calls.
42QUIESCE_RESUME_FAST_REBOOT
43  As above, but also reset the tracking of OS calls
44  into firmware as part of fast reboot (secondaries
45  will never return to OS, but instead be released
46  into a new OS boot).
47
48target_cpu
49^^^^^^^^^^
50
51``cpu_nr >= 0``
52  The cpu server number of the target cpu to reset.
53``-1``
54  All cpus except the current one should be quiesced.
55
56Returns
57-------
58
59:ref:`OPAL_SUCCESS`
60  The quiesce call was successful.
61:ref:`OPAL_PARTIAL`
62  Some or all of the CPUs executing OPAL when the call was made did not
63  return to the host after a timeout of 1 second. This is a best effort
64  at quiescing OPAL, and QUIESCE_RESUME must be called to resume normal
65  firmware operation.
66:ref:`OPAL_PARAMETER`
67  A parameter was incorrect.
68:ref:`OPAL_BUSY`
69  This CPU was not able to complete the operation, either because another
70  has concurrently started quiescing the system, or because it has not
71  successfully called QUIESCE_HOLD or QUIESCE_REJECT before attempting
72  QUIESCE_LOCK_BREAK or QUIESCE_RESUME.
73