Skip to content

Commit a0c4b71

Browse files
committed
uefi/doc: improve documentation of exit_boot_services
TL;DR: Document why exit_boot_services needs to do more than just call the UEFI function. Exiting UEFI boot services requires a non-trivial sequence of steps, including safe retrieval and finalization of the memory map. To clarify why our exit_boot_services function is more than a thin wrapper, the documentation has been updated accordingly. This complexity is also reflected in the Linux source code [0]. In fact, the sequence of steps uefi-rs uses is inspired by the Linux source code. [0] https://github.com/torvalds/linux/blob/e544a0743/drivers/firmware/efi/libstub/efi-stub-helper.c#L375
1 parent a0a76eb commit a0c4b71

File tree

1 file changed

+11
-6
lines changed

1 file changed

+11
-6
lines changed

uefi/src/boot.rs

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1258,17 +1258,22 @@ unsafe fn get_memory_map_and_exit_boot_services(buf: &mut [u8]) -> Result<Memory
12581258
.to_result_with_val(|| memory_map)
12591259
}
12601260

1261-
/// Exit UEFI boot services.
1261+
/// Convenient wrapper to exit UEFI boot services along with corresponding
1262+
/// essential steps to get the memory map.
1263+
///
1264+
/// This wrapper ensures a safe and spec-compliant transition from UEFI boot
1265+
/// services phase to the runtime services phase by retrieving the system
1266+
/// memory map and invoking `ExitBootServices()` with the correct memory map
1267+
/// key, retrying if necessary.
12621268
///
12631269
/// After this function completes, UEFI hands over control of the hardware
12641270
/// to the executing OS loader, which implies that the UEFI boot services
12651271
/// are shut down and cannot be used anymore. Only UEFI configuration tables
1266-
/// and run-time services can be used.
1272+
/// and runtime services can be used.
12671273
///
1268-
/// The memory map at the time of exiting boot services returned. The map is
1269-
/// backed by a pool allocation of the given `memory_type`. Since the boot
1270-
/// services function to free that memory is no longer available after calling
1271-
/// `exit_boot_services`, the allocation will not be freed on drop.
1274+
/// Since the boot services function to free memory is no longer available after
1275+
/// this function returns, the allocation will not be freed on drop. It will
1276+
/// however be reflected by the memory map itself (self-contained).
12721277
///
12731278
/// Note that once the boot services are exited, associated loggers and
12741279
/// allocators can't use the boot services anymore. For the corresponding

0 commit comments

Comments
 (0)