multiboot2-common

Common helpers for the multiboot2 and multiboot2-header crates.

Features and no_std Compatibility

This crate is always no_std. The alloc feature enables heap-allocation helpers. The default builder feature enables alloc for consistency with the two consuming crates. Disable default features for allocator-free parsing.

Architecture Diagrams

The following figures, not displayable in lib.rs / on docs.rs unfortunately, outline the design of this crate. In the following figure, you can see the four classes of Multiboot2 structures and their memory properties. The four kinds of Multiboot2 structures are boot information, boot information tags, header, and header tags. All share the same technical foundation: They have a common header and a possible dynamic size, depending on the header.

In the next figure, you see how the types from multiboot2-common are used to parse a raw byte slice as the corresponding Multiboot2 structure in a safe manner. The BytesRef wrapper ensures basic memory guarantees for the underlying &[u8] slice, while DynSizedStructure can then be used to safely cast to the target type.

The next figure is like the previous figure, but shows a more specific parsing flow by using example types of the multiboot2 crate. Specifically, it shows how the header structs for each Multiboot2 structure implement the Header trait and provide the size information needed for the final tag type.

Green shows the raw memory, purple boxes refer to logic in multiboot2-common, and red components show structs from the multiboot2 crate.

The last complex figure shows all traits and structs from multiboot2-common, their relationships, and how consumers (multiboot2 and multiboot2-header) consume them. As this figure is quite complex, we recommend to first study the inner box (multiboot2-common) and then study how types from multiboot2 (orange) and multiboot2-header (green) interface with multiboot2-common.

Stability

This crate primarily supports multiboot2 and multiboot2-header. Its public API may evolve with their internals and is not intended as an independent stable abstraction.

MSRV

The MSRV is 1.85.1 stable.

License & Contribution

See main README file.