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

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.

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))
 }