# Memory layout diagram

A memory or binary layout diagram is a grid of fields with byte offsets, and Bytefield exists to draw exactly that. It handles nested structures and variable-length regions, which is where hand-drawn versions fall apart.

It is the diagram that turns a struct definition into something a person can hold in their head.

---

## When to reach for one

* File format and binary protocol documentation.
* Embedded work: register maps, EEPROM layouts, flash partitions.
* Explaining alignment and padding, which nobody believes until they see it.

---

## How to draw it in Capable

| **Route**  | **Use when**                                          |
| ---------- | ----------------------------------------------------- |
| Bytefield  | Byte-oriented layouts with offsets, nesting and gaps. |
| PacketDiag | Bit-oriented network headers with a fixed word width. |

---

## A worked example

A record header with a fixed part and a variable payload:

![Memory layout diagram](https://help.gocapable.com/images/att1418690697.svg)

The source, which you can paste into a new diagram and edit:

```
(defattrs :bg-green {:fill "#a0ffa0"})
(defattrs :bg-cyan {:fill "#a0fafa"})

(draw-column-headers)

(draw-box "magic" {:span 4 :borders #{:left :top :bottom} :fill "#e0e0ff"})
(draw-box "version" {:span 2})
(draw-box "flags" {:span 2})
(draw-box "length" {:span 4 :attrs :bg-cyan})
(draw-box "checksum" {:span 4})
(draw-gap "payload (length bytes)")
(draw-box "crc32" {:span 4 :attrs :bg-green})
(draw-bottom)
```

---

## A few things that catch people out

* State the endianness once, at the top. Half of all binary format bugs start here.
* Draw padding explicitly. Invisible padding is what breaks a struct on a different compiler.
* Use a gap for variable-length regions rather than pretending they have a fixed size.

---

## Related

[Neural network diagramLayers, connections and shapes.](https://help.gocapable.com/diagrams/neural-network-diagram.html)

[Scientific diagrams with TikZFeynman diagrams, quantum circuits, molecules.](https://help.gocapable.com/diagrams/scientific-diagrams-with-tikz.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Approximately right is wrong here._