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!

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: Implement a [global allocator] using UEFI functions. 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-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.

The global_allocator and logger features require special handling to perform initialization and tear-down. The uefi-services crate provides an init method that takes care of this.

Re-exports

• pub use self::data_types::CString16;
• pub use self::data_types::Identify;
• 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::Guid;
• pub use self::data_types::Handle;

Modules

• data_types
  Data type definitions
• global_allocatorglobal_allocator
  This module implements Rust’s global allocator interface using UEFI’s memory allocation functions.
• loggerlogger
  This optional feature adds support for the log crate, providing a custom logger implementation which writes to a UEFI text output protocol.
• 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 at compile time.
• newtype_enum
  Interface a C-style enum as an integer newtype.

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.
• Status
  UEFI uses status codes in order to report successes, errors, and warnings.

Traits

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

Type Definitions

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