Skip to content

Commit d176d93

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of rust-lang#99760 - dvdhrm:rw/uefiplat, r=ehuss
doc/rustc: describe the uefi target platforms Add a `platform-support` entry to the rustc-docs for the different `*-unknown-uefi` targets. This describes in detail how this platform works, a few basic examples, and how to compile for the platform. Red Hat is sponsoring my work on this platform, so I am putting myself down as target maintainer. Co-maintainers are more than welcome to join me in the effort. Communication is going on off-list to coordinate the different efforts. Note that the ultimate goal is to move the UEFI targets to Tier-2 so bootloaders can be more easily supported in commercial products. This documentation is the first step towards that goal, but should be a viable documentation even for the current Tier-3 status of the targets. I also want to point out that there is an ongoing GSoC-effort to port the rust standard library to UEFI (by Ayush Singh). While this work is not necessarily required to get to Tier-2, we definitely should coordinate the efforts and update the documentation as soon as any such ports are merged. Note that the targets are already used by multiple commercial and non commercial production systems, including, but not limited to: * Tianocore-EDK2 (Official UEFI SDK by Intel) comes with rust support in its staging repository (not part of any release, yet). (https://github.com/tianocore/edk2-staging/tree) * Intel's research program "Project Mu" uses the rust UEFI targets to show possible future replacements for Tianocore-EDK2. * The Rust OS "Redox" uses the UEFI targets for its bootloader. (https://www.redox-os.org/) * The hugely popular in-depth documentation of OS development in Rust by Philipp Oppermann uses the UEFI targets. (https://os.phil-opp.com/)
2 parents 48316df + e849f9b commit d176d93

File tree

2 files changed

+255
-0
lines changed

2 files changed

+255
-0
lines changed

‎src/doc/rustc/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
- [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
2929
- [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
3030
- [*-unknown-openbsd](platform-support/openbsd.md)
31+
- [\*-unknown-uefi](platform-support/unknown-uefi.md)
3132
- [wasm64-unknown-unknown](platform-support/wasm64-unknown-unknown.md)
3233
- [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
3334
- [Targets](targets/index.md)

‎src/doc/rustc/src/platform-support/unknown-uefi.md

+254
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# `*-unknown-uefi`
2+
3+
**Tier: 3**
4+
5+
Unified Extensible Firmware Interface (UEFI) targets for application, driver,
6+
and core UEFI binaries.
7+
8+
Available targets:
9+
10+
- `aarch64-unknown-uefi`
11+
- `i686-unknown-uefi`
12+
- `x86_64-unknown-uefi`
13+
14+
## Target maintainers
15+
16+
- David Rheinsberg ([@dvdhrm](https://github.com/dvdhrm))
17+
- Nicholas Bishop ([@nicholasbishop](https://github.com/nicholasbishop))
18+
19+
## Requirements
20+
21+
All UEFI targets can be used as `no-std` environments via cross-compilation.
22+
Support for `std` is missing, but actively worked on. `alloc` is supported if
23+
an allocator is provided by the user. No host tools are supported.
24+
25+
The UEFI environment resembles the environment for Microsoft Windows, with some
26+
minor differences. Therefore, cross-compiling for UEFI works with the same
27+
tools as cross-compiling for Windows. The target binaries are PE32+ encoded,
28+
the calling convention is different for each architecture, but matches what
29+
Windows uses (if the architecture is supported by Windows). The special
30+
`efiapi` Rust calling-convention chooses the right ABI for the target platform
31+
(`extern "C"` is incorrect on Intel targets at least). The specification has an
32+
elaborate section on the different supported calling-conventions, if more
33+
details are desired.
34+
35+
MMX, SSE, and other FP-units are disabled by default, to allow for compilation
36+
of core UEFI code that runs before they are set up. This can be overridden for
37+
individual compilations via rustc command-line flags. Not all firmwares
38+
correctly configure those units, though, so careful inspection is required.
39+
40+
As native to PE32+, binaries are position-dependent, but can be relocated at
41+
runtime if their desired location is unavailable. The code must be statically
42+
linked. Dynamic linking is not supported. Code is shared via UEFI interfaces,
43+
rather than dynamic linking. Additionally, UEFI forbids running code on
44+
anything but the boot CPU/thread, nor is interrupt-usage allowed (apart from
45+
the timer interrupt). Device drivers are required to use polling methods.
46+
47+
UEFI uses a single address-space to run all code in. Multiple applications can
48+
be loaded simultaneously and are dispatched via cooperative multitasking on a
49+
single stack.
50+
51+
By default, the UEFI targets use the `link`-flavor of the LLVM linker `lld` to
52+
link binaries into the final PE32+ file suffixed with `*.efi`. The PE subsystem
53+
is set to `EFI_APPLICATION`, but can be modified by passing `/subsystem:<...>`
54+
to the linker. Similarly, the entry-point is to to `efi_main` but can be
55+
changed via `/entry:<...>`. The panic-strategy is set to `abort`,
56+
57+
The UEFI specification is available online for free:
58+
[UEFI Specification Directory](https://uefi.org/specifications)
59+
60+
## Building rust for UEFI targets
61+
62+
Rust can be built for the UEFI targets by enabling them in the `rustc` build
63+
configuration. Note that you can only build the standard libraries. The
64+
compiler and host tools currently cannot be compiled for UEFI targets. A sample
65+
configuration would be:
66+
67+
```toml
68+
[build]
69+
build-stage = 1
70+
target = ["x86_64-unknown-uefi"]
71+
```
72+
73+
## Building Rust programs
74+
75+
Rust does not yet ship pre-compiled artifacts for this target. To compile for
76+
this target, you will either need to build Rust with the target enabled (see
77+
"Building rust for UEFI targets" above), or build your own copy of `core` by
78+
using `build-std`, `cargo-buildx`, or similar.
79+
80+
A native build with the unstable `build-std`-feature can be achieved via:
81+
82+
```sh
83+
cargo +nightly build \
84+
-Zbuild-std=core,compiler_builtins \
85+
-Zbuild-std-features=compiler-builtins-mem \
86+
--target x86_64-unknown-uefi
87+
```
88+
89+
Alternatively, you can install `cargo-xbuild` via
90+
`cargo install --force cargo-xbuild` and build for the UEFI targets via:
91+
92+
```sh
93+
cargo \
94+
+nightly \
95+
xbuild \
96+
--target x86_64-unknown-uefi
97+
```
98+
99+
## Testing
100+
101+
UEFI applications can be copied into the ESP on any UEFI system and executed
102+
via the firmware boot menu. The qemu suite allows emulating UEFI systems and
103+
executing UEFI applications as well. See its documentation for details.
104+
105+
The [uefi-run](https://github.com/Richard-W/uefi-run) rust tool is a simple
106+
wrapper around `qemu` that can spawn UEFI applications in qemu. You can install
107+
it via `cargo install uefi-run` and execute qemu applications as
108+
`uefi-run ./application.efi`.
109+
110+
## Cross-compilation toolchains and C code
111+
112+
There are 3 common ways to compile native C code for UEFI targets:
113+
114+
- Use the official SDK by Intel:
115+
[Tianocore/EDK2](https://github.com/tianocore/edk2). This supports a
116+
multitude of platforms, comes with the full specification transposed into C,
117+
lots of examples and build-system integrations. This is also the only
118+
officially supported platform by Intel, and is used by many major firmware
119+
implementations. Any code compiled via the SDK is compatible to rust binaries
120+
compiled for the UEFI targets. You can link them directly into your rust
121+
binaries, or call into each other via UEFI protocols.
122+
- Use the **GNU-EFI** suite. This approach is used by many UEFI applications
123+
in the Linux/OSS ecosystem. The GCC compiler is used to compile ELF binaries,
124+
and linked with a pre-loader that converts the ELF binary to PE32+
125+
**at runtime**. You can combine such binaries with the rust UEFI targets only
126+
via UEFI protocols. Linking both into the same executable will fail, since
127+
one is an ELF executable, and one a PE32+. If linking to **GNU-EFI**
128+
executables is desired, you must compile your rust code natively for the same
129+
GNU target as **GNU-EFI** and use their pre-loader. This requires careful
130+
consideration about which calling-convention to use when calling into native
131+
UEFI protocols, or calling into linked **GNU-EFI** code (similar to how these
132+
differences need to be accounted for when writing **GNU-EFI** C code).
133+
- Use native Windows targets. This means compiling your C code for the Windows
134+
platform as if it was the UEFI platform. This works for static libraries, but
135+
needs adjustments when linking into an UEFI executable. You can, however,
136+
link such static libraries seemlessly into rust code compiled for UEFI
137+
targets. Be wary of any includes that are not specifically suitable for UEFI
138+
targets (especially the C standard library includes are not always
139+
compatible). Freestanding compilations are recommended to avoid
140+
incompatibilites.
141+
142+
## Ecosystem
143+
144+
The rust language has a long history of supporting UEFI targets. Many crates
145+
have been developed to provide access to UEFI protocols and make UEFI
146+
programming more ergonomic in rust. The following list is a short overview (in
147+
alphabetical ordering):
148+
149+
- **efi**: *Ergonomic Rust bindings for writing UEFI applications*. Provides
150+
_rustified_ access to UEFI protocols, implements allocators and a safe
151+
environment to write UEFI applications.
152+
- **r-efi**: *UEFI Reference Specification Protocol Constants and Definitions*.
153+
A pure transpose of the UEFI specification into rust. This provides the raw
154+
definitions from the specification, without any extended helpers or
155+
_rustification_. It serves as baseline to implement any more elaborate rust
156+
UEFI layers.
157+
- **uefi-rs**: *Safe and easy-to-use wrapper for building UEFI apps*. An
158+
elaborate library providing safe abstractions for UEFI protocols and
159+
features. It implements allocators and provides an execution environment to
160+
UEFI applications written in rust.
161+
- **uefi-run**: *Run UEFI applications*. A small wrapper around _qemu_ to spawn
162+
UEFI applications in an emulated `x86_64` machine.
163+
164+
## Example: Freestanding
165+
166+
The following code is a valid UEFI application returning immediately upon
167+
execution with an exit code of 0. A panic handler is provided. This is executed
168+
by rust on panic. For simplicity, we simply end up in an infinite loop.
169+
170+
Note that as of rust-1.31.0, all features used here are stabilized. No unstable
171+
features are required, nor do we rely on nightly compilers. However, if you do
172+
not compile rustc for the UEFI targets, you need a nightly compiler to support
173+
the `-Z build-std` flag.
174+
175+
This example can be compiled as binary crate via `cargo`:
176+
177+
```sh
178+
cargo +nightly build \
179+
-Zbuild-std=core,compiler_builtins \
180+
-Zbuild-std-features=compiler-builtins-mem \
181+
--target x86_64-unknown-uefi
182+
```
183+
184+
```rust,ignore (platform-specific,eh-personality-is-unstable)
185+
#![no_main]
186+
#![no_std]
187+
188+
#[panic_handler]
189+
fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
190+
loop {}
191+
}
192+
193+
#[export_name = "efi_main"]
194+
pub extern "C" fn main(_h: *mut core::ffi::c_void, _st: *mut core::ffi::c_void) -> usize {
195+
0
196+
}
197+
```
198+
199+
## Example: Hello World
200+
201+
This is an example UEFI application that prints "Hello World!", then waits for
202+
key input before it exits. It serves as base example how to write UEFI
203+
applications without any helper modules other than the standalone UEFI protocol
204+
definitions provided by the `r-efi` crate.
205+
206+
This extends the "Freestanding" example and builds upon its setup. See there
207+
for instruction how to compile this as binary crate.
208+
209+
Note that UEFI uses UTF-16 strings. Since rust literals are UTF-8, we have to
210+
use an open-coded, zero-terminated, UTF-16 array as argument to
211+
`output_string()`. Similarly to the panic handler, real applications should
212+
rather use UTF-16 modules.
213+
214+
```rust,ignore (platform-specific,eh-personality-is-unstable)
215+
#![no_main]
216+
#![no_std]
217+
218+
use r_efi::efi;
219+
220+
#[panic_handler]
221+
fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
222+
loop {}
223+
}
224+
225+
#[export_name = "efi_main"]
226+
pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status {
227+
let s = [
228+
0x0048u16, 0x0065u16, 0x006cu16, 0x006cu16, 0x006fu16, // "Hello"
229+
0x0020u16, // " "
230+
0x0057u16, 0x006fu16, 0x0072u16, 0x006cu16, 0x0064u16, // "World"
231+
0x0021u16, // "!"
232+
0x000au16, // "\n"
233+
0x0000u16, // NUL
234+
];
235+
236+
// Print "Hello World!".
237+
let r =
238+
unsafe { ((*(*st).con_out).output_string)((*st).con_out, s.as_ptr() as *mut efi::Char16) };
239+
if r.is_error() {
240+
return r;
241+
}
242+
243+
// Wait for key input, by waiting on the `wait_for_key` event hook.
244+
let r = unsafe {
245+
let mut x: usize = 0;
246+
((*(*st).boot_services).wait_for_event)(1, &mut (*(*st).con_in).wait_for_key, &mut x)
247+
};
248+
if r.is_error() {
249+
return r;
250+
}
251+
252+
efi::Status::SUCCESS
253+
}
254+
```

0 commit comments

Comments
 (0)