multiboot2-common: init

Although the commit history doesn't reflect it, this is the outcome
after drying dozens of designs in much more time than I'd like to
admit :D

However, although this is complex, it solves real problems and is a
true value-add. Also, it reflects so many findings and learnings.

Author: phip1611

multiboot2-common/Cargo.toml

@@ -26,9 +26,15 @@ documentation = "https://docs.rs/multiboot2-common"
 #rust-version = "1.70"
 
 [features]
+default = ["builder"]
+alloc = []
+builder = ["alloc"]
+unstable = []
 
 
 [dependencies]
+derive_more.workspace = true
+ptr_meta.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true

multiboot2-common/src/boxed.rs

@@ -0,0 +1,116 @@
+//! Module for [`new_boxed`].
+
+use crate::{increase_to_alignment, Header, MaybeDynSized, ALIGNMENT};
+use alloc::boxed::Box;
+use core::alloc::Layout;
+use core::mem;
+use core::ops::Deref;
+use core::ptr;
+
+/// Creates a new tag implementing [`MaybeDynSized`] on the heap. This works for
+/// sized and unsized tags. However, it only makes sense to use this for tags
+/// that are DSTs (unsized). For regular sized structs, you can just create a
+/// typical constructor and box the result.
+///
+/// The provided `header`' total size (see [`Header`]) will be set dynamically
+/// by this function using [`Header::set_size`]. However, it must contain all
+/// other relevant metadata or update it in the `set_size` callback.
+///
+/// # Parameters
+/// - `additional_bytes_slices`: Array of byte slices that should be included
+///   without additional padding in-between. You don't need to add the bytes
+///   for [`Header`], but only additional payload.
+#[must_use]
+pub fn new_boxed<T: MaybeDynSized<Metadata = usize> + ?Sized>(
+    mut header: T::Header,
+    additional_bytes_slices: &[&[u8]],
+) -> Box<T> {
+    let additional_size = additional_bytes_slices
+        .iter()
+        .map(|b| b.len())
+        .sum::<usize>();
+
+    let tag_size = mem::size_of::<T::Header>() + additional_size;
+    header.set_size(tag_size);
+
+    // Allocation size is multiple of alignment.
+    // See <https://doc.rust-lang.org/reference/type-layout.html>
+    let alloc_size = increase_to_alignment(tag_size);
+    let layout = Layout::from_size_align(alloc_size, ALIGNMENT).unwrap();
+    let heap_ptr = unsafe { alloc::alloc::alloc(layout) };
+    assert!(!heap_ptr.is_null());
+
+    // write header
+    {
+        let len = mem::size_of::<T::Header>();
+        let ptr = core::ptr::addr_of!(header);
+        unsafe {
+            ptr::copy_nonoverlapping(ptr.cast::<u8>(), heap_ptr, len);
+        }
+    }
+
+    // write body
+    {
+        let mut write_offset = mem::size_of::<T::Header>();
+        for &bytes in additional_bytes_slices {
+            let len = bytes.len();
+            let src = bytes.as_ptr();
+            unsafe {
+                let dst = heap_ptr.add(write_offset);
+                ptr::copy_nonoverlapping(src, dst, len);
+                write_offset += len;
+            }
+        }
+    }
+
+    // This is a fat pointer for DSTs and a thin pointer for sized `T`s.
+    let ptr: *mut T = ptr_meta::from_raw_parts_mut(heap_ptr.cast(), T::dst_len(&header));
+    let reference = unsafe { Box::from_raw(ptr) };
+
+    // If this panic triggers, there is a fundamental flaw in my logic. This is
+    // not the fault of an API user.
+    assert_eq!(
+        mem::size_of_val(reference.deref()),
+        alloc_size,
+        "Allocation should match Rusts expectation"
+    );
+
+    reference
+}
+
+/// Clones a [`MaybeDynSized`] by calling [`new_boxed`].
+#[must_use]
+pub fn clone_dyn<T: MaybeDynSized<Metadata = usize> + ?Sized>(tag: &T) -> Box<T> {
+    new_boxed(tag.header().clone(), &[tag.payload()])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_utils::{DummyDstTag, DummyTestHeader};
+    use crate::Tag;
+
+    #[test]
+    fn test_new_boxed() {
+        let header = DummyTestHeader::new(DummyDstTag::ID, 0);
+        let tag = new_boxed::<DummyDstTag>(header, &[&[0, 1, 2, 3]]);
+        assert_eq!(tag.header().typ(), 42);
+        assert_eq!(tag.payload(), &[0, 1, 2, 3]);
+
+        // Test that bytes are added consecutively without gaps.
+        let header = DummyTestHeader::new(0xdead_beef, 0);
+        let tag = new_boxed::<DummyDstTag>(header, &[&[0], &[1], &[2, 3]]);
+        assert_eq!(tag.header().typ(), 0xdead_beef);
+        assert_eq!(tag.payload(), &[0, 1, 2, 3]);
+    }
+
+    #[test]
+    fn test_clone_tag() {
+        let header = DummyTestHeader::new(DummyDstTag::ID, 0);
+        let tag = new_boxed::<DummyDstTag>(header, &[&[0, 1, 2, 3]]);
+        assert_eq!(tag.header().typ(), 42);
+        assert_eq!(tag.payload(), &[0, 1, 2, 3]);
+
+        let _cloned = clone_dyn(tag.as_ref());
+    }
+}

multiboot2-common/src/bytes_ref.rs

