| 1 |
//! UEFI Reference Specification Protocol Constants and Definitions |
| 2 |
//! |
| 3 |
//! This project provides protocol constants and definitions as defined in the UEFI Reference |
| 4 |
//! Specification. The aim is to provide all these constants as C-ABI compatible imports to rust. |
| 5 |
//! Safe rust abstractions over the UEFI API are out of scope of this project. That is, the |
| 6 |
//! purpose is really just to extract all the bits and pieces from the specification and provide |
| 7 |
//! them as rust types and constants. |
| 8 |
//! |
| 9 |
//! While we strongly recommend using safe abstractions to interact with UEFI systems, this |
| 10 |
//! project serves both as base to write those abstractions, but also as last resort if you have |
| 11 |
//! to deal with quirks and peculiarities of UEFI systems directly. Therefore, several examples |
| 12 |
//! are included, which show how to interact with UEFI systems from rust. These serve both as |
| 13 |
//! documentation for anyone interested in how the system works, but also as base for anyone |
| 14 |
//! implementing safe abstractions on top. |
| 15 |
//! |
| 16 |
//! # Target Configuration |
| 17 |
//! |
| 18 |
//! Rust code can be compiled natively for UEFI systems. However, you are quite unlikely to have a |
| 19 |
//! rust compiler running in an UEFI environment. Therefore, you will most likely want to cross |
| 20 |
//! compile your rust code for UEFI systems. To do this, you need a target-configuration for UEFI |
| 21 |
//! systems. As of rust-1.61, upstream rust includes the following UEFI targets: |
| 22 |
//! |
| 23 |
//! * `aarch64-unknown-uefi`: A native UEFI target for aarch64 systems (64bit ARM). |
| 24 |
//! * `i686-unknown-uefi`: A native UEFI target for i686 systems (32bit Intel x86). |
| 25 |
//! * `x86_64-unknown-uefi`: A native UEFI target for x86-64 systems (64bit Intel x86). |
| 26 |
//! |
| 27 |
//! If none of these targets match your architecture, you have to create the target specification |
| 28 |
//! yourself. Feel free to contact the `r-efi` project for help. |
| 29 |
//! |
| 30 |
//! # Transpose Guidelines |
| 31 |
//! |
| 32 |
//! The UEFI specification provides C language symbols and definitions of all |
| 33 |
//! its protocols and features. Those are integral parts of the specification |
| 34 |
//! and UEFI programming is often tightly coupled with the C language. For |
| 35 |
//! better compatibility to existing UEFI documentation, all the rust symbols |
| 36 |
//! are transposed from C following strict rules, aiming for close similarity |
| 37 |
//! to specification. This section gives a rationale on some of the less |
| 38 |
//! obvious choices and tries to describe as many of those rules as possible. |
| 39 |
//! |
| 40 |
//! * `no enums`: Rust enums do not allow random discriminant values. However, |
| 41 |
//! many UEFI enumerations use reserved ranges for vendor defined values. |
| 42 |
//! These cannot be represented with rust enums in an efficient manner. |
| 43 |
//! Hence, any enumerations are turned into rust constants with an |
| 44 |
//! accompanying type alias. |
| 45 |
//! |
| 46 |
//! A detailed discussion can be found in: |
| 47 |
//! |
| 48 |
//! ```gitlog |
| 49 |
//! commit 401a91901e860a5c0cd0f92b75dda0a72cf65322 |
| 50 |
//! Author: David Rheinsberg <[email protected]> |
| 51 |
//! Date: Wed Apr 21 12:07:07 2021 +0200 |
| 52 |
//! |
| 53 |
//! r-efi: convert enums to constants |
| 54 |
//! ``` |
| 55 |
//! |
| 56 |
//! * `no incomplete types`: Several structures use incomplete structure types |
| 57 |
//! by using an unbound array as last member. While rust can easily |
| 58 |
//! represent those within its type-system, such structures become DSTs, |
| 59 |
//! hence even raw pointers to them become fat-pointers, and would thus |
| 60 |
//! violate the UEFI ABI. |
| 61 |
//! |
| 62 |
//! Instead, we use const-generics to allow compile-time adjustment of the |
| 63 |
//! variable-sized structures, with a default value of 0. This allows |
| 64 |
//! computing different sizes of the structures without any runtime overhead. |
| 65 |
//! |
| 66 |
//! * `nullable callbacks as Option`: Rust has no raw function pointers, but |
| 67 |
//! just normal Rust function pointers. Those, however, have no valid null |
| 68 |
//! value. The Rust ABI guarantees that `Option<fn ...>` is an C-ABI |
| 69 |
//! compatible replacement for nullable function pointers, with `None` being |
| 70 |
//! mapped to `NULL`. Hence, whenever UEFI APIs require nullable function |
| 71 |
//! pointers, we use `Option<fn ...>`. |
| 72 |
//! |
| 73 |
//! * `prefer *mut over *const`: Whenever we transpose pointers from the |
| 74 |
//! specification into Rust, we prefer `*mut` in almost all cases. `*const` |
| 75 |
//! should only be used if the underlying value is known not to be accessible |
| 76 |
//! via any other mutable pointer type. Since this is rarely the case in |
| 77 |
//! UEFI, we avoid it. |
| 78 |
//! |
| 79 |
//! The reasoning is that Rust allows coercing immutable types into `*const` |
| 80 |
//! pointers, without any explicit casting required. However, immutable Rust |
| 81 |
//! references require that no other mutable reference exists simultaneously. |
| 82 |
//! This is not a guarantee of `const`-pointers in C / UEFI, hence this |
| 83 |
//! coercion is usually ill-advised or even wrong. |
| 84 |
//! |
| 85 |
//! Lastly, note that `*mut` and `*const` and be `as`-casted in both |
| 86 |
//! directions without violating any Rust guarantees. Any UB concerns always |
| 87 |
//! stem from the safety guarantees of the surrounding code, not of the |
| 88 |
//! raw-pointer handling. |
| 89 |
//! |
| 90 |
//! # Specification Details |
| 91 |
//! |
| 92 |
//! This section lists errata of, and general comments on, the UEFI |
| 93 |
//! specification relevant to the development of `r-efi`: |
| 94 |
//! |
| 95 |
//! * The `Unload` function-pointer of the LoadedImageProtocol can be `NULL`, |
| 96 |
//! despite the protocol documentation lacking any mention of this. Other |
| 97 |
//! parts of the specification refer to images lacking an unload function, |
| 98 |
//! but there is no explicit documentation how this manifests in the |
| 99 |
//! protocol structure. EDK2 assumes `NULL` indicates a lack of unload |
| 100 |
//! function, and an errata has been submitted to the UEFI forum. |
| 101 |
//! |
| 102 |
//! * The specification mandates an 8-byte alignment for the `GUID` structure |
| 103 |
//! However, all widespread implementations (including EDK2) use a 4-byte |
| 104 |
//! alignment. An errata has been reported to EDK2 (still pending). |
| 105 |
//! |
| 106 |
//! # Examples |
| 107 |
//! |
| 108 |
//! To write free-standing UEFI applications, you need to disable the entry-point provided by rust |
| 109 |
//! and instead provide your own. Most target-configurations look for a function called `efi_main` |
| 110 |
//! during linking and set it as entry point. If you use the target-configurations provided with |
| 111 |
//! upstream rust, they will pick the function called `efi_main` as entry-point. |
| 112 |
//! |
| 113 |
//! The following example shows a minimal UEFI application, which simply returns success upon |
| 114 |
//! invocation. Note that you must provide your own panic-handler when running without `libstd`. |
| 115 |
//! In our case, we use a trivial implementation that simply loops forever. |
| 116 |
//! |
| 117 |
//! ```ignore |
| 118 |
//! #![no_main] |
| 119 |
//! #![no_std] |
| 120 |
//! |
| 121 |
//! use r_efi::efi; |
| 122 |
//! |
| 123 |
//! #[panic_handler] |
| 124 |
//! fn panic_handler(_info: &core::panic::PanicInfo) -> ! { |
| 125 |
//! loop {} |
| 126 |
//! } |
| 127 |
//! |
| 128 |
//! #[export_name = "efi_main"] |
| 129 |
//! pub extern fn main(_h: efi::Handle, _st: *mut efi::SystemTable) -> efi::Status { |
| 130 |
//! efi::Status::SUCCESS |
| 131 |
//! } |
| 132 |
//! ``` |
| 133 |
|
| 134 |
// Mark this crate as `no_std`. We have no std::* dependencies (and we better don't have them), |
| 135 |
// so no reason to require it. This does not mean that you cannot use std::* with UEFI. You have |
| 136 |
// to port it to UEFI first, though. |
| 137 |
// |
| 138 |
// In case of unit-test compilation, we pull in `std` and drop the `no_std` marker. This allows |
| 139 |
// basic unit-tests on the compilation host. For integration tests, we have separate compilation |
| 140 |
// units, so they will be unaffected by this. |
| 141 |
#![cfg_attr(not(test), no_std)] |
| 142 |
|
| 143 |
// Import the different core modules. We separate them into different modules to make it easier to |
| 144 |
// work on them and describe what each part implements. This is different to the reference |
| 145 |
// implementation, which uses a flat namespace due to its origins in the C language. For |
| 146 |
// compatibility, we provide this flat namespace as well. See the `efi` submodule. |
| 147 |
#[macro_use] |
| 148 |
pub mod base; |
| 149 |
#[macro_use] |
| 150 |
pub mod hii; |
| 151 |
#[macro_use] |
| 152 |
pub mod system; |
| 153 |
|
| 154 |
// Import the protocols. Each protocol is separated into its own module, readily imported by the |
| 155 |
// meta `protocols` module. Note that this puts all symbols into their respective protocol |
| 156 |
// namespace, thus clearly separating them (unlike the UEFI Specification, which more often than |
| 157 |
// not violates its own namespacing). |
| 158 |
pub mod protocols; |
| 159 |
|
| 160 |
// Import vendor protocols. They are just like protocols in `protocols`, but |
| 161 |
// separated for better namespacing. |
| 162 |
pub mod vendor; |
| 163 |
|
| 164 |
/// Flat EFI Namespace |
| 165 |
/// |
| 166 |
/// The EFI namespace re-exports all symbols in a single, flat namespace. This allows mirroring |
| 167 |
/// the entire EFI namespace as given in the specification and makes it easier to refer to them |
| 168 |
/// with the same names as the reference C implementation. |
| 169 |
/// |
| 170 |
/// Note that the individual protocols are put into submodules. The specification does this in |
| 171 |
/// most parts as well (by prefixing all symbols). This is not true in all cases, as the |
| 172 |
/// specification suffers from lack of namespaces in the reference C language. However, we decided |
| 173 |
/// to namespace the remaining bits as well, for better consistency throughout the API. This |
| 174 |
/// should be self-explanatory in nearly all cases. |
| 175 |
pub mod efi { |
| 176 |
pub use crate::base::*; |
| 177 |
pub use crate::system::*; |
| 178 |
|
| 179 |
pub use crate::hii; |
| 180 |
pub use crate::protocols; |
| 181 |
pub use crate::vendor; |
| 182 |
} |