diff --git a/.github/workflows/default.yml b/.github/workflows/default.yml index 1ec5951..18359b6 100644 --- a/.github/workflows/default.yml +++ b/.github/workflows/default.yml @@ -18,8 +18,8 @@ jobs: matrix: python-version: ["3.10", "3.13"] steps: - - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v6 + - uses: actions/checkout@v7 + - uses: astral-sh/setup-uv@v10.3.3 with: python-version: ${{ matrix.python-version }} - run: uv sync --frozen @@ -32,8 +32,8 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v6 + - uses: actions/checkout@v7 + - uses: astral-sh/setup-uv@v10.3.3 with: python-version: "3.13" - run: uv build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a19c511..85eb5a7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -14,8 +14,8 @@ jobs: env: TAG: ${{ github.event.release.tag_name }} steps: - - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v6 + - uses: actions/checkout@v7 + - uses: astral-sh/setup-uv@v10.3.3 with: python-version: "3.13" diff --git a/AGENTS.md b/AGENTS.md index f04c773..24196cd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,20 @@ Run commands as `memmap ...` when it is installed, or `uv run memmap ...` inside 4. `memmap describe layout.yaml` -> confirm ranges and labels match intent. 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. + +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 +when W110 puts the regions in zooms of their own, their groups get a note instead. +`--min-size 0` turns folding off. + ## Rules - Never guess keys; run `memmap schema` when unsure. - Ranges are inclusive: end = start + size - 1. @@ -39,14 +53,16 @@ Run commands as `memmap ...` when it is installed, or `uv run memmap ...` inside - One-off change: memmap render layout.yaml --set 'view.columns[0].width=150' - 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) Quote `--set` values that contain `[` or `{`, since shells expand them. ## JSON output -With `--json`, `check` and `render` always print one object on stdout, for validation errors -and for usage and IO failures alike: `{"ok": ..., "diagnostics": [...]}`. `render` adds `output` -and `format` on success. `describe --json` prints the same object on failure. Only a mistake in -the command line itself, such as an unknown flag, is reported as plain text on stderr. +With `--json`, `check`, `render` and `from-elf` always print one object on stdout, for +validation errors and for usage and IO failures alike: `{"ok": ..., "diagnostics": [...]}`. +`render` adds `output` and `format` on success, `from-elf` adds `output` once it has written the +config. `describe --json` prints the same object on failure. Only a mistake in the command line +itself, such as an unknown flag, is reported as plain text on stderr. ## Checking the result `memmap describe layout.yaml --json` returns: @@ -87,11 +103,13 @@ Every diagnostic has a stable code, a YAML path, a line and usually a `hint`. In | E025 | Column expands into itself | | W100 | Region boundary not on a flash sector boundary | | W101 | Gap filled as reserved (only with `--verbose`) | -| W102 | Label text forced a block over `max_height` | +| W102 | Label or note text forced a block over `max_height` | | W103 | Region start not aligned to its size (needs `memory.check_alignment: true`) | | 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 | +| W111 | `from-elf`: section overlaps another one, left out | | 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) | @@ -102,5 +120,8 @@ Exit codes: `0` ok, `1` validation errors, `2` usage or IO error, `3` render err 3.10 and the latest supported version. - 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. - 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. diff --git a/README.md b/README.md index 98b0f1f..63e6672 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,38 @@ 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 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: + +```bash +uv run memmap from-elf build/firmware.elf -o layout.yaml --region flash=0x08000000:64K --region ram=0x20000000:20K +``` + +You get one column per region, titled with how much of it is used: + +- 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. + +The output is an ordinary config: edit it, then `render` it. + A minimal config: ```yaml @@ -148,6 +177,17 @@ 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: + +```bash +MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py +``` + +[docs/elf-testing.md](docs/elf-testing.md) explains the approach, lists the images and shows +their maps. + Text is measured with a built-in Helvetica/Arial width table, so wrapping is slightly approximate for other fonts. diff --git a/docs/elf-testing.md b/docs/elf-testing.md new file mode 100644 index 0000000..fe82deb --- /dev/null +++ b/docs/elf-testing.md @@ -0,0 +1,121 @@ +# Testing the ELF import + +`memmap from-elf` makes judgement calls: which sections to draw, which to fold, where free space +goes, what to call the flash copy of `.data`. Those are easy to get wrong on layouts nobody +thought of, so besides hand-made cases the tests run real firmware through the importer. + +## Test layers + +| Layer | Where | Covers | +| --- | --- | --- | +| Synthetic ELFs | `tests/test_from_elf.py`, built by `tests/elf_builder.py` | One rule per test: folding, free gaps, load images, several memory banks, ids, 64-bit, big-endian, converted images, bad files, the CLI | +| Real builds | `tests/fixtures/firmware*.elf`, from `tests/fixtures/elf_src/` | The reader on files binutils wrote: one firmware as 32- and 64-bit, little- and big-endian. `build.sh` rebuilds them with `arm-none-eabi-gcc` and GNU `objcopy` | +| Real firmware | `tests/test_elf_snapshots.py`, `tests/fixtures/elf_snapshots/` | Eight images from different toolchains, OSes and architectures, against golden configs and drawings | + +## Snapshots instead of ELF files + +The real images total 6.5 MB, mostly debug info memmap never reads, and they are other projects' +builds. So the repo keeps a snapshot of each instead: the section headers, the loadable segments, +the `--region` specs to import with, and the source URL and SHA-256. That is 3 to 6 KB of JSON, +with no code or data from the firmware. + +The test rebuilds each snapshot into a minimal ELF, imports it, and checks that the import reports +nothing, that the config matches `tests/golden/elf/.yaml` and passes `check --strict`, and +that its drawing matches `tests/golden/elf/.svg`. The configs from snapshots were identical +to those from the real files when the snapshots were made. + +Snapshots cannot catch quirks in how a toolchain writes the file itself, as the rebuilt files are +clean. The real builds and the synthetic tests cover the reader. + +## The images + +All come from [Renode](https://github.com/renode/renode), whose board scripts +(`scripts/single-node/*.resc`) load prebuilt firmware from `dl.antmicro.com`. Locally they live +in `build/elf/`, which git ignores. + +| Snapshot | Firmware | Regions | +| --- | --- | --- | +| `nrf52840_zephyr_shell` | Zephyr shell, nRF52840 (Cortex-M4) | flash 1M at 0, RAM 256K at 0x20000000 | +| `r52_zephyr_philosophers` | Zephyr philosophers, Cortex-R52 | DRAM 2G at 0 | +| `fe310_zephyr_shell` | Zephyr shell, SiFive FE310 (RISC-V), runs from SPI flash | SPI flash 12M at 0x20400000, DTIM 16K at 0x80000000 | +| `stm32f412_tock_kernel` | Tock (Rust) kernel, STM32F412 | flash 1M at 0x08000000, SRAM 256K at 0x20000000 | +| `msp430f2619_hello` | Hello world, MSP430F2619 (16-bit) | flash 0x1DF00 at 0x2100, RAM 4K at 0x1100 | +| `stm32f746_dartino_lines` | Dartino (Dart VM) demo, STM32F746 | flash 1M at 0x08000000, SRAM 320K at 0x20000000 | +| `stm32f4discovery` | STM32F4 Discovery demo, STM32F407 | flash 1M at 0x08000000, SRAM 128K at 0x20000000 | +| `apollo4_hello_uart` | AmbiqSuite hello world, Ambiq Apollo4 (Cortex-M4F) | MRAM 1952K at 0x18000, TCM 384K at 0x10000000, shared SRAM 1M at 0x10060000 | + +The region sizes are the chips' real flash and RAM, from datasheets and Renode's platform files +(`platforms/cpus/*.repl`), since the ELF does not record them. Where the firmware starts above +the bottom of its memory, the region starts there too: the FE310 shell runs from the user part of +SPI flash, and the Apollo4 application starts 96 KB into its 2 MB MRAM. + +## Refreshing and adding images + +`tests/fixtures/elf_snapshots/refresh.py` lists the images with their URL, description and +`--region` specs, and rewrites every snapshot whose ELF is in `build/elf/`. `--download` fetches +the missing ones first: + +```bash +uv run python tests/fixtures/elf_snapshots/refresh.py --download +``` + +To add an image, add it to `MANIFEST` in that script and run it. Then, as after any intended +change to the importer or the drawing, regenerate the goldens and review their diff: + +```bash +MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py +``` + +## The maps + +These are the goldens, so they always show what the current code draws. + +### nRF52840, Zephyr shell + +Two folded groups, each zoomed into, and one "RAM init data" block for the seven RAM sections +that startup code fills from flash. + +![nRF52840 Zephyr shell](../tests/golden/elf/nrf52840_zephyr_shell.svg) + +### Cortex-R52, Zephyr philosophers + +Three folded groups with a detail column each, in one 2 GB memory. + +![Cortex-R52 Zephyr philosophers](../tests/golden/elf/r52_zephyr_philosophers.svg) + +### FE310, Zephyr shell + +RISC-V running from SPI flash, with data in the 16 KB DTIM. + +![FE310 Zephyr shell](../tests/golden/elf/fe310_zephyr_shell.svg) + +### STM32F412, Tock kernel + +A 1-byte `.apps` section far up flash, with free space on both sides. + +![STM32F412 Tock kernel](../tests/golden/elf/stm32f412_tock_kernel.svg) + +### Apollo4, AmbiqSuite hello world + +Three banks: code in MRAM, data in TCM and in shared SRAM. Each bank's initial data is copied +from MRAM in a segment of its own, and each copy's note names the bank it goes to. + +![Apollo4 hello world](../tests/golden/elf/apollo4_hello_uart.svg) + +### MSP430F2619, hello world + +Small sections drawn in place, and the reset vector at 0xFFFE splitting flash in two. + +![MSP430F2619 hello world](../tests/golden/elf/msp430f2619_hello.svg) + +### STM32F746, Dartino lines + +A large `.data` copied from flash, and the stack and heap reserved as a section. + +![STM32F746 Dartino lines](../tests/golden/elf/stm32f746_dartino_lines.svg) + +### STM32F4 Discovery demo + +A conventional STM32 layout. + +![STM32F4 Discovery demo](../tests/golden/elf/stm32f4discovery.svg) diff --git a/memmap/cli.py b/memmap/cli.py index c45865b..6bc03e3 100644 --- a/memmap/cli.py +++ b/memmap/cli.py @@ -14,10 +14,13 @@ from .config import ConfigError from .describe import describe_data, describe_text from .diagnostics import Diagnostic +from .elf import ElfError, read_elf +from .from_elf import ImportProblem, import_elf, parse_region_spec from .pipeline import Result, run from .render.raster import RasterUnavailable, convert from .render.svg import render_svg from .schema import json_schema +from .units import parse_size # Process exit codes, documented in AGENTS.md. Success is 0. EXIT_VALIDATION = 1 @@ -240,6 +243,82 @@ def describe(config: Path, as_json: bool, sets: tuple[str, ...]) -> None: click.echo(describe_text(result)) +@app.command( + name="from-elf", + epilog=( + "\b\nExample:\n memmap from-elf firmware.elf -o layout.yaml " + "--region flash=0x08000000:64K --region ram=0x20000000:20K" + ), +) +@click.argument("elf", type=click.Path(path_type=Path)) +@click.option( + "-o", "--output", type=click.Path(path_type=Path), help="Config to write. Default: ELF.yaml." +) +@click.option( + "--region", + "regions", + multiple=True, + metavar="ID=START:SIZE[:NAME]", + help="A memory region, such as flash=0x08000000:64K:Flash (repeatable).", +) +@click.option( + "--min-size", + default="64", + show_default=True, + help="Fold runs of smaller sections into one block; smaller gaps get no Free block.", +) +@click.option("--force", is_flag=True, help="Overwrite the output if it exists.") +@json_option +@strict_option +def from_elf( + elf: Path, + output: Path | None, + regions: tuple[str, ...], + min_size: str, + force: bool, + as_json: bool, + strict: bool, +) -> None: + """Write a config from the allocated sections of an ELF file. + + ELF is a linked executable. Give each memory region with --region, as the ELF does not say + how big flash and RAM are; without any, sections are drawn on the whole address space. The + written config is then checked like `memmap check`. + """ + target = output or elf.with_suffix(".yaml") + if target.resolve() == elf.resolve(): + raise _fail(f"output {target} would overwrite the ELF", EXIT_USAGE, as_json) + if target.exists() and not force: + raise _fail(f"{target} exists, use --force to overwrite it", EXIT_USAGE, as_json) + try: + threshold = 0 if min_size.strip() == "0" else parse_size(min_size) + except ValueError as exc: + raise _fail(f"bad --min-size: {exc}", EXIT_USAGE, as_json) + try: + memories = [parse_region_spec(spec) for spec in regions] + except ImportProblem as exc: + raise _fail(str(exc), EXIT_USAGE, as_json) + try: + data = elf.read_bytes() + except OSError as exc: + raise _fail(f"cannot read {elf}: {exc}", EXIT_USAGE, as_json) + try: + imported = import_elf(read_elf(data), elf.name, memories, threshold) + except (ElfError, ImportProblem) as exc: + raise _fail(f"{elf}: {exc}", EXIT_USAGE, as_json) + _write(target, imported.text.encode("utf-8"), as_json) + result = _load(target, (), as_json=as_json) + result.diagnostics[:0] = imported.diagnostics + ok = _passes(result, strict) + if as_json: + _print_json(ok, result, output=str(target)) + else: + _print_diagnostics(result, target) + click.echo(str(target)) + if not ok: + raise Exit(EXIT_VALIDATION) + + @app.command(epilog="\b\nExample:\n memmap schema > memmap.schema.json") def schema() -> None: """Print the JSON Schema of the config.""" diff --git a/memmap/elf.py b/memmap/elf.py new file mode 100644 index 0000000..82e8a6f --- /dev/null +++ b/memmap/elf.py @@ -0,0 +1,155 @@ +"""A small ELF reader: the header, section headers and program headers, nothing more. + +memmap only needs where each section sits, so this avoids a dependency. It handles 32- and 64-bit +files in either byte order. +""" + +from __future__ import annotations + +import struct +from dataclasses import dataclass + +# Section header types and flags used by the importer. +SHT_NOBITS = 8 +SHF_ALLOC = 0x2 +SHF_TLS = 0x400 +PT_LOAD = 1 + +_ET_REL = 1 +_ET_CORE = 4 +_SHN_XINDEX = 0xFFFF +_PN_XNUM = 0xFFFF + +# Header layouts after e_ident, per ELF class: (file header, section header, program header). +_LAYOUTS = { + 32: ("HHIIIIIHHHHHH", "IIIIIIIIII", "IIIIIIII"), + 64: ("HHIQQQIHHHHHH", "IIQQQQIIQQ", "IIQQQQQQ"), +} +_IDENT_SIZE = 16 + + +class ElfError(ValueError): + """The file is not an ELF memmap can read.""" + + +@dataclass(frozen=True) +class Section: + """One section header. `address` is where the section runs (its VMA).""" + + name: str + kind: int + flags: int + address: int + offset: int + size: int + + @property + def allocated(self) -> bool: + """Whether the section occupies memory on the target.""" + return bool(self.flags & SHF_ALLOC) + + @property + def nobits(self) -> bool: + """Whether the section has no bytes in the file, like .bss.""" + return self.kind == SHT_NOBITS + + +@dataclass(frozen=True) +class Segment: + """One program header. `physical` is where its bytes are loaded (the LMA).""" + + kind: int + offset: int + virtual: int + physical: int + file_size: int + memory_size: int + + +@dataclass(frozen=True) +class Elf: + """What memmap reads from an ELF file.""" + + bits: int + sections: list[Section] + segments: list[Segment] + + +def _unpack(fmt: str, data: bytes, offset: int) -> tuple[int, ...]: + """Unpack one structure, reporting a short file as an ElfError. A 64-bit offset can be too + large for struct to take at all, which it reports as OverflowError.""" + try: + return struct.unpack_from(fmt, data, offset) + except (struct.error, OverflowError): + raise ElfError("file is truncated") from None + + +def _name(table: bytes, offset: int) -> str: + """A null-terminated string from a string table.""" + if offset >= len(table): + return "" + end = table.find(b"\0", offset) + return table[offset : end if end >= 0 else len(table)].decode("utf-8", "replace") + + +def _table( + data: bytes, fmt: str, offset: int, count: int, entry_size: int +) -> list[tuple[int, ...]]: + """Read `count` header entries of `entry_size` bytes each, starting at `offset`.""" + if count and entry_size < struct.calcsize(fmt): + raise ElfError(f"header entries of {entry_size} bytes are too small") + return [_unpack(fmt, data, offset + index * entry_size) for index in range(count)] + + +def read_elf(data: bytes) -> Elf: + """Parse an executable or shared ELF file, or an image converted to an object file. + Raises ElfError for anything else.""" + if data[:4] != b"\x7fELF": + raise ElfError("not an ELF file") + if len(data) < _IDENT_SIZE: + raise ElfError("file is truncated") + bits = {1: 32, 2: 64}.get(data[4]) + order = {1: "<", 2: ">"}.get(data[5]) + if bits is None or order is None: + raise ElfError("unknown ELF class or byte order") + header_fmt, section_fmt, segment_fmt = (order + fmt for fmt in _LAYOUTS[bits]) + header = _unpack(header_fmt, data, _IDENT_SIZE) + file_type, ph_offset, sh_offset = header[0], header[4], header[5] + ph_size, ph_count, sh_size, sh_count, sh_names = header[8:13] + if file_type == _ET_CORE: + raise ElfError("this is a core dump, not a firmware image") + + raw_sections: list[tuple[int, ...]] = [] + if sh_offset: + first = _table(data, section_fmt, sh_offset, 1, sh_size)[0] + if sh_count == 0: # more than 0xff00 sections: the count is in section 0 + sh_count = first[5] + if sh_names == _SHN_XINDEX: + sh_names = first[6] + if ph_count == _PN_XNUM: + ph_count = first[7] + raw_sections = _table(data, section_fmt, sh_offset, sh_count, sh_size) + + names = b"" + if raw_sections: + if sh_names >= len(raw_sections): + raise ElfError("section name table index is out of range") + table = raw_sections[sh_names] + names = data[table[4] : table[4] + table[5]] + + sections = [ + Section(_name(names, raw[0]), raw[1], raw[2], raw[3], raw[4], raw[5]) + for raw in raw_sections[1:] # section 0 is always empty + ] + # An unlinked object file has every section at address 0. One with real addresses, as + # objcopy makes from a .hex or .bin image, is drawn like an executable. + if file_type == _ET_REL and not any(s.allocated and s.address for s in sections): + raise ElfError("this is an object file (.o), link it into an executable first") + segments = [] + for raw in _table(data, segment_fmt, ph_offset, ph_count if ph_offset else 0, ph_size): + if bits == 32: + kind, offset, virtual, physical, file_size, memory_size = raw[:6] + else: # the 64-bit layout moves p_flags up to second place + kind, _, offset, virtual, physical, file_size, memory_size = raw[:7] + segments.append(Segment(kind, offset, virtual, physical, file_size, memory_size)) + return Elf(bits, sections, segments) diff --git a/memmap/from_elf.py b/memmap/from_elf.py new file mode 100644 index 0000000..3aa96b1 --- /dev/null +++ b/memmap/from_elf.py @@ -0,0 +1,530 @@ +"""Turn an ELF file into a memmap config: its allocated sections, placed in memory regions. + +The ELF says where each section runs and where its bytes are loaded from, but not how big flash +and RAM are; those come from `--region` specs. The result is ordinary YAML for the user to edit. +""" + +from __future__ import annotations + +import itertools +import json +import math +import re +from dataclasses import dataclass, field + +from .diagnostics import Diagnostic +from .elf import PT_LOAD, SHF_TLS, Elf, Section +from .units import diagnostic_address, format_address, parse_address, parse_size + +_ID_RE = re.compile(r"^[a-z0-9_]+$") +_NOTE_NAMES = 6 # section names a note lists before "+N more" +FOLD_OVER = 8 # a region with more blocks than this folds its runs of small sections +_SHF_EXECINSTR = 0x4 +COLUMN_WIDTH = 150 # px, room for section names such as .ARM.exidx and the usage title +_UNITS = ((1024**3, "GB"), (1024**2, "MB"), (1024, "KB")) + + +class ImportProblem(ValueError): + """The ELF and the `--region` specs do not fit together, or a spec is malformed.""" + + +@dataclass(frozen=True) +class MemorySpec: + """One memory region from `--region`: an id, a range and a display name.""" + + id: str + start: int + size: int + name: str + + @property + def end(self) -> int: + """Last address, inclusive.""" + return self.start + self.size - 1 + + +def parse_region_spec(text: str) -> MemorySpec: + """Parse `id=start:size[:name]`, such as `flash=0x08000000:64K:Internal flash`.""" + region_id, separator, rest = text.partition("=") + parts = rest.split(":", 2) + if not separator or len(parts) < 2: + raise ImportProblem(f"bad --region {text!r}, expected id=start:size[:name]") + region_id = region_id.strip() + if not _ID_RE.match(region_id): + raise ImportProblem(f"bad --region id {region_id!r}, use lowercase letters, digits and _") + try: + start, size = parse_address(parts[0]), parse_size(parts[1]) + except ValueError as exc: + raise ImportProblem(f"bad --region {text!r}: {exc}") from None + name = parts[2].strip() if len(parts) == 3 and parts[2].strip() else region_id.upper() + return MemorySpec(region_id, start, size, name) + + +@dataclass +class _Item: + """A block to write: a section, a load image, a folded group of small sections, or free + space. A group holds its sections as `children`; `expanded` gives it a detail column.""" + + id: str + name: str + start: int + size: int + note: str | None = None + free: bool = False + children: list[_Item] = field(default_factory=list) + expanded: bool = False + + @property + def end(self) -> int: + """Last address, inclusive.""" + return self.start + self.size - 1 + + +@dataclass +class _Bucket: + """The items placed in one memory region, or at the top level when `memory` is None.""" + + memory: MemorySpec | None + items: list[_Item] = field(default_factory=list) + + +@dataclass +class Imported: + """The generated YAML and what the import had to say about the ELF.""" + + text: str + diagnostics: list[Diagnostic] + + +class _Ids: + """Hands out unique region ids derived from section names.""" + + def __init__(self, taken: list[str]) -> None: + """Start with the ids that are already in use.""" + self.taken = set(taken) + + def make(self, text: str) -> str: + """A fresh id from `text`: lowercase, non-alphanumerics as _, suffixed when taken.""" + base = re.sub(r"[^a-z0-9]+", "_", text.lower()).strip("_") or "section" + candidate, number = base, 2 + while candidate in self.taken: + candidate, number = f"{base}_{number}", number + 1 + self.taken.add(candidate) + return candidate + + +def _check_memories(memories: list[MemorySpec]) -> None: + """Reject duplicate ids and overlapping regions among the `--region` specs.""" + seen: set[str] = set() + for memory in memories: + if memory.id in seen: + raise ImportProblem(f"--region {memory.id} is given twice") + seen.add(memory.id) + ordered = sorted(memories, key=lambda memory: memory.start) + for low, high in itertools.pairwise(ordered): + if high.start <= low.end: + raise ImportProblem(f"--region {low.id} and {high.id} overlap") + + +def _wanted(section: Section) -> bool: + """Whether a section takes space on the target. Thread-local .tbss only has a template.""" + if not section.allocated or section.size == 0: + return False + return not (section.nobits and section.flags & SHF_TLS) + + +def _approx_size(size: int) -> str: + """A size rounded to one decimal, for usage figures: 1.6 KB, 59.5 KB, 512 B.""" + for factor, suffix in _UNITS: + if size >= factor: + return f"{size / factor:.1f}".removesuffix(".0") + f" {suffix}" + return f"{size} B" + + +def _floor_size(size: int) -> str: + """A free size: exact when some unit shows it with one decimal (1920 KB, 4.5 KB), else + rounded down to three significant digits with ≈, so it never overstates (≈1.99 GB).""" + for factor, suffix in _UNITS: + value = size / factor + if value >= 1 and round(value, 1) == value: + return f"{value:.1f}".removesuffix(".0") + f" {suffix}" + for factor, suffix in _UNITS: + if size >= factor: + value = size / factor + decimals = 0 if value >= 100 else 1 if value >= 10 else 2 + floored = math.floor(value * 10**decimals) / 10**decimals + text = f"{floored:.{decimals}f}" + if "." in text: + text = text.rstrip("0").rstrip(".") + exact = floored * factor == size + return f"{'' if exact else '≈'}{text} {suffix}" + return f"{size} B" + + +def _name_list(names: list[str]) -> str: + """Section names for a note, cut short after _NOTE_NAMES.""" + shown = ", ".join(names[:_NOTE_NAMES]) + extra = len(names) - _NOTE_NAMES + return f"{shown}, +{extra} more" if extra > 0 else shown + + +class _Importer: + """Places the sections of one ELF into buckets, collecting diagnostics as it goes.""" + + def __init__(self, elf: Elf, memories: list[MemorySpec], min_size: int) -> None: + """Prepare one bucket per memory region and one for the top level.""" + self.elf = elf + self.memories = memories + self.min_size = min_size + self.ids = _Ids([memory.id for memory in memories]) + self.buckets = [_Bucket(memory) for memory in sorted(memories, key=lambda m: m.start)] + self.top = _Bucket(None) + self.used: dict[str, int] = {} # bytes taken in each memory region, before folding + self.diagnostics: list[Diagnostic] = [] + + def hex(self, value: int) -> str: + """An address at this ELF's width, the way diagnostics print it.""" + return diagnostic_address(value, self.elf.bits) + + def bucket_for(self, item: _Item) -> _Bucket: + """The memory region holding `item`, or the top level. An item that crosses a region + edge means the `--region` specs are wrong.""" + for bucket in self.buckets: + memory = bucket.memory + assert memory is not None + if memory.start <= item.start and item.end <= memory.end: + return bucket + if item.start <= memory.end and memory.start <= item.end: + raise ImportProblem( + f"{item.name} ({self.hex(item.start)} - {self.hex(item.end)}) crosses the " + f"edge of --region {memory.id} ({self.hex(memory.start)} - " + f"{self.hex(memory.end)}); check its start and size" + ) + if self.memories: + self.diagnostics.append( + Diagnostic( + "W110", + f"{item.name} ({self.hex(item.start)} - {self.hex(item.end)}) is outside " + "every --region, so it is placed at the top level", + hint="add a --region that covers it, or check the start and size of yours", + subject=item.id, + ) + ) + return self.top + + def place(self) -> None: + """Put every wanted section in a bucket where it runs, and each load image where it is + stored.""" + wanted = [section for section in self.elf.sections if _wanted(section)] + for section in wanted: + item = _Item(self.ids.make(section.name), section.name, section.address, section.size) + self.bucket_for(item).items.append(item) + for image in self.load_images(wanted): + self.bucket_for(image).items.append(image) + + def load_images(self, sections: list[Section]) -> list[_Item]: + """One block per loadable segment that is stored somewhere other than where it runs, + such as the initial values of .data. Startup code copies each in one piece.""" + images = [] + for segment in self.elf.segments: + if segment.kind != PT_LOAD or segment.file_size == 0: + continue + if segment.physical == segment.virtual: + continue + members = [ + section + for section in sections + if not section.nobits + and segment.offset <= section.offset < segment.offset + segment.file_size + ] + if not members: + continue + target = format_address(segment.virtual, self.elf.bits // 4) + names = [section.name for section in members] + if len(members) == 1: # with several banks, a bare address leaves the reader to look + bank = self.memory_at(segment.virtual) + where = f"{bank.name} at {target}" if bank else target + name, note = f"{names[0]} (load)", f"copied to {where}" + else: + name, note = self.image_name(segment.virtual, members), f"copied to {target}: " + note += _name_list(names) + images.append( + _Item(self.ids.make(name), name, segment.physical, segment.file_size, note=note) + ) + return images + + def memory_at(self, address: int) -> MemorySpec | None: + """The `--region` that holds `address`, if any.""" + return next((m for m in self.memories if m.start <= address <= m.end), None) + + def image_name(self, address: int, members: list[Section]) -> str: + """A name for a load image of several sections, after where it is copied to and what + it holds: RAM init data, or DTIM code and data when it includes code.""" + what = "code and data" if any(s.flags & _SHF_EXECINSTR for s in members) else "init data" + target = self.memory_at(address) + return f"{target.name} {what}" if target else what.capitalize() + + def drop_overlaps(self, bucket: _Bucket) -> None: + """Sort a bucket and leave out any item that overlaps the one before it.""" + kept: list[_Item] = [] + for item in sorted(bucket.items, key=lambda item: (item.start, -item.size)): + if kept and item.start <= kept[-1].end: + self.diagnostics.append( + Diagnostic( + "W111", + f"{item.name} overlaps {kept[-1].name}, so it is left out", + hint="overlays and NOLOAD sections can share addresses; add it by hand", + subject=item.id, + ) + ) + continue + kept.append(item) + bucket.items = kept + + def fold(self, bucket: _Bucket) -> None: + """Group each run of two or more consecutive sections under `min_size` into one block + that holds them as children. A gap of `min_size` or more ends a run, as it gets a Free + block of its own. A region of FOLD_OVER blocks or fewer draws every section in place.""" + if len(bucket.items) <= FOLD_OVER: + return + folded: list[_Item] = [] + run: list[_Item] = [] + + def flush() -> None: + """Move the pending run to `folded`, grouped when it holds more than one item.""" + if len(run) == 1: + folded.append(run[0]) + elif run: + start, end = run[0].start, run[-1].end + group = _Item( + self.ids.make("small_sections"), + f"{len(run)} small sections", + start, + end - start + 1, + note=_name_list([item.name for item in run]), + children=list(run), + ) + folded.append(group) + run.clear() + + for item in bucket.items: + if item.size < self.min_size: + if run and item.start - run[-1].end - 1 >= self.min_size: + flush() + run.append(item) + else: + flush() + folded.append(item) + flush() + bucket.items = folded + + def expand_groups(self) -> None: + """Give every group a detail column, one level deep. When the memory regions are + themselves zoomed out of a whole address space column, which happens when sections lie + outside them, their groups stay one block with a note, as that would be a second level.""" + zoomed_regions = bool(self.top.items) or not self.buckets + buckets = [self.top] if zoomed_regions else self.buckets + for bucket in buckets: + for item in bucket.items: + if item.children: + item.expanded = True + item.note = None # the detail column lists the sections + + def add_free(self, bucket: _Bucket) -> None: + """Add a Free block for each gap of at least `min_size` bytes in a memory region. + Smaller gaps stay unfilled, which draws them as an edge with both addresses.""" + memory = bucket.memory + assert memory is not None + threshold = max(self.min_size, 1) + items: list[_Item] = [] + cursor = memory.start + for item in [*bucket.items, None]: + limit = item.start if item is not None else memory.end + 1 + if limit - cursor >= threshold: + size = limit - cursor + name = f"Free\n{_floor_size(size)}" + items.append(_Item(self.ids.make(f"{memory.id}_free"), name, cursor, size, free=True)) + if item is not None: + items.append(item) + cursor = item.end + 1 + bucket.items = items + + def run(self) -> list[_Bucket]: + """Place, clean up and complete every bucket. Returns the memory region buckets.""" + self.place() + for bucket in [*self.buckets, self.top]: + self.drop_overlaps(bucket) + self.used = { + bucket.memory.id: sum(item.size for item in bucket.items) + for bucket in self.buckets + if bucket.memory is not None + } + if self.min_size > 0: + for bucket in [*self.buckets, self.top]: + self.fold(bucket) + self.expand_groups() + for bucket in self.buckets: + self.add_free(bucket) + return self.buckets + + +def _quote(text: str) -> str: + """A YAML double-quoted scalar. JSON strings are valid YAML.""" + return json.dumps(text, ensure_ascii=False) + + +def _comment_safe(text: str) -> str: + """`text` for a YAML comment: anything that could end the line becomes ?.""" + return "".join(char if char.isprintable() else "?" for char in text) + + +def _size_literal(size: int) -> str: + """A size in the shortest exact form: 64K, 1M, or plain bytes.""" + for factor, suffix in ((1024**3, "G"), (1024**2, "M"), (1024, "K")): + if size % factor == 0: + return f"{size // factor}{suffix}" + return str(size) + + +def _address_literal(value: int, bits: int) -> str: + """An address as zero-padded hex, such as 0x08000000.""" + return f"0x{value:0{bits // 4}X}" + + +def _item_fields(item: _Item, bits: int) -> list[str]: + """The keys of one region, as `key: value` strings.""" + fields = [f"id: {_quote(item.id)}", f"name: {_quote(item.name)}"] + if item.free: + fields.append("kind: reserved") + fields += [f"start: {_address_literal(item.start, bits)}", f"size: {_size_literal(item.size)}"] + if item.note: + fields.append(f"note: {_quote(item.note)}") + return fields + + +def _item_lines(item: _Item, bits: int, indent: str) -> list[str]: + """One region as list entry lines: a flow mapping on one line, or a block mapping with its + children one per line.""" + fields = _item_fields(item, bits) + if not item.children: + return [f"{indent}- {{ " + ", ".join(fields) + " }"] + lines = [f"{indent}- {fields[0]}"] + lines += [f"{indent} {field}" for field in fields[1:]] + lines.append(f"{indent} children:") + for child in item.children: + lines += _item_lines(child, bits, indent + " ") + return lines + + +def _usage_title(memory: MemorySpec, used: int) -> str: + """A column title: the region name, then how much of it the sections use.""" + percent = round(100 * used / memory.size) + if used < memory.size: + percent = min(percent, 99) # 99.6% is not full + shown = "<1" if percent == 0 and used else str(percent) + return f"{memory.name}\n{_approx_size(used)} of {_approx_size(memory.size)} ({shown}%)" + + +def _expansions(buckets: list[_Bucket], top: _Bucket) -> list[tuple[str, str]]: + """Region ids with a detail column of their own, with their titles.""" + found = [] + for bucket in [*buckets, top]: + for item in bucket.items: + if item.expanded: + where = bucket.memory.name if bucket.memory else "memory" + found.append((item.id, f"{item.name} in {where}")) + return found + + +def _write_yaml( + source: str, bits: int, buckets: list[_Bucket], top: _Bucket, used: dict[str, int] +) -> str: + """The config text, laid out like the examples: one line per section.""" + lines = [ + f"# Generated by `memmap from-elf` from {_comment_safe(source)}. Section ranges come from", + "# the ELF and memory regions from --region. Rename, merge or annotate blocks freely.", + "version: 1", + "", + "figure:", + f" title: {_quote(f'{source} memory map')}", + "", + "memory:", + ] + if bits == 64: + lines.append(" address_bits: 64") + lines += [ + " fill_gaps: none # gaps under --min-size show as a split edge", + " regions:", + ] + entries: list[tuple[int, list[str]]] = [] + for bucket in buckets: + memory = bucket.memory + assert memory is not None + block = [ + f" - id: {_quote(memory.id)}", + f" name: {_quote(memory.name)}", + f" start: {_address_literal(memory.start, bits)}", + f" size: {_size_literal(memory.size)}", + ] + if bucket.items: + block.append(" children:") + for item in bucket.items: + block += _item_lines(item, bits, " ") + entries.append((memory.start, block)) + entries += [(item.start, _item_lines(item, bits, " ")) for item in top.items] + for _, block in sorted(entries, key=lambda entry: entry[0]): + lines += block + + lines += [ + "", + "view:", + " defaults:", + " labels: { size: true }", + " columns:", + ] + expand: list[str] = [] + if buckets and not top.items: + for bucket in buckets: + memory = bucket.memory + assert memory is not None + title = _quote(_usage_title(memory, used[memory.id])) + lines.append( + f" - {{ id: {_quote(memory.id + '_col')}, root: {_quote(memory.id)}, title: {title}, " + f"width: {COLUMN_WIDTH} }}" + ) + else: # no regions, or sections outside them: show the whole address space + lines.append(f' - {{ id: all, root: "/", width: {COLUMN_WIDTH} }}') + for bucket in buckets: + memory = bucket.memory + assert memory is not None + title = _quote(_usage_title(memory, used[memory.id])) + expand.append(f" - {{ region: {_quote(memory.id)}, title: {title} }}") + for region, title in _expansions(buckets, top): # a column of its own, for its width + root, column = _quote(region), _quote(f"{region}_col") + lines.append(f" - {{ id: {column}, root: {root}, width: {COLUMN_WIDTH} }}") + expand.append(f" - {{ region: {root}, to: {column}, title: {_quote(title)} }}") + if expand: + lines += [" expand:", *expand] + lines += [ + "", + "style:", + " reserved: { show_label: true } # names the Free blocks", + "", + ] + return "\n".join(lines) + + +def import_elf( + elf: Elf, source: str, memories: list[MemorySpec], min_size: int = 64 +) -> Imported: + """Build a config from an ELF. `source` names the ELF in the header comment and title. + Raises ImportProblem when the sections and the memory regions do not fit together.""" + _check_memories(memories) + if not elf.sections: + raise ImportProblem(f"{source} has no section headers (stripped?), so nothing to draw") + importer = _Importer(elf, memories, min_size) + buckets = importer.run() + if not any(bucket.items for bucket in [*buckets, importer.top]): + raise ImportProblem(f"{source} has no allocated sections to draw") + text = _write_yaml(source, elf.bits, buckets, importer.top, importer.used) + return Imported(text, importer.diagnostics) diff --git a/memmap/layout/__init__.py b/memmap/layout/__init__.py index 9cfa208..cbd0e2b 100644 --- a/memmap/layout/__init__.py +++ b/memmap/layout/__init__.py @@ -12,13 +12,14 @@ from .columns import ( COLUMN_TITLE_GAP, LABEL_GAP, - NOTE_FONT_FACTOR, Block, ColumnLayout, assign_lanes, build_column, content_height, header_height, + note_indent, + note_size, place_horizontally, place_vertically, stretch_bands, @@ -38,6 +39,7 @@ MIN_TICK_SPACING = 3 # px, a block's ticks are dropped when any two would be closer than this MASK_PADDING = 2 # px around the patch of paper that hides a fan line behind an address label COLLISION_TOLERANCE = 1 # px, since text widths are approximate +NOTE_RULE_INSET = 3 # px, the rule beside a multi-line note stops this short of the block edges LEGEND_SWATCH = (16, 10) # px, width and height # Fills of the `color` palette, handed out in tree order and reused when they run out. @@ -204,14 +206,31 @@ def _draw_block(block: Block, layout: ColumnLayout, colors: dict[str, str]) -> l region=block.node.id, ) ) - if block.note: - note_size = size * NOTE_FONT_FACTOR + primitives += _draw_note(block, layout) + return primitives + + +def _draw_note(block: Block, layout: ColumnLayout) -> list[Primitive]: + """The note right of a block, one Text per line, centred on the block. A multi-line note + gets a rule along the block's right side, so it is clear which block it belongs to.""" + if not block.note_lines: + return [] + size = note_size(layout.options) + spacing = line_height(size) + count = len(block.note_lines) + first = block.y + block.h / 2 - spacing * (count - 1) / 2 + primitives: list[Primitive] = [] + if count > 1: + x = block.x + block.w + LABEL_GAP + inset = min(NOTE_RULE_INSET, block.h / 4) + primitives.append(Line(x, block.y + inset, x, block.y + block.h - inset, INK)) + for index, line in enumerate(block.note_lines): primitives.append( Text( - block.x + block.w + LABEL_GAP, - block.y + block.h / 2 + BASELINE_SHIFT * note_size, - block.note, - note_size, + block.x + block.w + note_indent(block), + first + index * spacing + BASELINE_SHIFT * size, + line, + size, anchor="start", role="note", column=layout.id, diff --git a/memmap/layout/columns.py b/memmap/layout/columns.py index dc5e3bb..849de5c 100644 --- a/memmap/layout/columns.py +++ b/memmap/layout/columns.py @@ -16,6 +16,8 @@ TEXT_INSET = 8 # px, taken off the column width when wrapping text inside a block LABEL_GAP = 8 # px, between a column and the labels or notes beside it NOTE_FONT_FACTOR = 0.85 # note size, relative to style.font_size +NOTE_WIDTH_EM = 20 # a note wraps after this many ems of its own font, 187 px at the default +NOTE_RULE_GAP = 6 # px, between the rule beside a multi-line note and its text LANE_STACK_GAP = 24 # px, between columns stacked in one lane MIN_FAN_ROOM = 16 # px of fan line kept clear of the next lane's left gutter COLUMN_TITLE_GAP = 6 # px, between a column title and the column @@ -38,7 +40,7 @@ class Block: band: int | None = None collapsed: bool = False lines: list[str] = field(default_factory=list) - note: str | None = None + note_lines: list[str] = field(default_factory=list) x: float = 0 y: float = 0 w: float = 0 @@ -116,15 +118,22 @@ def _block_name(block: Block, options: Options) -> str | None: return None +def note_size(options: Options) -> float: + """The font size of notes.""" + return options.style.font_size * NOTE_FONT_FACTOR + + def _block_text(block: Block, width: float, options: Options) -> None: - """Work out the lines inside the block and the note to its right.""" + """Work out the lines inside the block and the note lines to its right.""" if not block.show_name: return name = _block_name(block, options) block.lines = wrap(name, width, options.style.font_size) if name else [] if options.labels.size and not block.reserved: block.lines.append(format_size(block.display_size)) - block.note = block.node.note + note = block.node.note + size = note_size(options) + block.note_lines = wrap(note, NOTE_WIDTH_EM * size, size) if note else [] def _check_fit(blocks: list[Block], width: float, options: Options, out: list[Diagnostic]) -> None: @@ -142,7 +151,7 @@ def _check_fit(blocks: list[Block], width: float, options: Options, out: list[Di def _assign_heights(column: ColumnLayout, out: list[Diagnostic]) -> None: - """Set each block's height from its scale, growing it to fit its text (W102 past + """Set each block's height from its scale, growing it to fit its text and note (W102 past max_height). A reserved block over collapse_reserved_over collapses to min_height.""" blocks = column.blocks scale = column.options.scale @@ -155,16 +164,19 @@ def _assign_heights(column: ColumnLayout, out: list[Diagnostic]) -> None: block.collapsed = True override = override if override is not None else scale.min_height wanted = scaled_height(size, scale, total, override) - needed = text_height(len(block.lines), column.options.style.font_size) + needed = max( + text_height(len(block.lines), column.options.style.font_size), + text_height(len(block.note_lines), note_size(column.options)), + ) block.h = max(wanted, needed) if scale.max_height is not None and needed > scale.max_height: out.append( Diagnostic( "W102", - f"label text forced the block to {needed:g} px, over max_height " + f"text forced the block to {needed:g} px, over max_height " f"{scale.max_height:g}", block.node.path, - "shorten the name, widen the column, or raise max_height", + "shorten the name or note, widen the column, or raise max_height", block.node.id, ) ) @@ -262,12 +274,23 @@ def _measure_gutters(layout: ColumnLayout) -> None: left = width + LABEL_GAP if width else 0 if layout.view.spec.bands: left = max(left, text_width("00", ADDRESS_FONT_SIZE) + LABEL_GAP) - note_size = layout.options.style.font_size * NOTE_FONT_FACTOR - notes = [text_width(block.note, note_size) for block in layout.blocks if block.note] + notes = [note_width(block, layout.options) for block in layout.blocks if block.note_lines] layout.left_gutter = left layout.right_gutter = max(notes) + LABEL_GAP if notes else 0 +def note_indent(block: Block) -> float: + """How far a block's note text starts right of the block. A multi-line note has a rule + beside it, so it is clear which block it belongs to.""" + return LABEL_GAP + (NOTE_RULE_GAP if len(block.note_lines) > 1 else 0) + + +def note_width(block: Block, options: Options) -> float: + """The room a block's note takes right of the block, rule included.""" + size = note_size(options) + return note_indent(block) - LABEL_GAP + max(text_width(line, size) for line in block.note_lines) + + def dependency_order(plan: ViewPlan) -> list[ColumnView]: """Columns with each source before its targets, otherwise in definition order.""" targets: dict[str, list[ColumnView]] = {} diff --git a/memmap/schema.py b/memmap/schema.py index 4bfb41e..f007d60 100644 --- a/memmap/schema.py +++ b/memmap/schema.py @@ -196,7 +196,9 @@ class Region(Model): ) color: str | None = Field(default=None, description="Fill override.", examples=["#81b29a"]) note: str | None = Field( - default=None, description="Small text right of the block.", examples=["2 pages, A/B copy"] + default=None, + description="Small text right of the block. Long text wraps, \\n forces a line break.", + examples=["2 pages, A/B copy"], ) sectors: Sectors | None = Field( default=None, diff --git a/tests/elf_builder.py b/tests/elf_builder.py new file mode 100644 index 0000000..515e8ca --- /dev/null +++ b/tests/elf_builder.py @@ -0,0 +1,56 @@ +"""Build minimal ELF files for tests: headers only, no section contents.""" + +import struct + +from memmap.elf import SHF_ALLOC + +PROGBITS = 1 + + +def make_elf(sections, segments=(), bits=32, little=True, file_type=2): + """A minimal ELF with the given section and segment headers and no section contents. + Each section is (name, type, flags, address, size, offset); each segment is + (offset, virtual, physical, file_size, memory_size).""" + order = "<" if little else ">" + if bits == 32: + header_fmt, section_fmt, segment_fmt = "HHIIIIIHHHHHH", "IIIIIIIIII", "IIIIIIII" + else: + header_fmt, section_fmt, segment_fmt = "HHIQQQIHHHHHH", "IIQQQQIIQQ", "IIQQQQQQ" + header_size = 16 + struct.calcsize(order + header_fmt) + section_size = struct.calcsize(order + section_fmt) + segment_size = struct.calcsize(order + segment_fmt) + + names = b"\0" + name_offsets = [] + for section in [*sections, (".shstrtab",)]: + name_offsets.append(len(names)) + names += section[0].encode() + b"\0" + ph_offset = header_size + names_offset = ph_offset + len(segments) * segment_size + sh_offset = names_offset + len(names) + + def section_header(name, kind, flags, address, size, offset): + return struct.pack(order + section_fmt, name, kind, flags, address, offset, size, 0, 0, 1, 0) + + def segment_header(offset, virtual, physical, file_size, memory_size): + if bits == 32: + return struct.pack(order + segment_fmt, 1, offset, virtual, physical, file_size, memory_size, 5, 4) + return struct.pack(order + segment_fmt, 1, 5, offset, virtual, physical, file_size, memory_size, 4) + + count = len(sections) + 2 + ident = b"\x7fELF" + bytes([1 if bits == 32 else 2, 1 if little else 2, 1]) + bytes(9) + header = struct.pack( + order + header_fmt, file_type, 40, 1, 0, ph_offset if segments else 0, sh_offset, 0, + header_size, segment_size, len(segments), section_size, count, count - 1, + ) + data = ident + header + b"".join(segment_header(*segment) for segment in segments) + names + data += section_header(0, 0, 0, 0, 0, 0) + for name_offset, (_, kind, flags, address, size, offset) in zip(name_offsets, sections): + data += section_header(name_offset, kind, flags, address, size, offset) + data += section_header(name_offsets[-1], 3, 0, 0, len(names), names_offset) + return data + + +def code(name, address, size, offset=0x1000): + """An allocated PROGBITS section header tuple for make_elf.""" + return (name, PROGBITS, SHF_ALLOC, address, size, offset) diff --git a/tests/fixtures/elf_snapshots/apollo4_hello_uart.json b/tests/fixtures/elf_snapshots/apollo4_hello_uart.json new file mode 100644 index 0000000..4de7e41 --- /dev/null +++ b/tests/fixtures/elf_snapshots/apollo4_hello_uart.json @@ -0,0 +1,190 @@ +{ + "name": "apollo4_hello_uart", + "about": "AmbiqSuite hello world on Ambiq Apollo4 (Cortex-M4F): three banks, with data in TCM and shared SRAM, each copied from MRAM", + "url": "https://dl.antmicro.com/projects/renode/hello_world_uart.axf-s_307536-899c2682fa35d4bf27992bba5a0b5845ae331ba3", + "sha256": "dfece1279153b64e4418cfd8b3880fae46e2e9281bdf7dd32d88f15958859999", + "regions": [ + "mram=0x18000:1952K:MRAM (app)", + "tcm=0x10000000:384K:TCM", + "sram=0x10060000:1M:Shared SRAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": ".text", + "type": 1, + "flags": 6, + "address": "0x18000", + "size": 15608, + "offset": 32768 + }, + { + "name": ".stack", + "type": 8, + "flags": 3, + "address": "0x10000000", + "size": 4096, + "offset": 196608 + }, + { + "name": ".heap", + "type": 1, + "flags": 3, + "address": "0x10001000", + "size": 0, + "offset": 200704 + }, + { + "name": ".data", + "type": 1, + "flags": 3, + "address": "0x10001000", + "size": 32, + "offset": 69632 + }, + { + "name": ".bss", + "type": 8, + "flags": 3, + "address": "0x10001020", + "size": 1828, + "offset": 69664 + }, + { + "name": ".shared", + "type": 1, + "flags": 3, + "address": "0x10060000", + "size": 64, + "offset": 131072 + }, + { + "name": ".ARM.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 52, + "offset": 200704 + }, + { + "name": ".debug_info", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 51245, + "offset": 200756 + }, + { + "name": ".debug_abbrev", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 2560, + "offset": 252001 + }, + { + "name": ".debug_aranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 432, + "offset": 254561 + }, + { + "name": ".debug_line", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 5895, + "offset": 254993 + }, + { + "name": ".debug_str", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 32556, + "offset": 260888 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 73, + "offset": 293444 + }, + { + "name": ".debug_ranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 328, + "offset": 293517 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 1116, + "offset": 293848 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 7296, + "offset": 294964 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 4334, + "offset": 302260 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 181, + "offset": 306594 + } + ], + "segments": [ + { + "offset": 0, + "virtual": "0x10000", + "physical": "0x10000", + "file_size": 48376, + "memory_size": 48376 + }, + { + "offset": 69632, + "virtual": "0x10001000", + "physical": "0x1BCF8", + "file_size": 32, + "memory_size": 1860 + }, + { + "offset": 131072, + "virtual": "0x10060000", + "physical": "0x1BD18", + "file_size": 64, + "memory_size": 64 + }, + { + "offset": 196608, + "virtual": "0x10000000", + "physical": "0x10000000", + "file_size": 4096, + "memory_size": 4096 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/fe310_zephyr_shell.json b/tests/fixtures/elf_snapshots/fe310_zephyr_shell.json new file mode 100644 index 0000000..ba464bc --- /dev/null +++ b/tests/fixtures/elf_snapshots/fe310_zephyr_shell.json @@ -0,0 +1,214 @@ +{ + "name": "fe310_zephyr_shell", + "about": "Zephyr shell on SiFive FE310 (RISC-V), running from SPI flash", + "url": "https://dl.antmicro.com/projects/renode/zephyr-fe310-shell.elf-s_323068-cf87169150ecdb30ad5a14c87ae209c53dd3eca2", + "sha256": "15290d9da9e8798efe69defc71e928394733ae005d3f51dda8aaec449c3b464c", + "regions": [ + "flash=0x20400000:12M:SPI flash (user)", + "dtim=0x80000000:16K:DTIM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": "vector", + "type": 1, + "flags": 6, + "address": "0x20400000", + "size": 16, + "offset": 148 + }, + { + "name": "exceptions", + "type": 1, + "flags": 6, + "address": "0x20400010", + "size": 628, + "offset": 164 + }, + { + "name": "text", + "type": 1, + "flags": 7, + "address": "0x20400284", + "size": 17292, + "offset": 792 + }, + { + "name": "devconfig", + "type": 1, + "flags": 3, + "address": "0x20404610", + "size": 132, + "offset": 18084 + }, + { + "name": "rodata", + "type": 1, + "flags": 2, + "address": "0x20404694", + "size": 2452, + "offset": 18216 + }, + { + "name": "datas", + "type": 1, + "flags": 3, + "address": "0x80000000", + "size": 168, + "offset": 20668 + }, + { + "name": "initlevel", + "type": 1, + "flags": 3, + "address": "0x800000A8", + "size": 132, + "offset": 20836 + }, + { + "name": "initshell", + "type": 1, + "flags": 3, + "address": "0x8000012C", + "size": 24, + "offset": 20968 + }, + { + "name": "bss", + "type": 8, + "flags": 3, + "address": "0x80000148", + "size": 1336, + "offset": 21000 + }, + { + "name": "noinit", + "type": 8, + "flags": 3, + "address": "0x80000680", + "size": 6608, + "offset": 21000 + }, + { + "name": ".debug_info", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 120305, + "offset": 20992 + }, + { + "name": ".debug_abbrev", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 26865, + "offset": 141297 + }, + { + "name": ".debug_aranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 3064, + "offset": 168176 + }, + { + "name": ".debug_line", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 60979, + "offset": 171240 + }, + { + "name": ".debug_str", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 19827, + "offset": 232219 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 17, + "offset": 252046 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 9288, + "offset": 252064 + }, + { + "name": ".debug_loc", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 33596, + "offset": 261352 + }, + { + "name": ".debug_ranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 6688, + "offset": 294960 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 9248, + "offset": 301648 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 11035, + "offset": 310896 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 215, + "offset": 321931 + } + ], + "segments": [ + { + "offset": 148, + "virtual": "0x20400000", + "physical": "0x20400000", + "file_size": 20520, + "memory_size": 20520 + }, + { + "offset": 20668, + "virtual": "0x80000000", + "physical": "0x20405028", + "file_size": 324, + "memory_size": 324 + }, + { + "offset": 21000, + "virtual": "0x80000148", + "physical": "0x80000148", + "file_size": 0, + "memory_size": 7944 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/msp430f2619_hello.json b/tests/fixtures/elf_snapshots/msp430f2619_hello.json new file mode 100644 index 0000000..28c693d --- /dev/null +++ b/tests/fixtures/elf_snapshots/msp430f2619_hello.json @@ -0,0 +1,188 @@ +{ + "name": "msp430f2619_hello", + "about": "Hello world on MSP430F2619 (16-bit), reset vector at the top of flash", + "url": "https://dl.antmicro.com/projects/renode/msp430f2619-hello_world.elf-s_7912-e951b1bdd3bb562397ca9da8da88722c503507a3", + "sha256": "03c4beb276acfbb62e48ed611f38cb7e39c234bc3fa08c088f8850dade06745b", + "regions": [ + "flash=0x2100:0x1DF00:Flash", + "ram=0x1100:4K:RAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": "__reset_vector", + "type": 1, + "flags": 2, + "address": "0xFFFE", + "size": 2, + "offset": 798 + }, + { + "name": ".lower.rodata", + "type": 1, + "flags": 1, + "address": "0x2100", + "size": 0, + "offset": 800 + }, + { + "name": ".rodata", + "type": 1, + "flags": 2, + "address": "0x2100", + "size": 80, + "offset": 212 + }, + { + "name": ".rodata2", + "type": 1, + "flags": 1, + "address": "0x2150", + "size": 0, + "offset": 800 + }, + { + "name": ".data", + "type": 1, + "flags": 3, + "address": "0x1100", + "size": 0, + "offset": 800 + }, + { + "name": ".bss", + "type": 8, + "flags": 3, + "address": "0x1100", + "size": 2, + "offset": 292 + }, + { + "name": ".noinit", + "type": 1, + "flags": 1, + "address": "0x1102", + "size": 0, + "offset": 800 + }, + { + "name": ".heap", + "type": 8, + "flags": 3, + "address": "0x1102", + "size": 4, + "offset": 294 + }, + { + "name": ".lowtext", + "type": 1, + "flags": 6, + "address": "0x2150", + "size": 24, + "offset": 292 + }, + { + "name": ".lower.text", + "type": 1, + "flags": 1, + "address": "0x2168", + "size": 0, + "offset": 800 + }, + { + "name": ".text", + "type": 1, + "flags": 6, + "address": "0x2168", + "size": 480, + "offset": 316 + }, + { + "name": ".upper.text", + "type": 1, + "flags": 1, + "address": "0x10000", + "size": 0, + "offset": 800 + }, + { + "name": ".MSP430.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 23, + "offset": 800 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 57, + "offset": 823 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 4848, + "offset": 880 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 1312, + "offset": 5728 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 151, + "offset": 7040 + } + ], + "segments": [ + { + "offset": 0, + "virtual": "0x202C", + "physical": "0x202C", + "file_size": 292, + "memory_size": 292 + }, + { + "offset": 0, + "virtual": "0x1100", + "physical": "0x2150", + "file_size": 0, + "memory_size": 2 + }, + { + "offset": 2, + "virtual": "0x1102", + "physical": "0x2150", + "file_size": 0, + "memory_size": 4 + }, + { + "offset": 292, + "virtual": "0x2150", + "physical": "0x2150", + "file_size": 504, + "memory_size": 504 + }, + { + "offset": 798, + "virtual": "0xFFFE", + "physical": "0xFFFE", + "file_size": 2, + "memory_size": 2 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/nrf52840_zephyr_shell.json b/tests/fixtures/elf_snapshots/nrf52840_zephyr_shell.json new file mode 100644 index 0000000..e807e97 --- /dev/null +++ b/tests/fixtures/elf_snapshots/nrf52840_zephyr_shell.json @@ -0,0 +1,302 @@ +{ + "name": "nrf52840_zephyr_shell", + "about": "Zephyr shell on nRF52840 (Cortex-M4): many small sections, one RAM init image", + "url": "https://dl.antmicro.com/projects/renode/renode-nrf52840-zephyr_shell_module.elf-gf8d05cf-s_1310072-c00fbffd6b65c6238877c4fe52e8228c2a38bf1f", + "sha256": "596906f502af17463c02c57e5a6ba526d4b0ea29e68463d5a046e1edda5a19cb", + "regions": [ + "flash=0x0:1M:Flash", + "ram=0x20000000:256K:RAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": "rom_start", + "type": 1, + "flags": 7, + "address": "0x0", + "size": 256, + "offset": 192 + }, + { + "name": "text", + "type": 1, + "flags": 6, + "address": "0x100", + "size": 49376, + "offset": 448 + }, + { + "name": ".ARM.exidx", + "type": 1879048193, + "flags": 130, + "address": "0xC1E0", + "size": 8, + "offset": 49824 + }, + { + "name": "initlevel", + "type": 1, + "flags": 2, + "address": "0xC1E8", + "size": 120, + "offset": 49832 + }, + { + "name": "sw_isr_table", + "type": 1, + "flags": 3, + "address": "0xC260", + "size": 384, + "offset": 49952 + }, + { + "name": "log_const_sections", + "type": 1, + "flags": 2, + "address": "0xC3E0", + "size": 96, + "offset": 50336 + }, + { + "name": "log_backends_sections", + "type": 1, + "flags": 2, + "address": "0xC440", + "size": 32, + "offset": 50432 + }, + { + "name": "shell_area", + "type": 1, + "flags": 2, + "address": "0xC460", + "size": 48, + "offset": 50464 + }, + { + "name": "shell_root_cmds_sections", + "type": 1, + "flags": 2, + "address": "0xC490", + "size": 112, + "offset": 50512 + }, + { + "name": "rodata", + "type": 1, + "flags": 2, + "address": "0xC500", + "size": 10936, + "offset": 50624 + }, + { + "name": ".ramfunc", + "type": 1, + "flags": 1, + "address": "0x20000000", + "size": 0, + "offset": 62236 + }, + { + "name": "datas", + "type": 1, + "flags": 3, + "address": "0x20000000", + "size": 372, + "offset": 61560 + }, + { + "name": "devices", + "type": 1, + "flags": 2, + "address": "0x20000174", + "size": 116, + "offset": 61932 + }, + { + "name": "log_dynamic_sections", + "type": 1, + "flags": 3, + "address": "0x200001E8", + "size": 48, + "offset": 62048 + }, + { + "name": "k_timer_area", + "type": 1, + "flags": 3, + "address": "0x20000218", + "size": 56, + "offset": 62096 + }, + { + "name": "k_mutex_area", + "type": 1, + "flags": 3, + "address": "0x20000250", + "size": 20, + "offset": 62152 + }, + { + "name": "k_msgq_area", + "type": 1, + "flags": 3, + "address": "0x20000264", + "size": 40, + "offset": 62172 + }, + { + "name": "k_sem_area", + "type": 1, + "flags": 3, + "address": "0x2000028C", + "size": 24, + "offset": 62212 + }, + { + "name": "bss", + "type": 8, + "flags": 3, + "address": "0x200002A8", + "size": 4142, + "offset": 62248 + }, + { + "name": "noinit", + "type": 8, + "flags": 3, + "address": "0x200012E0", + "size": 8144, + "offset": 62248 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 50, + "offset": 62236 + }, + { + "name": ".debug_aranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 8216, + "offset": 62288 + }, + { + "name": ".debug_info", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 561067, + "offset": 70504 + }, + { + "name": ".debug_abbrev", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 84915, + "offset": 631571 + }, + { + "name": ".debug_line", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 196601, + "offset": 716486 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 21284, + "offset": 913088 + }, + { + "name": ".debug_str", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 58864, + "offset": 934372 + }, + { + "name": ".debug_loc", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 203162, + "offset": 993236 + }, + { + "name": ".debug_ranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 40392, + "offset": 1196400 + }, + { + "name": ".ARM.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 49, + "offset": 1236792 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 43536, + "offset": 1236844 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 27941, + "offset": 1280380 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 391, + "offset": 1308321 + } + ], + "segments": [ + { + "offset": 192, + "virtual": "0x0", + "physical": "0x0", + "file_size": 61368, + "memory_size": 61368 + }, + { + "offset": 61560, + "virtual": "0x20000000", + "physical": "0xEFB8", + "file_size": 676, + "memory_size": 676 + }, + { + "offset": 62248, + "virtual": "0x200002A8", + "physical": "0x200002A8", + "file_size": 0, + "memory_size": 12296 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/r52_zephyr_philosophers.json b/tests/fixtures/elf_snapshots/r52_zephyr_philosophers.json new file mode 100644 index 0000000..28790b3 --- /dev/null +++ b/tests/fixtures/elf_snapshots/r52_zephyr_philosophers.json @@ -0,0 +1,269 @@ +{ + "name": "r52_zephyr_philosophers", + "about": "Zephyr philosophers on Cortex-R52, all in one 2 GB DRAM", + "url": "https://dl.antmicro.com/projects/renode/fvp_baser_aemv8r_aarch32--zephyr-philosophers.elf-s_500280-b9bbb31c64dec3f3273535be657b8e4d7ca182f9", + "sha256": "f65dfa8c76d41caa63252c71eb3f2a0bf6abdae3cdc6a4dc83ea3be25a2fbfea", + "regions": [ + "dram=0x0:2G:DRAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": "rom_start", + "type": 1, + "flags": 6, + "address": "0x0", + "size": 60, + "offset": 180 + }, + { + "name": "text", + "type": 1, + "flags": 6, + "address": "0x3C", + "size": 25348, + "offset": 240 + }, + { + "name": ".ARM.exidx", + "type": 1879048193, + "flags": 130, + "address": "0x6340", + "size": 8, + "offset": 25588 + }, + { + "name": "rodata_start", + "type": 8, + "flags": 3, + "address": "0x6348", + "size": 56, + "offset": 25596 + }, + { + "name": "initlevel", + "type": 1, + "flags": 2, + "address": "0x6380", + "size": 32, + "offset": 25600 + }, + { + "name": "devices", + "type": 1, + "flags": 2, + "address": "0x63A0", + "size": 24, + "offset": 25632 + }, + { + "name": "sw_isr_table", + "type": 1, + "flags": 3, + "address": "0x63B8", + "size": 1024, + "offset": 25656 + }, + { + "name": "device_handles", + "type": 1, + "flags": 2, + "address": "0x67B8", + "size": 6, + "offset": 26680 + }, + { + "name": "log_const_sections", + "type": 1, + "flags": 2, + "address": "0x67C0", + "size": 24, + "offset": 26688 + }, + { + "name": "zephyr_dbg_info", + "type": 1, + "flags": 3, + "address": "0x67D8", + "size": 64, + "offset": 26712 + }, + { + "name": "rodata", + "type": 1, + "flags": 2, + "address": "0x6818", + "size": 2792, + "offset": 26776 + }, + { + "name": "bss", + "type": 8, + "flags": 3, + "address": "0x7300", + "size": 1654, + "offset": 29568 + }, + { + "name": "noinit", + "type": 8, + "flags": 3, + "address": "0x7978", + "size": 16896, + "offset": 29568 + }, + { + "name": "datas", + "type": 1, + "flags": 3, + "address": "0xBB78", + "size": 44, + "offset": 29568 + }, + { + "name": "device_states", + "type": 1, + "flags": 3, + "address": "0xBBA4", + "size": 2, + "offset": 29612 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 32, + "offset": 29618 + }, + { + "name": ".debug_aranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 3272, + "offset": 29656 + }, + { + "name": ".debug_info", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 221284, + "offset": 32928 + }, + { + "name": ".debug_abbrev", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 28444, + "offset": 254212 + }, + { + "name": ".debug_line", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 71675, + "offset": 282656 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 7076, + "offset": 354332 + }, + { + "name": ".debug_str", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 20816, + "offset": 361408 + }, + { + "name": ".debug_loc", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 71039, + "offset": 382224 + }, + { + "name": ".debug_ranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 14504, + "offset": 453264 + }, + { + "name": ".ARM.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 51, + "offset": 467768 + }, + { + "name": ".last_section", + "type": 1, + "flags": 2, + "address": "0xBBA6", + "size": 4, + "offset": 29614 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 17104, + "offset": 467820 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 13828, + "offset": 484924 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 326, + "offset": 498752 + } + ], + "segments": [ + { + "offset": 180, + "virtual": "0x0", + "physical": "0x0", + "file_size": 25416, + "memory_size": 25472 + }, + { + "offset": 25600, + "virtual": "0x6380", + "physical": "0x6380", + "file_size": 3968, + "memory_size": 22520 + }, + { + "offset": 29568, + "virtual": "0xBB78", + "physical": "0xBB78", + "file_size": 50, + "memory_size": 50 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/refresh.py b/tests/fixtures/elf_snapshots/refresh.py new file mode 100644 index 0000000..ea980d7 --- /dev/null +++ b/tests/fixtures/elf_snapshots/refresh.py @@ -0,0 +1,147 @@ +"""Rewrite the ELF header snapshots in this folder from the real ELF files in build/elf/. + +A snapshot keeps only what `memmap from-elf` reads: the section headers and the loadable +segments, plus the `--region` specs to import with. No code or data from the firmware is kept, +so the snapshots are small and carry none of the firmware's own files. docs/elf-testing.md +explains how the tests use them. + + uv run python tests/fixtures/elf_snapshots/refresh.py # all snapshots + uv run python tests/fixtures/elf_snapshots/refresh.py --download # fetch missing ELFs first + +After a refresh, regenerate the goldens with +MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py and review their diff. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import sys +import urllib.request +from pathlib import Path + +from memmap.elf import PT_LOAD, read_elf + +HERE = Path(__file__).parent +ROOT = HERE.parent.parent.parent +ELF_DIR = ROOT / "build" / "elf" +RENODE = "https://dl.antmicro.com/projects/renode/" + +# name: where to download the ELF, what it shows, and the memory regions to import it with. +# Region sizes are the chip's real flash and RAM, from its datasheet or Renode's platform file. +MANIFEST: dict[str, dict[str, object]] = { + "nrf52840_zephyr_shell": { + "url": RENODE + "renode-nrf52840-zephyr_shell_module.elf-gf8d05cf-s_1310072" + "-c00fbffd6b65c6238877c4fe52e8228c2a38bf1f", + "about": "Zephyr shell on nRF52840 (Cortex-M4): many small sections, one RAM init image", + "regions": ["flash=0x0:1M:Flash", "ram=0x20000000:256K:RAM"], + }, + "fe310_zephyr_shell": { + "url": RENODE + "zephyr-fe310-shell.elf-s_323068-cf87169150ecdb30ad5a14c87ae209c53dd3eca2", + "about": "Zephyr shell on SiFive FE310 (RISC-V), running from SPI flash", + "regions": ["flash=0x20400000:12M:SPI flash (user)", "dtim=0x80000000:16K:DTIM"], + }, + "msp430f2619_hello": { + "url": RENODE + "msp430f2619-hello_world.elf-s_7912-e951b1bdd3bb562397ca9da8da88722c503507a3", + "about": "Hello world on MSP430F2619 (16-bit), reset vector at the top of flash", + "regions": ["flash=0x2100:0x1DF00:Flash", "ram=0x1100:4K:RAM"], + }, + "stm32f412_tock_kernel": { + "url": RENODE + "stm32f412gdiscovery--tock_kernel.elf-s_3392340" + "-6da12cfcd5c4180b60ce7bf2ad32f019c9e8216e", + "about": "Tock (Rust) kernel on STM32F412, with an app area far up flash", + "regions": ["flash=0x08000000:1M:Flash", "sram=0x20000000:256K:SRAM"], + }, + "r52_zephyr_philosophers": { + "url": RENODE + "fvp_baser_aemv8r_aarch32--zephyr-philosophers.elf-s_500280" + "-b9bbb31c64dec3f3273535be657b8e4d7ca182f9", + "about": "Zephyr philosophers on Cortex-R52, all in one 2 GB DRAM", + "regions": ["dram=0x0:2G:DRAM"], + }, + "stm32f4discovery": { + "url": RENODE + "stm32f4discovery.elf-s_445441-827a0dedd3790f4559d7518320006613768b5e72", + "about": "STM32F4 Discovery demo (STM32F407), a classic CubeMX-style layout", + "regions": ["flash=0x08000000:1M:Flash", "sram=0x20000000:128K:SRAM"], + }, + "stm32f746_dartino_lines": { + "url": RENODE + "dartino-lines.elf-s_486816-cd8876ab9de60af779f4429dfe16c79bf831b84d", + "about": "Dartino (Dart VM) lines demo on STM32F746", + "regions": ["flash=0x08000000:1M:Flash", "sram=0x20000000:320K:SRAM"], + }, + "apollo4_hello_uart": { + "url": RENODE + "hello_world_uart.axf-s_307536-899c2682fa35d4bf27992bba5a0b5845ae331ba3", + "about": "AmbiqSuite hello world on Ambiq Apollo4 (Cortex-M4F): three banks, with data in " + "TCM and shared SRAM, each copied from MRAM", + # The 2 MB MRAM starts at 0, the application at 0x18000. + "regions": [ + "mram=0x18000:1952K:MRAM (app)", + "tcm=0x10000000:384K:TCM", + "sram=0x10060000:1M:Shared SRAM", + ], + }, +} + + +def snapshot(name: str, entry: dict[str, object], data: bytes) -> dict[str, object]: + """The snapshot of one ELF: its source, regions, header fields, sections and segments.""" + elf = read_elf(data) + return { + "name": name, + "about": entry["about"], + "url": entry["url"], + "sha256": hashlib.sha256(data).hexdigest(), + "regions": entry["regions"], + "bits": elf.bits, + "little_endian": data[5] == 1, + "file_type": int.from_bytes(data[16:18], "little" if data[5] == 1 else "big"), + "sections": [ + { + "name": s.name, + "type": s.kind, + "flags": s.flags, + "address": f"0x{s.address:X}", + "size": s.size, + "offset": s.offset, + } + for s in elf.sections + ], + "segments": [ # only loadable ones, the importer reads no others + { + "offset": s.offset, + "virtual": f"0x{s.virtual:X}", + "physical": f"0x{s.physical:X}", + "file_size": s.file_size, + "memory_size": s.memory_size, + } + for s in elf.segments + if s.kind == PT_LOAD + ], + } + + +def main() -> int: + """Refresh every snapshot whose ELF is in build/elf/. Returns the exit code.""" + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--download", action="store_true", help="fetch missing ELFs first") + args = parser.parse_args() + ELF_DIR.mkdir(parents=True, exist_ok=True) + missing = [] + for name, entry in MANIFEST.items(): + file = ELF_DIR / f"{name}.elf" + if not file.exists() and args.download: + print(f"downloading {name}") + urllib.request.urlretrieve(str(entry["url"]), file) + if not file.exists(): + missing.append(name) + continue + text = json.dumps(snapshot(name, entry, file.read_bytes()), indent=2) + "\n" + (HERE / f"{name}.json").write_text(text, encoding="utf-8", newline="\n") + print(f"wrote {name}.json") + for name in missing: + print(f"skipped {name}: build/elf/{name}.elf is missing", file=sys.stderr) + return 1 if missing else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/fixtures/elf_snapshots/stm32f412_tock_kernel.json b/tests/fixtures/elf_snapshots/stm32f412_tock_kernel.json new file mode 100644 index 0000000..33c135d --- /dev/null +++ b/tests/fixtures/elf_snapshots/stm32f412_tock_kernel.json @@ -0,0 +1,221 @@ +{ + "name": "stm32f412_tock_kernel", + "about": "Tock (Rust) kernel on STM32F412, with an app area far up flash", + "url": "https://dl.antmicro.com/projects/renode/stm32f412gdiscovery--tock_kernel.elf-s_3392340-6da12cfcd5c4180b60ce7bf2ad32f019c9e8216e", + "sha256": "bb2e0c9a23d28e5066af605ef3da6cd96ff3d45004011c6fcc7cad273f8adf82", + "regions": [ + "flash=0x08000000:1M:Flash", + "sram=0x20000000:256K:SRAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": ".stack", + "type": 8, + "flags": 3, + "address": "0x20000000", + "size": 8192, + "offset": 308 + }, + { + "name": ".text", + "type": 1, + "flags": 22, + "address": "0x8000000", + "size": 99516, + "offset": 512 + }, + { + "name": ".ARM.exidx", + "type": 1879048193, + "flags": 130, + "address": "0x80184BC", + "size": 16, + "offset": 100028 + }, + { + "name": ".storage", + "type": 1, + "flags": 2, + "address": "0x80184CC", + "size": 0, + "offset": 100044 + }, + { + "name": ".apps", + "type": 1, + "flags": 2, + "address": "0x8030000", + "size": 1, + "offset": 100352 + }, + { + "name": ".relocate", + "type": 1, + "flags": 3, + "address": "0x20002000", + "size": 40, + "offset": 100864 + }, + { + "name": ".sram", + "type": 8, + "flags": 3, + "address": "0x20002028", + "size": 65496, + "offset": 100904 + }, + { + "name": ".debug_loc", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 323337, + "offset": 100904 + }, + { + "name": ".debug_abbrev", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 5008, + "offset": 424241 + }, + { + "name": ".debug_info", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 1186046, + "offset": 429249 + }, + { + "name": ".debug_aranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 7552, + "offset": 1615296 + }, + { + "name": ".debug_ranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 83344, + "offset": 1622848 + }, + { + "name": ".debug_str", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 617334, + "offset": 1706192 + }, + { + "name": ".debug_pubnames", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 231974, + "offset": 2323526 + }, + { + "name": ".debug_pubtypes", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 569173, + "offset": 2555500 + }, + { + "name": ".ARM.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 48, + "offset": 3124673 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 16148, + "offset": 3124724 + }, + { + "name": ".debug_line", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 160794, + "offset": 3140872 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 147, + "offset": 3301666 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 25520, + "offset": 3301816 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 241, + "offset": 3327336 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 63843, + "offset": 3327577 + } + ], + "segments": [ + { + "offset": 512, + "virtual": "0x8000000", + "physical": "0x8000000", + "file_size": 99516, + "memory_size": 99516 + }, + { + "offset": 100028, + "virtual": "0x80184BC", + "physical": "0x80184BC", + "file_size": 16, + "memory_size": 16 + }, + { + "offset": 100352, + "virtual": "0x8030000", + "physical": "0x8030000", + "file_size": 1, + "memory_size": 1 + }, + { + "offset": 100864, + "virtual": "0x20002000", + "physical": "0x80184CC", + "file_size": 40, + "memory_size": 40 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/stm32f4discovery.json b/tests/fixtures/elf_snapshots/stm32f4discovery.json new file mode 100644 index 0000000..000e58f --- /dev/null +++ b/tests/fixtures/elf_snapshots/stm32f4discovery.json @@ -0,0 +1,183 @@ +{ + "name": "stm32f4discovery", + "about": "STM32F4 Discovery demo (STM32F407), a classic CubeMX-style layout", + "url": "https://dl.antmicro.com/projects/renode/stm32f4discovery.elf-s_445441-827a0dedd3790f4559d7518320006613768b5e72", + "sha256": "a25bd1bf148fd0ba3f98085ae86585b5b7199554669a3c509efab6fe238ae198", + "regions": [ + "flash=0x08000000:1M:Flash", + "sram=0x20000000:128K:SRAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": ".isr_vector", + "type": 1, + "flags": 3, + "address": "0x8000000", + "size": 392, + "offset": 32768 + }, + { + "name": ".text", + "type": 1, + "flags": 6, + "address": "0x8000188", + "size": 77680, + "offset": 33160 + }, + { + "name": ".ARM", + "type": 1879048193, + "flags": 130, + "address": "0x80130F8", + "size": 8, + "offset": 110840 + }, + { + "name": ".data", + "type": 1, + "flags": 3, + "address": "0x20000000", + "size": 2716, + "offset": 131072 + }, + { + "name": ".bss", + "type": 8, + "flags": 3, + "address": "0x20000A9C", + "size": 22212, + "offset": 133788 + }, + { + "name": "._user_heap_stack", + "type": 8, + "flags": 3, + "address": "0x20006160", + "size": 1024, + "offset": 133788 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 31, + "offset": 133788 + }, + { + "name": ".ARM.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 55, + "offset": 133819 + }, + { + "name": ".debug_info", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 120272, + "offset": 133874 + }, + { + "name": ".debug_abbrev", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 24653, + "offset": 254146 + }, + { + "name": ".debug_aranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 2256, + "offset": 278800 + }, + { + "name": ".debug_line", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 28197, + "offset": 281056 + }, + { + "name": ".debug_str", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 8026, + "offset": 309253 + }, + { + "name": ".debug_loc", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 76069, + "offset": 317279 + }, + { + "name": ".debug_ranges", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 3520, + "offset": 393348 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 3764, + "offset": 396868 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 206, + "offset": 400632 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 25152, + "offset": 401640 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 18649, + "offset": 426792 + } + ], + "segments": [ + { + "offset": 32768, + "virtual": "0x8000000", + "physical": "0x8000000", + "file_size": 78080, + "memory_size": 78080 + }, + { + "offset": 131072, + "virtual": "0x20000000", + "physical": "0x8013100", + "file_size": 2716, + "memory_size": 25952 + } + ] +} diff --git a/tests/fixtures/elf_snapshots/stm32f746_dartino_lines.json b/tests/fixtures/elf_snapshots/stm32f746_dartino_lines.json new file mode 100644 index 0000000..129682c --- /dev/null +++ b/tests/fixtures/elf_snapshots/stm32f746_dartino_lines.json @@ -0,0 +1,158 @@ +{ + "name": "stm32f746_dartino_lines", + "about": "Dartino (Dart VM) lines demo on STM32F746", + "url": "https://dl.antmicro.com/projects/renode/dartino-lines.elf-s_486816-cd8876ab9de60af779f4429dfe16c79bf831b84d", + "sha256": "e764ffa7bbe0bdfef136d0f868e322eb0d253a48824dbcb1cba09cf7158ff452", + "regions": [ + "flash=0x08000000:1M:Flash", + "sram=0x20000000:320K:SRAM" + ], + "bits": 32, + "little_endian": true, + "file_type": 2, + "sections": [ + { + "name": ".isr_vector", + "type": 1, + "flags": 2, + "address": "0x8000000", + "size": 456, + "offset": 65536 + }, + { + "name": ".text", + "type": 1, + "flags": 6, + "address": "0x80001D0", + "size": 158288, + "offset": 66000 + }, + { + "name": ".rodata", + "type": 1, + "flags": 2, + "address": "0x8026C20", + "size": 29008, + "offset": 224288 + }, + { + "name": ".ARM", + "type": 1879048193, + "flags": 130, + "address": "0x802DD70", + "size": 8, + "offset": 253296 + }, + { + "name": ".init_array", + "type": 14, + "flags": 3, + "address": "0x802DD78", + "size": 56, + "offset": 253304 + }, + { + "name": ".fini_array", + "type": 15, + "flags": 3, + "address": "0x802DDB0", + "size": 4, + "offset": 253360 + }, + { + "name": ".data", + "type": 1, + "flags": 3, + "address": "0x20000000", + "size": 37928, + "offset": 262144 + }, + { + "name": ".bss", + "type": 8, + "flags": 3, + "address": "0x20009428", + "size": 23276, + "offset": 300072 + }, + { + "name": "._user_heap_stack", + "type": 8, + "flags": 3, + "address": "0x2000EF14", + "size": 1540, + "offset": 323348 + }, + { + "name": ".ARM.attributes", + "type": 1879048195, + "flags": 0, + "address": "0x0", + "size": 48, + "offset": 300072 + }, + { + "name": ".comment", + "type": 1, + "flags": 48, + "address": "0x0", + "size": 110, + "offset": 300120 + }, + { + "name": ".debug_frame", + "type": 1, + "flags": 0, + "address": "0x0", + "size": 46524, + "offset": 300232 + }, + { + "name": ".shstrtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 149, + "offset": 486025 + }, + { + "name": ".symtab", + "type": 2, + "flags": 0, + "address": "0x0", + "size": 78624, + "offset": 346756 + }, + { + "name": ".strtab", + "type": 3, + "flags": 0, + "address": "0x0", + "size": 60645, + "offset": 425380 + } + ], + "segments": [ + { + "offset": 65536, + "virtual": "0x8000000", + "physical": "0x8000000", + "file_size": 187828, + "memory_size": 187828 + }, + { + "offset": 262144, + "virtual": "0x20000000", + "physical": "0x802DDB4", + "file_size": 37928, + "memory_size": 61204 + }, + { + "offset": 323348, + "virtual": "0x2000EF14", + "physical": "0x80371DC", + "file_size": 0, + "memory_size": 1540 + } + ] +} diff --git a/tests/fixtures/elf_src/build.sh b/tests/fixtures/elf_src/build.sh new file mode 100755 index 0000000..028a311 --- /dev/null +++ b/tests/fixtures/elf_src/build.sh @@ -0,0 +1,19 @@ +#!/bin/sh +# Rebuilds the real ELF fixtures in tests/fixtures/. Tests use the committed files. +# firmware.elf 32-bit little-endian, from arm-none-eabi-gcc +# firmware_be.elf 32-bit big-endian, the same code built with -mbig-endian +# firmware64.elf 64-bit little-endian, firmware.elf converted by GNU objcopy +# firmware64_be.elf 64-bit big-endian, firmware_be.elf converted by GNU objcopy +# They come from binutils, not from memmap's own code, so they check the reader independently. +# Needs arm-none-eabi-gcc, and a GNU objcopy with the elf64 targets (Homebrew's binutils) as +# $OBJCOPY, default objcopy. +set -eu +cd "$(dirname "$0")" +OBJCOPY=${OBJCOPY:-objcopy} +FLAGS="-mcpu=cortex-m4 -mthumb -Os -nostdlib -ffreestanding -Wl,--build-id=none -T firmware.ld" +arm-none-eabi-gcc $FLAGS -o ../firmware.elf firmware.c +arm-none-eabi-gcc $FLAGS -mbig-endian -o ../firmware_be.elf firmware.c +arm-none-eabi-strip --strip-debug ../firmware.elf ../firmware_be.elf +# objcopy moves the empty ._stack load address and says so; that segment has no bytes in flash. +"$OBJCOPY" -O elf64-little ../firmware.elf ../firmware64.elf 2>/dev/null +"$OBJCOPY" -O elf64-big ../firmware_be.elf ../firmware64_be.elf 2>/dev/null diff --git a/tests/fixtures/elf_src/firmware.c b/tests/fixtures/elf_src/firmware.c new file mode 100644 index 0000000..23d088a --- /dev/null +++ b/tests/fixtures/elf_src/firmware.c @@ -0,0 +1,31 @@ +/* Test firmware for the from-elf fixture. Built by build.sh; the code never runs. */ +#include + +extern uint32_t _sidata, _sdata, _edata, _sbss, _ebss, _estack; + +static const char banner[] = "memmap from-elf fixture firmware, version 1.0"; +static const uint16_t table[600] = {1, 2, 3}; +uint32_t counters[16] = {1}; +uint8_t rx_buffer[4096]; + +void reset_handler(void); + +__attribute__((section(".isr_vector"), used)) +static void (*const vectors[48])(void) = {(void (*)(void))&_estack, reset_handler}; + +static uint32_t mix(uint32_t value) { + for (int i = 0; i < 600; i++) { + value = value * 31u + table[i] + (uint8_t)banner[i % sizeof banner]; + } + return value; +} + +void reset_handler(void) { + uint32_t *src = &_sidata; + for (uint32_t *dst = &_sdata; dst < &_edata;) *dst++ = *src++; + for (uint32_t *dst = &_sbss; dst < &_ebss;) *dst++ = 0; + for (;;) { + counters[0] = mix(counters[0]); + rx_buffer[counters[0] % sizeof rx_buffer]++; + } +} diff --git a/tests/fixtures/elf_src/firmware.ld b/tests/fixtures/elf_src/firmware.ld new file mode 100644 index 0000000..a4f47be --- /dev/null +++ b/tests/fixtures/elf_src/firmware.ld @@ -0,0 +1,20 @@ +/* Minimal Cortex-M layout for the from-elf test fixture. */ +MEMORY +{ + FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 64K + RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 20K +} + +ENTRY(reset_handler) + +SECTIONS +{ + .isr_vector : { KEEP(*(.isr_vector)) } > FLASH + .text : { *(.text*) } > FLASH + .rodata : { . = ALIGN(4); *(.rodata*) } > FLASH + .ARM.exidx : { *(.ARM.exidx*) } > FLASH + .data : { . = ALIGN(4); _sdata = .; *(.data*) _edata = .; } > RAM AT > FLASH + _sidata = LOADADDR(.data); + .bss (NOLOAD) : { . = ALIGN(4); _sbss = .; *(.bss*) *(COMMON) _ebss = .; } > RAM + ._stack (NOLOAD) : { . = ALIGN(8); . = . + 2K; _estack = .; } > RAM +} diff --git a/tests/fixtures/firmware.elf b/tests/fixtures/firmware.elf new file mode 100755 index 0000000..f5da976 Binary files /dev/null and b/tests/fixtures/firmware.elf differ diff --git a/tests/fixtures/firmware64.elf b/tests/fixtures/firmware64.elf new file mode 100755 index 0000000..efa65c5 Binary files /dev/null and b/tests/fixtures/firmware64.elf differ diff --git a/tests/fixtures/firmware64_be.elf b/tests/fixtures/firmware64_be.elf new file mode 100755 index 0000000..73284a9 Binary files /dev/null and b/tests/fixtures/firmware64_be.elf differ diff --git a/tests/fixtures/firmware_be.elf b/tests/fixtures/firmware_be.elf new file mode 100755 index 0000000..d432b71 Binary files /dev/null and b/tests/fixtures/firmware_be.elf differ diff --git a/tests/golden/elf/apollo4_hello_uart.svg b/tests/golden/elf/apollo4_hello_uart.svg new file mode 100644 index 0000000..c5aae8c --- /dev/null +++ b/tests/golden/elf/apollo4_hello_uart.svg @@ -0,0 +1,56 @@ + + + +apollo4_hello_uart.elf memory map +0x0001 8000 +0x0001 BCF8 +0x0001 BD18 +0x0001 BD58 +0x001F FFFF +MRAM (app) +15.3 KB of 1.9 MB (1%) +0x1000 0000 +0x1000 1000 +0x1000 1020 +0x1000 1744 +0x1005 FFFF +TCM +5.8 KB of 384 KB (2%) +0x1006 0000 +0x1006 0040 +0x1015 FFFF +Shared SRAM +64 B of 1 MB (<1%) + +.text +15608 B + +.data (load) +32 B +copied to TCM at 0x1000 1000 + +.shared (load) +64 B +copied to Shared SRAM at 0x1006 0000 + +Free +≈1.89 MB + +.stack +4 KB + +.data +32 B + +.bss +1828 B + +Free +≈378 KB + +.shared +64 B + +Free +≈1023 KB + diff --git a/tests/golden/elf/apollo4_hello_uart.yaml b/tests/golden/elf/apollo4_hello_uart.yaml new file mode 100644 index 0000000..0c1d0eb --- /dev/null +++ b/tests/golden/elf/apollo4_hello_uart.yaml @@ -0,0 +1,46 @@ +# Generated by `memmap from-elf` from apollo4_hello_uart.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "apollo4_hello_uart.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "mram" + name: "MRAM (app)" + start: 0x00018000 + size: 1952K + children: + - { id: "text", name: ".text", start: 0x00018000, size: 15608 } + - { id: "data_load", name: ".data (load)", start: 0x0001BCF8, size: 32, note: "copied to TCM at 0x1000 1000" } + - { id: "shared_load", name: ".shared (load)", start: 0x0001BD18, size: 64, note: "copied to Shared SRAM at 0x1006 0000" } + - { id: "mram_free", name: "Free\n≈1.89 MB", kind: reserved, start: 0x0001BD58, size: 1983144 } + - id: "tcm" + name: "TCM" + start: 0x10000000 + size: 384K + children: + - { id: "stack", name: ".stack", start: 0x10000000, size: 4K } + - { id: "data", name: ".data", start: 0x10001000, size: 32 } + - { id: "bss", name: ".bss", start: 0x10001020, size: 1828 } + - { id: "tcm_free", name: "Free\n≈378 KB", kind: reserved, start: 0x10001744, size: 387260 } + - id: "sram" + name: "Shared SRAM" + start: 0x10060000 + size: 1M + children: + - { id: "shared", name: ".shared", start: 0x10060000, size: 64 } + - { id: "sram_free", name: "Free\n≈1023 KB", kind: reserved, start: 0x10060040, size: 1048512 } + +view: + defaults: + labels: { size: true } + columns: + - { id: "mram_col", root: "mram", title: "MRAM (app)\n15.3 KB of 1.9 MB (1%)", width: 150 } + - { id: "tcm_col", root: "tcm", title: "TCM\n5.8 KB of 384 KB (2%)", width: 150 } + - { id: "sram_col", root: "sram", title: "Shared SRAM\n64 B of 1 MB (<1%)", width: 150 } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/fe310_zephyr_shell.svg b/tests/golden/elf/fe310_zephyr_shell.svg new file mode 100644 index 0000000..00fc729 --- /dev/null +++ b/tests/golden/elf/fe310_zephyr_shell.svg @@ -0,0 +1,67 @@ + + + +fe310_zephyr_shell.elf memory map +0x2040 0000 +0x2040 0010 +0x2040 0284 +0x2040 4610 +0x2040 4694 +0x2040 5028 +0x2040 516C +0x20FF FFFF +SPI flash (user) +20.4 KB of 12 MB (<1%) +0x8000 0000 +0x8000 00A8 +0x8000 012C +0x8000 0148 +0x8000 0143 +0x8000 0680 +0x8000 2050 +0x8000 3FFF +DTIM +8.1 KB of 16 KB (50%) + +vector +16 B + +exceptions +628 B + +text +17292 B + +devconfig +132 B + +rodata +2452 B + +DTIM init data +324 B + +copied to 0x8000 0000: datas, initlevel, +initshell + +Free +≈11.9 MB + +datas +168 B + +initlevel +132 B + +initshell +24 B + +bss +1336 B + +noinit +6608 B + +Free +≈7.92 KB + diff --git a/tests/golden/elf/fe310_zephyr_shell.yaml b/tests/golden/elf/fe310_zephyr_shell.yaml new file mode 100644 index 0000000..aab9a46 --- /dev/null +++ b/tests/golden/elf/fe310_zephyr_shell.yaml @@ -0,0 +1,43 @@ +# Generated by `memmap from-elf` from fe310_zephyr_shell.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "fe310_zephyr_shell.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "flash" + name: "SPI flash (user)" + start: 0x20400000 + size: 12M + children: + - { id: "vector", name: "vector", start: 0x20400000, size: 16 } + - { id: "exceptions", name: "exceptions", start: 0x20400010, size: 628 } + - { id: "text", name: "text", start: 0x20400284, size: 17292 } + - { id: "devconfig", name: "devconfig", start: 0x20404610, size: 132 } + - { id: "rodata", name: "rodata", start: 0x20404694, size: 2452 } + - { id: "dtim_init_data", name: "DTIM init data", start: 0x20405028, size: 324, note: "copied to 0x8000 0000: datas, initlevel, initshell" } + - { id: "flash_free", name: "Free\n≈11.9 MB", kind: reserved, start: 0x2040516C, size: 12562068 } + - id: "dtim" + name: "DTIM" + start: 0x80000000 + size: 16K + children: + - { id: "datas", name: "datas", start: 0x80000000, size: 168 } + - { id: "initlevel", name: "initlevel", start: 0x800000A8, size: 132 } + - { id: "initshell", name: "initshell", start: 0x8000012C, size: 24 } + - { id: "bss", name: "bss", start: 0x80000148, size: 1336 } + - { id: "noinit", name: "noinit", start: 0x80000680, size: 6608 } + - { id: "dtim_free", name: "Free\n≈7.92 KB", kind: reserved, start: 0x80002050, size: 8112 } + +view: + defaults: + labels: { size: true } + columns: + - { id: "flash_col", root: "flash", title: "SPI flash (user)\n20.4 KB of 12 MB (<1%)", width: 150 } + - { id: "dtim_col", root: "dtim", title: "DTIM\n8.1 KB of 16 KB (50%)", width: 150 } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/msp430f2619_hello.svg b/tests/golden/elf/msp430f2619_hello.svg new file mode 100644 index 0000000..1820be8 --- /dev/null +++ b/tests/golden/elf/msp430f2619_hello.svg @@ -0,0 +1,47 @@ + + + +msp430f2619_hello.elf memory map +0x0000 1100 +0x0000 1102 +0x0000 1106 +0x0000 20FF +RAM +6 B of 4 KB (<1%) +0x0000 2100 +0x0000 2150 +0x0000 2168 +0x0000 2348 +0x0000 FFFE +0x0001 0000 +0x0001 FFFF +Flash +586 B of 119.8 KB (<1%) + +.bss +2 B + +.heap +4 B + +Free +≈3.99 KB + +.rodata +80 B + +.lowtext +24 B + +.text +480 B + +Free +≈55.1 KB + +__reset_vector +2 B + +Free +64 KB + diff --git a/tests/golden/elf/msp430f2619_hello.yaml b/tests/golden/elf/msp430f2619_hello.yaml new file mode 100644 index 0000000..ba467f1 --- /dev/null +++ b/tests/golden/elf/msp430f2619_hello.yaml @@ -0,0 +1,39 @@ +# Generated by `memmap from-elf` from msp430f2619_hello.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "msp430f2619_hello.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "ram" + name: "RAM" + start: 0x00001100 + size: 4K + children: + - { id: "bss", name: ".bss", start: 0x00001100, size: 2 } + - { id: "heap", name: ".heap", start: 0x00001102, size: 4 } + - { id: "ram_free", name: "Free\n≈3.99 KB", kind: reserved, start: 0x00001106, size: 4090 } + - id: "flash" + name: "Flash" + start: 0x00002100 + size: 122624 + children: + - { id: "rodata", name: ".rodata", start: 0x00002100, size: 80 } + - { id: "lowtext", name: ".lowtext", start: 0x00002150, size: 24 } + - { id: "text", name: ".text", start: 0x00002168, size: 480 } + - { id: "flash_free", name: "Free\n≈55.1 KB", kind: reserved, start: 0x00002348, size: 56502 } + - { id: "reset_vector", name: "__reset_vector", start: 0x0000FFFE, size: 2 } + - { id: "flash_free_2", name: "Free\n64 KB", kind: reserved, start: 0x00010000, size: 64K } + +view: + defaults: + labels: { size: true } + columns: + - { id: "ram_col", root: "ram", title: "RAM\n6 B of 4 KB (<1%)", width: 150 } + - { id: "flash_col", root: "flash", title: "Flash\n586 B of 119.8 KB (<1%)", width: 150 } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/nrf52840_zephyr_shell.svg b/tests/golden/elf/nrf52840_zephyr_shell.svg new file mode 100644 index 0000000..8c48f10 --- /dev/null +++ b/tests/golden/elf/nrf52840_zephyr_shell.svg @@ -0,0 +1,130 @@ + + + +nrf52840_zephyr_shell.elf memory map + + + + +0x0000 0000 +0x0000 0100 +0x0000 C1E0 +0x0000 C1E8 +0x0000 C260 +0x0000 C3E0 +0x0000 C440 +0x0000 C490 +0x0000 C500 +0x0000 EFB8 +0x0000 F25C +0x000F FFFF +Flash +60.6 KB of 1 MB (6%) +0x2000 0000 +0x2000 0174 +0x2000 01E8 +0x2000 02A8 +0x2000 02A3 +0x2000 12E0 +0x2000 12D5 +0x2000 32B0 +0x2003 FFFF +RAM +12.7 KB of 256 KB (5%) + +0x0000 C440 + +0x0000 C460 + +0x0000 C48F +2 small sections in Flash + +0x2000 01E8 + +0x2000 0218 + +0x2000 0250 + +0x2000 0264 + +0x2000 028C + +0x2000 02A3 +5 small sections in RAM + +rom_start +256 B + +text +49376 B + +.ARM.exidx +8 B + +initlevel +120 B + +sw_isr_table +384 B + +log_const_sections +96 B + +2 small sections +80 B + +shell_root_cmds_sections +112 B + +rodata +10936 B + +RAM init data +676 B + +copied to 0x2000 0000: datas, devices, +log_dynamic_sections, k_timer_area, +k_mutex_area, k_msgq_area, +1 more + +Free +≈963 KB + +datas +372 B + +devices +116 B + +5 small sections +188 B + +bss +4142 B + +noinit +8144 B + +Free +≈243 KB + +log_backends_sections +32 B + +shell_area +48 B + +log_dynamic_sections +48 B + +k_timer_area +56 B + +k_mutex_area +20 B + +k_msgq_area +40 B + +k_sem_area +24 B + diff --git a/tests/golden/elf/nrf52840_zephyr_shell.yaml b/tests/golden/elf/nrf52840_zephyr_shell.yaml new file mode 100644 index 0000000..dbe0f47 --- /dev/null +++ b/tests/golden/elf/nrf52840_zephyr_shell.yaml @@ -0,0 +1,67 @@ +# Generated by `memmap from-elf` from nrf52840_zephyr_shell.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "nrf52840_zephyr_shell.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "flash" + name: "Flash" + start: 0x00000000 + size: 1M + children: + - { id: "rom_start", name: "rom_start", start: 0x00000000, size: 256 } + - { id: "text", name: "text", start: 0x00000100, size: 49376 } + - { id: "arm_exidx", name: ".ARM.exidx", start: 0x0000C1E0, size: 8 } + - { id: "initlevel", name: "initlevel", start: 0x0000C1E8, size: 120 } + - { id: "sw_isr_table", name: "sw_isr_table", start: 0x0000C260, size: 384 } + - { id: "log_const_sections", name: "log_const_sections", start: 0x0000C3E0, size: 96 } + - id: "small_sections" + name: "2 small sections" + start: 0x0000C440 + size: 80 + children: + - { id: "log_backends_sections", name: "log_backends_sections", start: 0x0000C440, size: 32 } + - { id: "shell_area", name: "shell_area", start: 0x0000C460, size: 48 } + - { id: "shell_root_cmds_sections", name: "shell_root_cmds_sections", start: 0x0000C490, size: 112 } + - { id: "rodata", name: "rodata", start: 0x0000C500, size: 10936 } + - { id: "ram_init_data", name: "RAM init data", start: 0x0000EFB8, size: 676, note: "copied to 0x2000 0000: datas, devices, log_dynamic_sections, k_timer_area, k_mutex_area, k_msgq_area, +1 more" } + - { id: "flash_free", name: "Free\n≈963 KB", kind: reserved, start: 0x0000F25C, size: 986532 } + - id: "ram" + name: "RAM" + start: 0x20000000 + size: 256K + children: + - { id: "datas", name: "datas", start: 0x20000000, size: 372 } + - { id: "devices", name: "devices", start: 0x20000174, size: 116 } + - id: "small_sections_2" + name: "5 small sections" + start: 0x200001E8 + size: 188 + children: + - { id: "log_dynamic_sections", name: "log_dynamic_sections", start: 0x200001E8, size: 48 } + - { id: "k_timer_area", name: "k_timer_area", start: 0x20000218, size: 56 } + - { id: "k_mutex_area", name: "k_mutex_area", start: 0x20000250, size: 20 } + - { id: "k_msgq_area", name: "k_msgq_area", start: 0x20000264, size: 40 } + - { id: "k_sem_area", name: "k_sem_area", start: 0x2000028C, size: 24 } + - { id: "bss", name: "bss", start: 0x200002A8, size: 4142 } + - { id: "noinit", name: "noinit", start: 0x200012E0, size: 8144 } + - { id: "ram_free", name: "Free\n≈243 KB", kind: reserved, start: 0x200032B0, size: 249168 } + +view: + defaults: + labels: { size: true } + columns: + - { id: "flash_col", root: "flash", title: "Flash\n60.6 KB of 1 MB (6%)", width: 150 } + - { id: "ram_col", root: "ram", title: "RAM\n12.7 KB of 256 KB (5%)", width: 150 } + - { id: "small_sections_col", root: "small_sections", width: 150 } + - { id: "small_sections_2_col", root: "small_sections_2", width: 150 } + expand: + - { region: "small_sections", to: "small_sections_col", title: "2 small sections in Flash" } + - { region: "small_sections_2", to: "small_sections_2_col", title: "5 small sections in RAM" } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/r52_zephyr_philosophers.svg b/tests/golden/elf/r52_zephyr_philosophers.svg new file mode 100644 index 0000000..2337d10 --- /dev/null +++ b/tests/golden/elf/r52_zephyr_philosophers.svg @@ -0,0 +1,115 @@ + + + +r52_zephyr_philosophers.elf memory map + + + + + + +0x0000 0000 +0x0000 003C +0x0000 6340 +0x0000 63B8 +0x0000 67B8 +0x0000 67D8 +0x0000 6818 +0x0000 7300 +0x0000 7978 +0x0000 7975 +0x0000 BB78 +0x0000 BBAA +0x7FFF FFFF +DRAM +46.9 KB of 2 GB (<1%) + +0x0000 6340 + +0x0000 6348 + +0x0000 6380 + +0x0000 63A0 + +0x0000 63B7 +4 small sections in DRAM + +0x0000 67B8 + +0x0000 67C0 + +0x0000 67BD + +0x0000 67D7 +2 small sections in DRAM + +0x0000 BB78 + +0x0000 BBA4 + +0x0000 BBA6 + +0x0000 BBA9 +3 small sections in DRAM + +rom_start +60 B + +text +25348 B + +4 small sections +120 B + +sw_isr_table +1 KB + +2 small sections +32 B + +zephyr_dbg_info +64 B + +rodata +2792 B + +bss +1654 B + +noinit +16.5 KB + +3 small sections +50 B + +Free +≈1.99 GB + +.ARM.exidx +8 B + +rodata_start +56 B + +initlevel +32 B + +devices +24 B + +device_handles +6 B + +log_const_sections +24 B + +datas +44 B + +device_states +2 B + +.last_section +4 B + diff --git a/tests/golden/elf/r52_zephyr_philosophers.yaml b/tests/golden/elf/r52_zephyr_philosophers.yaml new file mode 100644 index 0000000..f10370d --- /dev/null +++ b/tests/golden/elf/r52_zephyr_philosophers.yaml @@ -0,0 +1,63 @@ +# Generated by `memmap from-elf` from r52_zephyr_philosophers.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "r52_zephyr_philosophers.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "dram" + name: "DRAM" + start: 0x00000000 + size: 2G + children: + - { id: "rom_start", name: "rom_start", start: 0x00000000, size: 60 } + - { id: "text", name: "text", start: 0x0000003C, size: 25348 } + - id: "small_sections" + name: "4 small sections" + start: 0x00006340 + size: 120 + children: + - { id: "arm_exidx", name: ".ARM.exidx", start: 0x00006340, size: 8 } + - { id: "rodata_start", name: "rodata_start", start: 0x00006348, size: 56 } + - { id: "initlevel", name: "initlevel", start: 0x00006380, size: 32 } + - { id: "devices", name: "devices", start: 0x000063A0, size: 24 } + - { id: "sw_isr_table", name: "sw_isr_table", start: 0x000063B8, size: 1K } + - id: "small_sections_2" + name: "2 small sections" + start: 0x000067B8 + size: 32 + children: + - { id: "device_handles", name: "device_handles", start: 0x000067B8, size: 6 } + - { id: "log_const_sections", name: "log_const_sections", start: 0x000067C0, size: 24 } + - { id: "zephyr_dbg_info", name: "zephyr_dbg_info", start: 0x000067D8, size: 64 } + - { id: "rodata", name: "rodata", start: 0x00006818, size: 2792 } + - { id: "bss", name: "bss", start: 0x00007300, size: 1654 } + - { id: "noinit", name: "noinit", start: 0x00007978, size: 16896 } + - id: "small_sections_3" + name: "3 small sections" + start: 0x0000BB78 + size: 50 + children: + - { id: "datas", name: "datas", start: 0x0000BB78, size: 44 } + - { id: "device_states", name: "device_states", start: 0x0000BBA4, size: 2 } + - { id: "last_section", name: ".last_section", start: 0x0000BBA6, size: 4 } + - { id: "dram_free", name: "Free\n≈1.99 GB", kind: reserved, start: 0x0000BBAA, size: 2147435606 } + +view: + defaults: + labels: { size: true } + columns: + - { id: "dram_col", root: "dram", title: "DRAM\n46.9 KB of 2 GB (<1%)", width: 150 } + - { id: "small_sections_col", root: "small_sections", width: 150 } + - { id: "small_sections_2_col", root: "small_sections_2", width: 150 } + - { id: "small_sections_3_col", root: "small_sections_3", width: 150 } + expand: + - { region: "small_sections", to: "small_sections_col", title: "4 small sections in DRAM" } + - { region: "small_sections_2", to: "small_sections_2_col", title: "2 small sections in DRAM" } + - { region: "small_sections_3", to: "small_sections_3_col", title: "3 small sections in DRAM" } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/stm32f412_tock_kernel.svg b/tests/golden/elf/stm32f412_tock_kernel.svg new file mode 100644 index 0000000..8bfd292 --- /dev/null +++ b/tests/golden/elf/stm32f412_tock_kernel.svg @@ -0,0 +1,52 @@ + + + +stm32f412_tock_kernel.elf memory map +0x0800 0000 +0x0801 84BC +0x0801 84CC +0x0801 84F4 +0x0803 0000 +0x0803 0001 +0x080F FFFF +Flash +97.2 KB of 1 MB (9%) +0x2000 0000 +0x2000 2000 +0x2000 2028 +0x2001 2000 +0x2003 FFFF +SRAM +72 KB of 256 KB (28%) + +.text +99516 B + +.ARM.exidx +16 B + +.relocate (load) +40 B +copied to SRAM at 0x2000 2000 + +Free +≈94.7 KB + +.apps +1 B + +Free +≈831 KB + +.stack +8 KB + +.relocate +40 B + +.sram +65496 B + +Free +184 KB + diff --git a/tests/golden/elf/stm32f412_tock_kernel.yaml b/tests/golden/elf/stm32f412_tock_kernel.yaml new file mode 100644 index 0000000..1058a0c --- /dev/null +++ b/tests/golden/elf/stm32f412_tock_kernel.yaml @@ -0,0 +1,40 @@ +# Generated by `memmap from-elf` from stm32f412_tock_kernel.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "stm32f412_tock_kernel.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "flash" + name: "Flash" + start: 0x08000000 + size: 1M + children: + - { id: "text", name: ".text", start: 0x08000000, size: 99516 } + - { id: "arm_exidx", name: ".ARM.exidx", start: 0x080184BC, size: 16 } + - { id: "relocate_load", name: ".relocate (load)", start: 0x080184CC, size: 40, note: "copied to SRAM at 0x2000 2000" } + - { id: "flash_free", name: "Free\n≈94.7 KB", kind: reserved, start: 0x080184F4, size: 97036 } + - { id: "apps", name: ".apps", start: 0x08030000, size: 1 } + - { id: "flash_free_2", name: "Free\n≈831 KB", kind: reserved, start: 0x08030001, size: 851967 } + - id: "sram" + name: "SRAM" + start: 0x20000000 + size: 256K + children: + - { id: "stack", name: ".stack", start: 0x20000000, size: 8K } + - { id: "relocate", name: ".relocate", start: 0x20002000, size: 40 } + - { id: "sram_2", name: ".sram", start: 0x20002028, size: 65496 } + - { id: "sram_free", name: "Free\n184 KB", kind: reserved, start: 0x20012000, size: 184K } + +view: + defaults: + labels: { size: true } + columns: + - { id: "flash_col", root: "flash", title: "Flash\n97.2 KB of 1 MB (9%)", width: 150 } + - { id: "sram_col", root: "sram", title: "SRAM\n72 KB of 256 KB (28%)", width: 150 } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/stm32f4discovery.svg b/tests/golden/elf/stm32f4discovery.svg new file mode 100644 index 0000000..cefb599 --- /dev/null +++ b/tests/golden/elf/stm32f4discovery.svg @@ -0,0 +1,48 @@ + + + +stm32f4discovery.elf memory map +0x0800 0000 +0x0800 0188 +0x0801 30F8 +0x0801 3100 +0x0801 3B9C +0x080F FFFF +Flash +78.9 KB of 1 MB (8%) +0x2000 0000 +0x2000 0A9C +0x2000 6160 +0x2000 6560 +0x2001 FFFF +SRAM +25.3 KB of 128 KB (20%) + +.isr_vector +392 B + +.text +77680 B + +.ARM +8 B + +.data (load) +2716 B +copied to SRAM at 0x2000 0000 + +Free +≈945 KB + +.data +2716 B + +.bss +22212 B + +._user_heap_stack +1 KB + +Free +≈102 KB + diff --git a/tests/golden/elf/stm32f4discovery.yaml b/tests/golden/elf/stm32f4discovery.yaml new file mode 100644 index 0000000..2a25f22 --- /dev/null +++ b/tests/golden/elf/stm32f4discovery.yaml @@ -0,0 +1,39 @@ +# Generated by `memmap from-elf` from stm32f4discovery.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "stm32f4discovery.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "flash" + name: "Flash" + start: 0x08000000 + size: 1M + children: + - { id: "isr_vector", name: ".isr_vector", start: 0x08000000, size: 392 } + - { id: "text", name: ".text", start: 0x08000188, size: 77680 } + - { id: "arm", name: ".ARM", start: 0x080130F8, size: 8 } + - { id: "data_load", name: ".data (load)", start: 0x08013100, size: 2716, note: "copied to SRAM at 0x2000 0000" } + - { id: "flash_free", name: "Free\n≈945 KB", kind: reserved, start: 0x08013B9C, size: 967780 } + - id: "sram" + name: "SRAM" + start: 0x20000000 + size: 128K + children: + - { id: "data", name: ".data", start: 0x20000000, size: 2716 } + - { id: "bss", name: ".bss", start: 0x20000A9C, size: 22212 } + - { id: "user_heap_stack", name: "._user_heap_stack", start: 0x20006160, size: 1K } + - { id: "sram_free", name: "Free\n≈102 KB", kind: reserved, start: 0x20006560, size: 105120 } + +view: + defaults: + labels: { size: true } + columns: + - { id: "flash_col", root: "flash", title: "Flash\n78.9 KB of 1 MB (8%)", width: 150 } + - { id: "sram_col", root: "sram", title: "SRAM\n25.3 KB of 128 KB (20%)", width: 150 } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/golden/elf/stm32f746_dartino_lines.svg b/tests/golden/elf/stm32f746_dartino_lines.svg new file mode 100644 index 0000000..f389922 --- /dev/null +++ b/tests/golden/elf/stm32f746_dartino_lines.svg @@ -0,0 +1,61 @@ + + + +stm32f746_dartino_lines.elf memory map +0x0800 0000 +0x0800 01D0 +0x0800 01C7 +0x0802 6C20 +0x0802 DD70 +0x0802 DD78 +0x0802 DDB0 +0x0802 DDB4 +0x0803 71DC +0x080F FFFF +Flash +220.5 KB of 1 MB (22%) +0x2000 0000 +0x2000 9428 +0x2000 EF14 +0x2000 F518 +0x2004 FFFF +SRAM +61.3 KB of 320 KB (19%) + +.isr_vector +456 B + +.text +158288 B + +.rodata +29008 B + +.ARM +8 B + +.init_array +56 B + +.fini_array +4 B + +.data (load) +37928 B +copied to SRAM at 0x2000 0000 + +Free +≈803 KB + +.data +37928 B + +.bss +23276 B + +._user_heap_stack +1540 B + +Free +≈258 KB + diff --git a/tests/golden/elf/stm32f746_dartino_lines.yaml b/tests/golden/elf/stm32f746_dartino_lines.yaml new file mode 100644 index 0000000..5f31d41 --- /dev/null +++ b/tests/golden/elf/stm32f746_dartino_lines.yaml @@ -0,0 +1,42 @@ +# Generated by `memmap from-elf` from stm32f746_dartino_lines.elf. Section ranges come from +# the ELF and memory regions from --region. Rename, merge or annotate blocks freely. +version: 1 + +figure: + title: "stm32f746_dartino_lines.elf memory map" + +memory: + fill_gaps: none # gaps under --min-size show as a split edge + regions: + - id: "flash" + name: "Flash" + start: 0x08000000 + size: 1M + children: + - { id: "isr_vector", name: ".isr_vector", start: 0x08000000, size: 456 } + - { id: "text", name: ".text", start: 0x080001D0, size: 158288 } + - { id: "rodata", name: ".rodata", start: 0x08026C20, size: 29008 } + - { id: "arm", name: ".ARM", start: 0x0802DD70, size: 8 } + - { id: "init_array", name: ".init_array", start: 0x0802DD78, size: 56 } + - { id: "fini_array", name: ".fini_array", start: 0x0802DDB0, size: 4 } + - { id: "data_load", name: ".data (load)", start: 0x0802DDB4, size: 37928, note: "copied to SRAM at 0x2000 0000" } + - { id: "flash_free", name: "Free\n≈803 KB", kind: reserved, start: 0x080371DC, size: 822820 } + - id: "sram" + name: "SRAM" + start: 0x20000000 + size: 320K + children: + - { id: "data", name: ".data", start: 0x20000000, size: 37928 } + - { id: "bss", name: ".bss", start: 0x20009428, size: 23276 } + - { id: "user_heap_stack", name: "._user_heap_stack", start: 0x2000EF14, size: 1540 } + - { id: "sram_free", name: "Free\n≈258 KB", kind: reserved, start: 0x2000F518, size: 264936 } + +view: + defaults: + labels: { size: true } + columns: + - { id: "flash_col", root: "flash", title: "Flash\n220.5 KB of 1 MB (22%)", width: 150 } + - { id: "sram_col", root: "sram", title: "SRAM\n61.3 KB of 320 KB (19%)", width: 150 } + +style: + reserved: { show_label: true } # names the Free blocks diff --git a/tests/test_cli.py b/tests/test_cli.py index 56661ca..99acddb 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -264,7 +264,7 @@ def test_examples_are_valid_commented_starters(example): assert invoke("check", example).exit_code == 0 -@pytest.mark.parametrize("command", ["render", "check", "describe", "schema", "guide"]) +@pytest.mark.parametrize("command", ["render", "check", "describe", "from-elf", "schema", "guide"]) def test_help_ends_with_an_example(command): lines = invoke(command, "--help").stdout.rstrip().splitlines() assert lines[-1].strip().startswith("memmap ") @@ -296,6 +296,7 @@ def test_group_help_points_to_the_guide(): ["view.columns[0].width=150"], ["view.overrides=[{region: boot, top_label: end}]"], ["view.overrides=[{region: boot, height: 48}]"], + ['memory.regions[0].note="line one\\nline two"'], ], ) def test_agents_guide_recipes_are_valid(sets, tmp_path): diff --git a/tests/test_elf_snapshots.py b/tests/test_elf_snapshots.py new file mode 100644 index 0000000..3c98ba3 --- /dev/null +++ b/tests/test_elf_snapshots.py @@ -0,0 +1,88 @@ +"""Real firmware layouts through `from-elf`, from the header snapshots in +tests/fixtures/elf_snapshots/. See docs/elf-testing.md. + +Each snapshot is rebuilt into a minimal ELF, imported with its regions, and the config and its +drawing are compared with tests/golden/elf/. Regenerate after an intended change with: + + MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_elf_snapshots.py +""" + +import json +import os + +import pytest +from conftest import ROOT, codes, drawn +from elf_builder import make_elf + +from memmap.elf import read_elf +from memmap.from_elf import import_elf, parse_region_spec +from memmap.pipeline import run +from memmap.render.svg import render_svg + +SNAPSHOTS = ROOT / "tests" / "fixtures" / "elf_snapshots" +GOLDEN = ROOT / "tests" / "golden" / "elf" +UPDATE = os.environ.get("MEMMAP_UPDATE_GOLDEN") == "1" +NAMES = sorted(path.stem for path in SNAPSHOTS.glob("*.json")) + + +def load(name): + """A snapshot as a dict.""" + return json.loads((SNAPSHOTS / f"{name}.json").read_text(encoding="utf-8")) + + +def rebuild(snapshot): + """The snapshot as ELF bytes. make_elf adds its own section name table.""" + sections = [ + (s["name"], s["type"], s["flags"], int(s["address"], 16), s["size"], s["offset"]) + for s in snapshot["sections"] + if s["name"] != ".shstrtab" + ] + segments = [ + (s["offset"], int(s["virtual"], 16), int(s["physical"], 16), s["file_size"], s["memory_size"]) + for s in snapshot["segments"] + ] + return make_elf( + sections, + segments, + bits=snapshot["bits"], + little=snapshot["little_endian"], + file_type=snapshot["file_type"], + ) + + +def compare(golden, text): + """Check `text` against a golden file, or rewrite it with MEMMAP_UPDATE_GOLDEN=1.""" + if UPDATE: + golden.parent.mkdir(parents=True, exist_ok=True) + golden.write_text(text, encoding="utf-8", newline="\n") + assert text == golden.read_text(encoding="utf-8") + + +def test_there_are_snapshots(): + assert len(NAMES) >= 8 + + +@pytest.mark.parametrize("name", NAMES) +def test_snapshot_rebuilds_to_the_same_headers(name): + snapshot = load(name) + elf = read_elf(rebuild(snapshot)) + wanted = [s for s in snapshot["sections"] if s["name"] != ".shstrtab"] + assert [(s.name, s.kind, s.flags, s.address, s.size) for s in elf.sections[: len(wanted)]] == [ + (s["name"], s["type"], s["flags"], int(s["address"], 16), s["size"]) for s in wanted + ] + assert elf.bits == snapshot["bits"] + + +@pytest.mark.parametrize("name", NAMES) +def test_snapshot_imports_to_the_golden_config_and_drawing(name, tmp_path): + snapshot = load(name) + memories = [parse_region_spec(spec) for spec in snapshot["regions"]] + imported = import_elf(read_elf(rebuild(snapshot)), f"{name}.elf", memories) + assert imported.diagnostics == [] + compare(GOLDEN / f"{name}.yaml", imported.text) + + config = tmp_path / f"{name}.yaml" + config.write_text(imported.text, encoding="utf-8") + result = run(config) + assert codes(result) == [] # passes check --strict + compare(GOLDEN / f"{name}.svg", render_svg(drawn(result))) diff --git a/tests/test_from_elf.py b/tests/test_from_elf.py new file mode 100644 index 0000000..85a395b --- /dev/null +++ b/tests/test_from_elf.py @@ -0,0 +1,529 @@ +import json +import re +import struct + +import pytest +from click.testing import CliRunner +from conftest import ROOT +from elf_builder import PROGBITS, code, make_elf + +from memmap.cli import app +from memmap.elf import SHF_ALLOC, SHF_TLS, SHT_NOBITS, ElfError, read_elf +from memmap.from_elf import ImportProblem, MemorySpec, import_elf, parse_region_spec +from memmap.pipeline import run + +FIXTURES = ROOT / "tests" / "fixtures" +FIRMWARE = FIXTURES / "firmware.elf" +# The same firmware written by binutils in every ELF class and byte order (see elf_src/build.sh). +REAL_VARIANTS = { + "firmware.elf": 32, + "firmware_be.elf": 32, + "firmware64.elf": 64, + "firmware64_be.elf": 64, +} +FLASH = "flash=0x08000000:64K" +RAM = "ram=0x20000000:20K" +runner = CliRunner() + + +def invoke(*args): + return runner.invoke(app, [str(arg) for arg in args]) + + +def check_strict(text, tmp_path): + """Write generated text to layout.yaml and return the codes the pipeline reports, so that + `== []` means it passes `check --strict`.""" + file = tmp_path / "layout.yaml" + file.write_text(text) + return [d.code for d in run(file).diagnostics] + + +# Reading + + +def test_reads_the_fixture_firmware(): + elf = read_elf(FIRMWARE.read_bytes()) + assert elf.bits == 32 + by_name = {section.name: section for section in elf.sections} + assert by_name[".isr_vector"].address == 0x08000000 + assert by_name[".bss"].nobits and by_name[".bss"].allocated + assert not by_name[".comment"].allocated + loads = [(s.virtual, s.physical, s.file_size) for s in elf.segments if s.kind == 1] + assert (0x20000000, 0x08000622, 0x40) in loads # .data runs in RAM, stored in flash + + +@pytest.mark.parametrize("bits", [32, 64]) +@pytest.mark.parametrize("little", [True, False]) +def test_reads_every_class_and_byte_order(bits, little): + data = make_elf( + [code(".text", 0x1000, 0x40, 0x200), code(".data", 0x8000, 0x10, 0x240)], + segments=[(0x200, 0x1000, 0x1000, 0x40, 0x40), (0x240, 0x8000, 0x1040, 0x10, 0x10)], + bits=bits, + little=little, + ) + elf = read_elf(data) + assert elf.bits == bits + assert [(s.name, s.address, s.size) for s in elf.sections[:2]] == [ + (".text", 0x1000, 0x40), + (".data", 0x8000, 0x10), + ] + assert [(s.virtual, s.physical) for s in elf.segments] == [(0x1000, 0x1000), (0x8000, 0x1040)] + + +@pytest.mark.parametrize( + ("data", "message"), + [ + (b"PK\x03\x04", "not an ELF"), + (b"\x7fELF\x01", "truncated"), + (b"\x7fELF\x03\x01" + bytes(10), "unknown ELF class"), + (make_elf([code(".text", 0, 4)])[:60], "truncated"), + (make_elf([code(".text", 0, 4)], file_type=1), "object file"), + (make_elf([code(".text", 0x100, 4)], file_type=4), "core dump"), + ], +) +def test_rejects_what_it_cannot_read(data, message): + with pytest.raises(ElfError, match=message): + read_elf(data) + + +@pytest.mark.parametrize("field", [32, 40]) # e_phoff, e_shoff +def test_rejects_a_64_bit_header_offset_past_any_file(field): + data = bytearray(make_elf([code(".text", 0, 4)], segments=[(0x100, 0, 0, 4, 4)], bits=64)) + struct.pack_into("= 0x400] + assert images[:2] == [ + ("RAM init data", 0x400, 0x60, "copied to 0x0000 8000: datas, devices"), + (".fast (load)", 0x460, 0x10, "copied to RAM at 0x0000 9000"), + ] + with_code = make_elf(sections(SHF_ALLOC | 0x4), segments) # 0x4: SHF_EXECINSTR + assert '"RAM code and data"' in import_elf(read_elf(with_code), "fw", memories).text + assert '"Init data"' in import_elf(read_elf(make_elf(sections(SHF_ALLOC), segments)), "fw", []).text + + +def test_several_banks_get_a_column_each_and_copies_name_their_bank(tmp_path): + """Like an STM32H7: code in flash and ITCM, data in DTCM and AXI SRAM, SRAM4 unused.""" + run_code, data = SHF_ALLOC | 0x4, SHF_ALLOC | 0x1 # executable, writable + sections = [ + (".text", PROGBITS, run_code, 0x08000000, 0x8000, 0x1000), + (".itcm_text", PROGBITS, run_code, 0x00000000, 0x800, 0x9000), + (".data", PROGBITS, data, 0x20000000, 0x100, 0x9800), + (".bss", SHT_NOBITS, data, 0x20000100, 0x1000, 0x9900), + (".axi_data", PROGBITS, data, 0x24000000, 0x80, 0x9900), + (".framebuffer", SHT_NOBITS, data, 0x24000080, 0x10000, 0x9980), + ] + segments = [ + (0x1000, 0x08000000, 0x08000000, 0x8000, 0x8000), + (0x9000, 0x00000000, 0x08008000, 0x800, 0x800), # each copy goes to another bank + (0x9800, 0x20000000, 0x08008800, 0x100, 0x1100), + (0x9900, 0x24000000, 0x08008900, 0x80, 0x10080), + ] + specs = [ + "flash=0x08000000:2M:Flash", + "itcm=0x0:64K:ITCM", + "dtcm=0x20000000:128K:DTCM", + "axi=0x24000000:512K:AXI SRAM", + "sram4=0x38000000:64K:SRAM4", + ] + memories = [parse_region_spec(spec) for spec in specs] + imported = import_elf(read_elf(make_elf(sections, segments)), "fw", memories) + assert imported.diagnostics == [] + assert check_strict(imported.text, tmp_path) == [] + index = run(tmp_path / "layout.yaml").tree.index + assert {copy: index[copy].note for copy in ("itcm_text_load", "data_load", "axi_data_load")} == { + "itcm_text_load": "copied to ITCM at 0x0000 0000", + "data_load": "copied to DTCM at 0x2000 0000", + "axi_data_load": "copied to AXI SRAM at 0x2400 0000", + } + assert [(c.name, c.size) for c in index["sram4"].children] == [("Free\n64 KB", 0x10000)] + assert re.findall(r'root: "(\w+)"', imported.text) == ["itcm", "flash", "dtcm", "axi", "sram4"] + assert '"SRAM4\\n0 B of 64 KB (0%)"' in imported.text + + +def test_free_blocks_print_their_size_rounded_down(tmp_path): + data = make_elf([code(".text", 0x000, 0x100), code(".data", 0x80000000, 0x10)]) + memories = [MemorySpec("flash", 0, 0x10000, "Flash"), MemorySpec("ram", 0x80000000, 1 << 31, "RAM")] + imported = import_elf(read_elf(data), "fw", memories) + assert check_strict(imported.text, tmp_path) == [] + index = run(tmp_path / "layout.yaml").tree.index + assert index["flash_free"].name == "Free\n≈63.7 KB" # 63.75 KB, never rounded up + assert index["ram_free"].name == "Free\n≈1.99 GB" + exact = import_elf(read_elf(data), "fw", [MemorySpec("flash", 0, 0x780100, "Flash")]).text + assert '"Free\\n7.5 MB"' in exact # exact, so no ≈ + + +def test_only_gaps_of_min_size_get_a_free_block(tmp_path): + data = make_elf([code(".a", 0x000, 0x100), code(".b", 0x110, 0x100), code(".c", 0x300, 0x100)]) + imported = import_elf(read_elf(data), "fw", [MemorySpec("mem", 0, 0x1000, "MEM")], min_size=64) + assert check_strict(imported.text, tmp_path) == [] + free = [n for n in run(tmp_path / "layout.yaml").tree.index.values() if n.reserved] + assert [(n.start, n.end) for n in free] == [(0x210, 0x2FF), (0x400, 0xFFF)] + + +def test_ids_are_cleaned_up_and_unique(tmp_path): + data = make_elf( + [code(".ARM.exidx", 0x000, 0x100), code("arm_exidx", 0x100, 0x100), code(".mem", 0x200, 0x100)] + ) + imported = import_elf(read_elf(data), "fw", [MemorySpec("mem", 0, 0x1000, "MEM")]) + assert check_strict(imported.text, tmp_path) == [] + index = run(tmp_path / "layout.yaml").tree.index + assert index["arm_exidx"].name == ".ARM.exidx" + assert index["arm_exidx_2"].name == "arm_exidx" + assert index["mem_2"].name == ".mem" + + +def test_64_bit_elf_sets_address_bits(tmp_path): + data = make_elf([code(".text", 0x8000_0000_0000, 0x1000)], bits=64) + imported = import_elf(read_elf(data), "fw", []) + assert "address_bits: 64" in imported.text + assert check_strict(imported.text, tmp_path) == [] + + +def test_ids_and_references_are_quoted_so_yaml_keeps_them_strings(tmp_path): + data = make_elf([code("123", 0x000, 0x100), code(".true", 0x100, 0x100), code(".null", 0x200, 0x100)]) + memories = [parse_region_spec("456=0:0x1000"), parse_region_spec("no=0x1000:0x1000")] + imported = import_elf(read_elf(data), "fw", memories) + assert check_strict(imported.text, tmp_path) == [] + index = run(tmp_path / "layout.yaml").tree.index + assert {"123", "true", "null", "456", "no"} <= set(index) + + +def test_a_line_break_in_the_file_name_stays_inside_the_comment(tmp_path): + imported = import_elf(read_elf(FIRMWARE.read_bytes()), "fw\nversion: 2.elf", []) + assert imported.text.splitlines()[0].startswith("# Generated by `memmap from-elf` from fw?version") + assert check_strict(imported.text, tmp_path) == [] + + +def test_usage_percent_rounds_down(): + data = make_elf([code(".text", 0, 996)]) + text = import_elf(read_elf(data), "fw", [MemorySpec("mem", 0, 1000, "MEM")]).text + assert "996 B of 1000 B (99%)" in text # 99.6%, not shown as full + + +def test_a_file_without_section_headers_is_an_import_problem(): + data = bytearray(make_elf([code(".text", 0x100, 4)], segments=[(0x100, 0x100, 0x100, 4, 4)])) + struct.pack_into(" 3 assert block(result, "m").h > 24 + + +def test_long_notes_wrap_and_the_block_grows_to_hold_them(load): + note = "copied to 0x2000 0000: datas, devices, log_dynamic_sections, k_timer_area, k_sem_area" + text = regions( + " - id: m\n size: 8K\n children:\n" + f' - {{ id: a, size: 4K, note: "{note}" }}\n - {{ id: b, size: 4K, note: short }}' + ) + view = "view:\n defaults:\n scale: { mode: equal }\n columns:\n - { id: c, root: m }\n" + result = load(text + view) + assert codes(result) == [] + notes = [t for t in drawn(result).texts() if t.role == "note" and t.region == "a"] + assert len(notes) > 1 and " ".join(t.text for t in notes) == note + a = block(result, "a") + assert all(a.y < t.y < a.y + a.h for t in notes) # every line sits beside its own block + assert a.h > block(result, "b").h # equal scale, so only the note made it taller + rules = [p for p in drawn(result).primitives if isinstance(p, Line) and p.x1 == p.x2] + assert [(r.y1 > a.y, r.y2 < a.y + a.h) for r in rules if a.x + a.w < r.x1 < notes[0].x] == [ + (True, True) + ] + + +def test_a_note_line_break_is_kept(load): + text = regions(' - id: m\n size: 4K\n note: "one\\ntwo"') + notes = [t.text for t in drawn(load(text)).texts() if t.role == "note"] + assert notes == ["one", "two"]