Struct uefi::table::boot::BootServices

source ·
pub struct BootServices(/* private fields */);
Expand description

Contains pointers to all of the boot services.

§Accessing BootServices

A reference to BootServices can only be accessed by calling SystemTable::boot_services.

§Accessing protocols

Protocols can be opened using several methods of BootServices. Most commonly, open_protocol_exclusive should be used. This ensures that nothing else can use the protocol until it is closed, and returns a ScopedProtocol that takes care of closing the protocol when it is dropped.

Other methods for opening protocols:

For protocol definitions, see the proto module.

§Use of UnsafeCell for protocol references

Some protocols require mutable access to themselves. For example, most of the methods of the Output protocol take &mut self, because the internal function pointers specified by UEFI for that protocol take a mutable *This pointer. We don’t want to directly return a mutable reference to a protocol though because the lifetime of the protocol is tied to BootServices. (That lifetime improves safety by ensuring protocols aren’t accessed after exiting boot services.) If methods like open_protocol protocol took a mutable reference to BootServices and returned a mutable reference to a protocol it would prevent all other access to BootServices until the protocol reference was dropped. To work around this, the protocol reference is wrapped in an UnsafeCell. Callers can then get a mutable reference to the protocol if needed.

Implementations§

source§

impl BootServices

source

pub fn image_handle(&self) -> Handle

Get the Handle of the currently-executing image.

source

pub unsafe fn set_image_handle(&self, image_handle: Handle)

Update the global image Handle.

This is called automatically in the main entry point as part of uefi_macros::entry. It should not be called at any other point in time, unless the executable does not use uefi_macros::entry, in which case it should be called once before calling other BootServices functions.

§Safety

This function should only be called as described above, and the image_handle must be a valid image Handle. Then safety guarantees of BootServices::open_protocol_exclusive rely on the global image handle being correct.

source

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.

source

pub fn allocate_pages( &self, ty: AllocateType, mem_ty: MemoryType, count: usize ) -> Result<PhysicalAddress>

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.

§Errors

See section EFI_BOOT_SERVICES.AllocatePages() in the UEFI Specification for more details.

source

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

Frees memory pages allocated by UEFI.

§Safety

The caller must ensure that no references into the allocation remain, and that the memory at the allocation is not used after it is freed.

§Errors

See section EFI_BOOT_SERVICES.FreePages() in the UEFI Specification for more details.

source

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.

source

pub fn memory_map<'buf>( &self, buffer: &'buf mut [u8] ) -> Result<MemoryMap<'buf>>

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.

§Errors

See section EFI_BOOT_SERVICES.GetMemoryMap() in the UEFI Specification for more details.

source

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.

§Errors

See section EFI_BOOT_SERVICES.AllocatePool() in the UEFI Specification for more details.

source

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

Frees memory allocated from a pool.

§Safety

The caller must ensure that no references into the allocation remain, and that the memory at the allocation is not used after it is freed.

§Errors

See section EFI_BOOT_SERVICES.FreePool() in the UEFI Specification for more details.

source

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.

§Errors

See section EFI_BOOT_SERVICES.CreateEvent() in the UEFI Specification for more details.

source

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.

This operation is only supported starting with UEFI 2.0; earlier versions will fail with Status::UNSUPPORTED.

§Safety

The caller must ensure they are passing a valid Guid as event_group, if applicable.

§Errors

See section EFI_BOOT_SERVICES.CreateEventEx() in the UEFI Specification for more details.

source

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

Sets the trigger for EventType::TIMER event.

§Errors

See section EFI_BOOT_SERVICES.SetTimer() in the UEFI Specification for more details.

source

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

§Errors

See section EFI_BOOT_SERVICES.WaitForEvent() in the UEFI Specification for more details.

source

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.

§Errors

See section EFI_BOOT_SERVICES.SignalEvent() in the UEFI Specification for more details.

Currently, (as of UEFI Spec v2.9) this only returns EFI_SUCCESS.

source

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.

§Errors

See section EFI_BOOT_SERVICES.CloseEvent() in the UEFI Specification for more details.

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. To be safe, ensure that error codes are handled properly.

source

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.

§Errors

See section EFI_BOOT_SERVICES.CheckEvent() in the UEFI Specification for more details.

Note: Instead of returning the EFI_NOT_READY error, as listed in the UEFI Specification, this function will return false.

source

pub unsafe fn install_protocol_interface( &self, handle: Option<Handle>, protocol: &Guid, interface: *const c_void ) -> Result<Handle>

Installs a protocol interface on a device handle. If the inner Option in handle is None, one will be created and added to the list of handles in the system and then returned.

