uefi: Make exit_boot_services unsafe

This method was already unsafe in practice, since it's very hard to statically
ensure that no references to boot-services data exist. Change the signature to
acknowledge that reality, and update the docstring with details.

Author: nicholasbishop

uefi-test-runner/src/main.rs

@@ -199,7 +199,7 @@ fn shutdown(mut st: SystemTable<Boot>) -> ! {
     info!("Testing complete, exiting boot services...");
 
     // Exit boot services as a proof that it works :)
-    let (st, mmap) = st.exit_boot_services(MemoryType::LOADER_DATA);
+    let (st, mmap) = unsafe { st.exit_boot_services(MemoryType::LOADER_DATA) };
 
     info!("Memory Map:");
     for desc in mmap.entries() {

uefi/CHANGELOG.md

@@ -12,6 +12,10 @@
   This provides an initial API for global tables that do not require passing
   around a reference.
 
+## Changed
+- `SystemTable::exit_boot_services` is now `unsafe`. See that method's
+  documentation for details of obligations for callers.
+
 ## Removed
 - Removed the `panic-on-logger-errors` feature of the `uefi` crate. Logger
   errors are now silently ignored.

uefi/src/table/system.rs

@@ -208,8 +208,27 @@ impl SystemTable<Boot> {
     ///
     /// Note that once the boot services are exited, associated loggers and
     /// allocators can't use the boot services anymore. For the corresponding
-    /// abstractions provided by this crate, invoking this function will
-    /// automatically disable them.
+    /// abstractions provided by this crate (see the [`helpers`] module),
+    /// invoking this function will automatically disable them. If the
+    /// `global_allocator` feature is enabled, attempting to use the allocator
+    /// after exiting boot services will panic.
+    ///
+    /// # Safety
+    ///
+    /// The caller is responsible for ensuring that no references to
+    /// boot-services data remain. A non-exhaustive list of resources to check:
+    ///
+    /// * All protocols will be invalid after exiting boot services. This
+    ///   includes the [`Output`] protocols attached to stdout/stderr. The
+    ///   caller must ensure that no protocol references remain.
+    /// * The pool allocator is not usable after exiting boot services. Types
+    ///   such as [`PoolString`] which call [`BootServices::free_pool`] on drop
+    ///   must be cleaned up before calling `exit_boot_services`, or leaked to
+    ///   avoid drop ever being called.
+    /// * All data in the memory map marked as
+    ///   [`MemoryType::BOOT_SERVICES_CODE`] and
+    ///   [`MemoryType::BOOT_SERVICES_DATA`] will become free memory, the caller
+    ///   must ensure that no references to such memory exist.
     ///
     /// # Errors
     ///
@@ -220,8 +239,12 @@ impl SystemTable<Boot> {
     /// All errors are treated as unrecoverable because the system is
     /// now in an undefined state. Rather than returning control to the
     /// caller, the system will be reset.
+    ///
+    /// [`helpers`]: crate::helpers
+    /// [`Output`]: crate::proto::console::text::Output
+    /// [`PoolString`]: crate::proto::device_path::text::PoolString
     #[must_use]
-    pub fn exit_boot_services(
+    pub unsafe fn exit_boot_services(
         self,
         memory_type: MemoryType,
     ) -> (SystemTable<Runtime>, MemoryMap<'static>) {