rustsbi/src/hsm.rs

use sbi_spec::binary::SbiRet;

/// 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 requestd 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 a 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 hierarchial topology groups can be represented as platform specific suspend states of a hart.
/// A SBI implementation can utilize the suspend states of higher topology groups using one of the following approaches:
///
/// 1. *Platform-coordinated:* In this approach, when a hart becomes idle the supervisor-mode power-managment software
///   will request deepest suspend state for the hart and higher topology groups.
///   A SBI implementation should choose a suspend state at 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
/// 2. *OS-inititated:* In this approach, the supervisor-mode power-managment software will directly request a suspend state
///   for higher topology group after the last hart in that group becomes idle.
///   When a hart becomes idle, the supervisor-mode power-managment software will always select suspend state for the hart itself
///   but it will select a suspend state for a higher topology group only if the hart is the last running hart in the group.
///   A SBI implementation should:
/// - Never choose a suspend state for higher topology group different from the specified suspend state
/// - Always prefer most recent suspend state requested for higher topology group
///
/// Ref: [Section 8, RISC-V Supervisor Binary Interface Specification](https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/riscv-sbi.adoc#8-hart-state-management-extension-eid-0x48534d-hsm)
pub trait Hsm {
    /// 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 implemenation 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 which 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 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.
    fn hart_start(&self, hartid: usize, start_addr: usize, opaque: usize) -> 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
    fn hart_stop(&self) -> 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
    fn hart_get_status(&self, hartid: usize) -> SbiRet;
    /// Request 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 recieves an interrupt or platform specific hardware event.
    ///
    /// # Suspend behavior
    ///
    /// The platform specific suspend states for a hart can be either retentive or non-rententive 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 which will be set in the `a1`
    /// register when the hart resumes exectution 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 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.
    fn hart_suspend(&self, suspend_type: u32, resume_addr: usize, opaque: usize) -> SbiRet {
        let _ = (suspend_type, resume_addr, opaque);
        SbiRet::not_supported()
    }
}

impl<T: Hsm> Hsm for &T {
    #[inline]
    fn hart_start(&self, hartid: usize, start_addr: usize, opaque: usize) -> SbiRet {
        T::hart_start(self, hartid, start_addr, opaque)
    }
    #[inline]
    fn hart_stop(&self) -> SbiRet {
        T::hart_stop(self)
    }
    #[inline]
    fn hart_get_status(&self, hartid: usize) -> SbiRet {
        T::hart_get_status(self, hartid)
    }
    #[inline]
    fn hart_suspend(&self, suspend_type: u32, resume_addr: usize, opaque: usize) -> SbiRet {
        T::hart_suspend(self, suspend_type, resume_addr, opaque)
    }
}