When a protocol interface is installed, firmware will call all functions that have registered to wait for that interface to be installed.

§Safety

The caller is responsible for ensuring that they pass a valid Guid for protocol.

§Errors

See section EFI_BOOT_SERVICES.InstallProtocolInterface() in the UEFI Specification for more details.

source

pub unsafe fn reinstall_protocol_interface( &self, handle: Handle, protocol: &Guid, old_interface: *const c_void, new_interface: *const c_void ) -> Result<()>

Reinstalls a protocol interface on a device handle. old_interface is replaced with new_interface. These interfaces may be the same, in which case the registered protocol notifies occur for the handle without replacing the interface.

As with install_protocol_interface, any process that has registered to wait for the installation of the interface is notified.

§Safety

The caller is responsible for ensuring that there are no references to the old_interface that is being removed.

§Errors

See section EFI_BOOT_SERVICES.ReinstallProtocolInterface() in the UEFI Specification for more details.

source

pub unsafe fn uninstall_protocol_interface( &self, handle: Handle, protocol: &Guid, interface: *const c_void ) -> Result<()>

Removes a protocol interface from a device handle.

§Safety

The caller is responsible for ensuring that there are no references to a protocol interface that has been removed. Some protocols may not be able to be removed as there is no information available regarding the references. This includes Console I/O, Block I/O, Disk I/o, and handles to device protocols.

The caller is responsible for ensuring that they pass a valid Guid for protocol.

§Errors

See section EFI_BOOT_SERVICES.UninstallProtocolInterface() in the UEFI Specification for more details.

source

