doc: internally handle BUFFER_TOO_SMALL in uefi::boot::memory_map()

Author: phip1611

uefi/CHANGELOG.md

@@ -4,6 +4,10 @@
 - **Breaking:** Removed `BootPolicyError` as `BootPolicy` construction is no
   longer fallible. `BootPolicy` now tightly integrates the new `Boolean` type
   of `uefi-raw`.
+- `boot::memory_map()` will never return `Status::BUFFER_TOO_SMALL` from now on,
+  as this is considered a hard internal error where users can't do anything
+  about it anyway. It will panic instead.
+
 
 # uefi - 0.34.1 (2025-02-07)
 

uefi/src/boot.rs

@@ -249,9 +249,7 @@ pub(crate) fn memory_map_size() -> MemoryMapMeta {
 /// 
 /// The implementation tries to mitigate some UEFI pitfalls, such as getting
 /// the right allocation size for the memory map to prevent
-/// [`Status::BUFFER_TOO_SMALL`]. If [`Status::BUFFER_TOO_SMALL`] is returned, 
-/// further calls are likely to fail as well. If so, the situation may be
-/// considered as unrecoverable error.
+/// [`Status::BUFFER_TOO_SMALL`]. 
 ///
 /// # Parameters
 ///
@@ -261,12 +259,28 @@ pub(crate) fn memory_map_size() -> MemoryMapMeta {
 ///
 /// # Errors
 ///
-/// * [`Status::BUFFER_TOO_SMALL`]
-/// * [`Status::INVALID_PARAMETER`]
+/// * [`Status::INVALID_PARAMETER`]: Invalid [`MemoryType`]
+/// * [`Status::OUT_OF_RESOURCES`]: allocation failed.
+/// 
+/// # Panics
+/// 
+/// Panics if the memory map can't be retrieved.
 pub fn memory_map(mt: MemoryType) -> Result<MemoryMapOwned> {
     let mut buffer = MemoryMapBackingMemory::new(mt)?;
 
-    let meta = get_memory_map(buffer.as_mut_slice())?;
+    let meta = get_memory_map(buffer.as_mut_slice());
+    
+    if let Err(e) = &meta {
+        // We don't want to confuse users and let them think they should handle
+        // this, as they can't do anything about it anyway.
+        //
+        // This path won't be taken in OOM situations, but only if for unknown
+        // reasons, we failed to properly allocate the memory map.
+        if e.status() == Status::BUFFER_TOO_SMALL {
+            panic!("Failed to get a proper allocation for the memory map");
+        }
+    }
+    let meta = meta?;
 
     Ok(MemoryMapOwned::from_initialized_mem(buffer, meta))
 }