Trait Hsm

Source

pub trait Hsm {
    // Required methods
    fn hart_start(
        &self,
        hartid: usize,
        start_addr: usize,
        opaque: usize,
    ) -> SbiRet;
    fn hart_stop(&self) -> SbiRet;
    fn hart_get_status(&self, hartid: usize) -> SbiRet;

    // Provided method
    fn hart_suspend(
        &self,
        suspend_type: u32,
        resume_addr: usize,
        opaque: usize,
    ) -> SbiRet { ... }
}

Expand description

Hart State Management extension.

The Hart State Management (HSM) Extension introduces a set hart states and a set of functions which allow the supervisor-mode software to request a hart state change.

§Hart states

The possible hart states along with a unique State ID are as follows:

State ID	State Name	Description
0	`STARTED`	The hart is physically powered-up and executing normally.
1	`STOPPED`	The hart is not executing in supervisor-mode or any lower privilege mode. It is probably powered-down by the SBI implementation if the underlying platform has a mechanism to physically power-down harts.
2	`START_PENDING`	Some other hart has requested to start (or power-up) the hart from the STOPPED state, and the SBI implementation is still working to get the hart in the STARTED state.
3	`STOP_PENDING`	The hart has requested to stop (or power-down) itself from the STARTED state and the SBI implementation is still working to get the hart in the STOPPED state.
4	`SUSPENDED`	This hart is in a platform-specific suspend (or low power) state.
5	`SUSPEND_PENDING`	The hart has requested to put itself in a platform specific low power state from the STARTED state and the SBI implementation is still working to get the hart in the platform specific SUSPENDED state.
6	`RESUME_PENDING`	An interrupt or platform specific hardware event has caused the hart to resume normal execution from the SUSPENDED state and the SBI implementation is still working to get the hart in the STARTED state.

At any point in time, a hart should be in one of the above-mentioned hart states.

§Topology hart groups

A platform can have multiple harts grouped into hierarchical topology groups (namely cores, clusters, nodes, etc.) with separate platform specific low-power states for each hierarchical group. These platform-specific low-power states of hierarchical topology groups can be represented as platform-specific suspend states of a hart. An SBI implementation can utilize the suspend states of higher topology groups using one of the following approaches:

Platform-coordinated: In this approach, when a hart becomes idle, the supervisor-mode power-management software will request deepest suspend state for the hart and higher topology groups. An SBI implementation should choose a suspend state at a higher topology group which is:
- Not deeper than the specified suspend state
- Wake-up latency is not higher than the wake-up latency of the specified suspend state
OS-initiated: In this approach, the supervisor-mode power-management software will directly request a suspend state for a higher topology group after the last hart in that group becomes idle. When a hart becomes idle, the supervisor-mode power-management software will always select suspend state for the hart itself. However, it will select a suspend state for a higher topology group only if the hart is the last running hart in the group. An SBI implementation should:
- Never choose a suspend state for a higher topology group different from the specified suspend state
- Always prefer the most recent suspend state requested for a higher topology group

Ref: Section 8, RISC-V Supervisor Binary Interface Specification

Required Methods§

Source

fn hart_start(&self, hartid: usize, start_addr: usize, opaque: usize) -> SbiRet

Request the SBI implementation to start executing the given hart at specified address in supervisor-mode.

This call is asynchronous - more specifically, the hart_start() may return before target hart starts executing as long as the SBI implementation is capable of ensuring the return code is accurate.

It is recommended that if the SBI implementation is a platform runtime firmware executing in machine-mode (M-mode) then it MUST configure PMP and other the M-mode state before executing in supervisor-mode.

§Parameters

The hartid parameter specifies the target hart, which is to be started.
The start_addr parameter points to a runtime-specified physical address, where the hart can start executing in supervisor-mode.
The opaque parameter is a usize value that will be set in the a1 register when the hart starts executing at start_addr.

NOTE: A single usize parameter is sufficient as start_addr, because the hart will start execution in supervisor-mode with the MMU off, hence start_addr must be less than XLEN bits wide.

§Behavior

The target hart jumps to supervisor mode at address specified by start_addr with specific register values described as follows.

Register Name	Register Value
`satp`	0
`sstatus.SIE`	0
a0	hartid
a1	`opaque` parameter

§Return value

The possible return error codes returned in SbiRet.error are shown in the table below:

Return code	Description
`SbiRet::success()`	Hart was previously in stopped state. It will start executing from `start_addr`.
`SbiRet::invalid_address()`	`start_addr` is not valid, possibly due to the following reasons: it is not a valid physical address, or executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor-mode.
`SbiRet::invalid_param()`	`hartid` is not a valid hartid as corresponding hart cannot be started in supervisor mode.
`SbiRet::already_available()`	The given hartid is already started.
`SbiRet::failed()`	The start request failed for unspecified or unknown other reasons.

Source

fn hart_stop(&self) -> SbiRet

Request the SBI implementation to stop executing the calling hart in supervisor-mode and return its ownership to the SBI implementation.

This call is not expected to return under normal conditions. The hart_stop() must be called with supervisor-mode interrupts disabled.

§Return value

The possible return error codes returned in SbiRet.error are shown in the table below:

Error code	Description
`SbiRet::failed()`	Failed to stop execution of the current hart

Source

fn hart_get_status(&self, hartid: usize) -> SbiRet

Get the current status (or HSM state id) of the given hart.

The harts may transition HSM states at any time due to any concurrent hart_start() or hart_stop() calls, the return value from this function may not represent the actual state of the hart at the time of return value verification.

§Parameters

The hartid parameter specifies the target hart which status is required.

§Return value

The possible status values returned in SbiRet.value are shown in the table below:

Name	Value	Description
STARTED	0	Hart Started
STOPPED	1	Hart Stopped
START_PENDING	2	Hart start request pending
STOP_PENDING	3	Hart stop request pending

The possible return error codes returned in SbiRet.error are shown in the table below:

Error code	Description
`SbiRet::invalid_param()`	The given `hartid` is not valid

Provided Methods§

Source

fn hart_suspend( &self, suspend_type: u32, resume_addr: usize, opaque: usize, ) -> SbiRet

Request the SBI implementation to put the calling hart in a platform specific 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 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 supervisor-mode with the MMU off, hence 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 executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor-mode.
`SbiRet::failed()`
The suspend request failed for unspecified or unknown other reasons.