Merge pull request #245 from rust-osdev/doc

multiboot2: various small fixes and doc improvements

Author: phip1611

multiboot2-common/README.md

@@ -25,9 +25,13 @@ safely cast to the target type.
 ![Generic parsing flow overview](./parsing-flow-generic.drawio.png "Generic parsing flow overview: From raw bytes to specific structures")
 
 The next figure is like the previous figure, but shows a more specific parsing
-flow by using types of the `multiboot2` crate. Green shows the raw memory.
-Purple boxes refers to logic in `multiboot2-common`. Red components show structs
-from the `multiboot2` crate.
+flow by using example types of the `multiboot2` crate. Specifically, it shows
+how the header structs for each multiboot2 structure, each implementing
+the `Header` trait, are utilized as generic types to get the right size
+information of the final type tag type.
+
+Green shows the raw memory, purple boxes refer to logic in `multiboot2-common`,
+and red components show structs from the `multiboot2` crate.
 
 ![Specific parsing flow overview](./parsing-flow-specific.drawio.png "Specific parsing flow overview: From raw bytes to multiboot2 structures")
 

multiboot2-common/parsing-flow-specific.drawio.png

@@ -7,11 +7,14 @@ use core::marker::PhantomData;
 use core::mem;
 
 /// Iterates over the tags (modelled by [`DynSizedStructure`]) of the underlying
-/// byte slice. Each tag is expected to have the same common [`Header`].
+/// byte slice. Each tag is expected to have the same common [`Header`] with
+/// the corresponding ABI guarantees.
 ///
 /// As the iterator emits elements of type [`DynSizedStructure`], users should
-/// casted them to specific [`Tag`]s using [`DynSizedStructure::cast`] following
-/// a user policy. This can for example happen on the basis of some ID.
+/// cast them to specific [`Tag`]s using [`DynSizedStructure::cast`] following
+/// a user-specific policy. This can for example happen on the basis of some ID.
+///
+/// This iterator also emits end tags and doesn't treat them separately.
 ///
 /// This type ensures the memory safety guarantees promised by this crates
 /// documentation.
@@ -30,6 +33,8 @@ pub struct TagIter<'a, H: Header> {
 impl<'a, H: Header> TagIter<'a, H> {
     /// Creates a new iterator.
     #[must_use]
+    // TODO we could take a BytesRef here, but the surrounding code should be
+    //  bullet-proof enough.
     pub fn new(mem: &'a [u8]) -> Self {
         // Assert alignment.
         assert_eq!(mem.as_ptr().align_offset(ALIGNMENT), 0);

multiboot2-common/parsing-flow-specific.drawio.xml

@@ -64,7 +64,7 @@ pub trait MaybeDynSized: Pointee {
     /// data, read the tag size from [`Self::header`] and create a sub slice.
     fn as_bytes(&self) -> BytesRef<Self::Header> {
         let ptr = core::ptr::addr_of!(*self);
-        // Actual tag size, optionally with terminating padding.
+        // Actual tag size with optional terminating padding.
         let size = mem::size_of_val(self);
         let slice = unsafe { slice::from_raw_parts(ptr.cast::<u8>(), size) };
         // Unwrap is fine as this type can't exist without the underlying memory

multiboot2-common/src/iter.rs

@@ -53,7 +53,7 @@ impl Debug for EntryAddressHeaderTag {
             .field("type", &self.typ())
             .field("flags", &self.flags())
             .field("size", &self.size())
-            .field("entry_addr", &(self.entry_addr as *const u32))
+            .field("entry_addr", &self.entry_addr)
             .finish()
     }
 }

multiboot2-common/src/tag.rs

@@ -62,7 +62,7 @@ impl Debug for EntryEfi32HeaderTag {
             .field("type", &self.typ())
             .field("flags", &self.flags())
             .field("size", &self.size())
-            .field("entry_addr", &(self.entry_addr as *const u32))
+            .field("entry_addr", &self.entry_addr)
             .finish()
     }
 }

multiboot2-header/src/entry_address.rs

@@ -62,7 +62,7 @@ impl Debug for EntryEfi64HeaderTag {
             .field("type", &self.typ())
             .field("flags", &self.flags())
             .field("size", &self.size())
-            .field("entry_addr", &(self.entry_addr as *const u32))
+            .field("entry_addr", &self.entry_addr)
             .finish()
     }
 }

multiboot2-header/src/entry_efi_32.rs

@@ -108,10 +108,10 @@ impl Debug for RelocatableHeaderTag {
             .field("flags", &self.flags())
             .field("size", &self.size())
             // trick to print this as hexadecimal pointer
-            .field("min_addr", &(self.min_addr as *const u32))
-            .field("max_addr", &(self.max_addr as *const u32))
-            .field("align", &{ self.align })
-            .field("preference", &{ self.preference })
+            .field("min_addr", &self.min_addr)
+            .field("max_addr", &self.max_addr)
+            .field("align", &self.align)
+            .field("preference", &self.preference)
             .finish()
     }
 }

multiboot2-header/src/entry_efi_64.rs

@@ -132,6 +132,7 @@ impl<'a> BootInformation<'a> {
 
     /// Get the start address of the boot info.
     #[must_use]
+    // TODO deprecated and use pointers only (see provenance discussions)
     pub fn start_address(&self) -> usize {
         self.as_ptr() as usize
     }
@@ -153,6 +154,7 @@ impl<'a> BootInformation<'a> {
     /// let end_addr = boot_info.start_address() + boot_info.total_size();
     /// ```
     #[must_use]
+    // TODO deprecated and use pointers only (see provenance discussions)
     pub fn end_address(&self) -> usize {
         self.start_address() + self.total_size()
     }