multiboot2-header: code improvements

Author: phip1611

multiboot2-header/README.md

@@ -15,10 +15,10 @@ What this library is good for:
 What this library is not optimal for:
 - compiling a Multiboot2 header statically into an object file using only Rust code
 
-## Example
+## Example 1: Builder + Parse
 ```rust
 use multiboot2_header::builder::Multiboot2HeaderBuilder;
-use multiboot2_header::{ConsoleHeaderTag, HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType, Multiboot2Header, RelocatableHeaderTag, RelocatableHeaderTagPreference, load_mb2_header};
+use multiboot2_header::{HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType, RelocatableHeaderTag, RelocatableHeaderTagPreference, Multiboot2Header};
 
 /// Small example that creates a Multiboot2 header and parses it afterwards.
 fn main() {
@@ -39,11 +39,21 @@ fn main() {
         .build();
 
     // Cast bytes in vector to Multiboot2 information structure
-    let mb2_hdr = unsafe { load_mb2_header(mb2_hdr_bytes.as_ptr() as usize) };
+    let mb2_hdr = unsafe { Multiboot2Header::from_addr(mb2_hdr_bytes.as_ptr() as usize) };
     println!("{:#?}", mb2_hdr);
 }
+```
 
+## Example 2: Multiboot2 header as static data in Rust file
+You can use the builder, construct a Multiboot2 header, write it to a file and include it like this:
+```
+#[used]
+#[no_mangle]
+#[link_section = ".text.multiboot2_header"]
+static MULTIBOOT2_HDR: &[u8; 64] = include_bytes!("mb2_hdr_dump.bin");
 ```
+You may need a special linker script to place this in a LOAD segment with a file offset with less than 32768 bytes.
+See specification.
 
 ## License & Contribution
 

multiboot2-header/examples/minimal.rs

@@ -1,5 +1,8 @@
 use multiboot2_header::builder::Multiboot2HeaderBuilder;
-use multiboot2_header::{ConsoleHeaderTag, HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType, Multiboot2Header, RelocatableHeaderTag, RelocatableHeaderTagPreference, load_mb2_header};
+use multiboot2_header::{
+    HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType, Multiboot2Header,
+    RelocatableHeaderTag, RelocatableHeaderTagPreference,
+};
 
 /// Small example that creates a Multiboot2 header and parses it afterwards.
 fn main() {
@@ -20,6 +23,6 @@ fn main() {
         .build();
 
     // Cast bytes in vector to Multiboot2 information structure
-    let mb2_hdr = unsafe { load_mb2_header(mb2_hdr_bytes.as_ptr() as usize) };
+    let mb2_hdr = unsafe { Multiboot2Header::from_addr(mb2_hdr_bytes.as_ptr() as usize) };
     println!("{:#?}", mb2_hdr);
 }

multiboot2-header/src/address.rs

@@ -42,25 +42,25 @@ impl AddressHeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
-    pub fn header_addr(&self) -> u32 {
+    pub const fn header_addr(&self) -> u32 {
         self.header_addr
     }
-    pub fn load_addr(&self) -> u32 {
+    pub const fn load_addr(&self) -> u32 {
         self.load_addr
     }
-    pub fn load_end_addr(&self) -> u32 {
+    pub const fn load_end_addr(&self) -> u32 {
         self.load_end_addr
     }
-    pub fn bss_end_addr(&self) -> u32 {
+    pub const fn bss_end_addr(&self) -> u32 {
         self.bss_end_addr
     }
 }

multiboot2-header/src/console.rs

@@ -1,6 +1,7 @@
 use crate::{HeaderTagFlag, HeaderTagType, StructAsBytes};
 use core::mem::size_of;
 
+/// Possible flags for [`ConsoleHeaderTag`].
 #[repr(u32)]
 #[derive(Copy, Clone, Debug)]
 pub enum ConsoleHeaderTagFlags {
@@ -31,16 +32,16 @@ impl ConsoleHeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
-    pub fn console_flags(&self) -> ConsoleHeaderTagFlags {
+    pub const fn console_flags(&self) -> ConsoleHeaderTagFlags {
         self.console_flags
     }
 }

multiboot2-header/src/end.rs

@@ -2,7 +2,7 @@ use crate::{HeaderTagFlag, HeaderTagType, StructAsBytes};
 use core::mem::size_of;
 
 /// Terminates a list of optional tags
-/// in a multiboot2 header.
+/// in a Multiboot2 header.
 #[derive(Copy, Clone, Debug)]
 #[repr(C, packed(8))]
 pub struct EndHeaderTag {
@@ -22,13 +22,13 @@ impl EndHeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
 }

multiboot2-header/src/entry_efi_32.rs

@@ -25,16 +25,16 @@ impl EntryEfi32HeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
-    pub fn entry_addr(&self) -> u32 {
+    pub const fn entry_addr(&self) -> u32 {
         self.entry_addr
     }
 }

multiboot2-header/src/entry_efi_64.rs

@@ -25,16 +25,16 @@ impl EntryEfi64HeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
-    pub fn entry_addr(&self) -> u32 {
+    pub const fn entry_addr(&self) -> u32 {
         self.entry_addr
     }
 }

multiboot2-header/src/entry_header.rs

@@ -25,16 +25,16 @@ impl EntryHeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
-    pub fn entry_addr(&self) -> u32 {
+    pub const fn entry_addr(&self) -> u32 {
         self.entry_addr
     }
 }

multiboot2-header/src/framebuffer.rs

@@ -28,22 +28,22 @@ impl FramebufferHeaderTag {
         }
     }
 
-    pub fn typ(&self) -> HeaderTagType {
+    pub const fn typ(&self) -> HeaderTagType {
         self.typ
     }
-    pub fn flags(&self) -> HeaderTagFlag {
+    pub const fn flags(&self) -> HeaderTagFlag {
         self.flags
     }
-    pub fn size(&self) -> u32 {
+    pub const fn size(&self) -> u32 {
         self.size
     }
-    pub fn width(&self) -> u32 {
+    pub const fn width(&self) -> u32 {
         self.width
     }
-    pub fn height(&self) -> u32 {
+    pub const fn height(&self) -> u32 {
         self.height
     }
-    pub fn depth(&self) -> u32 {
+    pub const fn depth(&self) -> u32 {
         self.depth
     }
 }

multiboot2-header/src/header/builder.rs

@@ -1,8 +1,10 @@
+//! Exports item [`Multiboot2HeaderBuilder`].
+
 use crate::HeaderTagISA;
 use crate::{
     AddressHeaderTag, ConsoleHeaderTag, EfiBootServiceHeaderTag, EndHeaderTag, EntryEfi32HeaderTag,
     EntryEfi64HeaderTag, EntryHeaderTag, FramebufferHeaderTag, InformationRequestHeaderTagBuilder,
-    ModuleAlignHeaderTag, Multiboot2HeaderInner, RelocatableHeaderTag, StructAsBytes,
+    ModuleAlignHeaderTag, Multiboot2BasicHeader, RelocatableHeaderTag, StructAsBytes,
 };
 use core::mem::size_of;
 
@@ -64,10 +66,10 @@ impl Multiboot2HeaderBuilder {
         }
     }
 
-    /// Returns the expected length of the multiboot2 header,
-    /// when the [`build`]-method gets called.
+    /// Returns the expected length of the Multiboot2 header,
+    /// when the `build()`-method gets called.
     pub fn expected_len(&self) -> usize {
-        let base_len = size_of::<Multiboot2HeaderInner>();
+        let base_len = size_of::<Multiboot2BasicHeader>();
         // size_or_up_aligned not required, because basic header length is 16 and the
         // begin is 8 byte aligned => first tag automatically 8 byte aligned
         let mut len = Self::size_or_up_aligned(base_len);
@@ -109,9 +111,9 @@ impl Multiboot2HeaderBuilder {
         len
     }
 
-    /// Adds the bytes of a tag to the final multiboot2 header byte vector.
+    /// Adds the bytes of a tag to the final Multiboot2 header byte vector.
     /// Align should be true for all tags except the end tag.
-    fn build_add_bytes(dest: &mut Vec<u8>, source: &Vec<u8>, is_end_tag: bool) {
+    fn build_add_bytes(dest: &mut Vec<u8>, source: &[u8], is_end_tag: bool) {
         dest.extend(source);
         if !is_end_tag {
             let size = source.len();
@@ -130,7 +132,7 @@ impl Multiboot2HeaderBuilder {
         Self::build_add_bytes(
             &mut data,
             // important that we write the correct expected length into the header!
-            &Multiboot2HeaderInner::new(self.arch, self.expected_len() as u32).struct_as_bytes(),
+            &Multiboot2BasicHeader::new(self.arch, self.expected_len() as u32).struct_as_bytes(),
             false,
         );
 
@@ -174,46 +176,48 @@ impl Multiboot2HeaderBuilder {
         data
     }
 
+    // clippy thinks this can be a const fn but the compiler denies it
+    #[allow(clippy::missing_const_for_fn)]
     pub fn information_request_tag(
         mut self,
         information_request_tag: InformationRequestHeaderTagBuilder,
     ) -> Self {
         self.information_request_tag = Some(information_request_tag);
         self
     }
-    pub fn address_tag(mut self, address_tag: AddressHeaderTag) -> Self {
+    pub const fn address_tag(mut self, address_tag: AddressHeaderTag) -> Self {
         self.address_tag = Some(address_tag);
         self
     }
-    pub fn entry_tag(mut self, entry_tag: EntryHeaderTag) -> Self {
+    pub const fn entry_tag(mut self, entry_tag: EntryHeaderTag) -> Self {
         self.entry_tag = Some(entry_tag);
         self
     }
-    pub fn console_tag(mut self, console_tag: ConsoleHeaderTag) -> Self {
+    pub const fn console_tag(mut self, console_tag: ConsoleHeaderTag) -> Self {
         self.console_tag = Some(console_tag);
         self
     }
-    pub fn framebuffer_tag(mut self, framebuffer_tag: FramebufferHeaderTag) -> Self {
+    pub const fn framebuffer_tag(mut self, framebuffer_tag: FramebufferHeaderTag) -> Self {
         self.framebuffer_tag = Some(framebuffer_tag);
         self
     }
-    pub fn module_align_tag(mut self, module_align_tag: ModuleAlignHeaderTag) -> Self {
+    pub const fn module_align_tag(mut self, module_align_tag: ModuleAlignHeaderTag) -> Self {
         self.module_align_tag = Some(module_align_tag);
         self
     }
-    pub fn efi_bs_tag(mut self, efi_bs_tag: EfiBootServiceHeaderTag) -> Self {
+    pub const fn efi_bs_tag(mut self, efi_bs_tag: EfiBootServiceHeaderTag) -> Self {
         self.efi_bs_tag = Some(efi_bs_tag);
         self
     }
-    pub fn efi_32_tag(mut self, efi_32_tag: EntryEfi32HeaderTag) -> Self {
+    pub const fn efi_32_tag(mut self, efi_32_tag: EntryEfi32HeaderTag) -> Self {
         self.efi_32_tag = Some(efi_32_tag);
         self
     }
-    pub fn efi_64_tag(mut self, efi_64_tag: EntryEfi64HeaderTag) -> Self {
+    pub const fn efi_64_tag(mut self, efi_64_tag: EntryEfi64HeaderTag) -> Self {
         self.efi_64_tag = Some(efi_64_tag);
         self
     }
-    pub fn relocatable_tag(mut self, relocatable_tag: RelocatableHeaderTag) -> Self {
+    pub const fn relocatable_tag(mut self, relocatable_tag: RelocatableHeaderTag) -> Self {
         self.relocatable_tag = Some(relocatable_tag);
         self
     }
@@ -222,8 +226,8 @@ impl Multiboot2HeaderBuilder {
 #[cfg(test)]
 mod tests {
     use crate::{
-        load_mb2_header, HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder,
-        MbiTagType, Multiboot2HeaderBuilder, RelocatableHeaderTag,
+        HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType,
+        Multiboot2Header, Multiboot2HeaderBuilder, RelocatableHeaderTag,
         RelocatableHeaderTagPreference,
     };
 
@@ -238,7 +242,7 @@ mod tests {
     #[test]
     fn test_size_builder() {
         let builder = Multiboot2HeaderBuilder::new(HeaderTagISA::I386);
-        // multiboot2 basic header + end tag
+        // Multiboot2 basic header + end tag
         let mut expected_len = 16 + 8;
         assert_eq!(builder.expected_len(), expected_len);
 
@@ -272,7 +276,7 @@ mod tests {
 
         let mb2_hdr_data = builder.build();
         let mb2_hdr = mb2_hdr_data.as_ptr() as usize;
-        let mb2_hdr = unsafe { load_mb2_header(mb2_hdr) };
+        let mb2_hdr = unsafe { Multiboot2Header::from_addr(mb2_hdr) };
         println!("{:#?}", mb2_hdr);
 
         /* you can write the binary to a file and a tool such as crate "bootinfo"