Struct firmware_uefi::service::nvram::spec_services::NvramSpecServices

pub struct NvramSpecServices<S: InspectableNvramStorage> { /* private fields */ }

An implementation of UEFI spec 8.2 - Variable Services

This API tries to match the API defined by the UEFI spec 1:1, hence why it doesn’t look very “Rust-y”.

If you need to interact with NvramServices outside the context of the UEFI device itself, consider importing the NvramServicesExt trait. This trait provides various helper methods that make it easier to get/set nvram variables, without worrying about the nitty-gritty details of UCS-2 string encoding, pointer sizes/nullness, etc…

Instead of returning a typical Result type, these methods all return a tuple of (Option<T>, EfiStatus, Option<NvramError>), where the EfiStatus field should be unconditionally returned to the guest, while the NvramError type provides additional context as to what error occurred in OpenVMM (i.e: for logging purposes).

Implementations

impl<S: InspectableNvramStorage> NvramSpecServices<S>

pub fn new(storage: S) -> NvramSpecServices<S>

Construct a new NvramServices instance from an existing storage backend.

pub async fn is_empty(&mut self) -> Result<bool, NvramStorageError>

Check if the nvram store is empty.

pub async fn update_setup_mode(&mut self) -> Result<(), NvramStorageError>

Update “SetupMode” based on the current value of “PK”

From UEFI spec section 32.3

While no Platform Key is enrolled, the SetupMode variable shall be equal to 1. While SetupMode == 1, the platform firmware shall not require authentication in order to modify the Platform Key, Key Enrollment Key, OsRecoveryOrder, OsRecovery####, and image security databases.

After the Platform Key is enrolled, the SetupMode variable shall be equal to 0. While SetupMode == 0, the platform firmware shall require authentication in order to modify the Platform Key, Key Enrollment Key, OsRecoveryOrder, OsRecovery####, and image security databases.

pub fn exit_boot_services(&mut self)

Nvram behavior changes after the guest signals that ExitBootServices has been called (e.g: hiding variables that are only accessible at boot-time).

pub fn reset(&mut self)

Called when the VM resets to return to the preboot state.

pub fn prepare_for_boot(&mut self)

Called after injecting any pre-boot nvram vars, transitioning the nvram store to start accepting calls from guest UEFI.

pub async fn uefi_get_variable( &mut self, name: Option<&[u8]>, in_vendor: Guid, out_attr: &mut u32, in_out_data_size: &mut u32, data_is_null: bool, ) -> NvramResult<Option<Vec<u8>>>

Get a variable identified by name + vendor, returning the variable’s attributes and data.

• in_name
  • (In) Variable name (a null-terminated UTF-16 string, or None if the guest passed a nullptr)
• in_vendor
  • (In) Variable vendor guid
• out_attr
  • (Out) Variable’s attributes
  • Note: According to the UEFI spec: attr will be populated on both EFI_SUCCESS and when EFI_BUFFER_TOO_SMALL is returned.
• in_out_data_size
  • (In) Size of available data buffer (provided by guest)
  • (Out) Size of data to be written into buffer
  • Note: If data_is_null is true, and in_out_data_size is set to 0, in_out_data_size will be updated with the size required to store the variable.
• data_is_null
  • (In) bool indicating if guest passed nullptr as the data addr

pub async fn uefi_set_variable( &mut self, name: Option<&[u8]>, in_vendor: Guid, in_attr: u32, in_data_size: u32, data: Option<Vec<u8>>, ) -> NvramResult<()>

Set a variable identified by name + vendor with the specified attr and data

• name
  • (In) Variable name (a null-terminated UTF-16 string, or None if the guest passed a nullptr)
  • Note: name must contain one or more character.
• in_vendor
  • (In) Variable vendor guid
• in_attr
  • (In) Variable’s attributes
• in_data_size
  • (In) Length of data to be written
  • If len in 0, and the EFI_VARIABLE_APPEND_WRITE, EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS, EFI_VARIABLE_ENHANCED_AUTHENTICATED_ACCESS, or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS are not set, the variable will be deleted.
• data
  • (In) Variable data (or None if the guest passed a nullptr)

pub async fn uefi_get_next_variable( &mut self, in_out_name_size: &mut u32, name: Option<&[u8]>, vendor: Guid, ) -> NvramResult<Option<(Vec<u8>, Guid)>>

Return the variable immediately following the variable identified by name + vendor key.

If name is an empty string, the first variable is returned.

• name
  • (In) Variable name (a null-terminated UTF-16 string, or None if the guest passed a nullptr)
• in_out_name_size
  • (In) Length of the provided name
  • (Out) Length of the next variable name
  • Note: If there is insufficient space in the name buffer to store the next variable, in_out_name_size will be updated with the size required to store the variable.
• vendor
  • (In) Variable vendor guid

Trait Implementations

impl<S: Debug + InspectableNvramStorage> Debug for NvramSpecServices<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: InspectableNvramStorage> Inspect for NvramSpecServices<S>

fn inspect(&self, req: Request<'_>)

Inspects the object.

impl<S: InspectableNvramStorage> NvramServicesExt for NvramSpecServices<S>

fn get_variable<'life0, 'life1, 'async_trait>( &'life0 mut self, vendor: Guid, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(u32, Vec<u8>), (EfiStatus, Option<NvramError>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get a variable identified by name (as a Rust string) + vendor, returning the variable’s attributes and data.

fn get_variable_ucs2<'life0, 'life1, 'async_trait>( &'life0 mut self, vendor: Guid, name: &'life1 Ucs2LeSlice, ) -> Pin<Box<dyn Future<Output = Result<(u32, Vec<u8>), (EfiStatus, Option<NvramError>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get a variable identified by name (as a UCS-2 string) + vendor, returning the variable’s attributes and data.

fn set_variable<'life0, 'life1, 'async_trait>( &'life0 mut self, vendor: Guid, name: &'life1 str, attr: u32, data: Vec<u8>, ) -> Pin<Box<dyn Future<Output = Result<(), (EfiStatus, Option<NvramError>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Set a variable identified by name (as a Rust string) + vendor with the specified attr and data.

fn set_variable_ucs2<'life0, 'life1, 'async_trait>( &'life0 mut self, vendor: Guid, name: &'life1 Ucs2LeSlice, attr: u32, data: Vec<u8>, ) -> Pin<Box<dyn Future<Output = Result<(), (EfiStatus, Option<NvramError>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Set a variable identified by name (as a UCS-2 string) + vendor with the specified attr and data.

impl<S: InspectableNvramStorage> SaveRestore for NvramSpecServices<S>

type SavedState = SavedState

The concrete saved state type.

fn save(&mut self) -> Result<Self::SavedState, SaveError>

Saves the object’s state.

fn restore(&mut self, state: Self::SavedState) -> Result<(), RestoreError>

Restores the object’s state.