Debian Codegraph @

.cargo/vendor/r-efi/src/lib.rs

raw
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 }