Struct uefi::table::SystemTable [−][src]
#[repr(transparent)]pub struct SystemTable<View: SystemTableView> { /* fields omitted */ }Expand description
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
Return the firmware vendor string
Return the firmware revision
Returns the revision of this table, which is defined to be the revision of the UEFI specification implemented by the firmware.
Returns the config table entries, a linear array of structures pointing to other system-specific tables.
Access runtime services
Access boot services
pub fn exit_boot_services(
self,
image: Handle,
mmap_buf: &mut [u8]
) -> Result<(SystemTable<Runtime>, impl ExactSizeIterator<Item = &MemoryDescriptor> + Clone)>
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.
Once boot services are exited, the logger and allocator provided by
this crate can no longer be used. The logger should be disabled using
the Logger::disable method, and the allocator should be disabled by
calling alloc::exit_boot_services. Note that if the logger and
allocator were initialized with uefi_services::init, they will be
disabled automatically when exit_boot_services is called.
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.
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.
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>
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.
Return the address of the SystemTable that resides in a UEFI runtime services memory region.