uefi: mem: add public constructors for MemoryMapRef and MemoryMapRefMut

There is no public constructor for MemoryMapOwned, as the construction of it is
quite complicated and therefore hidden behind BootServices::memory_map() respectively
SystemTable::exit_boot_services.

The real-world use case for the public constructors for the other types is when
parsing the UEFI memory map from kernels after a bootloader, such as GRUB or Limine,
passed the UEFI memory map via the corresponding boot information.

This also streamlines the documentation.

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 doesn't
+    /// necessarily is the key of the latest valid UEFI memory map.
     #[must_use]
     fn key(&self) -> MemoryMapKey;
 
@@ -67,6 +68,13 @@ pub trait MemoryMap: Debug + Index<usize, Output = MemoryDescriptor> {
     fn buffer(&self) -> &[u8];
 
     /// Returns an Iterator of type [`MemoryMapIter`].
+    ///
+    /// # Safety
+    ///
+    /// 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.
+    #[must_use]
     fn entries(&self) -> MemoryMapIter<'_>;
 }
 

uefi/src/mem/memory_map/impl_.rs

@@ -3,20 +3,62 @@
 
 use super::*;
 use crate::table::system_table_boot;
+use core::fmt::{Debug, Display, Formatter};
 use core::ops::{Index, IndexMut};
 use core::ptr::NonNull;
 use core::{mem, ptr};
 use uefi_raw::PhysicalAddress;
 
+/// Errors that may happen when  constructing a [`MemoryMapRef`] or
+/// [`MemoryMapRefMut`].
+#[derive(Copy, Clone, Debug)]
+pub enum MemoryMapError {
+    /// The buffer is not 8-byte aligned.
+    Misaligned,
+    /// The memory map size is either null or otherwise invalid.
+    InvalidSize,
+}
+
+impl Display for MemoryMapError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        Debug::fmt(self, f)
+    }
+}
+
+#[cfg(feature = "unstable")]
+impl core::error::Error for MemoryMapError {}
+
 /// Implementation of [`MemoryMap`] for the given buffer.
 #[derive(Debug)]
-#[allow(dead_code)] // TODO: github.com/rust-osdev/uefi-rs/issues/1247
 pub struct MemoryMapRef<'a> {
     buf: &'a [u8],
     meta: MemoryMapMeta,
     len: usize,
 }
 
+impl<'a> MemoryMapRef<'a> {
+    /// Constructs a new [`MemoryMapRef`].
+    ///
+    /// # Safety
+    ///
+    /// The underlying memory might contain an invalid/malformed memory map
+    /// which can't be checked during construction of this type. The entry
+    /// iterator might yield unexpected results.
+    pub fn new(buffer: &'a [u8], meta: MemoryMapMeta) -> Result<Self, MemoryMapError> {
+        if buffer.as_ptr().align_offset(8) != 0 {
+            return Err(MemoryMapError::Misaligned);
+        }
+        if buffer.is_empty() || buffer.len() < meta.map_size {
+            return Err(MemoryMapError::InvalidSize);
+        }
+        Ok(Self {
+            buf: buffer,
+            meta,
+            len: meta.entry_count(),
+        })
+    }
+}
+
 impl<'a> MemoryMap for MemoryMapRef<'a> {
     fn meta(&self) -> MemoryMapMeta {
         self.meta
@@ -58,6 +100,29 @@ pub struct MemoryMapRefMut<'a> {
     len: usize,
 }
 
+impl<'a> MemoryMapRefMut<'a> {
+    /// Constructs a new [`MemoryMapRefMut`].
+    ///
+    /// # Safety
+    ///
+    /// The underlying memory might contain an invalid/malformed memory map
+    /// which can't be checked during construction of this type. The entry
+    /// iterator might yield unexpected results.
+    pub fn new(buffer: &'a mut [u8], meta: MemoryMapMeta) -> Result<Self, MemoryMapError> {
+        if buffer.as_ptr().align_offset(8) != 0 {
+            return Err(MemoryMapError::Misaligned);
+        }
+        if buffer.is_empty() || buffer.len() < meta.map_size {
+            return Err(MemoryMapError::InvalidSize);
+        }
+        Ok(Self {
+            buf: buffer,
+            meta,
+            len: meta.entry_count(),
+        })
+    }
+}
+
 impl<'a> MemoryMap for MemoryMapRefMut<'a> {
     fn meta(&self) -> MemoryMapMeta {
         self.meta

uefi/src/mem/memory_map/iter.rs

@@ -1,7 +1,12 @@
 use super::*;
 
-/// An iterator of [`MemoryDescriptor`]. The underlying memory map is always
-/// associated with a unique [`MemoryMapKey`].
+/// An iterator for [`MemoryMap`].
+///
+/// # Safety
+///
+/// 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

@@ -50,12 +50,13 @@ impl Align for MemoryDescriptor {
     }
 }
 
-/// A unique identifier of a memory map.
+/// A unique identifier of a memory map, necessary to tell proof UEFI that one
+/// has the latest valid UEFI 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.
+#[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