multiboot2-common: add generic TagIter

Author: phip1611

multiboot2-common/src/iter.rs

@@ -0,0 +1,75 @@
+//! Iterator over Multiboot2 structures. Technically, the process is the same
+//! for iterating
+
+use crate::{increase_to_alignment, BytesRef, Header, ALIGNMENT};
+use core::marker::PhantomData;
+
+/// Iterates over the tag bytes of a structure while guaranteeing all necessary
+/// memory rules of Multiboot2 and Rustc/Miri. It emits elements of type
+/// [`BytesRef`].
+///
+/// This only operates on bytes rather than tags, as I didn't find a solution
+/// to make the iterator `Clone`able and also make it work with DSTs. However,
+/// the necessary glue-code for users is minimal.
+#[derive(Clone, Debug)]
+pub struct TagBytesIter<'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> TagBytesIter<'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);
+
+        TagBytesIter {
+            next_tag_offset: 0,
+            buffer: mem,
+            _t: PhantomData,
+        }
+    }
+}
+
+impl<'a, H: Header> Iterator for TagBytesIter<'a, H> {
+    type Item = BytesRef<'a, 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 bytes = {
+            let from = self.next_tag_offset;
+            let len = 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 come to this point at all, if there are memory
+        // issues.
+        let bytes = BytesRef::try_from(bytes).unwrap();
+        Some(bytes)
+    }
+}

multiboot2-common/src/lib.rs

@@ -30,9 +30,12 @@
 extern crate std;
 
 // Doesn't work: #[cfg(test)]
+pub mod iter;
 #[allow(unused)]
 pub mod test_utils;
 
+pub use iter::TagBytesIter;
+
 use core::fmt::Debug;
 use core::marker::PhantomData;
 use core::mem;

multiboot2-common/src/test_utils.rs

@@ -1,5 +1,7 @@
 //! Various test utilities.
 
+#![allow(missing_docs)]
+
 use crate::Header;
 use core::borrow::Borrow;
 use core::ops::Deref;
@@ -65,6 +67,27 @@ impl Header for DummyTestHeader {
     }
 }
 
+/*#[derive(Debug, PartialEq, Eq, ptr_meta::Pointee)]
+#[repr(C, align(8))]
+pub struct DummyDstTag {
+    header: DummyTestHeader,
+    payload: [u8],
+}
+
+impl DummyDstTag {
+    const BASE_SIZE: usize = size_of::<DummyTestHeader>();
+
+    #[must_use]
+    pub const fn header(&self) -> &DummyTestHeader {
+        &self.header
+    }
+
+    #[must_use]
+    pub const fn payload(&self) -> &[u8] {
+        &self.payload
+    }
+}*/
+
 #[cfg(test)]
 mod tests {
     use super::*;