uefi: mem: misc improvements

Author: phip1611

uefi/src/mem/memory_map/api.rs

@@ -31,7 +31,8 @@ pub trait MemoryMap: Debug + Index<usize, Output = MemoryDescriptor> {
     #[must_use]
     fn meta(&self) -> MemoryMapMeta;
 
-    /// Returns the associated [`MemoryMapKey`].
+    /// Returns the associated [`MemoryMapKey`]. Note that this isn't
+    /// necessarily the key of the latest valid UEFI memory map.
     #[must_use]
     fn key(&self) -> MemoryMapKey;
 
@@ -64,9 +65,11 @@ pub trait MemoryMap: Debug + Index<usize, Output = MemoryDescriptor> {
     }
 
     /// Returns a reference to the underlying memory.
+    #[must_use]
     fn buffer(&self) -> &[u8];
 
     /// Returns an Iterator of type [`MemoryMapIter`].
+    #[must_use]
     fn entries(&self) -> MemoryMapIter<'_>;
 }
 

uefi/src/mem/memory_map/iter.rs

@@ -1,7 +1,10 @@
 use super::*;
 
-/// An iterator of [`MemoryDescriptor`]. The underlying memory map is always
-/// associated with a unique [`MemoryMapKey`].
+/// An iterator for [`MemoryMap`].
+///
+/// The underlying memory might contain an invalid/malformed memory map
+/// which can't be checked during construction of this type. The iterator
+/// might yield unexpected results.  
 #[derive(Debug, Clone)]
 pub struct MemoryMapIter<'a> {
     pub(crate) memory_map: &'a dyn MemoryMap,

uefi/src/mem/memory_map/mod.rs

@@ -16,8 +16,7 @@
 //!
 //! If you have a chunk of memory and want to parse it as UEFI memory map, which
 //! might be the case if a bootloader such as GRUB or Limine passes its boot
-//! information, you can use  [`MemoryMapRef`] or [`MemoryMapRefMut`].
-//! TODO add constructors.
+//! information, you can use [`MemoryMapRef`] or [`MemoryMapRefMut`].
 //!
 //! # All relevant exports:
 //!
@@ -50,12 +49,13 @@ impl Align for MemoryDescriptor {
     }
 }
 
-/// A unique identifier of a memory map.
+/// A unique identifier of a UEFI memory map, used to tell the firmware that one  
+/// has the latest valid memory map when exiting boot services.
 ///
-/// If the memory map changes, this value is no longer valid.
-#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+/// If the memory map changes, due to any allocation or deallocation, this value
+/// is no longer valid, and exiting boot services will fail.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 #[repr(C)]
-// TODO add some convenience?!
 pub struct MemoryMapKey(pub(crate) usize);
 
 /// A structure containing the meta attributes associated with a call to