Merge pull request #164 from rust-osdev/foobar

multiboot2: API refactorings and simplifications: Make TagTrait more useful

Author: phip1611

Cargo.lock

@@ -16,10 +16,10 @@ What this library is not optimal for:
 - compiling a Multiboot2 header statically into an object file using only Rust code
 
 ## Features and `no_std` Compatibility
-This library is always `no_std`. However, the default `builder`-feature requires
-the `alloc`-crate to be available. You need the `builder` only if you want to
-construct new headers at run time. For parsing, this is not relevant, and you
-can deactivate the default feature.
+This library is always `no_std` without `alloc`. However, the default `builder`-
+feature requires the `alloc`-crate and an `#[global_allocator]` to be available.
+You need the `builder` only if you want to construct new headers at runtime.
+For parsing, this is not relevant, and you can deactivate the default feature.
 
 ```toml
 # without `builder`-feature (and without `alloc`-crate)

integration-test/bins/Cargo.lock

@@ -1,5 +1,15 @@
 # CHANGELOG for crate `multiboot2`
 
+## 0.18.0 (2023-xx-xx)
+- **BREAKING** The `TagTrait` was enhanced and now has an associated `ID`
+  constant. This is only breaking to users that used `BootInformation::get_tag`
+  or that implement custom tags. `BootInformation::get_tag` doesn't need the
+  `typ` parameter anymore, as it can be deduced from the provided type.
+- **BREAKING** `BoxedDst::new` doesn't have the `typ` parameter anymore. This
+  only effects you when you wrote a custom DST tag.
+- **BREAKING** Removed deprecated functions `load` and `load_with_offset`. Use
+  `BootInformation::load` instead.
+
 ## 0.17.0 (2023-07-12)
 - **BREAKING** Make functions of `InformationBuilder` chainable. They now consume the builder.
 - **BREAKING** Allow non-standard memory area types by using new pair of

multiboot2-header/README.md

@@ -11,10 +11,11 @@ is `no_std` and can be used in a Multiboot2-kernel.
 It follows the Multiboot 2.0 specification at https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html and the ELF 64 specification at http://www.uclibc.org/docs/elf-64-gen.pdf.
 
 ## Features and `no_std` Compatibility
-This library is always `no_std`. However, the default `builder`-feature requires
-the `alloc`-crate to be available. You need the `builder` only if you want to
-construct new boot information structures at run time. For parsing, this is not
-relevant, and you can deactivate the default feature.
+This library is always `no_std` without `alloc`. However, the default `builder`-
+feature requires the `alloc`-crate and an `#[global_allocator]` to be available.
+You need the `builder` only if you want to construct new boot information
+structures at runtime. For parsing, this is not relevant, and you can
+deactivate the default feature.
 
 ## Background: The Multiboot 2 Information Structure
 The Multiboot information structure looks like this:

multiboot2/Changelog.md

@@ -1,13 +1,9 @@
-use crate::{Tag, TagTrait, TagTypeId};
+use crate::{Tag, TagTrait, TagType, TagTypeId};
 use core::fmt::{Debug, Formatter};
 use core::mem::size_of;
 use core::str::Utf8Error;
-
 #[cfg(feature = "builder")]
-use {
-    crate::builder::traits::StructAsBytes, crate::builder::BoxedDst, crate::TagType,
-    alloc::vec::Vec,
-};
+use {crate::builder::BoxedDst, alloc::vec::Vec};
 
 const METADATA_SIZE: usize = size_of::<TagTypeId>() + size_of::<u32>();
 
@@ -29,7 +25,7 @@ impl BootLoaderNameTag {
             // terminating null-byte
             bytes.push(0);
         }
-        BoxedDst::new(TagType::BootLoaderName, &bytes)
+        BoxedDst::new(&bytes)
     }
 
     /// Reads the name of the bootloader that is booting the kernel as Rust
@@ -42,7 +38,9 @@ impl BootLoaderNameTag {
     /// # Examples
     ///
     /// ```rust,no_run
-    /// # let boot_info = unsafe { multiboot2::load(0xdeadbeef).unwrap() };
+    /// # use multiboot2::{BootInformation, BootInformationHeader};
+    /// # let ptr = 0xdeadbeef as *const BootInformationHeader;
+    /// # let boot_info = unsafe { BootInformation::load(ptr).unwrap() };
     /// if let Some(tag) = boot_info.boot_loader_name_tag() {
     ///     assert_eq!(Ok("GRUB 2.02~beta3-5"), tag.name());
     /// }
@@ -63,22 +61,17 @@ impl Debug for BootLoaderNameTag {
 }
 
 impl TagTrait for BootLoaderNameTag {
+    const ID: TagType = TagType::BootLoaderName;
+
     fn dst_size(base_tag: &Tag) -> usize {
         assert!(base_tag.size as usize >= METADATA_SIZE);
         base_tag.size as usize - METADATA_SIZE
     }
 }
 
-#[cfg(feature = "builder")]
-impl StructAsBytes for BootLoaderNameTag {
-    fn byte_size(&self) -> usize {
-        self.size.try_into().unwrap()
-    }
-}
-
 #[cfg(test)]
 mod tests {
-    use crate::{BootLoaderNameTag, Tag, TagType};
+    use crate::{BootLoaderNameTag, Tag, TagTrait, TagType};
 
     const MSG: &str = "hello";
 
@@ -114,10 +107,8 @@ mod tests {
     #[test]
     #[cfg(feature = "builder")]
     fn test_build_str() {
-        use crate::builder::traits::StructAsBytes;
-
         let tag = BootLoaderNameTag::new(MSG);
-        let bytes = tag.struct_as_bytes();
+        let bytes = tag.as_bytes();
         assert_eq!(bytes, get_bytes());
         assert_eq!(tag.name(), Ok(MSG));