Merge pull request #95 from rust-osdev/multiboot2-header-crate

multiboot2-header crate - initial release

Author: phip1611

README.md

@@ -6,8 +6,9 @@ Please check their individual README-files ([multiboot2](multiboot2/README.md),
 
 The `multiboot2` crate helps to parse the Multiboot2 information structure
 (MBI) and is relevant in kernels, that get booted by a bootloader such as
-GRUB, for example. `multiboot2-header` is relevant, if you want to write a bootloader that provides a MBI to a payload for
-example.
+GRUB, for example. `multiboot2-header` helps you to either build
+Multiboot2-headers yourself, or to parse Multiboot2 headers in custom bootloader
+or similar applications.
 
 ## License
 

multiboot2-header/Cargo.toml

@@ -4,7 +4,7 @@ description = """
 Library with type definitions and parsing functions for Multiboot2 headers.
 This library is `no_std` and can be used in bootloaders.
 """
-version = "0.0.0"
+version = "0.1.0"
 authors = [
     "Philipp Schuster <[email protected]>"
 ]
@@ -28,3 +28,5 @@ repository = "https://github.com/rust-osdev/multiboot2"
 documentation = "https://docs.rs/multiboot2-header"
 
 [dependencies]
+# used for MBI tags
+multiboot2 = "0.12.2"

multiboot2-header/README.md

@@ -6,6 +6,55 @@
 Rust library with type definitions and parsing functions for Multiboot2 headers.
 This library is `no_std` and can be used in bootloaders.
 
+What this library is good for:
+- writing a small binary which writes you a valid Multiboot2 header
+  into a file (such as `header.bin`)
+- understanding Multiboot2 headers better
+- analyze Multiboot2 headers at runtime
+
+What this library is not optimal for:
+- compiling a Multiboot2 header statically into an object file using only Rust code
+
+## Example 1: Builder + Parse
+```rust
+use multiboot2_header::builder::Multiboot2HeaderBuilder;
+use multiboot2_header::{HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType, RelocatableHeaderTag, RelocatableHeaderTagPreference, Multiboot2Header};
+
+/// Small example that creates a Multiboot2 header and parses it afterwards.
+fn main() {
+    // We create a Multiboot2 header during runtime here. A practical example is that your
+    // program gets the header from a file and parses it afterwards.
+    let mb2_hdr_bytes = Multiboot2HeaderBuilder::new(HeaderTagISA::I386)
+        .relocatable_tag(RelocatableHeaderTag::new(
+            HeaderTagFlag::Required,
+            0x1337,
+            0xdeadbeef,
+            4096,
+            RelocatableHeaderTagPreference::None,
+        ))
+        .information_request_tag(
+            InformationRequestHeaderTagBuilder::new(HeaderTagFlag::Required)
+                .add_irs(&[MbiTagType::Cmdline, MbiTagType::BootLoaderName]),
+        )
+        .build();
+
+    // Cast bytes in vector to Multiboot2 information structure
+    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
 
 See main [README](https://github.com/rust-osdev/multiboot2/blob/main/README.md) file.

multiboot2-header/examples/minimal.rs

@@ -0,0 +1,28 @@
+use multiboot2_header::builder::Multiboot2HeaderBuilder;
+use multiboot2_header::{
+    HeaderTagFlag, HeaderTagISA, InformationRequestHeaderTagBuilder, MbiTagType, Multiboot2Header,
+    RelocatableHeaderTag, RelocatableHeaderTagPreference,
+};
+
+/// Small example that creates a Multiboot2 header and parses it afterwards.
+fn main() {
+    // We create a Multiboot2 header during runtime here. A practical example is that your
+    // program gets the header from a file and parses it afterwards.
+    let mb2_hdr_bytes = Multiboot2HeaderBuilder::new(HeaderTagISA::I386)
+        .relocatable_tag(RelocatableHeaderTag::new(
+            HeaderTagFlag::Required,
+            0x1337,
+            0xdeadbeef,
+            4096,
+            RelocatableHeaderTagPreference::None,
+        ))
+        .information_request_tag(
+            InformationRequestHeaderTagBuilder::new(HeaderTagFlag::Required)
+                .add_irs(&[MbiTagType::Cmdline, MbiTagType::BootLoaderName]),
+        )
+        .build();
+
+    // Cast bytes in vector to Multiboot2 information structure
+    let mb2_hdr = unsafe { Multiboot2Header::from_addr(mb2_hdr_bytes.as_ptr() as usize) };
+    println!("{:#?}", mb2_hdr);
+}

multiboot2-header/src/address.rs

@@ -0,0 +1,68 @@
+use crate::{HeaderTagFlag, HeaderTagType, StructAsBytes};
+use core::mem::size_of;
+
+/// This information does not need to be provided if the kernel image is in ELF
+/// format, but it must be provided if the image is in a.out format or in some
+/// other format. Required for legacy boot (BIOS).
+/// Determines load addresses.
+#[derive(Copy, Clone, Debug)]
+#[repr(C, packed(8))]
+pub struct AddressHeaderTag {
+    typ: HeaderTagType,
+    flags: HeaderTagFlag,
+    size: u32,
+    /// Contains the address corresponding to the beginning of the Multiboot2 header — the physical memory location at which the magic value is supposed to be loaded. This field serves to synchronize the mapping between OS image offsets and physical memory addresses.
+    header_addr: u32,
+    /// Contains the physical address of the beginning of the text segment. The offset in the OS image file at which to start loading is defined by the offset at which the header was found, minus (header_addr - load_addr). load_addr must be less than or equal to header_addr.
+    ///
+    /// Special value -1 means that the file must be loaded from its beginning.
+    load_addr: u32,
+    /// Contains the physical address of the end of the data segment. (load_end_addr - load_addr) specifies how much data to load. This implies that the text and data segments must be consecutive in the OS image; this is true for existing a.out executable formats. If this field is zero, the boot loader assumes that the text and data segments occupy the whole OS image file.
+    load_end_addr: u32,
+    /// Contains the physical address of the end of the bss segment. The boot loader initializes this area to zero, and reserves the memory it occupies to avoid placing boot modules and other data relevant to the operating system in that area. If this field is zero, the boot loader assumes that no bss segment is present.
+    bss_end_addr: u32,
+}
+
+impl AddressHeaderTag {
+    pub const fn new(
+        flags: HeaderTagFlag,
+        header_addr: u32,
+        load_addr: u32,
+        load_end_addr: u32,
+        bss_end_addr: u32,
+    ) -> Self {
+        AddressHeaderTag {
+            typ: HeaderTagType::Address,
+            flags,
+            size: size_of::<Self>() as u32,
+            header_addr,
+            load_addr,
+            load_end_addr,
+            bss_end_addr,
+        }
+    }
+
+    pub const fn typ(&self) -> HeaderTagType {
+        self.typ
+    }
+    pub const fn flags(&self) -> HeaderTagFlag {
+        self.flags
+    }
+    pub const fn size(&self) -> u32 {
+        self.size
+    }
+    pub const fn header_addr(&self) -> u32 {
+        self.header_addr
+    }
+    pub const fn load_addr(&self) -> u32 {
+        self.load_addr
+    }
+    pub const fn load_end_addr(&self) -> u32 {
+        self.load_end_addr
+    }
+    pub const fn bss_end_addr(&self) -> u32 {
+        self.bss_end_addr
+    }
+}
+
+impl StructAsBytes for AddressHeaderTag {}

multiboot2-header/src/console.rs

@@ -0,0 +1,81 @@
+use crate::{HeaderTagFlag, HeaderTagType, StructAsBytes};
+use core::mem::size_of;
+
+/// Possible flags for [`ConsoleHeaderTag`].
+#[repr(u32)]
+#[derive(Copy, Clone, Debug)]
+pub enum ConsoleHeaderTagFlags {
+    /// Console required.
+    ConsoleRequired = 0,
+    /// EGA text support.
+    EgaTextSupported = 1,
+}
+
+/// Tells that a console must be available in MBI.
+/// Only relevant for legacy BIOS.
+#[derive(Copy, Clone, Debug)]
+#[repr(C, packed(8))]
+pub struct ConsoleHeaderTag {
+    typ: HeaderTagType,
+    flags: HeaderTagFlag,
+    size: u32,
+    console_flags: ConsoleHeaderTagFlags,
+}
+
+impl ConsoleHeaderTag {
+    pub const fn new(flags: HeaderTagFlag, console_flags: ConsoleHeaderTagFlags) -> Self {
+        ConsoleHeaderTag {
+            typ: HeaderTagType::ConsoleFlags,
+            flags,
+            size: size_of::<Self>() as u32,
+            console_flags,
+        }
+    }
+
+    pub const fn typ(&self) -> HeaderTagType {
+        self.typ
+    }
+    pub const fn flags(&self) -> HeaderTagFlag {
+        self.flags
+    }
+    pub const fn size(&self) -> u32 {
+        self.size
+    }
+    pub const fn console_flags(&self) -> ConsoleHeaderTagFlags {
+        self.console_flags
+    }
+}
+
+impl StructAsBytes for ConsoleHeaderTag {}
+
+#[cfg(test)]
+mod tests {
+    use crate::{ConsoleHeaderTag, ConsoleHeaderTagFlags, HeaderTagFlag, HeaderTagType};
+    use std::mem::size_of_val;
+
+    /// Checks if rust aligns the type correctly and still "pack" all properties.
+    /// This test is necessary, because Rust doesn't support "packed" together with "align()" yet.
+    /// It seems like "packed(N)" does the right thing tho.
+    ///
+    /// This test is representative for all header tags, because all use the "packed(8)" attribute.
+    #[test]
+    fn test_alignment_and_size() {
+        let tag = ConsoleHeaderTag::new(
+            HeaderTagFlag::Required,
+            ConsoleHeaderTagFlags::ConsoleRequired,
+        );
+        let ptr = get_ptr!(tag, ConsoleHeaderTag);
+        let is_aligned = ptr % 8 == 0;
+        assert!(is_aligned);
+        // 2x u16, 2x u32
+        assert_eq!(2 + 2 + 4 + 4, size_of_val(&tag));
+
+        assert_eq!(ptr + 0, get_field_ptr!(tag, typ, HeaderTagType));
+        assert_eq!(ptr + 2, get_field_ptr!(tag, flags, HeaderTagFlag));
+        assert_eq!(ptr + 4, get_field_ptr!(tag, size, u32));
+        assert_eq!(
+            ptr + 8,
+            get_field_ptr!(tag, console_flags, ConsoleHeaderTagFlags)
+        );
+    }
+}

multiboot2-header/src/end.rs

@@ -0,0 +1,36 @@
+use crate::{HeaderTagFlag, HeaderTagType, StructAsBytes};
+use core::mem::size_of;
+
+/// Terminates a list of optional tags
+/// in a Multiboot2 header.
+#[derive(Copy, Clone, Debug)]
+#[repr(C, packed(8))]
+pub struct EndHeaderTag {
+    // u16 value
+    typ: HeaderTagType,
+    // u16 value
+    flags: HeaderTagFlag,
+    size: u32,
+}
+
+impl EndHeaderTag {
+    pub const fn new() -> Self {
+        EndHeaderTag {
+            typ: HeaderTagType::End,
+            flags: HeaderTagFlag::Required,
+            size: size_of::<Self>() as u32,
+        }
+    }
+
+    pub const fn typ(&self) -> HeaderTagType {
+        self.typ
+    }
+    pub const fn flags(&self) -> HeaderTagFlag {
+        self.flags
+    }
+    pub const fn size(&self) -> u32 {
+        self.size
+    }
+}
+
+impl StructAsBytes for EndHeaderTag {}

multiboot2-header/src/entry_efi_32.rs

@@ -0,0 +1,53 @@
+use crate::{HeaderTagFlag, HeaderTagType, StructAsBytes};
+use core::fmt;
+use core::fmt::{Debug, Formatter};
+use core::mem::size_of;
+
+/// This tag is taken into account only on EFI i386 platforms when Multiboot2 image header
+/// contains EFI boot services tag. Then entry point specified in ELF header and the entry address
+/// tag of Multiboot2 header are ignored.
+#[derive(Copy, Clone)]
+#[repr(C, packed(8))]
+pub struct EntryEfi32HeaderTag {
+    typ: HeaderTagType,
+    flags: HeaderTagFlag,
+    size: u32,
+    entry_addr: u32,
+}
+
+impl EntryEfi32HeaderTag {
+    pub const fn new(flags: HeaderTagFlag, entry_addr: u32) -> Self {
+        EntryEfi32HeaderTag {
+            typ: HeaderTagType::EntryAddressEFI32,
+            flags,
+            size: size_of::<Self>() as u32,
+            entry_addr,
+        }
+    }
+
+    pub const fn typ(&self) -> HeaderTagType {
+        self.typ
+    }
+    pub const fn flags(&self) -> HeaderTagFlag {
+        self.flags
+    }
+    pub const fn size(&self) -> u32 {
+        self.size
+    }
+    pub const fn entry_addr(&self) -> u32 {
+        self.entry_addr
+    }
+}
+
+impl Debug for EntryEfi32HeaderTag {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.debug_struct("EntryEfi32HeaderTag")
+            .field("type", &{ self.typ })
+            .field("flags", &{ self.flags })
+            .field("size", &{ self.size })
+            .field("entry_addr", &(self.entry_addr as *const u32))
+            .finish()
+    }
+}
+
+impl StructAsBytes for EntryEfi32HeaderTag {}