Untitled :: RISC-V Ratified Specifications Library

19.1. SBI Firmware Features Extension (EID #0x46574654 "FWFT")

The Firmware Features extension enables supervisor-mode software to manage and control specific hardware capabilities or SBI implementation features. Table 77 defines 32-bit identifiers for the features which supervisor-mode software may request to set or get.

Table 77. FWFT Feature Types
Value	Name	Description
0x00000000	MISALIGNED_EXC_DELEG	Control misaligned access exception delegation to supervisor-mode
0x00000001	LANDING_PAD	Control landing pad support for supervisor-mode.
0x00000002	SHADOW_STACK	Control shadow stack support for supervisor-mode.
0x00000003	DOUBLE_TRAP	Control double trap support.
0x00000004	PTE_AD_HW_UPDATING	Control hardware updating of PTE A/D bits.
0x00000005	POINTER_MASKING_PMLEN	Control the pointer masking length for supervisor-mode.
0x00000006 - 0x3fffffff		Local feature types reserved for future use.
0x40000000 - 0x7fffffff		Platform specific local feature types.
0x80000000 - 0xbfffffff		Global feature types reserved for future use.
0xc0000000 - 0xffffffff		Platform specific global feature types.

These features have some attributes that define their behavior and are described in Table 78. The attribute values are defined for each feature in Table 79.

Table 78. FWFT Feature Attributes
Attribute	Description
Scope	Defines if a feature is local (per-hart) or global. Global features only need to be enabled/disabled by a single hart, whereas local features need to be enabled/disabled by each hart. The status and flags of local features can be different from one hart to another.
Reset value	Reset value of the feature. Might be implementation defined.
Values	Per feature values that can be set.

During non-retentive suspend, feature values are retained and restored by the SBI when resuming operations. Upon hart reset, local feature values are not retained and reset to their default reset values according to the feature description. Upon system reset, global and local feature values are reset.

Table 79. FWFT Feature Attribute Values

Feature Name

Reset

Scope

Values

MISALIGNED_EXC_DELEG

Implementation-defined

Local

Disable misaligned exception delegation.

Enable misaligned exception delegation.

LANDING_PAD

Local

Disable landing pad for supervisor-mode.

Enable landing pad for supervisor-mode.

SHADOW_STACK

Local

Disable shadow-stack for supervisor-mode.

Enable shadow-stack for supervisor-mode.

DOUBLE_TRAP

Local

Disable double trap

Enable double trap

PTE_AD_HW_UPDATING

Local

Disable hardware updating of PTE A/D bits for supervisor-mode.

Enable hardware updating of PTE A/D bits for supervisor-mode.

POINTER_MASKING_PMLEN

Local

Disable pointer masking for supervisor-mode.

Enable pointer masking for supervisor-mode with PMLEN = N.

19.1.1. Function: Firmware Features Set (FID #0)

struct sbiret sbi_fwft_set(uint32_t feature,
                           unsigned long value,
                           unsigned long flags)

A successful return from sbi_fwft_set() results in the requested firmware feature to be set according to the value and flags parameters for which per feature supported values are described in Table 79 and flags in Table 4.

The set operation will succeed if requested value matches the existing value.

Table 4. FWFT Firmware Features Set Flags
Name	Encoding	Description
LOCK	BIT[0]	If provided, once set, the feature value can no longer be modified until: - hart reset for feature with local scope - system reset for feature with global scope
	BIT[XLEN-1:1]	Reserved for future use and must be zero.

In case of failure, feature value is not modified and the possible error codes returned in sbiret.error are shown in Table 80 below.

Table 80. FWFT Firmware Features Set Errors
Error code	Description
SBI_SUCCESS	`feature` was set successfully.
SBI_ERR_NOT_SUPPORTED	`feature` is not reserved and valid, but the platform does not support it due to one or more missing dependencies (Hardware or SBI implementation).
SBI_ERR_INVALID_PARAM	Provided `value` or `flags` parameter is invalid.
SBI_ERR_DENIED	`feature` set operation failed because either: - it was denied by the SBI implementation - `feature` is reserved or is platform-specific and unimplemented
SBI_ERR_DENIED_LOCKED	`feature` set operation failed because the `feature` is locked
SBI_ERR_FAILED	The set operation failed for unspecified or unknown other reasons.

The rationale for an SBI implementation to return SBI_ERR_DENIED is for instance to allow some hypervisors to simply passthrough the misaligned delegation state to the Guest/VM and deny any changes to that delegation state from the Guest/VM. If authorized, an SBI call would be required at each Guest/VM switch if delegation choices are different between Host and Guest/VM.

19.1.2. Function: Firmware Features Get (FID #1)

struct sbiret sbi_fwft_get(uint32_t feature)

A successful return from sbi_fwft_get() results in the firmware feature configuration value to be returned in sbiret.value. Possible sbiret.value values are described in Table 79 for each feature ID.

In case of failure, the content of sbiret.value is zero and the possible error codes returned in sbiret.error are shown in Table 6.

Table 6. FWFT Firmware Features Get Errors
Error code	Description
SBI_SUCCESS	Feature status was retrieved successfully.
SBI_ERR_NOT_SUPPORTED	`feature` is not reserved and valid, but the platform does not support it due to one or more missing dependencies (Hardware or SBI implementation).
SBI_ERR_DENIED	`feature` is reserved or is platform-specific and unimplemented.
SBI_ERR_FAILED	The get operation failed for unspecified or unknown other reasons.

19.1.3. Function Listing

Table 81. FWFT Function List
Function Name	SBI Version	FID	EID
sbi_fwft_set	3.0	0	0x46574654
sbi_fwft_get	3.0	1	0x46574654