diff --git a/multiboot2-common/README.md b/multiboot2-common/README.md index 4694864f..caed0d84 100644 --- a/multiboot2-common/README.md +++ b/multiboot2-common/README.md @@ -5,22 +5,33 @@ Common helpers for the `multiboot2` and `multiboot2-header` crates. -## Architecture +## Architecture Diagrams 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. +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. + +![Overview Multiboot2 structures](./overview-multiboot2-structures.drawio.png "Overview of Multiboot2 structures and their memory properties") + +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 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. + +![Parsing flow overview](./parsing-flow.drawio.png "Parsing flow overview: From raw bytes to specific structures") + +The last complex figure shows all traits and structs from `multiboot2-common`, +their internal relation, 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`. + +![Architecture overview](./architecture.drawio.png "Architecture overview") ## MSRV diff --git a/multiboot2-common/architecture.drawio.png b/multiboot2-common/architecture.drawio.png index de80e91e..38fffab1 100644 Binary files a/multiboot2-common/architecture.drawio.png and b/multiboot2-common/architecture.drawio.png differ diff --git a/multiboot2-common/architecture.drawio.xml b/multiboot2-common/architecture.drawio.xml index ab1dc7eb..7fc2f26c 100644 --- a/multiboot2-common/architecture.drawio.xml +++ b/multiboot2-common/architecture.drawio.xml @@ -1,217 +1,507 @@ - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - + + + + + + + + - - + + - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - + + + + + + + + + + + + + + + + + + + - - + + - - - + + + - + - - + + + + + + - - - + + + + + + + + - - + + + + + + + + + - - + + - + - - + + + + + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - - + + - + - - + + + + + + - - - + + + - + + + + - - + + - - - + + - + + + + + + + + + + + + + + + + + - - + + - - - + + - - - - + + + - - + + - + - - + + + + + + - - + + - + + + + + + - - + + + + + + - - + + - - + + + + + + + + + + + + + + + + + + + + + + + + + - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + + + + - - + + + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + + + + + - - + + + + + + + + + - - + + + + - - + + + + + + + + + - - + + + + - - + + + + + + + + - - + + + + diff --git a/multiboot2-common/parsing-flow.drawio.png b/multiboot2-common/parsing-flow.drawio.png new file mode 100644 index 00000000..a3d0e18c Binary files /dev/null and b/multiboot2-common/parsing-flow.drawio.png differ diff --git a/multiboot2-common/parsing-flow.drawio.xml b/multiboot2-common/parsing-flow.drawio.xml new file mode 100644 index 00000000..1e87a57d --- /dev/null +++ b/multiboot2-common/parsing-flow.drawio.xml @@ -0,0 +1,217 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/multiboot2-common/src/lib.rs b/multiboot2-common/src/lib.rs index d4ed7e18..5a190e4f 100644 --- a/multiboot2-common/src/lib.rs +++ b/multiboot2-common/src/lib.rs @@ -143,11 +143,14 @@ //! //! # Architecture & Provided Abstractions //! -//! Figure 2 in the [README](https://crates.io/crates/multiboot2-common) +//! The figures 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. //! +//! Note that although the diagrams seem complex, most logic is in +//! `multiboot2-common`. For downstream users, the usage is quite simple. +//! //! ## Parsing and Casting //! //! First, we need byte slices which are guaranteed to be aligned and are a diff --git a/multiboot2-common/src/tag.rs b/multiboot2-common/src/tag.rs index 1501ede5..a57fc43f 100644 --- a/multiboot2-common/src/tag.rs +++ b/multiboot2-common/src/tag.rs @@ -90,6 +90,8 @@ pub trait Tag: MaybeDynSized { const ID: Self::IDType; } +// This implementation is not needed for parsing but for creation, when +// downstream types just wrap this type. impl MaybeDynSized for DynSizedStructure { type Header = H;