multiboot2: split TagType into TagType and TagTypeId

This change allows to get custom tag types.

Author: phip1611

multiboot2/Changelog.md

@@ -1,15 +1,24 @@
 # CHANGELOG for crate `multiboot2`
 
-## Unreleased
+## 0.15.0 (2023-03-XX)
 - MSRV is 1.56.1
-- **BREAKING** fixed lifetime issues: `VBEInfoTag` is no longer static
+- **BREAKING** fixed lifetime issues: `VBEInfoTag` is no longer `&static`
+- **BREAKING:** `TagType` is now split into `TagTypeId` and `TagType`
+  - `TagTypeId` is a binary-compatible form of a Multiboot2 tag id
+  - `TagType` is a higher-level abstraction for either specified or custom tags
+      but not ABI compatible.
 - fixed another internal lifetime issue
 - `BootInformation::framebuffer_tag()` now returns
   `Option<Result<FramebufferTag, UnknownFramebufferType>>` instead of
   `Option<FramebufferTag>` which prevents a possible panic. If the `--unstable`
   feature is used, `UnknownFramebufferType` implements `core::error::Error`.
 - Fixed misleading documentation of the `BootInformation::efi_memory_map_tag`
-  tag.
+- `BootInformation` now publicly exports the `get_tag` function allowing you to
+  work with custom tags. An example is given in the function documentation.
+  (check docs.rs). There is also a small unit test that you can use to learn
+  from.
+- There exists a seamless integration between `u32`, `TagType`, and `TagTypeId`
+  via `From` and `PartialEq`-implementations.
 
 ## 0.14.2 (2023-03-17)
 - documentation fixes

multiboot2/src/boot_loader_name.rs

@@ -1,4 +1,4 @@
-use crate::TagType;
+use crate::TagTypeId;
 use core::str::Utf8Error;
 
 /// This tag contains the name of the bootloader that is booting the kernel.
@@ -8,7 +8,7 @@ use core::str::Utf8Error;
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)] // only repr(C) would add unwanted padding before first_section
 pub struct BootLoaderNameTag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     /// Null-terminated UTF-8 string
     string: u8,
@@ -47,7 +47,7 @@ mod tests {
         // size is: 4 bytes for tag + 4 bytes for size + length of null-terminated string
         let size = (4 + 4 + MSG.as_bytes().len() + 1) as u32;
         [
-            &((TagType::BootLoaderName as u32).to_ne_bytes()),
+            &((TagType::BootLoaderName.val()).to_ne_bytes()),
             &size.to_ne_bytes(),
             MSG.as_bytes(),
             // Null Byte

multiboot2/src/command_line.rs

@@ -1,6 +1,6 @@
 //! Module for [CommandLineTag].
 
-use crate::TagType;
+use crate::TagTypeId;
 use core::mem;
 use core::slice;
 use core::str;
@@ -12,7 +12,7 @@ use core::str;
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)] // only repr(C) would add unwanted padding before first_section
 pub struct CommandLineTag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     /// Null-terminated UTF-8 string
     string: u8,
@@ -51,7 +51,7 @@ mod tests {
         // size is: 4 bytes for tag + 4 bytes for size + length of null-terminated string
         let size = (4 + 4 + MSG.as_bytes().len() + 1) as u32;
         [
-            &((TagType::Cmdline as u32).to_ne_bytes()),
+            &((TagType::Cmdline.val()).to_ne_bytes()),
             &size.to_ne_bytes(),
             MSG.as_bytes(),
             // Null Byte

multiboot2/src/efi.rs

@@ -1,12 +1,12 @@
 //! All MBI tags related to (U)EFI.
 
-use crate::TagType;
+use crate::TagTypeId;
 
 /// EFI system table in 32 bit mode
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)] // only repr(C) would add unwanted padding before first_section
 pub struct EFISdt32 {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     pointer: u32,
 }
