Repository files navigation

UEFI started as the successor firmware to the BIOS in x86 space and developedto a universal firmware specification for various platforms, such as ARM. Itprovides an early boot environment with a variety ofspecifiedready-to-use "high-level" functionality, such as accessing disks or the network.EFI images, the files that can be loaded by an UEFI environment, can leveragethese abstractions to extend the functionality in form of additional drivers,OS-specific bootloaders, or different kind of low-level applications.

Our mission is to providesafe andperformant wrappers for UEFIinterfaces, and allow developers to write idiomatic Rust code.

This repository provides various crates:

• uefi-raw: Raw Rust UEFI bindings for basic structures and functions.
• uefi: High-level wrapper around various low-level UEFI APIs.
  Offers various optional features for typical Rust convenience, such as aLogger and an Allocator. (This is what you are usually looking for!)
• uefi-macros: Helper macros. Used byuefi.

You can use the abstractions for example to:

• create OS-specific loaders and leverage UEFI boot service
• access UEFI runtime services from an OS

All crates are compatible with all platforms that both the Rust compiler andUEFI support, such asi686,x86_64, andaarch64). Please note that wecan't test all possible hardware/firmware/platform combinations.

Screenshot of an application running in QEMU on an UEFI firmware that leveragesour Rust library.

For a quick start, please check outthe UEFI application template.

Theuefi-rs book contains a tutorial, how-tos, and overviews of some importantUEFI concepts. Reference documentation for the various crates can be found ondocs.rs:

• docs.rs/uefi
• docs.rs/uefi-macros
• docs.rs/uefi-raw

For additional information, refer to theUEFI specification.

See theuefi package's README.

This project contains multiple sub-crates:

• uefi: defines the standard UEFI tables / interfaces.The objective is to stay unopinionated and safely wrap most interfaces.Additional opinionated features (such as a Logger) are feature-gated.

• uefi-macros: procedural macros that are used to derive some traitsinuefi.

• uefi-raw: raw types that closely match the definitions in the UEFISpecification. Safe wrappers for these types are provided by theueficrate. The raw types are suitable for implementing UEFI firmware.

• uefi-test-runner: a UEFI application that runs unit / integration tests.

Use thecargo xtask command to build and test the crate.

Available commands:

• build: build all the UEFI packages
  • --release: build in release mode
  • --target {x86_64,ia32,aarch64}: choose target UEFI arch
• clippy: run clippy on all the packages
  • --target {x86_64,ia32,aarch64}: choose target UEFI arch
  • --warnings-as-errors: treat warnings as errors
• doc: build the docs for the UEFI packages
  • --open: open the docs in a browser
  • --warnings-as-errors: treat warnings as errors
• run: builduefi-test-runner and run it in QEMU
  • --ci: disable some tests that don't work in the CI
  • --disable-kvm: disable hardware accelerated virtualization support inQEMU.Especially useful if you want to run the tests underWSL on Windows.
  • --example <NAME>: run an example instead of the main binary.
  • --headless: run QEMU without a GUI
  • --ovmf-code <PATH>: path of an OVMF code file
  • --ovmf-vars <PATH>: path of an OVMF vars file
  • --release: build in release mode
  • --target {x86_64,ia32,aarch64}: choose target UEFI arch
• test: run unit tests and doctests on the host

Theuefi-test-runner directory contains a sample UEFI app which exercisesmost of the library's functionality.

Check out the testing project'sREADME.md forprerequisites for running the tests.

We welcome issues and pull requests! For instructions on how to set up adevelopment environment and how to add new protocols, check outCONTRIBUTING.md.

The code in this repository is licensed under the Mozilla Public License 2.This license allows you to use the crate in proprietary programs, but anymodifications to the files must be open-sourced.

The full text of the license is available in thelicense file.