#header-parser #bootloader #multiboot2 #kernel #boot #header-file

no-std multiboot2-header

Library with type definitions and parsing functions for Multiboot2 headers. This library is no_std and can be used in bootloaders

7 unstable releases

0.3.2 Dec 16, 2023
0.3.1 Jun 28, 2023
0.2.0 May 3, 2022
0.1.1 May 2, 2022
0.0.0 Oct 1, 2021

#765 in Operating systems

MIT/Apache

265KB
5.5K SLoC

multiboot2-header

Build crates.io docs

Rust library with type definitions and parsing functions for Multiboot2 headers, as well as a builder to build them at runtime. This library is no_std and can be used in bootloaders.

What this library is good for:

  • construct a Multiboot2 header at runtime (constructing one at build-time with macros is not done yet, contributions are welcome!)
  • write a Multiboot2-bootloader that parses a Multiboot2-header
  • understanding Multiboot2 headers better
  • analyze Multiboot2 headers at runtime

Features and no_std Compatibility

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, the feature is not relevant, and you can deactivate it.

# without `builder`-feature (and without `alloc`-crate)
multiboot2-header = { version = "<latest>", default-features = false }
# else (requires `alloc`-crate)
multiboot2-header = "<latest>"

Example 1: Builder + Parse

use multiboot2_header::builder::{InformationRequestHeaderTagBuilder, Multiboot2HeaderBuilder};
use multiboot2_header::{HeaderTagFlag, HeaderTagISA, 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().cast()) };
    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 symbol in the first 32768 bytes of the ELF. See Multiboot2 specification.

MSRV

The MSRV is 1.69.0 stable.

License & Contribution

See main README file.

Dependencies

~2MB
~41K SLoC