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
45 changes: 35 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,36 @@ Run commands as `memmap ...` when it is installed, or `uv run memmap ...` inside
5. `memmap render layout.yaml -o layout.svg --json --strict`

## Typical task: map a linked firmware image
1. Read `ORIGIN` and `LENGTH` of each region in the linker script's `MEMORY` block, or in the
`Memory Configuration` table of a GNU ld `.map` file.
2. `memmap from-elf firmware.elf -o layout.yaml --region flash=0x08000000:64K
--region ram=0x20000000:20K --json` -> writes the config, then checks it like `check`.
Fix W110 (a section outside every region) by correcting or adding a `--region`.
3. Continue from step 4 above. Rename or merge blocks in `layout.yaml` as needed. `--force`
overwrites an existing output.
1. The ELF does not say how big flash and RAM are. Find the map file the linker wrote:

| Toolchain | Map | Found in |
| --- | --- | --- |
| GNU ld: gcc, Zephyr, ESP-IDF, Pico SDK | `firmware.map` (`-Wl,-Map=`) | next to the ELF |
| Arm armlink: Keil MDK | `project.map` | `Listings/` |
| IAR ILINK | `project.map` | `List/` |

lld (Rust, LLVM Embedded) maps list no regions, and memmap does not read linker scripts:
give each region with `--region flash=0x08000000:64K`, copying `ORIGIN` and `LENGTH` from
the script's `MEMORY` block.
2. `memmap from-elf firmware.elf -o layout.yaml --map firmware.map --json --strict` -> writes
the config, then checks it like `check`. A `--region` with the id of a map region replaces
it, and one with a new id adds a region. To split a map region, give one part its id.
3. When the map gives no region it can draw, `from-elf` writes nothing and exits 2 with E090.
Its `hint` names the `--region` specs to give, such as `--region er_ro=0x08000000:SIZE`:
fill in the sizes and run it again.
4. Fix W112 (a map region left out) and W110 (a section outside every region) by their hints:
give the `--region` the hint names, check that the map belongs to this ELF, or add a
`--region` that covers the section.
5. Continue from step 4 of the first task. Rename or merge blocks in `layout.yaml` as needed.
`--force` overwrites an existing output.

Regions take their names from the map: FLASH gets the id `flash`. IAR maps do not name their
regions, so they are called ROM, RAM or Memory by what is placed there, numbered in address
order (`ram`, `ram_2`). A region that holds no section stays in `memory` without a column. One
without a size, of size 0, past the address space, overlapping a lower or larger region, or
too small for a section is left out, with W112 when the drawing loses something. Comments in
`layout.yaml` list both. https://github.com/iharhl/memmap/blob/main/docs/from-elf.md has the
details and limits.

