multiboot2-common: init with test_util module and memory helpers

Author: phip1611

Cargo.lock

@@ -13,9 +13,11 @@ exclude = [
 bitflags = "2.6.0"
 derive_more = { version = "~0.99.18", default-features = false, features = ["display"] }
 log = { version = "~0.4", default-features = false }
+ptr_meta = { version = "~0.2", default-features = false }
 
-# This way, the "multiboot2" dependency in the multiboot2-header crate can be
-# referenced by version, while still the repository version is used
-# transparently during local development.
+# This way, the corresponding crate dependency can be normalley referenced by
+# version, while still the repository version is used transparently during local
+# development.
 [patch.crates-io]
 multiboot2 = { path = "multiboot2" }
+multiboot2-common = { path = "multiboot2-common" }

Cargo.toml

@@ -29,6 +29,7 @@ documentation = "https://docs.rs/multiboot2-common"
 
 
 [dependencies]
+ptr_meta.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true

multiboot2-common/Cargo.toml

@@ -24,3 +24,194 @@
 #![deny(missing_debug_implementations)]
 #![deny(rustdoc::all)]
 // --- END STYLE CHECKS ---
+
+#[cfg_attr(test, macro_use)]
+#[cfg(test)]
+extern crate std;
+
+// Doesn't work: #[cfg(test)]
+#[allow(unused)]
+pub mod test_utils;
+
+use core::fmt::Debug;
+use core::marker::PhantomData;
+use core::mem;
+use core::ops::Deref;
+
+/// The alignment of all Multiboot2 data structures.
+pub const ALIGNMENT: usize = 8;
+
+/// A sized header type for [`DynSizedStructure`]. Note that `header` refers to
+/// the header pattern. Thus, depending on the use case, this is not just the
+/// tag header. Instead, it refers to all bytes that are fixed and not part of
+/// any optional terminating dynamic `[u8]` slice.
+///
+/// It's alignment **must** be the alignment of the tags. Typically,
+/// [`ALIGNMENT`].
+pub trait Header: Sized + PartialEq + Eq + Debug {
+    /// Returns the length of the payload, i.e., the bytes that are additional
+    /// to the header. The value is measured in bytes.
+    fn payload_len(&self) -> usize;
+}
+
+/// Errors that occur when constructing [`DynSizedStructure`].
+#[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
+pub enum DynSizedStructureError {
+    /// The size-property has an illegal value that can't be fulfilled with the
+    /// given bytes.
+    SizeTooBig,
+}
+
+/// A dynamically sized type with a common sized header and a dynamic amount of
+/// bytes that owns all its memory. It is fulfilling all memory requirements and
+/// guarantees of Multiboot2 structures and Rustc/Miri.
+///
+/// # ABI
+/// This has a C ABI. The fixed [`Header`] portion is always there. Further,
+/// there is a variable amount of payload bytes. Thus, this type can only
+/// exist on the heap or references to it can be made by cast via fat pointers.
+#[derive(Debug, PartialEq, Eq, ptr_meta::Pointee)]
+#[repr(C, align(8))]
+pub struct DynSizedStructure<H: Header> {
+    header: H,
+    payload: [u8],
+    // Plus optional padding bytes to next alignment boundary, which are not
+    // reflected here. However, Rustc allocates them anyway and expects them
+    // to be there.
+    // See <https://doc.rust-lang.org/reference/type-layout.html>.
+}
+
+impl<H: Header> DynSizedStructure<H> {
+    /// Returns a new reference from the given [`BytesRef`].
+    pub fn ref_from(bytes: BytesRef<H>) -> Result<&Self, DynSizedStructureError> {
+        let header = bytes.as_ptr().cast::<H>();
+        let header = unsafe { &*header };
+
+        if header.payload_len() > bytes.len() {
+            return Err(DynSizedStructureError::SizeTooBig);
+        }
+
+        // Create fat pointer for DST.
+        let structure: *const Self =
+            ptr_meta::from_raw_parts(bytes.as_ptr().cast(), header.payload_len());
+        let structure = unsafe { &*structure };
+        Ok(structure)
+    }
+
+    /// Returns the underlying [`Header`].
+    pub const fn header(&self) -> &H {
+        &self.header
+    }
+
+    /// Returns the underlying payload.
+    pub const fn payload(&self) -> &[u8] {
+        &self.payload
+    }
+}
+
+/// Wraps a byte slice representing a Multiboot2 structure including an optional
+/// terminating padding, if necessary. Guarantees that the memory requirements
+/// for both Multiboot2 and Rustc/Miri are fulfilled.
+///
+/// Useful to construct [`DynSizedStructure`]. The main reason for this
+/// dedicated type is to create fine-grained unit-tests for Miri.
+///
+/// # Memory Requirements
+/// - At least as big as a `size_of::<HeaderT>()`
+/// - at least [`ALIGNMENT`]-aligned
+/// - Length is multiple of [`ALIGNMENT`]. In other words, there are enough
+///   padding bytes so that the pointer coming right after the last byte
+///   is [`ALIGNMENT`]-aligned.
+///
+/// See <https://doc.rust-lang.org/reference/type-layout.html> for information.
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[repr(transparent)]
+pub struct BytesRef<'a, H: Header> {
+    bytes: &'a [u8],
+    // Ensure that consumers can rely on the size properties for HeaderT that
+    // already have been verified when this type was constructed.
+    _h: PhantomData<H>,
+}
+
+impl<'a, H: Header> TryFrom<&'a [u8]> for BytesRef<'a, H> {
+    type Error = BytesRefError;
+
+    fn try_from(bytes: &'a [u8]) -> Result<Self, Self::Error> {
+        if bytes.len() < mem::size_of::<H>() {
+            return Err(BytesRefError::MinLengthNotSatisfied);
+        }
+        // Doesn't work as expected: if align_of_val(&value[0]) < ALIGNMENT {
+        if bytes.as_ptr().align_offset(ALIGNMENT) != 0 {
+            return Err(BytesRefError::WrongAlignment);
+        }
+        let padding_bytes = bytes.len() % ALIGNMENT;
+        if padding_bytes != 0 {
+            return Err(BytesRefError::MissingPadding);
+        }
+        Ok(Self {
+            bytes,
+            _h: PhantomData,
+        })
+    }
+}
+
+impl<'a, H: Header> Deref for BytesRef<'a, H> {
+    type Target = &'a [u8];
+
+    fn deref(&self) -> &Self::Target {
+        &self.bytes
+    }
+}
+
+/// Errors that occur when constructing [`BytesRef`].
+#[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
+pub enum BytesRefError {
+    /// The memory must be at least [`ALIGNMENT`]-aligned.
+    WrongAlignment,
+    /// The memory must cover at least the length of the sized structure header
+    /// type.
+    MinLengthNotSatisfied,
+    /// The buffer misses the terminating padding to the next alignment
+    /// boundary. The padding is relevant to satisfy Rustc/Miri, but also the
+    /// spec mandates that the padding is added.
+    MissingPadding,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_utils::{AlignedBytes, DummyTestHeader};
+
+    #[test]
+    fn test_bytes_ref() {
+        let empty: &[u8] = &[];
+        assert_eq!(
+            BytesRef::<'_, DummyTestHeader>::try_from(empty),
+            Err(BytesRefError::MinLengthNotSatisfied)
+        );
+
+        let slice = &[0_u8, 1, 2, 3, 4, 5, 6];
+        assert_eq!(
+            BytesRef::<'_, DummyTestHeader>::try_from(&slice[..]),
+            Err(BytesRefError::MinLengthNotSatisfied)
+        );
+
+        let slice = AlignedBytes([0_u8, 1, 2, 3, 4, 5, 6, 7, 0, 0, 0]);
+        // Guaranteed wrong alignment
+        let unaligned_slice = &slice[3..];
+        assert_eq!(
+            BytesRef::<'_, DummyTestHeader>::try_from(unaligned_slice),
+            Err(BytesRefError::WrongAlignment)
+        );
+
+        let slice = AlignedBytes([0_u8, 1, 2, 3, 4, 5, 6, 7]);
+        let slice = &slice[..];
+        assert_eq!(
+            BytesRef::try_from(slice),
+            Ok(BytesRef {
+                bytes: slice,
+                _h: PhantomData::<DummyTestHeader>
+            })
+        );
+    }
+}

