doc: add figures and better discuss chosen design

.typos.toml

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

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

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&lt;br&gt;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&lt;br&gt;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&lt;br&gt;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&lt;br&gt;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;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;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;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;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&lt;br&gt;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&lt;br&gt;&lt;br&gt;DynSized&lt;br&gt;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&lt;br&gt;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&lt;br&gt;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="&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Source+Code+Pro&quot; face=&quot;Source Code Pro&quot;&gt;implements&lt;/font&gt;" 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="&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; face=&quot;Roboto&quot;&gt;Structures as raw bytes from&lt;br&gt;external source&lt;/font&gt;" 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&lt;br&gt;(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>

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="&lt;b&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; face=&quot;Roboto&quot;&gt;CommandLineTag&lt;/font&gt;&lt;/b&gt;&lt;br&gt;&amp;nbsp;&lt;font color=&quot;#0000cc&quot;&gt;type: u32 = 1&lt;br&gt;&amp;nbsp;size: u32 = 11&lt;/font&gt;&lt;br&gt;&amp;nbsp;str: [u8] = [&lt;br&gt;&amp;nbsp; &#39;h&#39;&lt;br&gt;&amp;nbsp; &#39;i&#39;&lt;br&gt;&amp;nbsp; &#39;\0&#39;&lt;br&gt;&amp;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="&lt;b&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; face=&quot;Roboto&quot;&gt;Multiboot2&lt;br&gt;Boot Information&lt;/font&gt;&lt;/b&gt;" 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="&lt;b&gt;Multiboot2&lt;br&gt;Header&lt;/b&gt;" 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="&amp;nbsp; &amp;nbsp; &lt;b&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; face=&quot;Roboto&quot;&gt;Tag X&lt;/font&gt;&lt;/b&gt;&lt;br&gt;&amp;nbsp;&lt;font color=&quot;#0000cc&quot;&gt;type: u32 = x&lt;br&gt;&lt;/font&gt;&lt;div&gt;&lt;font color=&quot;#0000cc&quot;&gt;&amp;nbsp;size: u32 = y&lt;/font&gt;&lt;div&gt;&amp;nbsp;a: u16 = z&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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="&lt;b&gt;&lt;font face=&quot;Roboto&quot;&gt;InformationReq&lt;/font&gt;&lt;/b&gt;&lt;br&gt;&amp;nbsp;&lt;font color=&quot;#007fff&quot;&gt;type: u16 = 1&lt;br&gt;&amp;nbsp;flags: u16 = 0&lt;br&gt;&amp;nbsp;size: u32 = 11&lt;/font&gt;&lt;br&gt;&amp;nbsp;reqs: [u32] = [&lt;br&gt;&amp;nbsp; 1&lt;br&gt;&amp;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="&amp;nbsp; &amp;nbsp; &amp;nbsp; &lt;b&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; face=&quot;Roboto&quot;&gt;Tag Y&lt;/font&gt;&lt;/b&gt;&lt;br&gt;&amp;nbsp;&lt;font color=&quot;#007fff&quot;&gt;type: u16 = x&lt;br&gt;&amp;nbsp;flags: u16 = y&lt;br&gt;&amp;nbsp;size: u32 = z&lt;/font&gt;&lt;br&gt;&amp;nbsp;bar: u64 = x&lt;br&gt;&lt;div&gt;&lt;div&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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="&lt;div&gt;&lt;div&gt;&lt;div&gt;...&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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="&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; style=&quot;font-size: 10px;&quot;&gt;8-byte&lt;br style=&quot;font-size: 10px;&quot;&gt;alignment&lt;/font&gt;" 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="&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; style=&quot;font-size: 10px;&quot;&gt;8-byte&lt;br style=&quot;font-size: 10px;&quot;&gt;alignment&lt;/font&gt;" 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="&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; style=&quot;font-size: 10px;&quot;&gt;8-byte&lt;br style=&quot;font-size: 10px;&quot;&gt;alignment&lt;/font&gt;" 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="&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Roboto&quot; style=&quot;font-size: 10px;&quot;&gt;8-byte&lt;br style=&quot;font-size: 10px;&quot;&gt;alignment&lt;/font&gt;" 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="&lt;div&gt;&lt;div&gt;&lt;div&gt;...&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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="&lt;div&gt;&lt;div&gt;&lt;div&gt;...&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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="&lt;div&gt;&lt;div&gt;&lt;div&gt;...&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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="&lt;div&gt;&lt;div&gt;&lt;div&gt;...&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;" 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>

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,23 +118,36 @@
 //!
 //! ## 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.
 //!
+//! 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.
+//!
 //! # 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
 //!
 //! First, we need byte slices which are guaranteed to be aligned and are a
@@ -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

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

multiboot2-header/Cargo.toml

@@ -1,8 +1,10 @@
 [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"
 authors = [

multiboot2-header/README.md

@@ -4,9 +4,18 @@
 [![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.
+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:
 

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
 //!

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

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
 //!