ext-firmware-features.adoc

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

The Firmware Features extension is meant to control the behavior of specific firmware features. FWFT Feature Types defines 32-bit identifiers for the features which supervisor-mode software may request to set or get.

Table 1. FWFT Feature Types

Value	Name	Description
0x00000000	MISALIGNED_EXC_DELEG	Control misaligned access exception delegation to supervisor-mode if medeleg is present.
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 for supervisor-mode.
0x00000004	PTE_AD_HW_UPDATING	Control hardware updating of PTE A/D bits for supervisor-mode.
0x00000005 - 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 FWFT Feature Attributes. The attribute values are defined for each feature in FWFT Feature Attribute Values.

Table 2. 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 3. FWFT Feature Attribute Values

Feature Name	Reset	Scope	Values
MISALIGNED_EXC_DELEG	Implementation-defined	Local	0 Disable misaligned exception delegation. 1 Enable misaligned exception delegation.
LANDING_PAD	0	Local	0 Disable landing pad for supervisor-mode. 1 Enable landing pad for supervisor-mode.
SHADOW_STACK	0	Local	0 Disable shadow-stack for supervisor-mode. 1 Enable shadow-stack for supervisor-mode.
DOUBLE_TRAP	0	Local	0 Disable double trap for supervisor-mode. 1 Enable double trap for supervisor-mode.
PTE_AD_HW_UPDATING	0	Local	0 Disable hardware updating of PTE A/D bits for supervisor-mode. 1 Enable hardware updating of PTE A/D bits for supervisor-mode.

Function: Firmware Features Set (FID #0)

struct sbiret sbi_fwft_set(unsigned long 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 FWFT Feature Attributes and flags in FWFT Firmware Features Set Flags.

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.

In case of failure, feature value is not modified and the possible error codes returned in sbiret.error are shown in FWFT Firmware Features Set Errors below.

Table 5. FWFT Firmware Features Set Errors

Error code	Description
SBI_SUCCESS	feature was set successfully.
SBI_ERR_NOT_SUPPORTED	feature is not reserved and is implemented, but the platform does not support it due to one or more missing dependencies.
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 locked - feature is reserved or is platform-specific and unimplemented
SBI_ERR_FAILED	The set operation failed for unspecified or unknown other reasons.

Note

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.

Function: Firmware Features Get (FID #1)

struct sbiret sbi_fwft_get(unsigned long 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 FWFT Feature Attributes 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 FWFT Firmware Features Get Errors.

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 is implemented, but the platform does not support it due to one or more missing dependencies.
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.

Function Listing

Table 7. FWFT Function List

Function Name	SBI Version	FID	EID
sbi_fwft_set	3.0	0	0x46574654
sbi_fwft_get	3.0	1	0x46574654