cleanup/follow-up: memory_map

uefi-test-runner/src/boot/memory.rs

@@ -1,7 +1,7 @@
-use uefi::boot;
-use uefi::table::boot::{AllocateType, BootServices, MemoryMap, MemoryMapMut, MemoryType};
-
 use alloc::vec::Vec;
+use uefi::boot;
+use uefi::mem::memory_map::{MemoryMap, MemoryMapMut, MemoryType};
+use uefi::table::boot::{AllocateType, BootServices};
 
 pub fn test(bt: &BootServices) {
     info!("Testing memory functions");

uefi-test-runner/src/boot/misc.rs

@@ -2,10 +2,11 @@ use core::ffi::c_void;
 use core::ptr::{self, NonNull};
 
 use core::mem;
+use uefi::mem::memory_map::MemoryType;
 use uefi::proto::unsafe_protocol;
 use uefi::table::boot::{
-    BootServices, EventType, MemoryType, OpenProtocolAttributes, OpenProtocolParams, SearchType,
-    TimerTrigger, Tpl,
+    BootServices, EventType, OpenProtocolAttributes, OpenProtocolParams, SearchType, TimerTrigger,
+    Tpl,
 };
 use uefi::table::{Boot, SystemTable};
 use uefi::{guid, Event, Guid, Identify};

uefi-test-runner/src/main.rs

@@ -8,11 +8,11 @@ extern crate alloc;
 
 use alloc::string::ToString;
 use alloc::vec::Vec;
+use uefi::mem::memory_map::{MemoryMap, MemoryType};
 use uefi::prelude::*;
 use uefi::proto::console::serial::Serial;
 use uefi::proto::device_path::build::{self, DevicePathBuilder};
 use uefi::proto::device_path::messaging::Vendor;
-use uefi::table::boot::{MemoryMap, MemoryType};
 use uefi::{print, println, system, Result};
 
 mod boot;

uefi/CHANGELOG.md

@@ -24,7 +24,16 @@
 - **Breaking:** `PcrEvent::new_in_buffer` and `PcrEventInputs::new_in_buffer`
   now take an initialized buffer (`[u8`] instead of `[MaybeUninit<u8>]`), and if
   the buffer is too small the required size is returned in the error data.
-
+- **Breaking** Exports of Memory Map-related types from `uefi::table::boot` are
+  now removed. Use `uefi::mem::memory_map` instead. The patch you have to apply
+  to the `use` statements of your code might look as follows:
+  ```diff
+  1c1,2
+  < use uefi::table::boot::{BootServices, MemoryMap, MemoryMapMut, MemoryType};
+  ---
+  > use uefi::mem::memory_map::{MemoryMap, MemoryMapMut, MemoryType};
+  > use uefi::table::boot::BootServices;
+  ```
 
 # uefi - 0.29.0 (2024-07-02)
 

uefi/src/allocator.rs

@@ -16,8 +16,9 @@ use core::ffi::c_void;
 use core::ptr;
 use core::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
 
+use crate::mem::memory_map::MemoryType;
 use crate::proto::loaded_image::LoadedImage;
-use crate::table::boot::{BootServices, MemoryType};
+use crate::table::boot::BootServices;
 use crate::table::{Boot, SystemTable};
 
 /// Reference to the system table, used to call the boot services pool memory

uefi/src/mem/memory_map/api.rs

@@ -0,0 +1,104 @@
+//! Module for the traits [`MemoryMap`] and [`MemoryMapMut`].
+
+use super::*;
+use core::fmt::Debug;
+use core::ops::{Index, IndexMut};
+
+/// An accessory to the UEFI memory map and associated metadata that can be
+/// either iterated or indexed like an array.
+///
+/// A [`MemoryMap`] is always associated with the unique [`MemoryMapKey`]
+/// bundled with the map.
+///
+/// To iterate over the entries, call [`MemoryMap::entries`].
+///
+/// ## UEFI pitfalls
+/// Note that a MemoryMap can quickly become outdated, as soon as any explicit
+/// or hidden allocation happens.
+///
+/// As soon as boot services are excited, all previous obtained memory maps must
+/// be considered as outdated, except if the [`MemoryMapKey`] equals the one
+/// returned by `exit_boot_services()`.
+///
+/// **Please note** that when working with memory maps, the `entry_size` is
+/// usually larger than `size_of::<MemoryDescriptor` [[0]]. So to be safe,
+/// always use `entry_size` as step-size when interfacing with the memory map on
+/// a low level.
+///
+/// [0]: https://github.com/tianocore/edk2/blob/7142e648416ff5d3eac6c6d607874805f5de0ca8/MdeModulePkg/Core/PiSmmCore/Page.c#L1059
+pub trait MemoryMap: Debug + Index<usize, Output = MemoryDescriptor> {
+    /// Returns the associated [`MemoryMapMeta`].
+    #[must_use]
+    fn meta(&self) -> MemoryMapMeta;
+
+    /// Returns the associated [`MemoryMapKey`].
+    #[must_use]
+    fn key(&self) -> MemoryMapKey;
+
+    /// Returns the number of keys in the map.
+    #[must_use]
+    fn len(&self) -> usize;
+
+    /// Returns if the memory map is empty.
+    #[must_use]
+    fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// Returns a reference to the [`MemoryDescriptor`] at the given index, if
+    /// present.
+    #[must_use]
+    fn get(&self, index: usize) -> Option<&MemoryDescriptor> {
+        if index >= self.len() {
+            None
+        } else {
+            let offset = index * self.meta().desc_size;
+            unsafe {
+                self.buffer()
+                    .as_ptr()
+                    .add(offset)
+                    .cast::<MemoryDescriptor>()
+                    .as_ref()
+            }
+        }
+    }
+
+    /// Returns a reference to the underlying memory.
+    fn buffer(&self) -> &[u8];
+
+    /// Returns an Iterator of type [`MemoryMapIter`].
+    fn entries(&self) -> MemoryMapIter<'_>;
+}
+
+/// Extension to [`MemoryMap`] that adds mutable operations. This also includes
+/// the ability to sort the memory map.
+pub trait MemoryMapMut: MemoryMap + IndexMut<usize> {
+    /// Returns a mutable reference to the [`MemoryDescriptor`] at the given
+    /// index, if present.
+    #[must_use]
+    fn get_mut(&mut self, index: usize) -> Option<&mut MemoryDescriptor> {
+        if index >= self.len() {
+            None
+        } else {
+            let offset = index * self.meta().desc_size;
+            unsafe {
+                self.buffer_mut()
+                    .as_mut_ptr()
+                    .add(offset)
+                    .cast::<MemoryDescriptor>()
+                    .as_mut()
+            }
+        }
+    }
+
+    /// Sorts the memory map by physical address in place. This operation is
+    /// optional and should be invoked only once.
+    fn sort(&mut self);
+
+    /// Returns a reference to the underlying memory.
+    ///
+    /// # Safety
+    ///
+    /// This is unsafe as there is a potential to create invalid entries.
+    unsafe fn buffer_mut(&mut self) -> &mut [u8];
+}