aaa

multiboot2-common/src/lib.rs

@@ -120,17 +120,22 @@
 //!
 //! ## Rustc Requirements
 //!
-//! The allocation space that Rust requires for types is a multiple of the
+//! The required allocation space that Rust uses for types is a multiple of the
 //! alignment. This means that if we cast between byte slices and specific
-//! types, Rust doesn't just see the size reported by the header but also
-//! any necessary padding bytes. If this is not the case, for example we
-//! cast to a structure from a `&[u8; 15]`, Miri will complain as it expects
-//! `&[u8; 16]`
+//! types, Rust doesn't just see the "trimmed down actual payload" defined by
+//! struct members, but also any necessary, but hidden, padding bytes. If we
+//! don't guarantee the correct is not the case, for example we cast the bytes
+//! from a `&[u8; 15]` to an 8-byte aligned struct, Miri will complain as it
+//! expects `&[u8; 16]`.
 //!
 //! See <https://doc.rust-lang.org/reference/type-layout.html> for information.
 //!
+//! Further, this also means that we can't cast smaller structs to
+//!
 //! Further, the [`Layout`]
 //!
+//!
+//!
 //! # Provided Abstractions
 //!
 //! Figure 2 in the [README](https://crates.io/crates/multiboot2-common)
@@ -317,10 +322,17 @@ impl<H: Header> DynSizedStructure<H> {
         &self.payload
     }
 
-    /// Casts the structure tag to a specific [`MaybeDynSized`] implementation which
-    /// may be a ZST or DST typed tag. The output type will have the exact same
-    /// size as `*self`. The target type must be sufficient for that. If not,
-    /// the function will panic.
+    /// Performs a memory-safe same-size cast from the base-structure to a
+    /// specific [`MaybeDynSized`]. The idea here is to cast the generic
+    /// mostly semantic-free version to a specific type with fields that have
+    /// a semantic.
+    ///
+    /// The provided `T` of type [`MaybeDynSized`] might be may be sized type
+    /// or DST. This depends on the type.
+    ///
+    /// # Panic
+    /// Panics if base assumptions are violated. For example, the
+    /// `T` of type [`MaybeDynSized`] must allow a proper casting to it.
     ///
     /// # Safety
     /// This function is safe due to various sanity checks and the overall

multiboot2-common/src/tag.rs

@@ -10,7 +10,8 @@ use ptr_meta::Pointee;
 /// [`DynSizedStructure::cast`].
 ///
 /// Structs that are a DST must provide a **correct**
-/// [`MaybeDynSized::dst_len`] implementation.
+/// [`MaybeDynSized::dst_len`] implementation. Further, implementors **must**
+/// use `#[repr(C)]`.
 ///
 /// [`ID`]: Tag::ID
 /// [`DynSizedStructure`]: crate::DynSizedStructure