13 System Suspend Extension (EID #0x53555350 "SUSP")

The system suspend extension defines a set of system-level sleep states and a function which allows the supervisor-mode software to request that the system transitions to a sleep state. Sleep states are identified with 32-bit wide identifiers (sleep_type). The possible values for the identifiers are shown in Table 54.

The term "system" refers to the world-view of the supervisor software domain invoking the call. System suspend may only suspend the part of the overall system which is visible to the invoking supervisor software domain.

The system suspend extension does not provide any way for supported sleep types to be probed. Platforms are expected to specify their supported system sleep types and per-type wake up devices in their hardware descriptions. The SUSPEND_TO_RAM sleep type is the one exception, and its presence is implied by that of the extension.

Table 54. SUSP System Sleep Types

Type	Name	Description
0	SUSPEND_TO_RAM	This is a “suspend to RAM” sleep type, similar to ACPI’s S2 or S3. Entry requires all but the calling hart be in the HSM STOPPED state and all hart registers and CSRs saved to RAM.
0x00000001 - 0x7fffffff		Reserved for future use
0x80000000 - 0xffffffff		Platform-specific system sleep types

13.1 Function: System Suspend (FID #0)

struct sbiret sbi_system_suspend(uint32_t sleep_type,
                                 unsigned long resume_addr,
                                 unsigned long opaque)

A return from a sbi_system_suspend() call implies an error and an error code from Table 56 will be in sbiret.error. A successful suspend and wake up, results in the hart which initiated the suspend, resuming from the STOPPED state. To resume, the hart will jump to supervisor-mode, at the address specified by resume_addr, with the specific register values described in Table 55.

Table 55. SUSP System Resume Register State

Register Name	Register Value
satp	0
sstatus.SIE	0
a0	hartid
a1	opaque parameter
All other registers remain in an undefined state.

note

A single unsigned long parameter is sufficient for resume_addr, because the hart will resume execution in supervisor-mode with the MMU off, hence resume_addr must be less than XLEN bits wide.

The resume_addr parameter points to a runtime-specified physical address, where the hart can resume execution in supervisor-mode after a system suspend.

The opaque parameter is an XLEN-bit value which will be set in the a1 register when the hart resumes execution at resume_addr after a system suspend.

Besides ensuring all entry criteria for the selected sleep type are met, such as ensuring other harts are in the STOPPED state, the caller must ensure all power units and domains are in a state compatible with the selected sleep type. The preparation of the power units, power domains, and wake-up devices used for resumption from the system sleep state is platform specific and beyond the scope of this specification.

When supervisor software is running inside a virtual machine, the SBI implementation is provided by a hypervisor. System suspend will behave similarly to the native case from the point of view of the supervisor software.

The possible error codes returned in sbiret.error are shown in Table 56.

Table 56. SUSP System Suspend Errors

Error code	Description
SBI_ERR_INVALID_PARAM	sleep_type is reserved or is platform-specific and unimplemented.
SBI_ERR_NOT_SUPPORTED	sleep_type is not reserved and is implemented, but the platform does not support it due to one or more missing dependencies.
SBI_ERR_INVALID_ADDRESS	resume_addr is not valid, possibly due to the * Executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor mode.
SBI_ERR_DENIED	The suspend request failed due to unsatisfied entry criteria.
SBI_ERR_FAILED	The suspend request failed for unspecified or unknown other reasons.

13.2 Function Listing

Table 57. SUSP Function List

Function Name	SBI Version	FID	EID
sbi_system_suspend	2.0	0	0x53555350