Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,32 @@ positions in the flash chip, drawn from 0, not CPU addresses. The column also ho
bootloader, the partition table and `Free` blocks; the header comments say where each setting
came from. https://github.com/iharhl/memmap/blob/main/docs/from-partitions.md has the details.

## Typical task: map a Zephyr or nRF Connect SDK flash layout
1. Find the build's layout. Zephyr: `build/zephyr/zephyr.dts`, the merged devicetree
(`build/<app>/zephyr/zephyr.dts` under sysbuild), not a board `.dts` or overlay. nRF Connect
SDK with the Partition Manager: `build/partitions.yml`, or the project's `pm_static.yml`.
2. `memmap from-partitions build/zephyr/zephyr.dts -o layout.yaml --json --strict`. It needs no
options, and the ESP-IDF ones are refused.
3. Fix W114 (a partition left out: it partly overlaps another or lies outside its flash) by
correcting the partition in the overlay or pm_static.yml. W100 marks a partition edge
inside an erase block.
4. Continue from step 4 of the first task.

Each flash with `fixed-partitions`, or each Partition Manager region, is a region and column.
A flash on a SPI or QSPI bus, and Partition Manager's `external_flash`, has no CPU address: it
gets a `space` of its own and is drawn from 0. A partition inside another, a Zephyr
`fixed-subpartitions` node or a Partition Manager container (`span`), is drawn inside it and
zoomed into. Notes give MCUboot's slots, scratch and image header.
https://github.com/iharhl/memmap/blob/main/docs/from-partitions.md has the details.

## Rules
- Never guess keys; run `memmap schema` when unsure.
- Ranges are inclusive: end = start + size - 1.
- Prefer `size` over `end`, and sequential placement over explicit `start`.
- Display tweaks go in `view`, never by changing `memory`.
- One address space per drawing, except top-level regions with a `space`: memory the CPU does
not map, such as an external flash from 0. They may overlap the others, and a `/` column
leaves them out (E020 when no region is left). Without `view.columns`, each gets a column.
- The look is fixed on purpose: font family, address format, outlines and label side have no
keys. Connectors only choose solid or dashed lines (`style.connectors`).
- Use `--strict` on `check` and `render` to fail on warnings. Without it they exit 0 with
Expand All @@ -97,6 +118,7 @@ came from. https://github.com/iharhl/memmap/blob/main/docs/from-partitions.md ha
- Label one edge: view.overrides: [{ region: ahb1, top_label: end }]
- Block height: view.overrides: [{ region: boot, height: 48 }]
- Multi-line note: note: "line one\nline two" (long notes also wrap)
- External flash at 0: space: qspi on its top-level region, then a column with root: qspi

Quote `--set` values that contain `[` or `{`, since shells expand them.

Expand Down Expand Up @@ -149,7 +171,7 @@ Every diagnostic has a stable code, a YAML path, a line and usually a `hint`. In
| E013 | More than one `auto` size, or nothing left for `auto` |
| E014 | Gap inside a region with `fill_gaps: error` |
| E015 | Too many flash sectors |
| E020 | Column root, expansion or override target does not exist |
| E020 | Column root, expansion or override target does not exist, or a `/` column with only `space` regions |
| E021 | Expansion `to` column has a different root than `region` |
| E022 | Expanded region is not drawn in the `from` column |
| E023 | Duplicate column id |
Expand All @@ -167,6 +189,7 @@ Every diagnostic has a stable code, a YAML path, a line and usually a `hint`. In
| W111 | `from-elf`: section overlaps another one, left out |
| W112 | `from-elf`: map region left out (no size, past the address space, overlap, too small) |
| W113 | `from-partitions`: the CSV breaks a rule of ESP-IDF's partition table check |
| W114 | `from-partitions`: a Zephyr or Partition Manager partition left out (partial overlap, outside its flash) |
| E090 | Usage or IO failure, such as a missing file or bad `--set` (`--json` only) |
| E091 | Render or internal failure, such as missing cairo (`--json` only) |