pub fn register_protocol_notify( &self, protocol: &Guid, event: Event ) -> Result<(Event, SearchType<'_>)>

Registers event to be signalled whenever a protocol interface is registered for protocol by install_protocol_interface() or reinstall_protocol_interface().

Once event has been signalled, BootServices::locate_handle() can be used to identify the newly (re)installed handles that support protocol. The returned SearchKey on success corresponds to the search_key parameter in locate_handle().

Events can be unregistered from protocol interface notification by calling close_event().

§Errors

See section EFI_BOOT_SERVICES.RegisterProtocolNotify() in the UEFI Specification for more details.

source

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.

§Errors

See section EFI_BOOT_SERVICES.LocateHandle() in the UEFI Specification for more details.

source

pub fn locate_device_path<P: ProtocolPointer + ?Sized>( &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.

§Errors

See section EFI_BOOT_SERVICES.LocateDevicePath() in the UEFI Specification for more details.

source

pub fn get_handle_for_protocol<P: ProtocolPointer + ?Sized>( &self ) -> Result<Handle>

Find an arbitrary handle that supports a particular Protocol. Returns NOT_FOUND if no handles support the protocol.

This method is a convenient wrapper around BootServices::locate_handle_buffer for getting just one handle. This is useful when you don’t care which handle the protocol is opened on. For example, DevicePathToText isn’t tied to a particular device, so only a single handle is expected to exist.

§Example
use uefi::proto::device_path::text::DevicePathToText;
use uefi::table::boot::{BootServices, OpenProtocolAttributes, OpenProtocolParams};
use uefi::Handle;

let handle = boot_services.get_handle_for_protocol::<DevicePathToText>()?;
let device_path_to_text = boot_services.open_protocol_exclusive::<DevicePathToText>(handle)?;
§Errors

Returns NOT_FOUND if no handles support the requested protocol.

source

pub fn load_image( &self, parent_image_handle: Handle, source: LoadImageSource<'_> ) -> Result<Handle>

Load an EFI image into memory and return a Handle to the image.

There are two ways to load the image: by copying raw image data from a source buffer, or by loading the image via the SimpleFileSystem protocol. See LoadImageSource for more details of the source parameter.

The parent_image_handle is used to initialize the parent_handle field of the LoadedImage protocol for the image.

If the image is successfully loaded, a Handle supporting the LoadedImage and LoadedImageDevicePath protocols is returned. The image can be started with start_image or unloaded with unload_image.

§Errors

See section EFI_BOOT_SERVICES.LoadImage() in the UEFI Specification for more details.

source

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

Unload an EFI image.

§Errors

See section EFI_BOOT_SERVICES.UnloadImage() in the UEFI Specification for more details.

As this function can return an error code from the unloaded image, any error type can be returned by this function.

The following error codes can also be returned while unloading an image:

source

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

Transfer control to a loaded image’s entry point.

§Errors

See section EFI_BOOT_SERVICES.StartImage() in the UEFI Specification for more details.

As this function can return an error code from the started image, any error type can be returned by this function.

The following error code can also be returned while starting an image:

source

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.

source

pub fn stall(&self, time: usize)

Stalls the processor for an amount of time.

The time is in microseconds.

source

pub unsafe fn install_configuration_table( &self, guid_entry: &Guid, table_ptr: *const c_void ) -> Result

Adds, updates, or removes a configuration table entry from the EFI System Table.

§Safety

This relies on table_ptr being allocated in the pool of type uefi::table::boot::MemoryType::RUNTIME_SERVICES_DATA according to the specification. Other memory types such as uefi::table::boot::MemoryType::ACPI_RECLAIM can be considered.

§Errors

See section EFI_BOOT_SERVICES.InstallConfigurationTable() in the UEFI Specification for more details.

source

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.

§Errors

See section EFI_BOOT_SERVICES.SetWatchdogTimer() in the UEFI Specification for more details.

source

pub fn connect_controller( &self, controller: Handle, driver_image: Option<Handle>, remaining_device_path: Option<&DevicePath>, recursive: bool ) -> Result

Connect one or more drivers to a controller.

Usually one disconnects and then reconnects certain drivers to make them rescan some state that changed, e.g. reconnecting a BlockIO handle after your app changed the partitions somehow.

§Errors

See section EFI_BOOT_SERVICES.ConnectController() in the UEFI Specification for more details.

source

pub fn disconnect_controller( &self, controller: Handle, driver_image: Option<Handle>, child: Option<Handle> ) -> Result

Disconnect one or more drivers from a controller.

See connect_controller.

§Errors

See section EFI_BOOT_SERVICES.DisconnectController() in the UEFI Specification for more details.

source

pub unsafe fn open_protocol<P: ProtocolPointer + ?Sized>( &self, params: OpenProtocolParams, attributes: OpenProtocolAttributes ) -> Result<ScopedProtocol<'_, P>>

Open a protocol interface for a handle.

See also open_protocol_exclusive, which provides a safe subset of this functionality.

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_exclusive or open_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.

§Safety

This function is unsafe because it can be used to open a protocol in ways that don’t get tracked by the UEFI implementation. This could allow the protocol to be removed from a handle, or for the handle to be deleted entirely, while a reference to the protocol is still active. The caller is responsible for ensuring that the handle and protocol remain valid until the ScopedProtocol is dropped.

§Errors

See section EFI_BOOT_SERVICES.OpenProtocol() in the UEFI Specification for more details.

source

pub fn open_protocol_exclusive<P: ProtocolPointer + ?Sized>( &self, handle: Handle ) -> Result<ScopedProtocol<'_, P>>

Open a protocol interface for a handle in exclusive mode.

If successful, a ScopedProtocol is returned that will automatically close the protocol interface when dropped.

§Errors

See section EFI_BOOT_SERVICES.OpenProtocol() in the UEFI Specification for more details.

source

pub fn test_protocol<P: ProtocolPointer + ?Sized>( &self, params: OpenProtocolParams ) -> Result<()>

Test whether a handle supports a protocol.

§Errors

See section EFI_BOOT_SERVICES.OpenProtocol() in the UEFI Specification for more details.

source

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

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

§Errors

See section EFI_BOOT_SERVICES.ProtocolsPerHandle() in the UEFI Specification for more details.

source

pub fn locate_handle_buffer( &self, search_ty: SearchType<'_> ) -> Result<HandleBuffer<'_>>

Returns an array of handles that support the requested protocol in a buffer allocated from pool.

§Errors

See section EFI_BOOT_SERVICES.LocateHandleBuffer() in the UEFI Specification for more details.

source

pub fn get_image_file_system( &self, image_handle: Handle ) -> Result<ScopedProtocol<'_, SimpleFileSystem>>

Retrieves a SimpleFileSystem protocol associated with the device the given image was loaded from.

§Errors

This function can return errors from open_protocol_exclusive and locate_device_path. See those functions for more details.

source§

impl BootServices

source

pub fn find_handles<P: ProtocolPointer + ?Sized>(&self) -> Result<Vec<Handle>>

Available on crate feature alloc only.

Returns all the handles implementing a certain protocol.

§Errors

All errors come from calls to locate_handle.

Trait Implementations§

source§

impl Debug for BootServices

source§

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

Formats the value using the given formatter. Read more
source§

impl Table for BootServices

source§

const SIGNATURE: u64 = 6_220_110_259_551_162_178u64

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

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Pointee for T

§

type Metadata = ()

The type for metadata in pointers and references to Self.
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.