Skip to content

from-elf: read memory regions from linker maps (--map) - #5

Merged
iharhl merged 1 commit into
mainfrom
feature/linker-maps
Nov 4, 2026
Merged

iharhl merged 1 commit into
mainfrom
feature/linker-maps

Conversation

@iharhl

@iharhl iharhl commented Nov 4, 2026

Copy link
Copy Markdown
Owner

What changed

memmap from-elf firmware.elf --map firmware.map now takes the memory regions from the map file the linker writes, so most users no longer copy ORIGIN and LENGTH by hand.

Toolchain What is read
GNU ld (gcc, Zephyr, ESP-IDF, Pico SDK) The Memory Configuration table
Arm armlink (Keil) Each execution region's base, and its Max as the size
IAR ILINK The placement summary's ranges, named ROM, RAM or Memory by what is placed there
  • Format detection: memmap tells the formats apart by their content.
  • Combining with --region: a --region with a map region's id replaces it, and one with a new id adds a region.
  • Empty regions: a map region that holds no section stays in memory without a column.

Why maps only

Linker scripts, scatter files and .icf files are not read. A map already holds what the linker worked out, including preprocessing, INCLUDE and --defsym. That keeps one small reader per toolchain instead of an expression evaluator. An earlier draft of this branch also read MEMORY blocks with --ldscript; it was removed before this PR to keep the tool simpler.

When the map is not enough

  • Nothing to draw stops the import. This happens with an lld map (Rust, LLVM Embedded Toolchain), a GNU ld map without a MEMORY block, or an armlink map without a scatter file, when no --region stands in. from-elf writes nothing and exits 2 (E090). The hint names the --region specs to give, such as --region er_ro=0x08000000:SIZE. Failures from from-elf now carry hints in --json.
  • Left-out map regions get the new warning W112. A region is left out for no size, running past the address space, overlapping a --region or another map region, or being too small for a section. W112 fires only when the drawing loses something, and its hint gives the --region to use. Every left-out region is also noted in the config's header.
  • A section across a map region's edge no longer stops the import. That region is left out with W112 and the sections are placed again. A section across a --region's edge still stops the import.
  • Bad input is handled. A UTF-8 BOM is accepted, malformed IAR numbers give E090, reversed IAR ranges are skipped, and any other crash still prints one JSON object (E091).

For reviewers

  • One commit holds two things: the map feature and splitting memmap/from_elf.py into a package (importer, regions, writer, blocks, sizes, linker/). The ELF goldens in tests/golden/elf/ are unchanged, which shows the split kept the old behaviour.
  • docs/elf-testing.md is now docs/from-elf.md. It explains the feature in depth: each toolchain's map, a limits table, how sections become blocks, a Future ideas section (Rust and lld, armlink load regions, Arm Compiler 6, stable IAR ids), the tests, and the drawings. The README section is down to two commands and a link.
  • AGENTS.md has the new steps and W112. memmap guide prints it unchanged.
  • An independent review ran before this PR. Its findings are fixed here or listed under Future ideas.
  • Known limits:
    • Arm Compiler 6 maps are untested; the samples are armlink 5.05 and 5.06.
    • IAR ids follow address order: on an STM32F407, ram is the CCM and ram_2 the main SRAM.

Tests

  • Real maps: excerpts of 13 GNU ld, armlink and IAR maps, checked against tests/golden/linker/regions.json.
  • Fixture firmware: read with its own GNU ld map, which build.sh now writes. It gives the same config as the matching --region specs.
  • Synthetic cases:
    • lld maps
    • missing sizes, with the suggested specs followed through to a passing --strict run
    • overlaps
    • an armlink load image past its region
    • 32- and 64-bit address-space edges
    • files that are not maps

Locally, uv run pytest (570 passed), uv run mypy and uv run ruff check pass.

🤖 Generated with Claude Code

`memmap from-elf firmware.elf --map firmware.map` takes the memory
regions from the map file the linker writes, telling the format apart by
its content: the Memory Configuration table of GNU ld, the execution
regions of armlink (Keil), and the placement summary of IAR ILINK, whose
unnamed ranges are called ROM, RAM or Memory by what is placed there. A
--region with the id of a map region replaces it, and one with a new id
adds a region. A map region that holds no section stays in memory
without a column.

memmap reads maps, not linker scripts, scatter files or .icf files, as a
map holds what the linker worked out. When the map gives no region to
draw, as an lld map, a GNU ld map without MEMORY or an armlink map
without a scatter file does, and no --region stands in, from-elf writes
nothing and exits 2. Its hint names the --region specs to give, and
failures from from-elf now carry such hints in --json.

Map regions left out, for no size, size 0, running past the address
space, overlapping a --region or another map region, or being too small
for a section, are noted in the config's header. New warning W112
reports each one whose loss changes the drawing, with the --region to
give instead. A section across the edge of a map region leaves that
region out rather than stopping the import.

The from_elf module becomes a package, with the map readers in
from_elf/linker. docs/elf-testing.md becomes docs/from-elf.md, which
covers each toolchain's map, the limits, future ideas such as Rust and
lld, and the tests.

Tests: the readers on excerpts of 13 real GNU ld, armlink and IAR maps,
against tests/golden/linker/regions.json; the fixture firmware with its
own GNU ld map, which build.sh now writes; and synthetic cases for lld
maps, missing sizes, overlaps, address-space edges and files that are
not maps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@iharhl
iharhl merged commit 73e9d2f into main Nov 4, 2026
3 checks passed
@iharhl
iharhl deleted the feature/linker-maps branch November 4, 2026 20:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant