Struct uefi::table::SystemTable
source · pub struct SystemTable<View: SystemTableView> { /* private fields */ }
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§
source§impl<View: SystemTableView> SystemTable<View>
impl<View: SystemTableView> SystemTable<View>
sourcepub fn firmware_vendor(&self) -> &CStr16
pub fn firmware_vendor(&self) -> &CStr16
Return the firmware vendor string
sourcepub const fn firmware_revision(&self) -> u32
pub const fn firmware_revision(&self) -> u32
Return the firmware revision
sourcepub const fn uefi_revision(&self) -> 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.
sourcepub fn config_table(&self) -> &[ConfigTableEntry]
pub fn config_table(&self) -> &[ConfigTableEntry]
Returns the config table entries, a linear array of structures pointing to other system-specific tables.
sourcepub unsafe fn from_ptr(ptr: *mut c_void) -> Option<Self>
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.
source§impl SystemTable<Boot>
impl SystemTable<Boot>
sourcepub const fn runtime_services(&self) -> &RuntimeServices
pub const fn runtime_services(&self) -> &RuntimeServices
Access runtime services
sourcepub const fn boot_services(&self) -> &BootServices
pub const fn boot_services(&self) -> &BootServices
Access boot services
sourcepub fn exit_boot_services(
self,
memory_type: MemoryType
) -> (SystemTable<Runtime>, MemoryMap<'static>)
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
.
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 allocator::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.
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.
sourcepub const unsafe fn unsafe_clone(&self) -> Self
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.
source§impl SystemTable<Runtime>
impl SystemTable<Runtime>
sourcepub const unsafe fn runtime_services(&self) -> &RuntimeServices
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.
sourcepub 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.
sourcepub fn get_current_system_table_addr(&self) -> u64
pub fn get_current_system_table_addr(&self) -> u64
Return the address of the SystemTable that resides in a UEFI runtime services memory region.