Skip to content

Add from-elf: draw a linked firmware image from its ELF - #3

Merged
iharhl merged 3 commits into
mainfrom
feature/elf-import
Nov 4, 2026
Merged

iharhl merged 3 commits into
mainfrom
feature/elf-import

Conversation

@iharhl

@iharhl iharhl commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • New memmap from-elf ELF [-o OUT] [--region id=start:size[:name]] [--min-size N] [--force] [--json] [--strict]. It writes an ordinary config from a linked ELF's allocated sections, then checks it like check:
    • one column per --region, titled with its usage (TCM\n5.8 KB of 384 KB (2%))
    • Free blocks for gaps of --min-size or more (default 64 B), rounded down and marked ≈ when not exact
    • initialised data drawn again where it is stored, one block per loadable segment, with a note naming the bank it is copied to (copied to TCM at 0x1000 1000), or RAM init data when it holds several sections
    • in a region of more than 8 blocks, runs of small sections fold into a group with a detail column (--min-size 0 turns this off)
    • .debug_* and other non-allocated sections are skipped by their SHF_ALLOC flag, as is .tbss
    • new warnings W110 (section outside every --region) and W111 (section overlaps another, left out)
  • memmap/elf.py: a ~150-line reader for the file header, section headers and program headers, for 32- and 64-bit files in either byte order. No new dependency. It handles extended section/segment counts, .hex images converted to object files, and rejects core dumps and unlinked .o files. Truncated or corrupt files raise ElfError, which --json reports as E090.
  • Notes can span several lines (\n) and wrap after 20 ems. A multi-line note gets a rule beside it, and its height counts toward W102.
  • CI: actions/checkout v4 → v7 and astral-sh/setup-uv v6 → v10.3.3, which run on Node.js 24 and clear the Node.js 20 deprecation warning on every job.
  • Docs: README, AGENTS.md (task recipe, W110/W111, the --json contract) and a new docs/elf-testing.md.

Tests

  • Synthetic ELFs (tests/test_from_elf.py, built by tests/elf_builder.py): one rule per test, including a five-bank STM32H7-style layout.
  • Real builds (tests/fixtures/firmware*.elf): one firmware written by binutils in every class and byte order.
  • Real firmware (tests/test_elf_snapshots.py): eight images from Renode, kept as 3–6 KB header snapshots with golden configs and drawings. Ambiq Apollo4 is the one with three memory banks.

Test plan

  • uv run pytest: 489 passed
  • uv run mypy and uv run ruff check pass
  • Configs from the real Apollo4 ELF and from its snapshot are identical
  • Reviewed the golden SVGs that changed, rendered to PNG
  • Checks pass on this PR

🤖 Generated with Claude Code

iharhl and others added 3 commits November 4, 2026 17:27
`memmap from-elf firmware.elf --region flash=0x08000000:64K ...` reads the
allocated sections and loadable segments of a linked ELF and writes an
ordinary config, then checks it like `check`. Each --region gets a
column titled with its usage. Gaps of --min-size or more become Free
blocks, and initialised data is drawn again where it is stored in flash,
with a note naming the bank it is copied to. In a region of more than 8
blocks, runs of small sections fold into a group with a detail column.
New warnings: W110 (section outside every --region) and W111 (section
overlaps another, left out).

memmap/elf.py reads the file header, section headers and program
headers itself, for 32- and 64-bit files in either byte order, so there
is no new dependency. It gives the same fields as pyelftools on every
test image, and truncated or corrupt files raise ElfError, including
64-bit offsets too large for struct.

Notes can now span several lines and wrap after 20 ems. A multi-line
note gets a rule beside it, and its height counts toward W102.

Tests: synthetic ELFs, one rule each, including five memory banks;
firmware built by binutils in every class and byte order; and nine real
firmware images from Renode, kept as header snapshots with golden
configs and drawings. docs/elf-testing.md describes them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Its converted image imports to a single block, so it showed little in
the snapshot tests or the docs. The synthetic test for an image
converted to an object file still covers reading one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every job warned that actions/checkout@v4 and astral-sh/setup-uv@v6 target
the deprecated Node.js 20. checkout v7 and setup-uv v10.3.3 run on
Node.js 24. setup-uv no longer publishes major tags since v8, so it is
pinned to the exact release.

None of the breaking changes in between touch these workflows. Two change
behaviour: setup-uv v9 no longer prunes the uv cache by default, and v10
leaves the cache off for release events, so release.yml installs its
dependencies without one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@iharhl
iharhl merged commit c2a9c84 into main Nov 4, 2026
3 checks passed
@iharhl
iharhl deleted the feature/elf-import branch November 4, 2026 17:14
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