@@ -0,0 +1,87 @@
+//! Module for [`BytesRef`].
+
+use crate::{Header, MemoryError, ALIGNMENT};
+use core::marker::PhantomData;
+use core::mem;
+use core::ops::Deref;
+
+/// Wraps a byte slice representing a Multiboot2 structure including an optional
+/// terminating padding, if necessary. It guarantees that the memory
+/// requirements promised in the crates description are respected.
+#[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 `H` 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 = MemoryError;
+
+    fn try_from(bytes: &'a [u8]) -> Result<Self, Self::Error> {
+        if bytes.len() < mem::size_of::<H>() {
+            return Err(MemoryError::MinLengthNotSatisfied);
+        }
+        // Doesn't work as expected: if align_of_val(&value[0]) < ALIGNMENT {
+        if bytes.as_ptr().align_offset(ALIGNMENT) != 0 {
+            return Err(MemoryError::WrongAlignment);
+        }
+        let padding_bytes = bytes.len() % ALIGNMENT;
+        if padding_bytes != 0 {
+            return Err(MemoryError::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
+    }
+}
+
+#[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(MemoryError::MinLengthNotSatisfied)
+        );
+
+        let slice = &[0_u8, 1, 2, 3, 4, 5, 6];
+        assert_eq!(
+            BytesRef::<'_, DummyTestHeader>::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!(
+            BytesRef::<'_, DummyTestHeader>::try_from(unaligned_slice),
+            Err(MemoryError::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/iter.rs

@@ -0,0 +1,125 @@
+//! Iterator over Multiboot2 structures. Technically, the process for iterating
+//! Multiboot2 information tags and iterating Multiboot2 header tags is the
+//! same.
+
+use crate::{increase_to_alignment, DynSizedStructure, Header, ALIGNMENT};
+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`].
+///
+/// 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.
+///
+/// This type ensures the memory safety guarantees promised by this crates
+/// documentation.
+///
+/// [`Tag`]: crate::Tag
+#[derive(Clone, Debug)]
+pub struct TagIter<'a, H: Header> {
+    /// Absolute offset to next tag and updated in each iteration.
+    next_tag_offset: usize,
+    buffer: &'a [u8],
+    // Ensure that all instances are bound to a specific `Header`.
+    // Otherwise, UB can happen.
+    _t: PhantomData<H>,
+}
+
+impl<'a, H: Header> TagIter<'a, H> {
+    /// Creates a new iterator.
+    #[must_use]
+    pub fn new(mem: &'a [u8]) -> Self {
+        // Assert alignment.
+        assert_eq!(mem.as_ptr().align_offset(ALIGNMENT), 0);
+
+        TagIter {
+            next_tag_offset: 0,
+            buffer: mem,
+            _t: PhantomData,
+        }
+    }
+}
+
+impl<'a, H: Header + 'a> Iterator for TagIter<'a, H> {
+    type Item = &'a DynSizedStructure<H>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.next_tag_offset == self.buffer.len() {
+            return None;
+        }
+        assert!(self.next_tag_offset < self.buffer.len());
+
+        let ptr = unsafe { self.buffer.as_ptr().add(self.next_tag_offset) }.cast::<H>();
+        let tag_hdr = unsafe { &*ptr };
+
+        // Get relevant byte portion for the next tag. This includes padding
+        // bytes to fulfill Rust memory guarantees. Otherwise, Miri complains.
+        // See <https://doc.rust-lang.org/reference/type-layout.html>.
+        let slice = {
+            let from = self.next_tag_offset;
+            let len = mem::size_of::<H>() + tag_hdr.payload_len();
+            let to = from + len;
+
+            // The size of (the allocation for) a value is always a multiple of
+            // its alignment.
+            // https://doc.rust-lang.org/reference/type-layout.html
+            let to = increase_to_alignment(to);
+
+            // Update ptr for next iteration.
+            self.next_tag_offset += to - from;
+
+            &self.buffer[from..to]
+        };
+
+        // unwrap: We should not fail at this point.
+        let tag = DynSizedStructure::ref_from_slice(slice).unwrap();
+        Some(tag)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::test_utils::{AlignedBytes, DummyTestHeader};
+    use crate::TagIter;
+    use core::borrow::Borrow;
+
+    #[test]
+    fn test_tag_iter() {
+        #[rustfmt::skip]
+        let bytes = AlignedBytes::new(
+            [
+                /* Some minimal tag.  */
+                0xff, 0, 0, 0,
+                8, 0, 0, 0,
+                /* Some tag with payload.  */
+                0xfe, 0, 0, 0,
+                12, 0, 0, 0,
+                1, 2, 3, 4,
+                // Padding
+                0, 0, 0, 0,
+                /* End tag */
+                0, 0, 0, 0,
+                8, 0, 0, 0,
+            ],
+        );
+        let mut iter = TagIter::<DummyTestHeader>::new(bytes.borrow());
+        let first = iter.next().unwrap();
+        assert_eq!(first.header().typ(), 0xff);
+        assert_eq!(first.header().size(), 8);
+        assert!(first.payload().is_empty());
+
+        let second = iter.next().unwrap();
+        assert_eq!(second.header().typ(), 0xfe);
+        assert_eq!(second.header().size(), 12);
+        assert_eq!(&second.payload(), &[1, 2, 3, 4]);
+
+        let third = iter.next().unwrap();
+        assert_eq!(third.header().typ(), 0);
+        assert_eq!(third.header().size(), 8);
+        assert!(first.payload().is_empty());
+
+        assert_eq!(iter.next(), None);
+    }
+}