In a region of more than 8 blocks, small sections fold into groups such as `small_sections`,
which keep the sections as `children` and each get a detail column. Zooms go one level deep, so
Expand Down Expand Up @@ -108,8 +131,9 @@ Every diagnostic has a stable code, a YAML path, a line and usually a `hint`. In
| W104 | Sector list does not add up to the region size |
| W105 | Block name was split inside a word to fit the column |
| W106 | Text overlaps other text, or is wider than its block |
| W110 | `from-elf`: section outside every `--region`, placed at the top level |
| W110 | `from-elf`: section outside every memory region, placed at the top level |
| 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) |
| 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 @@ -121,7 +145,8 @@ Exit codes: `0` ok, `1` validation errors, `2` usage or IO error, `3` render err
- After an intended drawing change, review the SVG diff, then run
`MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_golden.py`.
- After an intended change to `from-elf` or the drawing, also review and regenerate the
real-firmware goldens: `MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py`.
docs/elf-testing.md describes them and how to add an image.
real-firmware goldens: `MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py
tests/test_linker.py`. docs/from-elf.md describes them and how to add an image or a
map.
- 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.
45 changes: 19 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,37 +66,30 @@ uv run memmap render layout.yaml -o layout.svg
| `memmap render CONFIG [-o OUT] [--format svg\|png\|pdf] [--json] [--strict] [--set key=value]` | Validate, then draw; `--strict` fails on warnings |
| `memmap check CONFIG [--json] [--strict]` | Validate only; `--strict` fails on warnings |
| `memmap describe CONFIG [--json]` | Resolved regions, blocks, labels and option origins |
| `memmap from-elf ELF [-o OUT] [--region id=start:size[:name]] [--min-size N] [--force] [--json] [--strict]` | Write a config from a linked ELF's sections, then check it |
| `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's sections, then check it |
| `memmap schema` | JSON Schema of the config |
| `memmap guide` | Print the agent guide, for agents using an installed copy |

### From an ELF file

`from-elf` writes a config from the allocated sections of a linked firmware image: `.text`,
`.data`, `.bss` and so on, each at its real address and size. The ELF does not record how big
flash and RAM are, so give them with `--region`, copying `ORIGIN` and `LENGTH` from the
linker script's `MEMORY` block, or from the `Memory Configuration` table of a GNU ld map file:
`from-elf` writes a config from the sections of a linked firmware image, each at its real
address and size. The ELF does not record how big flash and RAM are, so pass the map file the
linker writes, from GNU ld, Keil (armlink) or IAR:

```bash
uv run memmap from-elf build/firmware.elf -o layout.yaml --region flash=0x08000000:64K --region ram=0x20000000:20K
uv run memmap from-elf build/firmware.elf -o layout.yaml --map build/firmware.map
```

You get one column per region, titled with how much of it is used:
An lld map, as Rust and the LLVM Embedded Toolchain write, lists no regions. Give them with
`--region` instead, copying `ORIGIN` and `LENGTH` from the linker script's `MEMORY` block:

- Initialised data is drawn twice: in RAM where it runs, and in flash where startup code copies
it from. Each loadable segment is one flash block: `.data (load)`, with a note such as
`copied to RAM at 0x2000 0000`, or `RAM init data` when it holds several sections, as Zephyr's
do (`code and data` when it includes code).
- Gaps of at least `--min-size` (default 64 bytes) become Free blocks with their size, rounded
down and marked `≈` when not exact.
- In a region of more than 8 blocks, runs of smaller sections fold into one block that holds
them as children, and each such group gets a detail column beside it. Zooms go one level
deep: when sections outside every `--region` put the regions in a zoom of their own, their
groups list the section names in a note instead.
- Without `--region`, sections are drawn on the whole address space. Object files converted
from a `.hex` or `.bin` image, which keep their real addresses, are read too.
```bash
uv run memmap from-elf build/firmware.elf -o layout.yaml --region flash=0x08000000:64K --region ram=0x20000000:20K
```

The output is an ordinary config: edit it, then `render` it.
The output is an ordinary config: edit it, then `render` it. [docs/from-elf.md](docs/from-elf.md)
covers where each toolchain puts its map, what is read from it, what happens when it is not
enough, and how sections become blocks.

A minimal config:

Expand Down Expand Up @@ -128,6 +121,7 @@ set it on the expansion: `expand: [{ region: flash, title: Flash }]`.
## Learn more

- [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.
- [examples/](examples/): see the table below.
- `memmap schema`: every key with a description and an example. Point your editor's YAML extension
at it for completion.
Expand Down Expand Up @@ -177,16 +171,15 @@ regenerate them:
MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_golden.py
```

`from-elf` is also tested on eight real firmware images, kept as small header snapshots with
golden configs and drawings in `tests/golden/elf/`. After an intended change to the importer or
the drawing, review and regenerate those too:
`from-elf` is also tested on real firmware images and linker maps, kept as small snapshots with
goldens. After an intended change to the importer, the map readers or the drawing, review and
regenerate those too:

```bash
MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py
MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py tests/test_linker.py
```

[docs/elf-testing.md](docs/elf-testing.md) explains the approach, lists the images and shows
their maps.
[docs/from-elf.md](docs/from-elf.md#testing) explains the approach and shows the drawings.

Text is measured with a built-in Helvetica/Arial width table, so wrapping is slightly approximate
for other fonts.
Expand Down
121 changes: 0 additions & 121 deletions docs/elf-testing.md

This file was deleted.

Loading
Loading