multiboot2: expose get_tag publicly to allow custom tags

Author: phip1611

multiboot2/src/lib.rs

@@ -55,12 +55,17 @@ pub use memory_map::{
 };
 pub use module::{ModuleIter, ModuleTag};
 pub use rsdp::{RsdpV1Tag, RsdpV2Tag};
-pub use tag_type::TagType;
-use tag_type::{Tag, TagIter};
+pub use tag_type::Tag;
 pub use vbe_info::{
     VBECapabilities, VBEControlInfo, VBEDirectColorAttributes, VBEField, VBEInfoTag,
     VBEMemoryModel, VBEModeAttributes, VBEModeInfo, VBEWindowAttributes,
 };
+pub use {
+    tag_type::SpecifiedOrCustomTagType, tag_type::SpecifiedOrCustomTagTypeSerialized,
+    tag_type::TagType,
+};
+
+use tag_type::TagIter;
 
 #[macro_use]
 extern crate bitflags;
@@ -308,8 +313,41 @@ impl BootInformation {
         unsafe { &*self.inner }
     }
 
-    fn get_tag(&self, typ: TagType) -> Option<&Tag> {
-        self.tags().find(|tag| tag.typ == typ)
+    /// Public getter to find any tag type you are looking for.
+    ///
+    /// # Specified or Custom Tags
+    /// The Multiboot2 specification specifies a list of tags, see [`TagType`]. However, it doesn't
+    /// forbid to use custom tags. Because of this, there exists the [`SpecifiedOrCustomTagType`]
+    /// abstraction. **It is recommended** to use this getter only for custom tags. For specified
+    /// tags, use getters, such as [`Self::efi_64_ih`].
+    ///
+    /// ## Use Custom Tags
+    /// The following example shows how you may use this interface to parse custom tags from
+    /// the MBI.
+    ///
+    /// ```ignore
+    /// use multiboot2::SpecifiedOrCustomTagTypeSerialized;
+    /// #[repr(C, align(8))]
+    ///     struct CustomTag {
+    ///     // new type from the lib: has repr(u32)
+    ///     tag: SpecifiedOrCustomTagTypeSerialized,
+    ///     size: u32,
+    ///     // begin of inline string
+    ///     name: u8,
+    /// }
+    ///
+    /// let tag = bi
+    ///     // this function is now public!
+    ///     .get_tag(0x1337.into())
+    ///     .unwrap()
+    ///     // type definition from end user. must be Sized!
+    ///     .cast_tag::<CustomTag>();
+    /// let name = &tag.name as *const u8 as *const c_char;
+    /// let str = unsafe { CStr::from_ptr(name).to_str().unwrap() };
+    /// assert_eq!(str, "name");
+    /// ```
+    pub fn get_tag(&self, typ: SpecifiedOrCustomTagType) -> Option<&Tag> {
+        self.tags().find(|tag: &&Tag| tag.typ == typ)
     }
 
     fn tags(&self) -> TagIter {
@@ -319,16 +357,16 @@ impl BootInformation {
 
 impl BootInformationInner {
     fn has_valid_end_tag(&self) -> bool {
-        const END_TAG: Tag = Tag {
-            typ: TagType::End,
+        let end_tag_prototype: Tag = Tag {
+            typ: TagType::End.into(),
             size: 8,
         };
 
         let self_ptr = self as *const _;
-        let end_tag_addr = self_ptr as usize + (self.total_size - END_TAG.size) as usize;
+        let end_tag_addr = self_ptr as usize + (self.total_size - end_tag_prototype.size) as usize;
         let end_tag = unsafe { &*(end_tag_addr as *const Tag) };
 
-        end_tag.typ == END_TAG.typ && end_tag.size == END_TAG.size
+        end_tag.typ == end_tag_prototype.typ && end_tag.size == end_tag_prototype.size
     }
 }
 
@@ -437,6 +475,7 @@ impl Reader {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::ffi::{c_char, CStr};
 
     #[test]
     fn no_tags() {

multiboot2/src/module.rs

@@ -75,7 +75,7 @@ impl<'a> Iterator for ModuleIter<'a> {
 
     fn next(&mut self) -> Option<&'a ModuleTag> {
         self.iter
-            .find(|x| x.typ == TagType::Module)
+            .find(|tag| tag.typ == TagType::Module)
             .map(|tag| unsafe { &*(tag as *const Tag as *const ModuleTag) })
     }
 }

multiboot2/src/tag_type.rs

@@ -345,15 +345,16 @@ impl TagType {
     pub const MAX_INDEX: u32 = 21;
 }
 
-/// All tags that could passed via the Multiboot2 information structure to a payload/program/kernel.
-/// Better not confuse this with the Multiboot2 header tags. They are something different.
+/// Common base structure for all tags that can be passed via the Multiboot2 information structure
+/// (MBI) to a Multiboot2 payload/program/kernel.
+///
+/// Do not confuse them with the Multiboot2 header tags. They are something different.
 #[derive(Clone, Copy)]
 #[repr(C)]
 pub struct Tag {
-    // u32 value
-    pub typ: TagType,
+    pub typ: SpecifiedOrCustomTagTypeSerialized, // u32
     pub size: u32,
-    // tag specific fields
+    // additional, tag specific fields
 }
 
 impl Tag {
@@ -365,11 +366,18 @@ impl Tag {
 
 impl Debug for Tag {
     fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
-        f.debug_struct("Tag")
-            .field("typ", &self.typ)
-            .field("typ (numeric)", &(self.typ as u32))
-            .field("size", &(self.size))
-            .finish()
+        let tag_type = SpecifiedOrCustomTagType::from(self.typ);
+
+        let mut debug = f.debug_struct("Tag");
+        debug.field("typ", &tag_type);
+
+        if matches!(tag_type, SpecifiedOrCustomTagType::Specified(_)) {
+            debug.field("typ (numeric)", &(u32::from(self.typ)));
+        }
+
+        debug.field("size", &(self.size));
+
+        debug.finish()
     }
 }
 
@@ -394,7 +402,8 @@ impl<'a> Iterator for TagIter<'a> {
     fn next(&mut self) -> Option<&'a Tag> {
         match unsafe { &*self.current } {
             &Tag {
-                typ: TagType::End,
+                // END-Tag
+                typ: SpecifiedOrCustomTagTypeSerialized(0),
                 size: 8,
             } => None, // end tag
             tag => {