Struct uefi::table::boot::BootServices

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

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) -> usize

Retrieves the size, in bytes, of the current memory map.

A buffer of this size will be capable of holding the whole current memory map, including padding. Note, however, that allocations will increase the size of the memory map, therefore it is better to allocate some extra space.

pub fn memory_map<'buf>(
    &self,
    buffer: &'buf mut [u8]
) -> Result<(MemoryMapKey, MemoryMapIter<'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.

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<fn(_: Event)>
) -> 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 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 set_timer(&self, event: Event, trigger_time: TimerTrigger) -> Result

Sets the trigger for EventType::TIMER event.

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

Query a handle for a certain protocol.

This function attempts to get the protocol implementation of a handle, based on the protocol GUID.

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 [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 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 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 memset(&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.

Trait Implementations

impl Table for BootServices

const SIGNATURE: u64

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