add SpecifiedOrCustomTagType[Serialized] abstraction

Author: phip1611

multiboot2/src/tag_type.rs

@@ -1,10 +1,49 @@
-//! Module for [`TagType`].
+//! Module for the basic Multiboot2 tag and corresponding tag types.
+//!
+//! In serialized form, each [`Tag`] has a `typ` field of type [`SpecifiedOrCustomTagTypeSerialized`].
+//! This is ABI-compatible with an `u32` value. From this type, you can construct
+//! [`SpecifiedOrCustomTagType`] that contains the variants [`SpecifiedOrCustomTagType::Specified`]
+//! and [`SpecifiedOrCustomTagType::Custom`]. This type is NOT ABI-compatible with u32. However,
+//! the payload of the two variants, either [`TagType`] or `u32`, is.
 
+use core::convert::TryFrom;
 use core::fmt::{Debug, Formatter};
 use core::hash::Hash;
 use core::marker::PhantomData;
 
-/// Possible types of a Tag in the Multiboot2 Information Structure (MBI), therefore the value
+/// Serialized version of [`SpecifiedOrCustomTagType`]. Values `0`..[`TagType::MAX_INDEX`] belong to
+/// [`SpecifiedOrCustomTagType::Specified`]. All others are mapped to
+/// [`SpecifiedOrCustomTagType::Custom`].
+///
+/// A `SpecifiedOrCustomTagSerialized` can be constructed from [`u32`].
+#[derive(Copy, Clone, Debug, Eq, Ord, PartialOrd, PartialEq, Hash)]
+#[repr(transparent)]
+pub struct SpecifiedOrCustomTagTypeSerialized(u32);
+
+/// Abstraction over Multiboot2 tag types that are either specified or custom.
+///
+/// The Multiboot2 spec doesn't disallow custom Multiboot2 tags.
+///
+/// A `SpecifiedOrCustomTagType` can be constructed from [`SpecifiedOrCustomTagSerialized`].
+#[derive(Copy, Clone, Eq, Ord, PartialOrd, PartialEq, Hash)]
+pub enum SpecifiedOrCustomTagType {
+    /// Specified tags, see [`TagType`].
+    Specified(TagType),
+    /// Custom tags. The value is bigger than the maximum value of [`TagType`].
+    /// The inner value can never conflict with [`TagType`].
+    Custom(u32),
+}
+
+impl Debug for SpecifiedOrCustomTagType {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        match self {
+            SpecifiedOrCustomTagType::Specified(tag_type) => <TagType as Debug>::fmt(tag_type, f),
+            SpecifiedOrCustomTagType::Custom(custom) => write!(f, "Custom({custom:#x})"),
+        }
+    }
+}
+
+/// Specified types of a Tag in the Multiboot2 Information Structure (MBI), therefore the value
 /// of the the `typ` property. The names and values are taken from the example C code
 /// at the bottom of the Multiboot2 specification.
 #[repr(u32)]
@@ -86,23 +125,226 @@ pub enum TagType {
     /// This tag contains image load base physical address. The spec tells
     /// "It is provided only if image has relocatable header tag." but experience showed
     /// that this is not true for at least GRUB 2.
-    LoadBaseAddr = 21,
+    LoadBaseAddr = TagType::MAX_INDEX,
+}
+
+/// `From`-implementations for conversions between `u32` and tag type abstractions.
+///
+/// There is a bijection for all conversions between `u32`, [`SpecifiedOrCustomTagTypeSerialized`],
+/// and [`SpecifiedOrCustomTagType`].
+mod primitive_conversion_impls {
+    use super::*;
+
+    impl From<u32> for SpecifiedOrCustomTagTypeSerialized {
+        fn from(value: u32) -> Self {
+            // SAFETY: the type has repr(transparent)
+            unsafe { core::mem::transmute(value) }
+        }
+    }
+
+    impl From<SpecifiedOrCustomTagTypeSerialized> for u32 {
+        fn from(value: SpecifiedOrCustomTagTypeSerialized) -> Self {
+            value.0 as _
+        }
+    }
+
+    impl From<u32> for SpecifiedOrCustomTagType {
+        fn from(value: u32) -> Self {
+            let value = SpecifiedOrCustomTagTypeSerialized::from(value);
+            SpecifiedOrCustomTagType::from(value)
+        }
+    }
+
+    impl From<SpecifiedOrCustomTagType> for u32 {
+        fn from(value: SpecifiedOrCustomTagType) -> Self {
+            match value {
+                SpecifiedOrCustomTagType::Specified(tag_type) => u32::from(tag_type),
+                SpecifiedOrCustomTagType::Custom(custom) => custom,
+            }
+        }
+    }
+
+    impl From<u32> for TagType {
+        fn from(value: u32) -> Self {
+            // SAFETY: safe as TagType has repr(u32)
+            unsafe { core::mem::transmute(value) }
+        }
+    }
+
+    impl From<TagType> for u32 {
+        fn from(value: TagType) -> Self {
+            value as _
+        }
+    }
 }
 
