Struct uefi::prelude::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.
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.