Crate uefi

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 the alloc crate from the Rust standard library. For example, methods that return a Vec rather than filling a statically-sized array. This requires a global allocator; you can use the global_allocator feature or provide your own.
• global_allocator: Set allocator::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 standard log 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 to stdout.
• 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 the alloc-feature, this gate allows the allocator_api on certain functions.
• qemu: Enable some code paths to adapt their execution when executed in QEMU, such as using the special qemu-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

• allocator
  This module implements Rust’s global allocator interface using UEFI’s memory allocation functions.
• data_types
  Data type definitions
• fsalloc
  A high-level file system API for UEFI applications close to the std::fs module from Rust’s standard library. The main export of this module is FileSystem.
• helpers
  This module provides miscellaneous opinionated but optional helpers to better integrate your application with the Rust runtime and the Rust ecosystem.
• prelude
  This module is used to simplify importing the most common UEFI types.
• proto
  Protocol definitions.
• table
  Standard UEFI tables.

Macros

• cstr8
  Builds a CStr8 literal at compile time from a string literal.
• cstr16
  Builds a CStr16 literal at compile time from a string literal.
• guid
  Create a Guid from a string at compile time.
• opaque_type
  Create an opaque struct suitable for use as an FFI pointer.
• print
  Prints to the standard output.
• println
  Prints to the standard output, with a newline.

Structs

• Error
  An UEFI-related error with optionally additional payload data. The error kind is encoded in the status field (see Status). Additional payload may be inside the data field.
• Guid
  Globally-unique identifier.
• Status
  UEFI uses status codes in order to report successes, errors, and warnings.

Traits

• ResultExt
  Extension trait which provides some convenience methods for Result.
• StatusExt
  Extension trait which provides some convenience methods for Status.

Type Aliases

• Result
  Return type of most UEFI functions. Both success and error payloads are optional.

Attribute Macros

• entry
  Custom attribute for a UEFI executable entry point.