multiboot2-common/src/lib.rs

@@ -0,0 +1,94 @@
+//! Various test utilities.
+
+use crate::Header;
+use core::borrow::Borrow;
+use core::ops::Deref;
+
+/// Helper to 8-byte align the underlying bytes, as mandated in the Multiboot2
+/// spec. With this type, one can create manual and raw Multiboot2 boot
+/// information or just the bytes for simple tags, in a manual and raw approach.
+#[derive(Debug)]
+#[repr(C, align(8))]
+pub struct AlignedBytes<const N: usize>(pub [u8; N]);
+
+impl<const N: usize> AlignedBytes<N> {
+    /// Creates a new type.
+    #[must_use]
+    pub const fn new(bytes: [u8; N]) -> Self {
+        Self(bytes)
+    }
+}
+
+impl<const N: usize> Borrow<[u8; N]> for AlignedBytes<N> {
+    fn borrow(&self) -> &[u8; N] {
+        &self.0
+    }
+}
+
+impl<const N: usize> Borrow<[u8]> for AlignedBytes<N> {
+    fn borrow(&self) -> &[u8] {
+        &self.0
+    }
+}
+
+impl<const N: usize> Deref for AlignedBytes<N> {
+    type Target = [u8; N];
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+/// Dummy test header.
+#[derive(Debug, PartialEq, Eq)]
+#[repr(C, align(8))]
+pub struct DummyTestHeader {
+    typ: u32,
+    size: u32,
+}
+
+impl DummyTestHeader {
+    #[must_use]
+    pub const fn typ(&self) -> u32 {
+        self.typ
+    }
+
+    #[must_use]
+    pub const fn size(&self) -> u32 {
+        self.size
+    }
+}
+
+impl Header for DummyTestHeader {
+    fn payload_len(&self) -> usize {
+        self.size as usize - size_of::<Self>()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ALIGNMENT;
+    use core::mem;
+    use core::ptr::addr_of;
+
+    #[test]
+    fn abi() {
+        assert_eq!(mem::align_of::<AlignedBytes<0>>(), ALIGNMENT);
+
+        let bytes = AlignedBytes([0]);
+        assert_eq!(bytes.as_ptr().align_offset(8), 0);
+        assert_eq!((addr_of!(bytes[0])).align_offset(8), 0);
+
+        let bytes = AlignedBytes([0, 1, 2, 3, 4, 5, 6, 7]);
+        assert_eq!(bytes.as_ptr().align_offset(8), 0);
+        assert_eq!((addr_of!(bytes[0])).align_offset(8), 0);
+
+        let bytes = AlignedBytes([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+        assert_eq!(bytes.as_ptr().align_offset(8), 0);
+        assert_eq!((addr_of!(bytes[0])).align_offset(8), 0);
+        assert_eq!((addr_of!(bytes[7])).align_offset(8), 1);
+        assert_eq!((addr_of!(bytes[8])).align_offset(8), 0);
+        assert_eq!((addr_of!(bytes[9])).align_offset(8), 7);
+    }
+}

multiboot2-common/src/test_utils.rs

@@ -44,8 +44,8 @@ unstable = []
 bitflags.workspace = true
 derive_more.workspace = true
 log.workspace = true
+ptr_meta.workspace = true
 
-ptr_meta = { version = "~0.2", default-features = false }
 # We only use a very basic type definition from this crate. To prevent MSRV
 # bumps from uefi-raw, I restrict this here. Upstream users are likely to have
 # two versions of this library in it, which is no problem, as we only use the

multiboot2/Cargo.toml

@@ -113,9 +113,6 @@ pub use vbe_info::{
 /// machine state.
 pub const MAGIC: u32 = 0x36d76289;
 
-/// The required alignment for tags and the boot information.
-pub const ALIGNMENT: usize = 8;
-
 #[cfg(test)]
 mod tests {
     use super::*;

multiboot2/src/lib.rs

@@ -328,33 +328,6 @@ mod tests {
         assert_eq!(custom_tag.payload[3], 0x13);
     }
 
-    #[test]
-    fn test_tag_bytes_ref() {
-        let empty: &[u8] = &[];
-        assert_eq!(
-            TagBytesRef::try_from(empty),
-            Err(MemoryError::MinLengthNotSatisfied)
-        );
-
-        let slice = &[0_u8, 1, 2, 3, 4, 5, 6];
-        assert_eq!(
-            TagBytesRef::try_from(&slice[..]),
-            Err(MemoryError::MinLengthNotSatisfied)
-        );
-
-        let slice = AlignedBytes([0_u8, 1, 2, 3, 4, 5, 6, 7, 0, 0, 0]);
-        // Guaranteed wrong alignment
-        let unaligned_slice = &slice[3..];
-        assert_eq!(
-            TagBytesRef::try_from(unaligned_slice),
-            Err(MemoryError::WrongAlignment)
-        );
-
-        let slice = AlignedBytes([0_u8, 1, 2, 3, 4, 5, 6, 7]);
-        let slice = &slice[..];
-        assert_eq!(TagBytesRef::try_from(slice), Ok(TagBytesRef(slice)));
-    }
-
     #[test]
     fn test_create_generic_tag() {
         #[rustfmt::skip]