@@ -22,7 +22,7 @@ impl EFISdt32 {
 #[derive(Clone, Copy, Debug)]
 #[repr(C)]
 pub struct EFISdt64 {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     pointer: u64,
 }
@@ -38,7 +38,7 @@ impl EFISdt64 {
 #[derive(Debug)]
 #[repr(C)]
 pub struct EFIImageHandle32 {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     pointer: u32,
 }
@@ -54,7 +54,7 @@ impl EFIImageHandle32 {
 #[derive(Debug)]
 #[repr(C)]
 pub struct EFIImageHandle64 {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     pointer: u64,
 }

multiboot2/src/elf_sections.rs

@@ -1,4 +1,5 @@
 use crate::tag_type::Tag;
+use crate::TagType;
 use core::fmt::{Debug, Formatter};
 
 /// This tag contains section header table from an ELF kernel.
@@ -11,7 +12,7 @@ pub struct ElfSectionsTag {
 }
 
 pub unsafe fn elf_sections_tag(tag: &Tag, offset: usize) -> ElfSectionsTag {
-    assert_eq!(9, tag.typ);
+    assert_eq!(TagType::ElfSections.val(), tag.typ);
     let es = ElfSectionsTag {
         inner: (tag as *const Tag).offset(1) as *const ElfSectionsTagInner,
         offset,

multiboot2/src/image_load_addr.rs

@@ -1,11 +1,11 @@
-use crate::TagType;
+use crate::TagTypeId;
 
 /// If the image has relocatable header tag, this tag contains the image's
 /// base physical address.
 #[derive(Debug)]
 #[repr(C)]
 pub struct ImageLoadPhysAddr {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     load_base_addr: u32,
 }

multiboot2/src/lib.rs

@@ -55,8 +55,8 @@ 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, TagType, TagTypeId};
+use tag_type::TagIter;
 pub use vbe_info::{
     VBECapabilities, VBEControlInfo, VBEDirectColorAttributes, VBEField, VBEInfoTag,
     VBEMemoryModel, VBEModeAttributes, VBEModeInfo, VBEWindowAttributes,
@@ -330,16 +330,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
     }
 }
 

multiboot2/src/memory_map.rs

@@ -1,4 +1,4 @@
-use crate::TagType;
+use crate::TagTypeId;
 use core::marker::PhantomData;
 
 /// This tag provides an initial host memory map.
@@ -14,7 +14,7 @@ use core::marker::PhantomData;
 #[derive(Debug)]
 #[repr(C)]
 pub struct MemoryMapTag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     entry_size: u32,
     entry_version: u32,
@@ -126,7 +126,7 @@ impl<'a> Iterator for MemoryAreaIter<'a> {
 #[derive(Debug)]
 #[repr(C)]
 pub struct EFIMemoryMapTag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     desc_size: u32,
     desc_version: u32,

multiboot2/src/module.rs

@@ -1,4 +1,5 @@
 use crate::tag_type::{Tag, TagIter, TagType};
+use crate::TagTypeId;
 use core::fmt::{Debug, Formatter};
 use core::str::Utf8Error;
 
@@ -7,7 +8,7 @@ use core::str::Utf8Error;
 #[derive(Clone, Copy)]
 #[repr(C, packed)] // only repr(C) would add unwanted padding near name_byte.
 pub struct ModuleTag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     mod_start: u32,
     mod_end: u32,
@@ -102,7 +103,7 @@ mod tests {
         //          4 bytes mod_start + 4 bytes mod_end
         let size = (4 + 4 + 4 + 4 + MSG.as_bytes().len() + 1) as u32;
         [
-            &((TagType::Module as u32).to_ne_bytes()),
+            &((TagType::Module.val()).to_ne_bytes()),
             &size.to_ne_bytes(),
             &0_u32.to_ne_bytes(),
             &0_u32.to_ne_bytes(),

multiboot2/src/rsdp.rs

@@ -8,7 +8,7 @@
 //!
 //! Even though the bootloader should give the address of the real RSDP/XSDT, the checksum and
 //! signature should be manually verified.
-use crate::TagType;
+use crate::TagTypeId;
 use core::slice;
 use core::str;
 use core::str::Utf8Error;
@@ -19,7 +19,7 @@ const RSDPV1_LENGTH: usize = 20;
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)]
 pub struct RsdpV1Tag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     signature: [u8; 8],
     checksum: u8,
@@ -66,7 +66,7 @@ impl RsdpV1Tag {
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)]
 pub struct RsdpV2Tag {
-    typ: TagType,
+    typ: TagTypeId,
     size: u32,
     signature: [u8; 8],
     checksum: u8,