Patina

This repository hosts the Patina project - a Rust implementation of UEFI firmware.

The goal of this project is to serve as a replacement for core UEFI firmware components so they are written in Pure Rust as opposed to Rust wrappers around core implementation still written in C.

We host a Patina Community Call. Details are maintained in the discussion thread. We welcome participation from anyone interested in learning more about Patina and contributing to its development.

Unsafe Code

[![methods_unsafe_code]][_methods_unsafe_code]

Background

There have been various instances of advocacy for building system level software in Rust.

This repository contains a Rust UEFI firmware implementation called Patina. We plan to enable an incremental migration of today's firmware components largely written in C to Rust starting with the core. The primary objective for this effort is to improve the security and stability of system firmware by leveraging the memory safety offered by Rust while retaining similar boot performance.

Patina is not a simple port of C UEFI code to Rust.

Patina is a pure‑Rust UEFI firmware implementation that removes legacy complexity and introduces a modern architecture, while preserving compatibility with current PI Specifications and enabling a clear path toward writing more firmware components in pure Rust over time.

Simply writing individual C UEFI drivers in Rust is not equivalent to Patina.

To better understand the types of memory safety problems that Patina helps mitigate, see Memory Safety Strategy.

Otherwise, read the docs to learn about concepts like Patina DXE Core Requirements and the Patina Component Model to better understand how Patina is structured and how to integrate it into a platform.

Docs

• Getting Started: Patina's official getting started guide, containing information regarding the project itself, integrating the Patina DXE Core into a platform, developing a Patina component for your platform, and developing Patina itself.
• Patina DXE Core API docs Patina DXE Core API documentation. Includes information for creating a Patina DXE Core EFI binary with platform customizations such as additional Patina components.
• Patina SDK API docs Patina SDK API documentation that describes how to write a Patina component.

Important Notes

Content in the main branch of the patina repository is expected to be functionally stable with the following exception:

• Patina has optional pieces of functionality called "Patina components". While components are expected to adhere to the same standards of readiness as the rest of the repository, when evaluating a new component, consumers should verify that the component does not have special disclaimers or limitations noted in its documentation.

Also, be aware that Patina has other branches that may host work that is not yet ready for the main branch. To learn more about these branches and the overall Patina release process, read the Patina Release Process RFC.

Platform testing and integration feedback is very welcome.

AI Policy

Patina does not accept contributions directly from AI tools (e.g. GitHub Copilot) and has an AI Policy defined in CONTRIBUTING.md that must be followed for any contributions that are AI-assisted.

Performing a Release

Below is the information required to perform a release that publishes to crates.io:

1. Review the current draft release on the github repo: Releases
2. If something is incorrect, update it in the draft release
3. If you need to manually change the version, make sure you update the associated git tag value in the draft release
4. Run the Create Crate Version Update PR workflow to generate a pull request that updates the repository crate version to the current release draft version.
5. Review, approve, and merge the pull request. Should others request additional pull requests be merged before the release is finalized, simply complete their pull requests first. Any changes to the release draft and pull request created in step 2 will be automatically updated.
6. Upon completion of the pull request created in step 2, the Publish Release workflow will automatically publish the github release and all crates in the repository to crates.io.

First-Time Tool Setup Instructions

1. Follow the steps outlined by Getting Started - Rust Programming Language (rust-lang.org) to install, update (if needed), and test cargo/rust.

2. The [toolchain] section of the rust-toolchain.toml file contains the tools necessary to compile and can be installed through rustup.

shell rustup toolchain install

1. The [tools] section of the rust-toolchain.toml file contains tools to support commands such as cargo make coverage and must be installed manually. A local build does not need them all, but at a minimum, cargo-make and cargo-llvm-cov should be installed.

shell cargo install cargo-make cargo install cargo-llvm-cov

1. Another optional tool that has proven useful for speeding up the build process is 'cargo-binstall', located on GitHub. See the readme.md file in that repository for installation and usage instructions.

Build

All of the Patina crates can be compiled in one of 3 supported targets; aarch64, x64, or native.

cargo make build-aarch64
   - or -
cargo make build-x64
   - or -
cargo make build

By default, the make compiles a developer build, but development or release can be indicated by using the "-p" flag

cargo make -p development build-aarch64
   - or -
cargo make -p release build-aarch64

Test

• Run all unit tests in the workspace:

cargo make test

• Run tests in an individual package:

cargo make test -p patina

Build on-platform tests in the workspace:

cargo make patina-test

• Build on-platform tests in an individual package:

cargo make patina-test -p patina

Rust Version Updates

Patina has a defined process that must be followed when updating the Rust or toolchain version used in the project. This sets clear expectations for developers and consumers. The update process can be found in the Rust Version Update Process page in the mdbook. If you are updating the toolchain version, you must follow that process.

Coverage

The coverage command will generate test coverage data for all crates in the project. To target a single crate, the name can be added to the command line.

cargo make coverage
   - or -
cargo make coverage dxe_core

Benchmarks

Various crates have benchmarks setup that can be executed using the cargo make bench command. Any arguments provided will be passed along to the bench command:

cargo make bench -p patina
cargo make bench -p patina --bench bench_component
cargo make bench -p patina --bench bench_component -- with_component

Benchmarks utilize the criterion benchmarking library, so if new benchmarks are to be added, they should follow that documentation. Benchmarks can be added to any crate to test performance by following the same layout as existing benchmarks, and adding the benchmark to the appropriate crate's Cargo.toml file.

High-Level Patina Roadmap

Patina's upcoming work falls into three main categories:

1. Stabilization - Bug fixes, performance improvements, and feature completion for existing functionality. This work is focused on ensuring that everything in Patina's main branch is stable and ready for production use. This is the primary focus for the next several months.
2. Expansion - Expansion of Patina's capabilities and this falls into two sub-categories:
3. Component Growth - Adding new components to Patina to replace equivalent C-based UEFI components. As new components are made available, it is expected that platforms adopting Patina will incrementally remove their C-based UEFI components as the equivalent Rust-based functionality is now available in their Patina build.
4. MM Core Support - Similar to the DXE Core support in Patina today, adding a Patina Standalone MM Core such that the Management Mode (MM) core environment is written in Rust and a larger portion of MM drivers can be ported to Patina MM components.
5. Ecosystem Integration - This is broken down into two sub-categories:
   1. Firmware Ecosystem - Patina adopters working together to ensure Patina works in their platforms and use cases. This includes things like platform bring-up, integration with existing firmware components, and validation against various hardware configurations.
   2. Rust Ecosystem - Engaging with the broader Rust community to ensure Patina aligns with Rust's best practices and leverages the latest Rust features. This includes things like contributing to Rust libraries, participating in Rust forums, and collaborating with other Rust projects.

Status

1. Stabilization - In Progress
2. Expansion
   1. Component Growth - In Progress
   2. MM Core Support - Planned
3. Ecosystem Integration
   1. Firmware Ecosystem - In Progress
   2. Rust Ecosystem - In Progress

Patina welcomes and encourages community contributions to help accelerate progress in these focus areas. We also value your ideas and feedback on additional priorities that matter to the community.

Contributing

• Review Rust Documentation in the /docs directory.
• Run unit tests and ensure all pass.