multiboot2-header 0.5.0

Library with type definitions and parsing functions for Multiboot2 headers. This library is `no_std` and can be used in bootloaders.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# multiboot2-header

![Build](https://github.com/rust-osdev/multiboot2/actions/workflows/rust.yml/badge.svg)
[![crates.io](https://img.shields.io/crates/v/multiboot2-header.svg)](https://crates.io/crates/multiboot2-header)
[![docs](https://docs.rs/multiboot2-header/badge.svg)](https://docs.rs/multiboot2-header/)

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.

```toml
# 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

```rust
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.70.0 stable.

## License & Contribution

See main [README](https://github.com/rust-osdev/multiboot2/blob/main/README.md)
file.