uefi: memory_map: streamline documentation

Author: phip1611

uefi/src/mem/memory_map/api.rs

@@ -27,8 +27,6 @@ use core::ops::{Index, IndexMut};
 ///
 /// [0]: https://github.com/tianocore/edk2/blob/7142e648416ff5d3eac6c6d607874805f5de0ca8/MdeModulePkg/Core/PiSmmCore/Page.c#L1059
 pub trait MemoryMap: Debug + Index<usize, Output = MemoryDescriptor> {
-    // TODO also require IntoIterator?! :)
-
     /// Returns the associated [`MemoryMapMeta`].
     #[must_use]
     fn meta(&self) -> MemoryMapMeta;

uefi/src/mem/memory_map/impl_.rs

@@ -201,6 +201,8 @@ impl IndexMut<usize> for MemoryMapRefMut<'_> {
 /// 1. create it using [`MemoryMapBackingMemory::new`]
 /// 2. pass it to [`BootServices::get_memory_map`]
 /// 3. construct a [`MemoryMapOwned`] from it
+///
+/// [`BootServices::get_memory_map`]: crate::table::boot::BootServices::get_memory_map
 #[derive(Debug)]
 #[allow(clippy::len_without_is_empty)] // this type is never empty
 pub(crate) struct MemoryMapBackingMemory(NonNull<[u8]>);
@@ -247,8 +249,9 @@ impl MemoryMapBackingMemory {
     }
 
     /// Returns a "safe" best-effort size hint for the memory map size with
-    /// some additional bytes in buffer compared to the [`crate::table::boot::mmap::MemoryMapMeta`].
-    /// This helps
+    /// some additional bytes in buffer compared to the [`MemoryMapMeta`]. This
+    /// takes into account that, as you go, more (small) allocations might
+    /// happen.
     #[must_use]
     fn safe_allocation_size_hint(mmm: MemoryMapMeta) -> usize {
         // Allocate space for extra entries beyond the current size of the

uefi/src/mem/memory_map/iter.rs

@@ -1,7 +1,7 @@
 use super::*;
 
 /// An iterator of [`MemoryDescriptor`]. The underlying memory map is always
-/// associated with a unique [`crate::table::boot::mmap::MemoryMapKey`].
+/// associated with a unique [`MemoryMapKey`].
 #[derive(Debug, Clone)]
 pub struct MemoryMapIter<'a> {
     pub(crate) memory_map: &'a dyn MemoryMap,

uefi/src/mem/memory_map/mod.rs

@@ -1,14 +1,36 @@
-//! This module bundles all relevant types and helpers to work with the UEFI
-//! memory map. Specifically, it provides
+//! Bundles all relevant types and helpers to work with the UEFI memory map.
+//!
+//! To work with the memory map, you should use one of the structs
+//! [`MemoryMapOwned`], [`MemoryMapRef`], or [`MemoryMapRefMut`] - depending on
+//! your use-case. The  traits [`MemoryMap`] and [`MemoryMapMut`] mainly exist
+//! to guarantee a streamlined API across these types. We recommend to work with
+//! the specific implementation.
+//!
+//! # Usecase: Obtain UEFI Memory Map
+//!
+//! You can use [`SystemTable::exit_boot_services`] or
+//! [`BootServices::memory_map`], which returns an properly initialized 
+//! [`MemoryMapOwned`].
+//!
+//! # Usecase: Parse Memory Slice as UEFI Memory Map
+//!
+//! 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.
+//!
+//! # All relevant exports:
 //!
 //! - the traits [`MemoryMap`] and [`MemoryMapMut`],
 //! - the trait implementations [`MemoryMapOwned`], [`MemoryMapRef`], and
 //!   [`MemoryMapRefMut`],
 //! - the iterator [`MemoryMapIter`]
-//! - various associated helper types, such as  [`MemoryMapKey`] and
+//! - various associated helper types, such as [`MemoryMapKey`] and
 //!   [`MemoryMapMeta`],
-//! - and re-exports the types [`MemoryDescriptor`], [`MemoryType`],
-//!   [`MemoryAttribute`]
+//! - re-exports [`MemoryDescriptor`], [`MemoryType`], and [`MemoryAttribute`].
+//!
+//! [`SystemTable::exit_boot_services`]: uefi::table::SystemTable::exit_boot_services
+//! [`BootServices::memory_map`]: uefi::table::boot::BootServices::memory_map
 
 mod api;
 mod impl_;