Expand description
Rusty wrapper for the Unified Extensible Firmware Interface.
See the Rust UEFI Book for a tutorial, how-tos, and overviews of some important UEFI concepts. For more details of UEFI, see the latest UEFI Specification.
Feel free to file bug reports and questions in our issue tracker, and PR contributions are also welcome!
§Interaction with uefi services
With this crate you can write code for the pre- and post-exit boot services
epochs. However, the uefi
crate unfolds its true potential when
interacting with UEFI boot services.
§Crate organisation
The top-level module contains some of the most used types and macros,
including the Handle
and Result
types, the CStr16
and
CString16
types for working with UCS-2 strings, and the entry
and
guid
macros.
§Tables
The SystemTable
provides access to almost everything in UEFI. It comes
in two flavors:
SystemTable<Boot>
: for boot-time applications such as bootloaders, provides access to both boot and runtime services.SystemTable<Runtime>
: for operating systems after boot services have been exited.
§Protocols
When boot services are active, most functionality is provided via UEFI protocols. Protocols provide operations such as reading and writing files, drawing to the screen, sending and receiving network requests, and much more. The list of protocols that are actually available when running an application depends on the device. For example, a PC with no network card may not provide network protocols.
See the BootServices
documentation for details of how to open a
protocol, and see the proto
module for protocol implementations. New
protocols can be defined with the unsafe_protocol
macro.
§Optional crate features
alloc
: Enable functionality requiring thealloc
crate from the Rust standard library. For example, methods that return aVec
rather than filling a statically-sized array. This requires a global allocator; you can use theglobal_allocator
feature or provide your own.global_allocator
: Setallocator::Allocator
as the global Rust allocator. This is a simple allocator that relies on the UEFI pool allocator. You can choose to provide your own allocator instead of using this feature, or no allocator at all if you don’t need to dynamically allocate any memory.logger
: Logging implementation for the standardlog
crate that prints output to the UEFI console. No buffering is done; this is not a high-performance logger.panic_handler
: Add a default panic handler that logs tostdout
.panic-on-logger-errors
(enabled by default): Panic if a text output error occurs in the logger.unstable
: Enable functionality that depends on unstable features in the nightly compiler. As example, in conjunction with thealloc
-feature, this gate allows theallocator_api
on certain functions.qemu
: Enable some code paths to adapt their execution when executed in QEMU, such as using the specialqemu-exit
device when the panic handler is called.
Some of these features, such as the logger
or panic_handler
features,
only unfold their potential when you invoke uefi::helpers::init
as soon
as possible in your application.
Re-exports§
pub use self::data_types::CString16;
alloc
pub use self::data_types::CStr16;
pub use self::data_types::CStr8;
pub use self::data_types::Char16;
pub use self::data_types::Char8;
pub use self::data_types::Event;
pub use self::data_types::Handle;
pub use self::data_types::Identify;
Modules§
- This module implements Rust’s global allocator interface using UEFI’s memory allocation functions.
- Data type definitions
- fs
alloc
A high-level file system API for UEFI applications close to thestd::fs
module from Rust’s standard library. The main export of this module isFileSystem
. - This module provides miscellaneous opinionated but optional helpers to better integrate your application with the Rust runtime and the Rust ecosystem.
- This module is used to simplify importing the most common UEFI types.
- Protocol definitions.
- Standard UEFI tables.
Macros§
- Builds a
CStr8
literal at compile time from a string literal. - Builds a
CStr16
literal at compile time from a string literal. - Create a
Guid
from a string at compile time. - Create an opaque struct suitable for use as an FFI pointer.
- Prints to the standard output.
- Prints to the standard output, with a newline.
Structs§
- An UEFI-related error with optionally additional payload data. The error kind is encoded in the
status
field (seeStatus
). Additional payload may be inside thedata
field. - Globally-unique identifier.
- UEFI uses status codes in order to report successes, errors, and warnings.
Traits§
- Extension trait which provides some convenience methods for
Result
. - Extension trait which provides some convenience methods for
Status
.
Type Aliases§
- Return type of most UEFI functions. Both success and error payloads are optional.
Attribute Macros§
- Custom attribute for a UEFI executable entry point.