Struct uefi::table::SystemTable

#[repr(transparent)]pub struct SystemTable<View: SystemTableView> { /* fields omitted */ }

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 fn firmware_revision(&self) -> Revision

Return the firmware revision

pub 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.

impl SystemTable<Boot>

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

Returns the standard input protocol.

pub fn stdout(&self) -> &mut Output<'_>

Returns the standard output protocol.

pub fn stderr(&self) -> &mut Output<'_>

Returns the standard error protocol.

pub fn runtime_services(&self) -> &RuntimeServices

Access runtime services

pub fn boot_services(&self) -> &BootServices

Access boot services

pub fn exit_boot_services(
    self,
    image: Handle,
    mmap_buf: &mut [u8]
) -> Result<(SystemTable<Runtime>, impl ExactSizeIterator<Item = &MemoryDescriptor> + Clone)>

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 handle passed must be the one of the currently executing image, which is received by the entry point of the UEFI application. In addition, the application must provide storage for a memory map, which will be retrieved automatically (as having an up-to-date memory map is a prerequisite for exiting UEFI boot services).

The storage must be aligned like a MemoryDescriptor.

The size of the memory map can be estimated by calling BootServices::memory_map_size(). But the memory map can grow under the hood between the moment where this size estimate is returned and the moment where boot services are exited, and calling the UEFI memory allocator will not be possible after the first attempt to exit the boot services. Therefore, UEFI applications are advised to allocate storage for the memory map right before exiting boot services, and to allocate a bit more storage than requested by memory_map_size.

If exit_boot_services succeeds, it will return a runtime view of the system table which more accurately reflects the state of the UEFI firmware following exit from boot services, along with a high-level iterator to the UEFI memory map.

pub 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 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.

Trait Implementations

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

pub const SIGNATURE: u64

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