From 074220296d83cc1b6b85b26c45e47a0264a6d111 Mon Sep 17 00:00:00 2001
From: Nicholas Bishop <nbishop@nbishop.net>
Date: Sat, 13 Jan 2024 12:59:00 -0500
Subject: [PATCH 1/2] Add crate links to unknown-uefi.md

---
 .../rustc/src/platform-support/unknown-uefi.md    | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/doc/rustc/src/platform-support/unknown-uefi.md b/src/doc/rustc/src/platform-support/unknown-uefi.md
index 1230ea22bd99b..a0bd2c502bd8b 100644
--- a/src/doc/rustc/src/platform-support/unknown-uefi.md
+++ b/src/doc/rustc/src/platform-support/unknown-uefi.md
@@ -88,7 +88,7 @@ UEFI applications can be copied into the ESP on any UEFI system and executed
 via the firmware boot menu. The qemu suite allows emulating UEFI systems and
 executing UEFI applications as well. See its documentation for details.
 
-The [uefi-run](https://github.com/Richard-W/uefi-run) rust tool is a simple
+The [uefi-run] rust tool is a simple
 wrapper around `qemu` that can spawn UEFI applications in qemu. You can install
 it via `cargo install uefi-run` and execute qemu applications as
 `uefi-run ./application.efi`.
@@ -132,19 +132,19 @@ have been developed to provide access to UEFI protocols and make UEFI
 programming more ergonomic in rust. The following list is a short overview (in
 alphabetical ordering):
 
-- **efi**: *Ergonomic Rust bindings for writing UEFI applications*. Provides
+- **[efi][efi-crate]**: *Ergonomic Rust bindings for writing UEFI applications*. Provides
   _rustified_ access to UEFI protocols, implements allocators and a safe
   environment to write UEFI applications.
-- **r-efi**: *UEFI Reference Specification Protocol Constants and Definitions*.
+- **[r-efi]**: *UEFI Reference Specification Protocol Constants and Definitions*.
   A pure transpose of the UEFI specification into rust. This provides the raw
   definitions from the specification, without any extended helpers or
   _rustification_. It serves as baseline to implement any more elaborate rust
   UEFI layers.
-- **uefi-rs**: *Safe and easy-to-use wrapper for building UEFI apps*. An
+- **[uefi-rs]**: *Safe and easy-to-use wrapper for building UEFI apps*. An
   elaborate library providing safe abstractions for UEFI protocols and
   features. It implements allocators and provides an execution environment to
   UEFI applications written in rust.
-- **uefi-run**: *Run UEFI applications*. A small wrapper around _qemu_ to spawn
+- **[uefi-run]**: *Run UEFI applications*. A small wrapper around _qemu_ to spawn
   UEFI applications in an emulated `x86_64` machine.
 
 ## Example: Freestanding
@@ -311,3 +311,8 @@ pub fn main() {
 The current implementation of std makes `BootServices` unavailable once `ExitBootServices` is called. Refer to [Runtime Drivers](https://edk2-docs.gitbook.io/edk-ii-uefi-driver-writer-s-guide/7_driver_entry_point/711_runtime_drivers) for more information regarding how to handle switching from using physical addresses to using virtual addresses.
 
 Note: It should be noted that it is up to the user to drop all allocated memory before `ExitBootServices` is called.
+
+[efi-crate]: https://github.com/gurry/efi
+[r-efi]: https://github.com/r-efi/r-efi
+[uefi-rs]: https://github.com/rust-osdev/uefi-rs
+[uefi-run]: https://github.com/Richard-W/uefi-run

From 3402f0741ac46d05cb572d27caa0b41e12f5ca1b Mon Sep 17 00:00:00 2001
From: Nicholas Bishop <nbishop@nbishop.net>
Date: Sat, 13 Jan 2024 13:08:17 -0500
Subject: [PATCH 2/2] Add doc and example for building a UEFI driver

---
 .../rustc/src/platform-support/unknown-uefi.md  | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/doc/rustc/src/platform-support/unknown-uefi.md b/src/doc/rustc/src/platform-support/unknown-uefi.md
index a0bd2c502bd8b..8fb155e1ffa00 100644
--- a/src/doc/rustc/src/platform-support/unknown-uefi.md
+++ b/src/doc/rustc/src/platform-support/unknown-uefi.md
@@ -82,6 +82,22 @@ rustup target add x86_64-unknown-uefi
 cargo build --target x86_64-unknown-uefi
 ```
 
+### Building a driver
+
+There are three types of UEFI executables: application, boot service
+driver, and runtime driver. All of Rust's UEFI targets default to
+producing applications. To build a driver instead, pass a
+[`subsystem`][linker-subsystem] linker flag with a value of
+`efi_boot_service_driver` or `efi_runtime_driver`.
+
+Example:
+
+```toml
+# In .cargo/config.toml:
+[build]
+rustflags = ["-C", "link-args=/subsystem:efi_runtime_driver"]
+```
+
 ## Testing
 
 UEFI applications can be copied into the ESP on any UEFI system and executed
@@ -313,6 +329,7 @@ The current implementation of std makes `BootServices` unavailable once `ExitBoo
 Note: It should be noted that it is up to the user to drop all allocated memory before `ExitBootServices` is called.
 
 [efi-crate]: https://github.com/gurry/efi
+[linker-subsystem]: https://learn.microsoft.com/en-us/cpp/build/reference/subsystem
 [r-efi]: https://github.com/r-efi/r-efi
 [uefi-rs]: https://github.com/rust-osdev/uefi-rs
 [uefi-run]: https://github.com/Richard-W/uefi-run