Function sbi_rt::hart_start

source ·

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

Expand description

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 the supervisor-mode with MMU off, hence the start_addr must be less than XLEN bits wide.

§Behavior

The target hart jumps to supervisor mode at the address specified by start_addr with the following values in specific registers.

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 the address is prohibited by PMP or H-extension G-stage to run in 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 unknown reasons.

This function is defined in RISC-V SBI Specification chapter 9.1.