Struct uefi::table::SystemTable

pub struct SystemTable<View: SystemTableView> { /* private fields */ }

UEFI System Table interface

The UEFI System Table is the gateway to all UEFI services which an UEFI application is provided access to on startup. However, not all UEFI services will remain accessible forever.

Some services, called “boot services”, may only be called during a bootstrap stage where the UEFI firmware still has control of the hardware, and will become unavailable once the firmware hands over control of the hardware to an operating system loader. Others, called “runtime services”, may still be used after that point, but require a rather specific CPU configuration which an operating system loader is unlikely to preserve.

We handle this state transition by providing two different views of the UEFI system table, the “Boot” view and the “Runtime” view. An UEFI application is initially provided with access to the “Boot” view, and may transition to the “Runtime” view through the ExitBootServices mechanism that is documented in the UEFI spec. At that point, the boot view of the system table will be destroyed (which conveniently invalidates all references to UEFI boot services in the eye of the Rust borrow checker) and a runtime view will be provided to replace it.

Implementations

impl<View: SystemTableView> SystemTable<View>

pub fn firmware_vendor(&self) -> &CStr16

Return the firmware vendor string

pub const fn firmware_revision(&self) -> u32

Return the firmware revision

pub const fn uefi_revision(&self) -> Revision

Returns the revision of this table, which is defined to be the revision of the UEFI specification implemented by the firmware.

pub fn config_table(&self) -> &[ConfigTableEntry]

Returns the config table entries, a linear array of structures pointing to other system-specific tables.

pub unsafe fn from_ptr(ptr: *mut c_void) -> Option<Self>

Creates a new SystemTable<View> from a raw address. The address might come from the Multiboot2 information structure or something similar.

Example

use core::ffi::c_void;
use uefi::prelude::{Boot, SystemTable};

let system_table_addr = 0xdeadbeef as *mut c_void;

let mut uefi_system_table = unsafe {
    SystemTable::<Boot>::from_ptr(system_table_addr).expect("Pointer must not be null!")
};

Safety

This function is unsafe because the caller must be sure that the pointer is valid. Otherwise, further operations on the object might result in undefined behaviour, even if the methods aren’t marked as unsafe.

pub fn as_ptr(&self) -> *const c_void

Get the underlying raw pointer.

impl SystemTable<Boot>

pub fn stdin(&mut self) -> &mut Input

Returns the standard input protocol.

pub fn stdout(&mut self) -> &mut Output

Returns the standard output protocol.

pub fn stderr(&mut self) -> &mut Output

Returns the standard error protocol.

pub const fn runtime_services(&self) -> &RuntimeServices

Access runtime services

pub const fn boot_services(&self) -> &BootServices

Access boot services

pub fn exit_boot_services( self, memory_type: MemoryType ) -> (SystemTable<Runtime>, MemoryMap<'static>)

Exit the UEFI boot services.

After this function completes, UEFI hands over control of the hardware to the executing OS loader, which implies that the UEFI boot services are shut down and cannot be used anymore. Only UEFI configuration tables and run-time services can be used, and the latter requires special care from the OS loader. We model this situation by consuming the SystemTable<Boot> view of the System Table and returning a more restricted SystemTable<Runtime> view as an output.

The memory map at the time of exiting boot services is also returned. The map is backed by a allocation with given memory_type. Since the boot services function to free that memory is no longer available after calling exit_boot_services, the allocation is live until the program ends. The lifetime of the memory map is therefore 'static.

Note that once the boot services are exited, associated loggers and allocators can’t use the boot services anymore. For the corresponding abstractions provided by this crate, invoking this function will automatically disable them.

Errors

This function will fail if it is unable to allocate memory for the memory map, if it fails to retrieve the memory map, or if exiting boot services fails (with up to one retry).

All errors are treated as unrecoverable because the system is now in an undefined state. Rather than returning control to the caller, the system will be reset.

pub const unsafe fn unsafe_clone(&self) -> Self

Clone this boot-time UEFI system table interface

Safety

This is unsafe because you must guarantee that the clone will not be used after boot services are exited. However, the singleton-based designs that Rust uses for memory allocation, logging, and panic handling require taking this risk.

impl SystemTable<Runtime>

pub const unsafe fn runtime_services(&self) -> &RuntimeServices

Access runtime services

Safety

This is unsafe because UEFI runtime services require an elaborate CPU configuration which may not be preserved by OS loaders. See the “Calling Conventions” chapter of the UEFI specification for details.

pub unsafe fn set_virtual_address_map( self, map: &mut [MemoryDescriptor], new_system_table_virtual_addr: u64 ) -> Result<Self>

Changes the runtime addressing mode of EFI firmware from physical to virtual. It is up to the caller to translate the old SystemTable address to a new virtual address and provide it for this function. See get_current_system_table_addr

Safety

Setting new virtual memory map is unsafe and may cause undefined behaviors.

pub fn get_current_system_table_addr(&self) -> u64

Return the address of the SystemTable that resides in a UEFI runtime services memory region.

Trait Implementations

impl<View: Debug + SystemTableView> Debug for SystemTable<View>

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

Formats the value using the given formatter.

impl<View: SystemTableView> Table for SystemTable<View>

const SIGNATURE: u64 = 6_076_298_535_811_760_713u64

A unique number assigned by the UEFI specification to the standard tables.