Expand All @@ -182,7 +205,8 @@ Exit codes: `0` ok, `1` validation errors, `2` usage or IO error, `3` render err
tests/test_linker.py`. docs/from-elf.md describes them and how to add an image or a
map.
- After an intended change to `from-partitions` or the drawing, regenerate its goldens:
`MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_from_partitions.py`. docs/from-partitions.md
describes the real ESP-IDF builds they come from.
`MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_from_partitions.py tests/test_from_zephyr.py`.
docs/from-partitions.md describes the real ESP-IDF, Zephyr and nRF Connect SDK builds they
come from.
- A new diagnostic code or recipe goes in this file too. `memmap guide` ships it to users, and
`tests/test_cli.py` covers the recipes.
40 changes: 31 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# memmap

Draw datasheet-style memory maps of MCU memory. You describe the layout in a YAML file, or
have `memmap` write that file from a linked firmware image or an ESP-IDF partition table. Either
have `memmap` write that file from a linked firmware image or a flash partition layout. Either
way you get the same config, which `memmap` checks and renders to SVG, PNG or PDF.

- **Write it by hand.** One YAML file holds the memory (`memory`) and how to draw it (`view`),
Expand All @@ -10,7 +10,8 @@ way you get the same config, which `memmap` checks and renders to SVG, PNG or PD
Keil armlink or IAR), and places every section at its real address and size in the chip's flash
and RAM regions.
- **Generate it from a partition table.** `from-partitions` reads an ESP-IDF partition table, CSV
or binary, and places every partition where the ESP-IDF build would.
or binary, and places every partition where the ESP-IDF build would. It also reads a Zephyr
build's devicetree and an nRF Connect SDK Partition Manager layout, with MCUboot's slots marked.
- **Check before drawing.** Validation catches overlaps, overflow and flash sector misalignment,
with the YAML path, line and a hint for each.
- **Verify as text.** Output is deterministic, and `describe` lists everything drawn, so agents and
Expand Down Expand Up @@ -111,6 +112,11 @@ Children without a `start` are placed one after another, and `auto` takes what i
take an optional `title`, drawn above them. For a detail column created by `view.expand`, set it
on the expansion: `expand: [{ region: flash, title: Flash }]`.

A config draws one address space. Memory the CPU does not map, such as an external SPI flash
whose offsets start at 0, goes in a top-level region with a `space`, so it may overlap the
others: `{ id: qspi, space: qspi, start: 0, size: 8M }`. A `/` column leaves such regions out,
so draw them in a column with their id as `root`. A config without `view.columns` gets one.

`memmap schema` prints every key with a description and an example. Point your editor's YAML
extension at it for completion. [AGENTS.md](AGENTS.md) has recipes for common tweaks.

Expand Down Expand Up @@ -138,12 +144,16 @@ ordinary config: rename or merge blocks, add `view` options, then `render` it.
[docs/from-elf.md](docs/from-elf.md) covers what is read from each map, what happens when it is
not enough, and how sections become blocks.

## Generating a config from an ESP-IDF partition table
## Generating a config from a partition layout

`from-partitions` draws a flash partition layout. It reads an ESP-IDF partition table, a Zephyr
build's merged devicetree or an nRF Connect SDK Partition Manager file, and tells them apart by
their content.

`from-partitions` draws the flash of an ESP-IDF project: the bootloader, the partition table,
each partition and the free space between them. It reads the partition table CSV the project
names in `CONFIG_PARTITION_TABLE_FILENAME`, or the `build/partition_table/partition-table.bin`
the build writes. Partitions with a blank offset are placed as the build places them, so the
For an ESP-IDF project, it draws the bootloader, the partition table, each partition and the
free space between them. It reads the partition table CSV the project names in
`CONFIG_PARTITION_TABLE_FILENAME`, or the `build/partition_table/partition-table.bin` the build
writes. Partitions with a blank offset are placed as the build places them, so the
drawing matches the binary table.

The table does not record the flash size, so pass the project's `sdkconfig`, which also gives
Expand All @@ -154,6 +164,17 @@ memmap from-partitions partitions.csv -o layout.yaml --flash-size 4M
```

A CSV that breaks a rule of ESP-IDF's own table check gets W113, with a hint.

For Zephyr, pass `build/zephyr/zephyr.dts`, the devicetree the build merged. Each flash with
`fixed-partitions` gets a column, with MCUboot's slots marked. An external SPI or QSPI flash is
drawn from 0, in an address space of its own. For the nRF Connect SDK, pass
`build/partitions.yml` or a `pm_static.yml`: each region gets a column, and containers such as
`mcuboot_primary` are zoomed into. Neither needs options:

```bash
memmap from-partitions build/zephyr/zephyr.dts -o layout.yaml
```

[docs/from-partitions.md](docs/from-partitions.md) covers what is read and drawn, and the limits.

## Commands
Expand All @@ -164,7 +185,7 @@ A CSV that breaks a rule of ESP-IDF's own table check gets W113, with a hint.
| `memmap check CONFIG [--json] [--strict]` | Validate only |
| `memmap describe CONFIG [--json]` | Resolved regions, blocks, labels and option origins |
| `memmap from-elf ELF [-o OUT] [--map FILE] [--region id=start:size[:name]] [--min-size N] [--force] [--json] [--strict]` | Write a config from a linked ELF, then check it |
| `memmap from-partitions TABLE [-o OUT] [--sdkconfig FILE] [--flash-size SIZE] [--table-offset OFFSET] [--bootloader-offset OFFSET] [--force] [--json] [--strict]` | Write a config from an ESP-IDF partition table, then check it |
| `memmap from-partitions TABLE [-o OUT] [--sdkconfig FILE] [--flash-size SIZE] [--table-offset OFFSET] [--bootloader-offset OFFSET] [--force] [--json] [--strict]` | Write a config from an ESP-IDF, Zephyr or Partition Manager partition layout, then check it |
| `memmap schema` | JSON Schema of the config |
| `memmap guide` | Print the agent guide, for agents using an installed copy |

Expand All @@ -175,7 +196,8 @@ scripts and agents.

- [AGENTS.md](AGENTS.md): task guide, recipes and the full diagnostic list. `memmap guide` prints it.
- [docs/from-elf.md](docs/from-elf.md): drawing a linked firmware image, its map readers and limits.
- [docs/from-partitions.md](docs/from-partitions.md): drawing an ESP-IDF partition table.
- [docs/from-partitions.md](docs/from-partitions.md): drawing an ESP-IDF, Zephyr or Partition
Manager partition layout.
- [Examples](#examples): one config per feature set, below.

## Examples
Expand Down
Loading
Loading