Improve the documentation for PhysicalMapping

There has been a fair amount of confusion surrounding how to correctly
map physical memory requested by `rsdp` and `acpi`, and especially the
meaning of the fields on `PhysicalMapping`. This adds more info around the
meaning of each field, based off A0lson's PR rust-osdev#162.


Co-authored-by: Alex Olson <[email protected]>
Co-authored-by: rcerc <[email protected]>

rsdp/src/handler.rs

@@ -3,6 +3,8 @@ use core::{ops::Deref, ptr::NonNull};
 /// Describes a physical mapping created by `AcpiHandler::map_physical_region` and unmapped by
 /// `AcpiHandler::unmap_physical_region`. The region mapped must be at least `size_of::<T>()`
 /// bytes, but may be bigger.
+///
+/// See `PhysicalMapping::new` for the meaning of each field.
 #[derive(Debug)]
 pub struct PhysicalMapping<H, T>
 where
@@ -20,15 +22,17 @@ where
     H: AcpiHandler,
 {
     /// Construct a new `PhysicalMapping`.
-    /// `mapped_length` may differ from `region_length` if padding is added for alignment.
     ///
-    /// ## Safety
-    ///
-    /// This function must only be called by an `AcpiHandler` of type `H` to make sure that it's safe to unmap the mapping.
-    ///
-    /// - `virtual_start` must be a valid pointer.
-    /// - `region_length` must be equal to or larger than `size_of::<T>()`.
-    /// - `handler` must be the same `AcpiHandler` that created the mapping.
+    /// - `physical_start` should be the physical address of the structure to be mapped.
+    /// - `virtual_start` should be the corresponding virtual address of that structure. It may differ from the
+    ///   start of the region mapped due to requirements of the paging system. It must be a valid, non-null
+    ///   pointer.
+    /// - `region_length` should be the number of bytes requested to be mapped. It must be equal to or larger than
+    ///   `size_of::<T>()`.
+    /// - `mapped_length` should be the number of bytes mapped to fulfill the request. It may be equal to or larger
+    ///   than `region_length`, due to requirements of the paging system or other reasoning.
+    /// - `handler` should be the same `AcpiHandler` that created the mapping. When the `PhysicalMapping` is
+    ///   dropped, it will be used to unmap the structure.
     pub unsafe fn new(
         physical_start: usize,
         virtual_start: NonNull<T>,
@@ -93,6 +97,9 @@ pub trait AcpiHandler: Clone {
     /// implementation may need to map more than `size` bytes. The virtual address the region is mapped to does not
     /// matter, as long as it is accessible to `acpi`.
     ///
+    /// See the documentation on `PhysicalMapping::new` for an explanation of each field on the `PhysicalMapping`
+    /// return type.
+    ///
     /// ## Safety
     ///
     /// - `physical_address` must point to a valid `T` in physical memory.