docs/concepts/kernel/suspend.md

# Suspend States (from Zircon's perspective)

From Zircon's perspective, there are different kinds of "suspend": system
suspend, task scheduling suspend (per-CPU), and platform-specific suspend
(per-CPU), and CPU Idle.

## System Suspend State

This is a system-wide state that is entered when a user program calls
[`zx_system_suspend_enter()`].  The defining characteristic is that while in
this state, task execution is suspended for all CPUs.  That is, while in this
state, no user thread will execute.  However, Zircon's interrupt handlers as
well each CPU's special "idle power thread" (part of Zircon) *may* continue to
execute as necessary.  More on this below.

When entering this state Zircon identifies which interrupts are designated as
wake vectors (`ZX_INTERRUPT_WAKE_VECTOR`) and ensures that only those interrupts
will bring the system out of this state.

This state builds on Task Scheduling Suspend State (see below).  In order for
the system to enter this state, every CPU must enter the Task Scheduling Suspend
State.

## Task Scheduling Suspend State

This is a per-CPU state.  When a CPU is in this state, its special "idle power
thread" is the only task that may execute.  This task is responsible for
managing state transitions, waking the system when necessary, and putting the
CPU into a Platform-Specific Suspend State or none is available, a CPU Idle
State.

## Platform-Specific Suspend State

This is a per-CPU state that's defined by the platform layer (think "PC" or
"generic ARM").  Currently, this state is only supported on the arm64
architecture and only for QEMU and Sorrel.

On Sorrel, this state is implemented via PSCI CPU_SUSPEND (see below).

When entering a Platform-Specific Suspend State, Zircon makes no effort to mask
off or otherwise disable hardware interrupts (think SPIs).  If, prior to
entering this state, a particular device had been configured to generate an
interrupt on some event *and* that event occurs while in this state, the
interrupt will be generated and the CPU will leave this state.

The CPU's handler will then execute and determine whether the interrupt is a
wake vector or not.  If the interrupt *is* a wake vector, then the CPU's idle
power thread will begin to transition all CPUs out of their Task Scheduling
Suspend State and the system out of System Suspend.  If the interrupt is *not* a
wake vector, then the idle power thread will immediately re-enter the
Platform-Specific Suspend State.

### PSCI CPU_SUSPEND

This is a state that a CPU enters by issuing a `CPU_SUSPEND` PSCI call.  On
Sorrel, this call comes in two flavors.  One flavor is for putting just the
calling CPU into a suspend state.  The other flavor is for putting the last
non-suspended CPU into suspend and powering down the AP complex.  That is,
entering AP Power Collapse.

When in this state, interrupting the CPU will cause the CPU to resume execution
(i.e. leave this state).

## CPU Idle

This isn't really a suspend state.  A CPU enters this state whenever it has
nothing better to do.  The CPU will pause execution, enter a lower power state
and wait until an interrupt occurs or another CPU has asked it to resume
execution.  On arm64 and riscv64, this is done using a `WFI` instruction.  On
x64, we use either `MWAIT` or `HLT`.  While a CPU may enter this state during
any of the above suspend states, this state is not inherently tied to System
Suspend, or Task Scheduling Suspend.

[`zx_system_suspend_enter()`]: /reference/syscalls/system_suspend_enter.md