diff --git a/.typos.toml b/.typos.toml
index 6947ea6e..1a9fcd8b 100644
--- a/.typos.toml
+++ b/.typos.toml
@@ -2,7 +2,7 @@
[files]
extend-exclude = [
- # "uefi/src/table/boot.rs"
+ "*.drawio.xml"
]
[default.extend-words]
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..5d848768
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,5 @@
+Please see:
+
+- [multiboot2/CHANGELOG.md](multiboot2/CHANGELOG.md)
+- [multiboot2-header/CHANGELOG.md](multiboot2-header/CHANGELOG.md)
+- [multiboot2-common/CHANGELOG.md](multiboot2-common/CHANGELOG.md)
diff --git a/Cargo.lock b/Cargo.lock
index 9010edda..40ee3afd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -27,7 +27,7 @@ checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24"
[[package]]
name = "multiboot2"
-version = "0.22.1"
+version = "0.22.2"
dependencies = [
"bitflags",
"derive_more",
@@ -39,7 +39,7 @@ dependencies = [
[[package]]
name = "multiboot2-common"
-version = "0.1.1"
+version = "0.1.2"
dependencies = [
"derive_more",
"ptr_meta",
@@ -47,7 +47,7 @@ dependencies = [
[[package]]
name = "multiboot2-header"
-version = "0.5.0"
+version = "0.5.1"
dependencies = [
"derive_more",
"log",
diff --git a/Cargo.toml b/Cargo.toml
index 57e82c6b..49bd0ea7 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,6 +13,8 @@ exclude = [
bitflags = "2.6.0"
derive_more = { version = "~0.99.18", default-features = false, features = ["display"] }
log = { version = "~0.4", default-features = false }
+multiboot2 = { version = "0.22.2", default-features = false }
+multiboot2-common = { version = "0.1.2", default-features = false }
ptr_meta = { version = "~0.2", default-features = false }
# This way, the corresponding crate dependency can be normalley referenced by
@@ -21,3 +23,4 @@ ptr_meta = { version = "~0.2", default-features = false }
[patch.crates-io]
multiboot2 = { path = "multiboot2" }
multiboot2-common = { path = "multiboot2-common" }
+multiboot2-header = { path = "multiboot2-header" }
diff --git a/Changelog.md b/Changelog.md
deleted file mode 100644
index bac17705..00000000
--- a/Changelog.md
+++ /dev/null
@@ -1,3 +0,0 @@
-Please see:
-- [multiboot2/Changelog.md](multiboot2/Changelog.md)
-- [multiboot2-header/Changelog.md](multiboot2-header/Changelog.md)
diff --git a/README.md b/README.md
index 012308f6..1ce60e83 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,10 @@
-# Multiboot2: MBI + Header
+# Rusty Wrappers for Multiboot2
-This repository contains the crates `multiboot2` and `multiboot2-header`.
-Please check their individual README-files ([multiboot2](multiboot2/README.md),
-[multiboot2-header](multiboot2-header/README.md)).
+## Repository Overview
-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` helps you to either build
-Multiboot2-headers yourself, or to parse Multiboot2 headers in custom bootloader
-or similar applications.
+- [`multiboot2`](./multiboot2/README.md)
+- [`multiboot2-header`](./multiboot2-header/README.md)
+- [`multiboot2-common`](./multiboot2-common/README.md)
## License
@@ -22,6 +18,6 @@ at your option.
### Contribution
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
-work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
-additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
diff --git a/integration-test/bins/Cargo.lock b/integration-test/bins/Cargo.lock
index 7d718dc6..dff4de92 100644
--- a/integration-test/bins/Cargo.lock
+++ b/integration-test/bins/Cargo.lock
@@ -96,7 +96,7 @@ dependencies = [
[[package]]
name = "multiboot2"
-version = "0.22.1"
+version = "0.22.2"
dependencies = [
"bitflags 2.6.0",
"derive_more",
@@ -108,7 +108,7 @@ dependencies = [
[[package]]
name = "multiboot2-common"
-version = "0.1.1"
+version = "0.1.2"
dependencies = [
"derive_more",
"ptr_meta",
@@ -116,7 +116,7 @@ dependencies = [
[[package]]
name = "multiboot2-header"
-version = "0.5.0"
+version = "0.5.1"
dependencies = [
"derive_more",
"log",
diff --git a/multiboot2-common/CHANGELOG.md b/multiboot2-common/CHANGELOG.md
new file mode 100644
index 00000000..d2ecb870
--- /dev/null
+++ b/multiboot2-common/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog for Crate `multiboot2-common`
+
+## v0.1.2 (2024-08-24)
+
+- Documentation improvements
+-
+
+## 0.1.0 / 0.1.1 (2024-08-20)
+
+Initial release.
diff --git a/multiboot2-common/Cargo.toml b/multiboot2-common/Cargo.toml
index 8ad25231..5ea30f70 100644
--- a/multiboot2-common/Cargo.toml
+++ b/multiboot2-common/Cargo.toml
@@ -3,7 +3,7 @@ name = "multiboot2-common"
description = """
Common helpers for the `multiboot2` and `multiboot2-header` crates.
"""
-version = "0.1.1"
+version = "0.1.2"
authors = [
"Philipp Schuster <phip1611@gmail.com>"
]
diff --git a/multiboot2-common/Changelog.md b/multiboot2-common/Changelog.md
deleted file mode 100644
index 8d3f3905..00000000
--- a/multiboot2-common/Changelog.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# CHANGELOG for crate `multiboot2`
-
-## 0.1.0 / 0.1.1 (2024-08-20)
-
-Initial release.
diff --git a/multiboot2-common/README.md b/multiboot2-common/README.md
index 3a4cd576..7a2282ed 100644
--- a/multiboot2-common/README.md
+++ b/multiboot2-common/README.md
@@ -5,6 +5,23 @@
Common helpers for the `multiboot2` and `multiboot2-header` crates.
+## Architecture
+
+The following figures, not displayable in `lib.rs` / on `docs.rs` unfortunately,
+outline the design of this crate:
+
+
+
+Overview of Multiboot2 structures: Multiboot2 boot information, boot
+information tags, Multiboot2 headers, and Multiboot2 header tags all share the
+same technical foundation: They have a common header and a possible dynamic
+size, depending on the header.
+
+
+
+Overview of how raw bytes are modelled to be representable by high-level
+ABI-compatible rusty types.
+
## MSRV
The MSRV is 1.70.0 stable.
diff --git a/multiboot2-common/architecture.drawio.png b/multiboot2-common/architecture.drawio.png
new file mode 100644
index 00000000..a3d0e18c
Binary files /dev/null and b/multiboot2-common/architecture.drawio.png differ
diff --git a/multiboot2-common/architecture.drawio.xml b/multiboot2-common/architecture.drawio.xml
new file mode 100644
index 00000000..1e87a57d
--- /dev/null
+++ b/multiboot2-common/architecture.drawio.xml
@@ -0,0 +1,217 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36" version="24.7.7">
+ <diagram name="Seite-1" id="ldH2TbbCgMykRvGRHne9">
+ <mxGraphModel dx="2074" dy="1098" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-1" value="Multiboot2<br>Boot Information" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
+ <mxGeometry x="50" y="40" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-2" value="Multiboot2<br>Header" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
+ <mxGeometry x="50" y="200" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-3" value="Multiboot2<br>Header Tag" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
+ <mxGeometry x="50" y="280" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-4" value="Multiboot2<br>Information Tag" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
+ <mxGeometry x="50" y="120" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-5" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" vertex="1">
+ <mxGeometry x="180" y="40" width="20" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-6" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" vertex="1">
+ <mxGeometry x="180" y="120" width="20" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-7" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" vertex="1">
+ <mxGeometry x="180" y="200" width="20" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-8" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" vertex="1">
+ <mxGeometry x="180" y="280" width="20" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-9" value="&amp;[u8]" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="200" y="60" width="50" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-10" value="&amp;[u8]" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="200" y="140" width="50" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-11" value="&amp;[u8]" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="200" y="220" width="50" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-12" value="&amp;[u8]" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="200" y="300" width="50" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-13" value="struct<br>BytesRef" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="320" y="170" width="70" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-18" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;strokeColor=default;entryX=-0.02;entryY=0.144;entryDx=0;entryDy=0;entryPerimeter=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" source="Nd9tWvGN_eLunvCUwfLw-9" target="Nd9tWvGN_eLunvCUwfLw-13" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="320" y="120" as="sourcePoint" />
+ <mxPoint x="317" y="170" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-41" value="create" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-18" vertex="1" connectable="0">
+ <mxGeometry x="-0.1248" y="1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-19" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.333;entryDx=0;entryDy=0;strokeColor=default;entryPerimeter=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" target="Nd9tWvGN_eLunvCUwfLw-13" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="250" y="150" as="sourcePoint" />
+ <mxPoint x="317" y="274" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-42" value="create" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-19" vertex="1" connectable="0">
+ <mxGeometry x="-0.1361" y="-1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-20" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;strokeColor=default;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" target="Nd9tWvGN_eLunvCUwfLw-13" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="250" y="230" as="sourcePoint" />
+ <mxPoint x="320" y="265" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-43" value="create" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-20" vertex="1" connectable="0">
+ <mxGeometry x="-0.3662" y="1" relative="1" as="geometry">
+ <mxPoint x="8" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-21" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.667;entryDx=0;entryDy=0;strokeColor=default;entryPerimeter=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" target="Nd9tWvGN_eLunvCUwfLw-13" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="250" y="311" as="sourcePoint" />
+ <mxPoint x="317" y="290" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-44" value="create" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-21" vertex="1" connectable="0">
+ <mxGeometry x="-0.1873" y="-1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-22" value="struct<br><br>DynSized<br>Structure" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="420" y="170" width="110" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-23" value="Trait<br>MaybeDynSized" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#d5e8d4;strokeColor=#82b366;" parent="1" vertex="1">
+ <mxGeometry x="520" y="10" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-25" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;strokeColor=default;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" source="Nd9tWvGN_eLunvCUwfLw-13" target="Nd9tWvGN_eLunvCUwfLw-22" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="260" y="240" as="sourcePoint" />
+ <mxPoint x="330" y="210" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-26" value="BootInformation" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="690" y="120" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-27" value="CommandLineTag" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="690" y="200" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-28" value="ModuleAlign<br>HeaderTag" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
+ <mxGeometry x="690" y="280" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-29" value="" style="endArrow=block;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.455;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;edgeStyle=orthogonalEdgeStyle;endFill=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" source="Nd9tWvGN_eLunvCUwfLw-23" target="Nd9tWvGN_eLunvCUwfLw-22" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="460" y="120" as="sourcePoint" />
+ <mxPoint x="510" y="70" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-30" value="" style="endArrow=block;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;edgeStyle=orthogonalEdgeStyle;endFill=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" target="Nd9tWvGN_eLunvCUwfLw-26" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="580" y="70" as="sourcePoint" />
+ <mxPoint x="480" y="180" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="580" y="100" />
+ <mxPoint x="750" y="100" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-49" value="<font data-font-src="https://fonts.googleapis.com/css?family=Source+Code+Pro" face="Source Code Pro">implements</font>" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="Nd9tWvGN_eLunvCUwfLw-30" vertex="1" connectable="0">
+ <mxGeometry x="-0.8271" y="-1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-31" value="" style="endArrow=block;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;edgeStyle=orthogonalEdgeStyle;endFill=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" target="Nd9tWvGN_eLunvCUwfLw-27" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="580" y="100" as="sourcePoint" />
+ <mxPoint x="750" y="230" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="820" y="100" />
+ <mxPoint x="820" y="190" />
+ <mxPoint x="750" y="190" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-32" value="" style="endArrow=block;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;edgeStyle=orthogonalEdgeStyle;endFill=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" target="Nd9tWvGN_eLunvCUwfLw-28" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="820" y="190" as="sourcePoint" />
+ <mxPoint x="760" y="210" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="820" y="190" />
+ <mxPoint x="820" y="270" />
+ <mxPoint x="750" y="270" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-33" value="" style="endArrow=classic;html=1;rounded=0;dashed=1;dashPattern=1 4;exitX=1;exitY=0.25;exitDx=0;exitDy=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" parent="1" source="Nd9tWvGN_eLunvCUwfLw-22" target="Nd9tWvGN_eLunvCUwfLw-26" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="550" y="280" as="sourcePoint" />
+ <mxPoint x="620" y="200" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-34" value="cast()" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-33" vertex="1" connectable="0">
+ <mxGeometry x="-0.08" y="-1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-36" value="" style="endArrow=classic;html=1;rounded=0;dashed=1;dashPattern=1 4;exitX=1;exitY=0.5;exitDx=0;exitDy=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" parent="1" source="Nd9tWvGN_eLunvCUwfLw-22" target="Nd9tWvGN_eLunvCUwfLw-27" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="540" y="210" as="sourcePoint" />
+ <mxPoint x="700" y="160" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-37" value="cast()" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-36" vertex="1" connectable="0">
+ <mxGeometry x="-0.08" y="-1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-38" value="" style="endArrow=classic;html=1;rounded=0;dashed=1;dashPattern=1 4;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;exitX=0.994;exitY=0.853;exitDx=0;exitDy=0;exitPerimeter=0;" parent="1" source="Nd9tWvGN_eLunvCUwfLw-22" target="Nd9tWvGN_eLunvCUwfLw-28" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="530" y="200" as="sourcePoint" />
+ <mxPoint x="710" y="170" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-39" value="cast()" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="Nd9tWvGN_eLunvCUwfLw-38" vertex="1" connectable="0">
+ <mxGeometry x="-0.08" y="-1" relative="1" as="geometry">
+ <mxPoint as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-45" value="create" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" parent="1" vertex="1" connectable="0">
+ <mxGeometry x="400.0018257191813" y="250.00185896531497" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-46" value="" style="endArrow=none;html=1;rounded=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;dashed=1;dashPattern=1 1;strokeColor=#808080;" parent="1" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="400" y="200" as="sourcePoint" />
+ <mxPoint x="400" y="240" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-47" value="<font data-font-src="https://fonts.googleapis.com/css?family=Roboto" face="Roboto">Structures as raw bytes from<br>external source</font>" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontColor=#6C8EBF;" parent="1" vertex="1">
+ <mxGeometry x="50" y="400" width="200" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-50" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;rotation=90;fontColor=#FF3333;strokeColor=#FF3333;" parent="1" vertex="1">
+ <mxGeometry x="470" y="220" width="20" height="320" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-51" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;rotation=90;fontColor=#00CC00;strokeColor=#00CC00;" parent="1" vertex="1">
+ <mxGeometry x="725" y="305" width="20" height="150" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-52" value="Types in consumer crates<br>(multiboot2, multiboot2-header)" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fontColor=#00CC00;" parent="1" vertex="1">
+ <mxGeometry x="610" y="383" width="250" height="40" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-53" value="Types in multiboot2-common" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fontColor=#FF3333;" parent="1" vertex="1">
+ <mxGeometry x="375" y="388" width="210" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Nd9tWvGN_eLunvCUwfLw-54" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;rotation=90;fontColor=#FF3333;strokeColor=#6C8EBF;" parent="1" vertex="1">
+ <mxGeometry x="140" y="280" width="20" height="200" as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/multiboot2-common/overview-multiboot2-structures.drawio.png b/multiboot2-common/overview-multiboot2-structures.drawio.png
new file mode 100644
index 00000000..f8971427
Binary files /dev/null and b/multiboot2-common/overview-multiboot2-structures.drawio.png differ
diff --git a/multiboot2-common/overview-multiboot2-structures.drawio.xml b/multiboot2-common/overview-multiboot2-structures.drawio.xml
new file mode 100644
index 00000000..898f0633
--- /dev/null
+++ b/multiboot2-common/overview-multiboot2-structures.drawio.xml
@@ -0,0 +1,97 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36" version="24.7.7">
+ <diagram name="Seite-1" id="t28IrSg9-075dSeR9zn3">
+ <mxGraphModel dx="989" dy="487" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-1" value="" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;" vertex="1" parent="1">
+ <mxGeometry x="80" y="40" width="140" height="380" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-2" value="" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;" vertex="1" parent="1">
+ <mxGeometry x="240" y="40" width="140" height="380" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-4" value="<b><font data-font-src="https://fonts.googleapis.com/css?family=Roboto" face="Roboto">CommandLineTag</font></b><br>&nbsp;<font color="#0000cc">type: u32 = 1<br>&nbsp;size: u32 = 11</font><br>&nbsp;str: [u8] = [<br>&nbsp; 'h'<br>&nbsp; 'i'<br>&nbsp; '\0'<br>&nbsp;]" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;align=left;" vertex="1" parent="1">
+ <mxGeometry x="90" y="110" width="120" height="130" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-7" value="<b><font data-font-src="https://fonts.googleapis.com/css?family=Roboto" face="Roboto">Multiboot2<br>Boot Information</font></b>" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;" vertex="1" parent="1">
+ <mxGeometry x="80" y="40" width="140" height="40" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-8" value="<b>Multiboot2<br>Header</b>" style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;" vertex="1" parent="1">
+ <mxGeometry x="240" y="40" width="140" height="40" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-10" value="size: u32" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" vertex="1" parent="1">
+ <mxGeometry x="80" y="80" width="140" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-11" value="size: u32" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;" vertex="1" parent="1">
+ <mxGeometry x="240" y="80" width="140" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-12" value="&nbsp; &nbsp; <b><font data-font-src="https://fonts.googleapis.com/css?family=Roboto" face="Roboto">Tag X</font></b><br>&nbsp;<font color="#0000cc">type: u32 = x<br></font><div><font color="#0000cc">&nbsp;size: u32 = y</font><div>&nbsp;a: u16 = z<div><br></div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=top;align=left;" vertex="1" parent="1">
+ <mxGeometry x="90" y="250" width="120" height="70" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-14" value="<b><font face="Roboto">InformationReq</font></b><br>&nbsp;<font color="#007fff">type: u16 = 1<br>&nbsp;flags: u16 = 0<br>&nbsp;size: u32 = 11</font><br>&nbsp;reqs: [u32] = [<br>&nbsp; 1<br>&nbsp;];" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;align=left;verticalAlign=top;" vertex="1" parent="1">
+ <mxGeometry x="250" y="110" width="120" height="110" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-15" value="&nbsp; &nbsp; &nbsp; <b><font data-font-src="https://fonts.googleapis.com/css?family=Roboto" face="Roboto">Tag Y</font></b><br>&nbsp;<font color="#007fff">type: u16 = x<br>&nbsp;flags: u16 = y<br>&nbsp;size: u32 = z</font><br>&nbsp;bar: u64 = x<br><div><div><div><br></div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=top;align=left;" vertex="1" parent="1">
+ <mxGeometry x="250" y="250" width="120" height="90" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-16" value="<div><div><div>...</div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=middle;align=center;" vertex="1" parent="1">
+ <mxGeometry x="90" y="390" width="120" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-20" value="" style="endArrow=none;dashed=1;html=1;dashPattern=1 2;strokeWidth=2;rounded=0;strokeColor=#FF9999;" edge="1" parent="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="30" y="250" as="sourcePoint" />
+ <mxPoint x="400" y="250" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-22" value="<font data-font-src="https://fonts.googleapis.com/css?family=Roboto" style="font-size: 10px;">8-byte<br style="font-size: 10px;">alignment</font>" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fontSize=10;fontColor=#FF3333;" vertex="1" parent="1">
+ <mxGeometry x="10" y="250" width="60" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-23" value="<font data-font-src="https://fonts.googleapis.com/css?family=Roboto" style="font-size: 10px;">8-byte<br style="font-size: 10px;">alignment</font>" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fontSize=10;fontColor=#FF3333;" vertex="1" parent="1">
+ <mxGeometry x="10" y="110" width="60" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-24" value="<font data-font-src="https://fonts.googleapis.com/css?family=Roboto" style="font-size: 10px;">8-byte<br style="font-size: 10px;">alignment</font>" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fontSize=10;fontColor=#FF3333;" vertex="1" parent="1">
+ <mxGeometry x="10" y="40" width="60" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-26" value="" style="endArrow=none;dashed=1;html=1;dashPattern=1 2;strokeWidth=2;rounded=0;strokeColor=#FF9999;" edge="1" parent="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="30" y="110" as="sourcePoint" />
+ <mxPoint x="400" y="110" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-27" value="" style="endArrow=none;dashed=1;html=1;dashPattern=1 2;strokeWidth=2;rounded=0;strokeColor=#FF9999;" edge="1" parent="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="30" y="39.31" as="sourcePoint" />
+ <mxPoint x="400" y="39.31" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-28" value="" style="endArrow=none;dashed=1;html=1;dashPattern=1 2;strokeWidth=2;rounded=0;strokeColor=#FF9999;" edge="1" parent="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="30" y="420" as="sourcePoint" />
+ <mxPoint x="400" y="420" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-29" value="<font data-font-src="https://fonts.googleapis.com/css?family=Roboto" style="font-size: 10px;">8-byte<br style="font-size: 10px;">alignment</font>" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;fontSize=10;fontColor=#FF3333;" vertex="1" parent="1">
+ <mxGeometry x="10" y="390" width="60" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-32" value="Overview of Multiboot2 Structures" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontFamily=Roboto;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DRoboto;fontSize=14;fontStyle=1" vertex="1" parent="1">
+ <mxGeometry x="80" width="300" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-33" value="<div><div><div>...</div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=middle;align=center;" vertex="1" parent="1">
+ <mxGeometry x="250" y="390" width="120" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-34" value="<div><div><div>...</div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=middle;align=center;" vertex="1" parent="1">
+ <mxGeometry x="250" y="360" width="120" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-35" value="<div><div><div>...</div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=middle;align=center;" vertex="1" parent="1">
+ <mxGeometry x="90" y="360" width="120" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-36" value="<div><div><div>...</div></div></div>" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=middle;align=center;" vertex="1" parent="1">
+ <mxGeometry x="90" y="330" width="120" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="Sv76AHv-8cPqDwbSuwtx-39" value="Padding" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Source Code Pro;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DSource%2BCode%2BPro;verticalAlign=middle;align=center;" vertex="1" parent="1">
+ <mxGeometry x="250" y="230" width="120" height="10" as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/multiboot2-common/src/lib.rs b/multiboot2-common/src/lib.rs
index 6f01e285..5bc7d5e9 100644
--- a/multiboot2-common/src/lib.rs
+++ b/multiboot2-common/src/lib.rs
@@ -15,7 +15,12 @@
//! - header structure (whole)
//! - header tags
//!
-//! # The Problem / Difficulties
+//! # Solved Problem & Difficulties Along the Way
+//!
+//! Firstly, the design choice to have ABI-compatible rusty types influenced the
+//! requirements and difficulties along the way. They, on the other side,
+//! influenced the design. The outcome is what we perceive as the optimal rusty
+//! and convenient solution.
//!
//! ## Multiboot2 Structures
//!
@@ -34,7 +39,9 @@
//!
//! Note that these structures can also be nested. So for example, the
//! Multiboot2 boot information contains Multiboot2 tags, and the Multiboot2
-//! header contains Multiboot2 header tags - both are itself dynamic structures.
+//! header contains Multiboot2 header tags - both are itself **dynamically
+//! sized** structures. This means, you can know the size (and amount of
+//! elements) **only at runtime!**
//!
//! A final `[u8]` field in the structs is the most rusty way to model this.
//! However, this makes the type a Dynamically Sized Type (DST). To create
@@ -42,7 +49,11 @@
//! are a language feature currently not constructable with stable Rust.
//! Luckily, we can utilize [`ptr_meta`].
//!
-//! ## Dynamic and Sized Structs
+//! Figure 1 in the [README](https://crates.io/crates/multiboot2-common)
+//! (currently not embeddable in lib.rs unfortunately) provides an overview of
+//! Multiboot2 structures.
+//!
+//! ## Dynamic and Sized Structs in Rust
//!
//! Note that we also have structures (tags) in Multiboot2 that looks like this:
//!
@@ -68,7 +79,38 @@
//! }
//! ```
//!
-//! ## Fat Pointer Requirements
+//! ## Chosen Design
+//!
+//! The overall common abstractions needed to solve the problems mentioned in
+//! this section are also mainly influenced by the fact that the `multiboot2`
+//! and `multiboot2-header` crates use a **zero-copy** design for parsing
+//! the corresponding structures.
+//!
+//! Further, by having **ABI-compatible types** that fully represent the
+//! reality, we can use the same type for parsing **and** for construction,
+//! as modelled in the following simplified example:
+//!
+//! ```rust,ignore
+//! /// ABI-compatible tag for parsing.
+//! pub struct MemoryMapTag {
+//! header: TagHeader,
+//! entry_size: u32,
+//! entry_version: u32,
+//! areas: [MemoryArea],
+//! }
+//!
+//! impl MemoryMapTag {
+//! // We can also create an ABI-compatible structure of that type.
+//! pub fn new(areas: &[MemoryArea]) -> Box<Self> {
+//! // omitted
+//! }
+//! }
+//! ```
+//!
+//! Hence, the structures can also be build at runtime. This is what we
+//! consider **idiomatic and rusty**.
+//!
+//! ## Creating Fat Pointers with [`ptr_meta`]
//!
//! To create fat pointers with [`ptr_meta`], each tag needs a `Metadata` type
//! which is either `usize` (for DSTs) or `()`. A trait is needed to abstract
@@ -76,22 +118,35 @@
//!
//! ## Multiboot2 Requirements
//!
-//! All tags must be 8-byte aligned. Space between multiple tags may be
-//! filled with zeroes if necessary. These zeroes are not reflected in the
-//! previous tag's size.
+//! All tags must be 8-byte aligned. The actual payload of tags may be followed
+//! by padding zeroes to fill the gap until the next alignment boundary, if
+//! necessary. These zeroes are not reflected in the tag's size, but for Rust,
+//! must be reflected in the memory allocation size.
//!
//! ## Rustc Requirements
//!
-//! The allocation space that Rust requires for types is a multiple of the
+//! The required allocation space that Rust uses for types is a multiple of the
//! alignment. This means that if we cast between byte slices and specific
-//! types, Rust doesn't just see the size reported by the header but also
-//! any necessary padding bytes. If this is not the case, for example we
-//! cast to a structure from a `&[u8; 15]`, Miri will complain as it expects
-//! `&[u8; 16]`
+//! types, Rust doesn't just see the "trimmed down actual payload" defined by
+//! struct members, but also any necessary, but hidden, padding bytes. If we
+//! don't guarantee the correct is not the case, for example we cast the bytes
+//! from a `&[u8; 15]` to an 8-byte aligned struct, Miri will complain as it
+//! expects `&[u8; 16]`.
//!
//! See <https://doc.rust-lang.org/reference/type-layout.html> for information.
//!
-//! # Provided Abstractions
+//! Further, this also means that we can't cast references to smaller structs
+//! to bigger ones. Also, once we construct a `Box` on the heap and construct
+//! it using the [`new_boxed`] helper, we must ensure that the default
+//! [`Layout`] for the underlying type equals the one we manually used for the
+//! allocation.
+//!
+//! # Architecture & Provided Abstractions
+//!
+//! Figure 2 in the [README](https://crates.io/crates/multiboot2-common)
+//! (currently not embeddable in lib.rs unfortunately) provides an overview of
+//! the parsing of Multiboot2 structures and how the definitions from this
+//! crate are used.
//!
//! ## Parsing and Casting
//!
@@ -122,6 +177,8 @@
//! # No Public API
//!
//! Not meant as stable public API for others outside Multiboot2.
+//!
+//! [`Layout`]: core::alloc::Layout
#![no_std]
#![cfg_attr(feature = "unstable", feature(error_in_core))]
@@ -270,10 +327,17 @@ impl<H: Header> DynSizedStructure<H> {
&self.payload
}
- /// Casts the structure tag to a specific [`MaybeDynSized`] implementation which
- /// may be a ZST or DST typed tag. The output type will have the exact same
- /// size as `*self`. The target type must be sufficient for that. If not,
- /// the function will panic.
+ /// Performs a memory-safe same-size cast from the base-structure to a
+ /// specific [`MaybeDynSized`]. The idea here is to cast the generic
+ /// mostly semantic-free version to a specific type with fields that have
+ /// a semantic.
+ ///
+ /// The provided `T` of type [`MaybeDynSized`] might be may be sized type
+ /// or DST. This depends on the type.
+ ///
+ /// # Panic
+ /// Panics if base assumptions are violated. For example, the
+ /// `T` of type [`MaybeDynSized`] must allow a proper casting to it.
///
/// # Safety
/// This function is safe due to various sanity checks and the overall
diff --git a/multiboot2-common/src/tag.rs b/multiboot2-common/src/tag.rs
index 2ff85104..29a4da53 100644
--- a/multiboot2-common/src/tag.rs
+++ b/multiboot2-common/src/tag.rs
@@ -10,7 +10,8 @@ use ptr_meta::Pointee;
/// [`DynSizedStructure::cast`].
///
/// Structs that are a DST must provide a **correct**
-/// [`MaybeDynSized::dst_len`] implementation.
+/// [`MaybeDynSized::dst_len`] implementation. Further, implementors **must**
+/// use `#[repr(C)]`.
///
/// [`ID`]: Tag::ID
/// [`DynSizedStructure`]: crate::DynSizedStructure
diff --git a/multiboot2-header/Changelog.md b/multiboot2-header/CHANGELOG.md
similarity index 96%
rename from multiboot2-header/Changelog.md
rename to multiboot2-header/CHANGELOG.md
index bf67ee82..d18a5953 100644
--- a/multiboot2-header/Changelog.md
+++ b/multiboot2-header/CHANGELOG.md
@@ -1,4 +1,8 @@
-# CHANGELOG for crate `multiboot2-header`
+# Changelog for Crate `multiboot2-header`
+
+## v0.5.1 (2024-08-24)
+
+- Documentation improvements
## v0.5.0 (2024-05-20)
diff --git a/multiboot2-header/Cargo.toml b/multiboot2-header/Cargo.toml
index 20321308..c8ca8787 100644
--- a/multiboot2-header/Cargo.toml
+++ b/multiboot2-header/Cargo.toml
@@ -1,10 +1,12 @@
[package]
name = "multiboot2-header"
description = """
-Library with type definitions and parsing functions for Multiboot2 headers.
-This library is `no_std` and can be used in bootloaders.
+Convenient and safe parsing of Multiboot2 Header structures and the
+contained header tags. Usable in no_std environments, such as a
+bootloader. An optional builder feature also allows the construction of
+the corresponding structures.
"""
-version = "0.5.0"
+version = "0.5.1"
authors = [
"Philipp Schuster <phip1611@gmail.com>"
]
@@ -43,9 +45,9 @@ unstable = []
[dependencies]
derive_more.workspace = true
log.workspace = true
+multiboot2-common.workspace = true
+multiboot2.workspace = true
ptr_meta.workspace = true
-multiboot2 = { version = "0.22.1", default-features = false }
-multiboot2-common = "0.1.1"
[package.metadata.docs.rs]
all-features = true
diff --git a/multiboot2-header/README.md b/multiboot2-header/README.md
index eebac8d0..b33cfb92 100644
--- a/multiboot2-header/README.md
+++ b/multiboot2-header/README.md
@@ -4,9 +4,18 @@
[](https://crates.io/crates/multiboot2-header)
[](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.
+Convenient and safe parsing of Multiboot2 Header structures and the
+contained header tags. Usable in `no_std` environments, such as a
+bootloader. An optional `builder` feature also allows the construction of
+the corresponding structures.
+
+## Design
+
+For every Multiboot2 header structure, there is an ABI-compatible rusty type.
+This enables a zero-copying parsing design while also enabling the creation of
+these structures via convenient constructors for the corresponding types.
+
+## Use-Cases
What this library is good for:
diff --git a/multiboot2-header/src/lib.rs b/multiboot2-header/src/lib.rs
index f9dd25d4..e2121b68 100644
--- a/multiboot2-header/src/lib.rs
+++ b/multiboot2-header/src/lib.rs
@@ -1,6 +1,13 @@
-//! 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.
+//! Convenient and safe parsing of Multiboot2 Header structures and the
+//! contained header tags. Usable in `no_std` environments, such as a
+//! bootloader. An optional builder feature also allows the construction of
+//! the corresponding structures.
+//!
+//! ## Design
+//!
+//! For every Multiboot2 header structure, there is an ABI-compatible rusty type.
+//! This enables a zero-copying parsing design while also enabling the creation
+//! of these structures via convenient constructors on the corresponding types.
//!
//! # Example: Parsing a Header
//!
diff --git a/multiboot2/Changelog.md b/multiboot2/CHANGELOG.md
similarity index 99%
rename from multiboot2/Changelog.md
rename to multiboot2/CHANGELOG.md
index 5c4faa82..6a875fe4 100644
--- a/multiboot2/Changelog.md
+++ b/multiboot2/CHANGELOG.md
@@ -1,7 +1,8 @@
-# CHANGELOG for crate `multiboot2`
+# Changelog for Crate `multiboot2`
-## Unreleased
+## v0.22.2 (2024-08-24)
+- Documentation improvements
- Improve debug formatting for EFIMemoryMapTag
## v0.22.1 (2024-08-20)
diff --git a/multiboot2/Cargo.toml b/multiboot2/Cargo.toml
index 0f7e61b9..05ff43cb 100644
--- a/multiboot2/Cargo.toml
+++ b/multiboot2/Cargo.toml
@@ -6,7 +6,7 @@ structures and the contained information tags. Usable in `no_std` environments,
such as a kernel. An optional builder feature also allows the construction of
the corresponding structures.
"""
-version = "0.22.1"
+version = "0.22.2"
authors = [
"Philipp Oppermann <dev@phil-opp.com>",
"Calvin Lee <cyrus296@gmail.com>",
@@ -46,8 +46,7 @@ bitflags.workspace = true
derive_more.workspace = true
log.workspace = true
ptr_meta.workspace = true
-multiboot2-common = { version = "0.1.1", default-features = false }
-
+multiboot2-common.workspace = true
# We only use a very basic type definition from this crate. To prevent MSRV
# bumps from uefi-raw, I restrict this here. Upstream users are likely to have
# two versions of this library in it, which is no problem, as we only use the
diff --git a/multiboot2/README.md b/multiboot2/README.md
index 9d65d1c1..5c15d837 100644
--- a/multiboot2/README.md
+++ b/multiboot2/README.md
@@ -5,13 +5,19 @@
Convenient and safe parsing of Multiboot2 Boot Information (MBI)
structures and the contained information tags. Usable in `no_std` environments,
-such as a kernel. An optional builder feature also allows the construction of
+such as a kernel. An optional `builder` feature also allows the construction of
the corresponding structures.
It follows the Multiboot 2.0 specification
at https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html and the
ELF 64 specification at http://www.uclibc.org/docs/elf-64-gen.pdf.
+## Design
+
+For every Multiboot2 structure, there is an ABI-compatible rusty type. This
+enables a zero-copying parsing design while also enabling the creation of these
+structures via convenient constructors on the corresponding types.
+
## Features and `no_std` Compatibility
This library is always `no_std` without `alloc`. However, the default `builder`-
diff --git a/multiboot2/src/lib.rs b/multiboot2/src/lib.rs
index cc8f7f40..8027c79a 100644
--- a/multiboot2/src/lib.rs
+++ b/multiboot2/src/lib.rs
@@ -17,15 +17,16 @@
#![deny(rustdoc::all)]
// --- END STYLE CHECKS ---
-//! Library that assists parsing the Multiboot2 Information Structure (MBI) from
-//! Multiboot2-compliant bootloaders, such as GRUB. It supports all tags from the
-//! specification including full support for the sections of ELF files. This library
-//! is `no_std` and can be used in a Multiboot2-kernel.
+//! Convenient and safe parsing of Multiboot2 Boot Information (MBI) structures
+//! and the contained information tags. Usable in `no_std` environments, such as
+//! a kernel. An optional builder feature also allows the construction of
+//! the corresponding structures.
//!
-//! The GNU Multiboot(2) specification aims to provide a standardised
-//! method of sharing commonly used information about the host machine at
-//! boot time and give the payload, i.e. a kernel, a well defined machine
-//! state.
+//! ## Design
+//!
+//! For every Multiboot2 structure, there is an ABI-compatible rusty type. This
+//! enables a zero-copying parsing design while also enabling the creation of
+//! these structures via convenient constructors on the corresponding types.
//!
//! ## Example
//!