-// each compare/equal direction must be implemented manually
-impl PartialEq<u32> for TagType {
-    fn eq(&self, other: &u32) -> bool {
-        *self as u32 == *other
+/// `From`-implementations for all sensible conversions between
+/// [`SpecifiedOrCustomTagTypeSerialized`], [`SpecifiedOrCustomTagType`], and [`TagType`].
+///
+/// - [`SpecifiedOrCustomTagType`] can be constructed from [`SpecifiedOrCustomTagTypeSerialized`]
+///   and [`TagType`]
+/// - [`SpecifiedOrCustomTagTypeSerialized`] can be constructed from [`SpecifiedOrCustomTagType`]
+///   and [`TagType`]
+/// - [`TagType`] can be constructed from [`SpecifiedOrCustomTagType`] via a `TryFrom`
+///   implementation.
+mod intermediate_conversion_impls {
+    use super::*;
+
+    impl From<TagType> for SpecifiedOrCustomTagTypeSerialized {
+        fn from(value: TagType) -> Self {
+            let value = u32::from(value);
+            value.into()
+        }
+    }
+
+    impl From<TagType> for SpecifiedOrCustomTagType {
+        fn from(value: TagType) -> Self {
+            Self::Specified(value)
+        }
+    }
+
+    impl From<SpecifiedOrCustomTagType> for SpecifiedOrCustomTagTypeSerialized {
+        fn from(value: SpecifiedOrCustomTagType) -> Self {
+            let value = match value {
+                SpecifiedOrCustomTagType::Specified(tag) => u32::from(tag),
+                SpecifiedOrCustomTagType::Custom(custom) => custom,
+            };
+            value.into()
+        }
+    }
+
+    impl TryFrom<SpecifiedOrCustomTagType> for TagType {
+        // todo add meaningful error type
+        type Error = ();
+
+        fn try_from(value: SpecifiedOrCustomTagType) -> Result<Self, Self::Error> {
+            match value {
+                SpecifiedOrCustomTagType::Specified(tag_type) => Ok(tag_type),
+                SpecifiedOrCustomTagType::Custom(_) => Err(()),
+            }
+        }
+    }
+
+    impl TryFrom<SpecifiedOrCustomTagTypeSerialized> for TagType {
+        // todo add meaningful error type
+        type Error = ();
+
+        fn try_from(value: SpecifiedOrCustomTagTypeSerialized) -> Result<Self, Self::Error> {
+            let value = u32::from(value);
+            let value = SpecifiedOrCustomTagType::from(value);
+            TagType::try_from(value)
+        }
+    }
+
+    impl From<SpecifiedOrCustomTagTypeSerialized> for SpecifiedOrCustomTagType {
+        fn from(value: SpecifiedOrCustomTagTypeSerialized) -> Self {
+            match value.0 {
+                value @ 0..=TagType::MAX_INDEX => Self::Specified(value.into()),
+                custom => Self::Custom(custom),
+            }
+        }
     }
 }
 
-// each compare/equal direction must be implemented manually
-impl PartialEq<TagType> for u32 {
-    fn eq(&self, other: &TagType) -> bool {
-        *self == *other as u32
+/// Implements `partial_eq` between all types ([`SpecifiedOrCustomTagTypeSerialized`],
+/// [`SpecifiedOrCustomTagType`], and [`TagType`]) for both directions. Two values equal if their
+/// `u32` representation is equal.
+mod partial_eq_impls {
+    use super::*;
+
+    impl PartialEq<u32> for TagType {
+        fn eq(&self, other: &u32) -> bool {
+            let this = u32::from(*self);
+            this == *other
+        }
+    }
+
+    // each compare/equal direction must be implemented manually
+    impl PartialEq<TagType> for u32 {
+        fn eq(&self, other: &TagType) -> bool {
+            other.eq(self)
+        }
+    }
+
+    impl PartialEq<u32> for SpecifiedOrCustomTagType {
+        fn eq(&self, other: &u32) -> bool {
+            let this = u32::from(*self);
+            this == *other
+        }
+    }
+
+    // each compare/equal direction must be implemented manually
+    impl PartialEq<SpecifiedOrCustomTagType> for u32 {
+        fn eq(&self, other: &SpecifiedOrCustomTagType) -> bool {
+            other.eq(self)
+        }
+    }
+
+    impl PartialEq<u32> for SpecifiedOrCustomTagTypeSerialized {
+        fn eq(&self, other: &u32) -> bool {
+            let this = u32::from(*self);
+            this == *other
+        }
+    }
+
+    // each compare/equal direction must be implemented manually
+    impl PartialEq<SpecifiedOrCustomTagTypeSerialized> for u32 {
+        fn eq(&self, other: &SpecifiedOrCustomTagTypeSerialized) -> bool {
+            other.eq(self)
+        }
+    }
+
+    impl PartialEq<SpecifiedOrCustomTagTypeSerialized> for SpecifiedOrCustomTagType {
+        fn eq(&self, other: &SpecifiedOrCustomTagTypeSerialized) -> bool {
+            let this = u32::from(*self);
+            let that = u32::from(*other);
+            this == that
+        }
+    }
+
+    // each compare/equal direction must be implemented manually
+    impl PartialEq<SpecifiedOrCustomTagType> for SpecifiedOrCustomTagTypeSerialized {
+        fn eq(&self, other: &SpecifiedOrCustomTagType) -> bool {
+            other.eq(self)
+        }
+    }
+
+    impl PartialEq<SpecifiedOrCustomTagTypeSerialized> for TagType {
+        fn eq(&self, other: &SpecifiedOrCustomTagTypeSerialized) -> bool {
+            let this = u32::from(*self);
+            let that = u32::from(*other);
+            this == that
+        }
+    }
+
+    // each compare/equal direction must be implemented manually
+    impl PartialEq<TagType> for SpecifiedOrCustomTagTypeSerialized {
+        fn eq(&self, other: &TagType) -> bool {
+            other.eq(self)
+        }
+    }
+
+    impl PartialEq<SpecifiedOrCustomTagType> for TagType {
+        fn eq(&self, other: &SpecifiedOrCustomTagType) -> bool {
+            let this = u32::from(*self);
+            let other = u32::from(*other);
+            this == other
+        }
+    }
+
+    // each compare/equal direction must be implemented manually
+    impl PartialEq<TagType> for SpecifiedOrCustomTagType {
+        fn eq(&self, other: &TagType) -> bool {
+            other.eq(self)
+        }
     }
 }
 
+impl TagType {
+    /// The maximum index of specified Multiboot2 tag types.
+    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.
 #[derive(Clone, Copy)]
@@ -170,6 +412,7 @@ impl<'a> Iterator for TagIter<'a> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::mem::{align_of, size_of};
 
     #[test]
     fn test_hashset() {
@@ -203,5 +446,44 @@ mod tests {
     fn test_partial_eq_u32() {
         assert_eq!(21, TagType::LoadBaseAddr);
         assert_eq!(TagType::LoadBaseAddr, 21);
+        assert_eq!(21, SpecifiedOrCustomTagTypeSerialized(21));
+        assert_eq!(SpecifiedOrCustomTagTypeSerialized(21), 21);
+        assert_eq!(42, SpecifiedOrCustomTagType::Custom(42));
+        assert_eq!(SpecifiedOrCustomTagType::Custom(42), 42);
+        assert_eq!(
+            TagType::LoadBaseAddr,
+            SpecifiedOrCustomTagType::Specified(TagType::LoadBaseAddr)
+        );
+        assert_eq!(
+            SpecifiedOrCustomTagType::Specified(TagType::LoadBaseAddr),
+            TagType::LoadBaseAddr
+        );
+    }
+
+    /// Tests the construction of [`SpecifiedOrCustomTagType`] from primitive `u32` values.
+    #[test]
+    #[allow(non_snake_case)]
+    fn test_SpecifiedOrCustomTag() {
+        assert_eq!(
+            size_of::<SpecifiedOrCustomTagTypeSerialized>(),
+            size_of::<u32>()
+        );
+        assert_eq!(
+            align_of::<SpecifiedOrCustomTagTypeSerialized>(),
+            align_of::<u32>()
+        );
+
+        let tag_cmdline: u32 = TagType::Cmdline.into();
+        let tag_cmdline: SpecifiedOrCustomTagTypeSerialized = tag_cmdline.into();
+        let tag_cmdline: SpecifiedOrCustomTagType = tag_cmdline.into();
+        matches!(
+            tag_cmdline,
+            SpecifiedOrCustomTagType::Specified(TagType::Cmdline)
+        );
+
+        let tag_custom: u32 = 0x1337;
+        let tag_custom: SpecifiedOrCustomTagTypeSerialized = tag_custom.into();
+        let tag_custom: SpecifiedOrCustomTagType = tag_custom.into();
+        matches!(tag_custom, SpecifiedOrCustomTagType::Custom(0x1337));
     }
 }