Merge pull request #228 from rust-osdev/doc

doc: add figures and better discuss chosen design

Author: phip1611

.typos.toml

@@ -2,7 +2,7 @@
 
 [files]
 extend-exclude = [
-    # "uefi/src/table/boot.rs"
+    "*.drawio.xml"
 ]
 
 [default.extend-words]

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)

Cargo.lock

@@ -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" }

Cargo.toml

@@ -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.

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.

README.md

@@ -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 <[email protected]>"
 ]

integration-test/bins/Cargo.lock

@@ -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 Multiboot2 Structures](./overview-multiboot2-structures.drawio.png "Overview Multiboot2 Structures")
+
+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.
+
+![Crate Architecture Overview](./architecture.drawio.png "Crate Architecture Overview")
+
+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.