Function sbi_rt::hart_suspend
source · pub fn hart_suspend<T>(
suspend_type: T,
resume_addr: usize,
opaque: usize
) -> SbiRetwhere
T: SuspendType,Expand description
Put the calling hart into suspend or platform specific lower power states.
This function requests the SBI implementation to put the calling hart in a platform specfic suspend
(or low power) state specified by the suspend_type parameter.
The hart will automatically come out of suspended state and resume normal execution when it receives an interrupt or platform specific hardware event.
§Suspend behavior
The platform-specific suspend states for a hart can be either retentive or non-retentive in nature.
A retentive suspend state will preserve hart register and CSR values for all privilege modes, whereas a non-retentive suspend state will not preserve hart register and CSR values.
§Resuming
Resuming from a retentive suspend state is straight forward, and the supervisor-mode software will see SBI suspend call return without any failures.
Resuming from a non-retentive suspend state is relatively more involved, and it requires software
to restore various hart registers and CSRs for all privilege modes.
Upon resuming from non-retentive suspend state, the hart will jump to supervisor-mode at address
specified by resume_addr with specific registers values described in the table below:
| Register Name | Register Value |
|---|---|
satp | 0 |
sstatus.SIE | 0 |
| a0 | hartid |
| a1 | opaque parameter |
§Parameters
The suspend_type parameter is 32 bits wide, and the possible values are shown in the table below:
| Value | Description |
|---|---|
| 0x00000000 | Default retentive suspend |
| 0x00000001 - 0x0FFFFFFF | Reserved for future use |
| 0x10000000 - 0x7FFFFFFF | Platform specific retentive suspend |
| 0x80000000 | Default non-retentive suspend |
| 0x80000001 - 0x8FFFFFFF | Reserved for future use |
| 0x90000000 - 0xFFFFFFFF | Platform specific non-retentive suspend |
| > 0xFFFFFFFF | Reserved |
The resume_addr parameter points to a runtime-specified physical address,
where the hart can resume execution in supervisor-mode after a non-retentive
suspend.
NOTE: A single usize parameter is sufficient as resume_addr,
because the hart will resume execution in the supervisor-mode with MMU off,
hence the resume_addr must be less than XLEN bits wide.
The opaque parameter is an XLEN-bit value that will be set in the a1
register when the hart resumes execution at resume_addr after a
non-retentive suspend.
§Return value
The possible return error codes returned in SbiRet.error are shown in the table below:
| Error code | Description |
|---|---|
SbiRet::success() | Hart has been suspended and resumed back successfully from a retentive suspend state. |
SbiRet::invalid_param() | suspend_type is not valid. |
SbiRet::not_supported() | suspend_type is valid but not implemented. |
SbiRet::invalid_address() | resume_addr is not valid, possibly due to the following reasons: it is not a valid physical address, or the address is prohibited by PMP or H-extension G-stage to run in supervisor-mode. |
SbiRet::failed() | The suspend request failed for unknown reasons. |
This function is defined in RISC-V SBI Specification chapter 9.4.