Struct uefi::table::boot::BootServices

#[repr(C)]
pub struct BootServices { /* private fields */ }

Contains pointers to all of the boot services.

Implementations

impl BootServices

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

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.

pub fn free_pages(&self, addr: u64, count: usize) -> Result

Frees memory pages allocated by UEFI.

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.

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.

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.

pub fn free_pool(&self, addr: *mut u8) -> Result

Frees memory allocated from a pool.

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.

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

pub fn set_timer(&self, event: &Event, trigger_time: TimerTrigger) -> Result

Sets the trigger for EventType::TIMER event.

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 an InvalidParameter 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.

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.

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.

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.

pub fn handle_protocol<P: Protocol>(
    &self,
    handle: Handle
) -> Result<&UnsafeCell<P>>

👎 Deprecated:

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.

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.

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.

pub fn load_image_from_buffer(
    &self,
    parent_image_handle: Handle,
    source_buffer: &[u8]
) -> Result<Handle>

Load an EFI image from a buffer.

pub fn unload_image(&self, image_handle: Handle) -> Result

Unload an EFI image.

pub fn start_image(&self, image_handle: Handle) -> Result

Transfer control to a loaded image’s entry point.

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.

pub fn stall(&self, time: usize)

Stalls the processor for an amount of time.

The time is in microseconds.

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.

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.

pub fn test_protocol<P: Protocol>(
    &self,
    params: OpenProtocolParams
) -> Result<()>

Test whether a handle supports a protocol.

pub fn protocols_per_handle(
    &self,
    handle: Handle
) -> Result<ProtocolsPerHandle<'_>>

Get the list of protocol interface Guids that are installed on a Handle.

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.

pub unsafe fn memmove(&self, dest: *mut u8, src: *const u8, size: usize)

Copies memory from source to destination. The buffers can overlap.

Safety

This function is unsafe as it can be used to violate most safety invariants of the Rust type system.

pub unsafe fn set_mem(&self, buffer: *mut u8, size: usize, value: u8)

Sets a buffer to a certain value.

Safety

This function is unsafe as it can be used to violate most safety invariants of the Rust type system.

impl BootServices

pub fn find_handles<P: Protocol>(&self) -> Result<Vec<Handle>>

Returns all the handles implementing a certain protocol.

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

impl Debug for BootServices

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Table for BootServices

const SIGNATURE: u64

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