#[repr(C)]pub struct BootServices { /* private fields */ }
Expand description
Contains pointers to all of the boot services.
Implementations
sourceimpl BootServices
impl BootServices
sourcepub unsafe fn raise_tpl(&self, tpl: Tpl) -> TplGuard<'_>
pub unsafe fn raise_tpl(&self, tpl: Tpl) -> TplGuard<'_>
Raises a task’s priority level and returns its previous level.
The effect of calling raise_tpl
with a Tpl
that is below the current
one (which, sadly, cannot be queried) is undefined by the UEFI spec,
which also warns against remaining at high Tpl
s for a long time.
This function outputs an RAII guard that will automatically restore the
original Tpl
when dropped.
Safety
Raising a task’s priority level can affect other running tasks and critical processes run by UEFI. The highest priority level is the most dangerous, since it disables interrupts.
sourcepub fn allocate_pages(
&self,
ty: AllocateType,
mem_ty: MemoryType,
count: usize
) -> Result<u64>
pub fn allocate_pages(
&self,
ty: AllocateType,
mem_ty: MemoryType,
count: usize
) -> Result<u64>
Allocates memory pages from the system.
UEFI OS loaders should allocate memory of the type LoaderData
. An u64
is returned even on 32-bit platforms because some hardware configurations
like Intel PAE enable 64-bit physical addressing on a 32-bit processor.
sourcepub fn free_pages(&self, addr: u64, count: usize) -> Result
pub fn free_pages(&self, addr: u64, count: usize) -> Result
Frees memory pages allocated by UEFI.
sourcepub fn memory_map_size(&self) -> MemoryMapSize
pub fn memory_map_size(&self) -> MemoryMapSize
Returns struct which contains the size of a single memory descriptor as well as the size of the current memory map.
Note that the size of the memory map can increase any time an allocation happens, so when creating a buffer to put the memory map into, it’s recommended to allocate a few extra elements worth of space above the size of the current memory map.
sourcepub fn memory_map<'buf>(
&self,
buffer: &'buf mut [u8]
) -> Result<(MemoryMapKey, impl ExactSizeIterator<Item = &'buf MemoryDescriptor> + Clone)>
pub fn memory_map<'buf>(
&self,
buffer: &'buf mut [u8]
) -> Result<(MemoryMapKey, impl ExactSizeIterator<Item = &'buf MemoryDescriptor> + Clone)>
Retrieves the current memory map.
The allocated buffer should be big enough to contain the memory map,
and a way of estimating how big it should be is by calling memory_map_size
.
The buffer must be aligned like a MemoryDescriptor
.
The returned key is a unique identifier of the current configuration of memory. Any allocations or such will change the memory map’s key.
If you want to store the resulting memory map without having to keep
the buffer around, you can use .copied().collect()
on the iterator.
sourcepub fn allocate_pool(&self, mem_ty: MemoryType, size: usize) -> Result<*mut u8>
pub fn allocate_pool(&self, mem_ty: MemoryType, size: usize) -> Result<*mut u8>
Allocates from a memory pool. The pointer will be 8-byte aligned.
sourcepub unsafe fn create_event(
&self,
event_ty: EventType,
notify_tpl: Tpl,
notify_fn: Option<unsafe extern "efiapi" fn(event: Event, context: Option<NonNull<c_void>>)>,
notify_ctx: Option<NonNull<c_void>>
) -> Result<Event>
pub unsafe fn create_event(
&self,
event_ty: EventType,
notify_tpl: Tpl,
notify_fn: Option<unsafe extern "efiapi" fn(event: Event, context: Option<NonNull<c_void>>)>,
notify_ctx: Option<NonNull<c_void>>
) -> Result<Event>
Creates an event
This function creates a new event of the specified type and returns it.
Events are created in a “waiting” state, and may switch to a “signaled”
state. If the event type has flag NotifySignal
set, this will result in
a callback for the event being immediately enqueued at the notify_tpl
priority level. If the event type has flag NotifyWait
, the notification
will be delivered next time wait_for_event
or check_event
is called.
In both cases, a notify_fn
callback must be specified.
Safety
This function is unsafe because callbacks must handle exit from boot services correctly.
sourcepub unsafe fn create_event_ex(
&self,
event_type: EventType,
notify_tpl: Tpl,
notify_fn: Option<unsafe extern "efiapi" fn(event: Event, context: Option<NonNull<c_void>>)>,
notify_ctx: Option<NonNull<c_void>>,
event_group: Option<NonNull<Guid>>
) -> Result<Event>
pub unsafe fn create_event_ex(
&self,
event_type: EventType,
notify_tpl: Tpl,
notify_fn: Option<unsafe extern "efiapi" fn(event: Event, context: Option<NonNull<c_void>>)>,
notify_ctx: Option<NonNull<c_void>>,
event_group: Option<NonNull<Guid>>
) -> Result<Event>
Creates a new Event
of type event_type
. The event’s notification function, context,
and task priority are specified by notify_fn
, notify_ctx
, and notify_tpl
, respectively.
The Event
will be added to the group of Event
s identified by event_group
.
If no group is specified by event_group
, this function behaves as if the same parameters
had been passed to create_event()
.
Event groups are collections of events identified by a shared Guid
where, when one member
event is signaled, all other events are signaled and their individual notification actions
are taken. All events are guaranteed to be signaled before the first notification action is
taken. All notification functions will be executed in the order specified by their Tpl
.
A single event can only be part of a single event group. An event may be removed from an
event group by using close_event()
.
The EventType
of an event uses the same values as create_event()
, except that
EventType::SIGNAL_EXIT_BOOT_SERVICES
and EventType::SIGNAL_VIRTUAL_ADDRESS_CHANGE
are not valid.
If event_type
has EventType::NOTIFY_SIGNAL
or EventType::NOTIFY_WAIT
, then notify_fn
mus be Some
and notify_tpl
must be a valid task priority level, otherwise these parameters
are ignored.
More than one event of type EventType::TIMER
may be part of a single event group. However,
there is no mechanism for determining which of the timers was signaled.
Safety
The caller must ensure they are passing a valid Guid
as event_group
, if applicable.
sourcepub fn set_timer(&self, event: &Event, trigger_time: TimerTrigger) -> Result
pub fn set_timer(&self, event: &Event, trigger_time: TimerTrigger) -> Result
Sets the trigger for EventType::TIMER
event.
sourcepub fn wait_for_event(
&self,
events: &mut [Event]
) -> Result<usize, Option<usize>>
pub fn wait_for_event(
&self,
events: &mut [Event]
) -> Result<usize, Option<usize>>
Stops execution until an event is signaled.
This function must be called at priority level Tpl::APPLICATION
. If an
attempt is made to call it at any other priority level, an Unsupported
error is returned.
The input Event
slice is repeatedly iterated from first to last until
an event is signaled or an error is detected. The following checks are
performed on each event:
- If an event is of type
NotifySignal
, then anInvalidParameter
error is returned with the index of the eve,t that caused the failure. - If an event is in the signaled state, the signaled state is cleared and the index of the event that was signaled is returned.
- If an event is not in the signaled state but does have a notification function, the notification function is queued at the event’s notification task priority level. If the execution of the event’s notification function causes the event to be signaled, then the signaled state is cleared and the index of the event that was signaled is returned.
To wait for a specified time, a timer event must be included in the Event slice.
To check if an event is signaled without waiting, an already signaled event can be used as the last event in the slice being checked, or the check_event() interface may be used.
sourcepub fn signal_event(&self, event: &Event) -> Result
pub fn signal_event(&self, event: &Event) -> Result
Place ‘event’ in the signaled stated. If ‘event’ is already in the signaled state,
then nothing further occurs and Status::SUCCESS
is returned. If event
is of type
EventType::NOTIFY_SIGNAL
, then the event’s notification function is scheduled to
be invoked at the event’s notification task priority level.
This function may be invoked from any task priority level.
If event
is part of an event group, then all of the events in the event group are
also signaled and their notification functions are scheduled.
When signaling an event group, it is possible to create an event in the group, signal it, and then close the event to remove it from the group.
sourcepub fn close_event(&self, event: Event) -> Result
pub fn close_event(&self, event: Event) -> Result
Removes event
from any event group to which it belongs and closes it. If event
was
registered with register_protocol_notify()
, then the corresponding registration will
be removed. It is safe to call this function within the corresponding notify function.
Note: The UEFI Specification v2.9 states that this may only return EFI_SUCCESS
, but,
at least for application based on EDK2 (such as OVMF), it may also return EFI_INVALID_PARAMETER
.
sourcepub fn check_event(&self, event: Event) -> Result<bool>
pub fn check_event(&self, event: Event) -> Result<bool>
Checks to see if an event is signaled, without blocking execution to wait for it.
The returned value will be true
if the event is in the signaled state,
otherwise false
is returned.
sourcepub fn handle_protocol<P: Protocol>(
&self,
handle: Handle
) -> Result<&UnsafeCell<P>>
👎 Deprecated: it is recommended to use open_protocol
instead
pub fn handle_protocol<P: Protocol>(
&self,
handle: Handle
) -> Result<&UnsafeCell<P>>
it is recommended to use open_protocol
instead
Query a handle for a certain protocol.
This function attempts to get the protocol implementation of a handle, based on the protocol GUID.
It is recommended that all new drivers and applications use
open_protocol
instead of handle_protocol
.
UEFI protocols are neither thread-safe nor reentrant, but the firmware
provides no mechanism to protect against concurrent usage. Such
protections must be implemented by user-level code, for example via a
global HashSet
.
sourcepub fn locate_handle(
&self,
search_ty: SearchType<'_>,
output: Option<&mut [MaybeUninit<Handle>]>
) -> Result<usize>
pub fn locate_handle(
&self,
search_ty: SearchType<'_>,
output: Option<&mut [MaybeUninit<Handle>]>
) -> Result<usize>
Enumerates all handles installed on the system which match a certain query.
You should first call this function with None
for the output buffer,
in order to retrieve the length of the buffer you need to allocate.
The next call will fill the buffer with the requested data.
sourcepub fn locate_device_path<P: Protocol>(
&self,
device_path: &mut &DevicePath
) -> Result<Handle>
pub fn locate_device_path<P: Protocol>(
&self,
device_path: &mut &DevicePath
) -> Result<Handle>
Locates the handle to a device on the device path that supports the specified protocol.
The device_path
is updated to point at the remaining part of the DevicePath
after
the part that matched the protocol. For example, it can be used with a device path
that contains a file path to strip off the file system portion of the device path,
leaving the file path and handle to the file system driver needed to access the file.
If the first node of device_path
matches the
protocol, the device_path
is advanced to the device path terminator node. If device_path
is a multi-instance device path, the function will operate on the first instance.
sourcepub fn load_image_from_buffer(
&self,
parent_image_handle: Handle,
source_buffer: &[u8]
) -> Result<Handle>
pub fn load_image_from_buffer(
&self,
parent_image_handle: Handle,
source_buffer: &[u8]
) -> Result<Handle>
Load an EFI image from a buffer.
sourcepub fn unload_image(&self, image_handle: Handle) -> Result
pub fn unload_image(&self, image_handle: Handle) -> Result
Unload an EFI image.
sourcepub fn start_image(&self, image_handle: Handle) -> Result
pub fn start_image(&self, image_handle: Handle) -> Result
Transfer control to a loaded image’s entry point.
sourcepub unsafe fn exit(
&self,
image_handle: Handle,
exit_status: Status,
exit_data_size: usize,
exit_data: *mut Char16
) -> !
pub unsafe fn exit(
&self,
image_handle: Handle,
exit_status: Status,
exit_data_size: usize,
exit_data: *mut Char16
) -> !
Exits the UEFI application and returns control to the UEFI component that started the UEFI application.
Safety
This function is unsafe because it is up to the caller to ensure that all resources allocated by the application is freed before invoking exit and returning control to the UEFI component that started the UEFI application.
sourcepub fn stall(&self, time: usize)
pub fn stall(&self, time: usize)
Stalls the processor for an amount of time.
The time is in microseconds.
sourcepub fn set_watchdog_timer(
&self,
timeout: usize,
watchdog_code: u64,
data: Option<&mut [u16]>
) -> Result
pub fn set_watchdog_timer(
&self,
timeout: usize,
watchdog_code: u64,
data: Option<&mut [u16]>
) -> Result
Set the watchdog timer.
UEFI will start a 5-minute countdown after an UEFI image is loaded.
The image must either successfully load an OS and call ExitBootServices
in that time, or disable the watchdog.
Otherwise, the firmware will log the event using the provided numeric code and data, then reset the system.
This function allows you to change the watchdog timer’s timeout to a certain amount of seconds or to disable the watchdog entirely. It also allows you to change what will be logged when the timer expires.
The watchdog codes from 0 to 0xffff (65535) are reserved for internal firmware use. Higher values can be used freely by applications.
If provided, the watchdog data must be a null-terminated string optionally followed by other binary data.
sourcepub fn open_protocol<P: Protocol>(
&self,
params: OpenProtocolParams,
attributes: OpenProtocolAttributes
) -> Result<ScopedProtocol<'_, P>>
pub fn open_protocol<P: Protocol>(
&self,
params: OpenProtocolParams,
attributes: OpenProtocolAttributes
) -> Result<ScopedProtocol<'_, P>>
Open a protocol interface for a handle.
This function attempts to get the protocol implementation of a
handle, based on the protocol GUID. It is an extended version of
handle_protocol
. It is recommended that all
new drivers and applications use open_protocol
instead of
handle_protocol
.
See OpenProtocolParams
and OpenProtocolAttributes
for
details of the input parameters.
If successful, a ScopedProtocol
is returned that will
automatically close the protocol interface when dropped.
UEFI protocols are neither thread-safe nor reentrant, but the firmware
provides no mechanism to protect against concurrent usage. Such
protections must be implemented by user-level code, for example via a
global HashSet
.
sourcepub fn test_protocol<P: Protocol>(
&self,
params: OpenProtocolParams
) -> Result<()>
pub fn test_protocol<P: Protocol>(
&self,
params: OpenProtocolParams
) -> Result<()>
Test whether a handle supports a protocol.
sourcepub fn protocols_per_handle(
&self,
handle: Handle
) -> Result<ProtocolsPerHandle<'_>>
pub fn protocols_per_handle(
&self,
handle: Handle
) -> Result<ProtocolsPerHandle<'_>>
sourcepub fn locate_protocol<P: Protocol>(&self) -> Result<&UnsafeCell<P>>
pub fn locate_protocol<P: Protocol>(&self) -> Result<&UnsafeCell<P>>
Returns a protocol implementation, if present on the system.
The caveats of BootServices::handle_protocol()
also apply here.
sourceimpl BootServices
impl BootServices
sourcepub fn find_handles<P: Protocol>(&self) -> Result<Vec<Handle>>
pub fn find_handles<P: Protocol>(&self) -> Result<Vec<Handle>>
Returns all the handles implementing a certain protocol.
sourcepub fn get_image_file_system(
&self,
image_handle: Handle
) -> Result<ScopedProtocol<'_, SimpleFileSystem>>
pub fn get_image_file_system(
&self,
image_handle: Handle
) -> Result<ScopedProtocol<'_, SimpleFileSystem>>
Retrieves the SimpleFileSystem
protocol associated with
the device the given image was loaded from.
You can retrieve the SFS protocol associated with the boot partition by passing the image handle received by the UEFI entry point to this function.
Trait Implementations
sourceimpl Debug for BootServices
impl Debug for BootServices
Auto Trait Implementations
impl RefUnwindSafe for BootServices
impl Send for BootServices
impl Sync for BootServices
impl Unpin for BootServices
impl UnwindSafe for BootServices
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more