asmdiff 0.1.7__tar.gz → 0.3.0__tar.gz

asmdiff-0.3.0/2026-07-07-table-layout-handoff.md

@@ -0,0 +1,90 @@
+# asmdiff summary-table legibility - checkpoint 2026-07-07
+
+Handoff for a fresh session in THIS repo (`~/esp-idf/tools/asmdiff`).
+Feature is COMPLETE and verified, NOTHING COMMITTED. Origin: ELF-mode
+output (`asmdiff build/S3-Amysynth.elf --filter 'core_'`) was unreadable -
+every row hard-wrapped in the terminal (screenshot in repo root,
+`Screenshot 2026-07-07 225145.jpg`).
+
+## Root cause
+
+`render_table` pads every column to its widest cell. The `calls` column
+sat in the middle; with real firmware call lists (~150 chars at the
+8-callee cap) plus 50-char LTO symbol names, `loop spans` started past
+column ~210 and every row wrapped: dangling `-` lines, split headers,
+call lists colliding with the next function name.
+
+## What changed (asmdiff.py)
+
+1. **Column order**: all three builders now emit
+   `function / [role] / insns / loop spans / calls` - calls (the one
+   unbounded column) moved last, ragged right. Builders:
+   `summary_table`, `file_summary_table` (TOTAL row spans cell stays
+   `-`), `inspect_table`. Each gained a `max_width=None` passthrough
+   param.
+2. **Width-aware trim**: `render_table(rows, max_width=None)` - when
+   set, fixed columns keep full width, the last column's over-budget
+   cells are trimmed by `_fit_calls`: whole callees dropped from the
+   end, closed with `Total Calls:N` (N = full callee count, preserved
+   from an existing summary). The FIRST callee is never dropped - a
+   single huge symbol overflows/wraps instead of vanishing
+   (`sequencer_core_set_melodic_envelope2` is the real-world case).
+   Cells that fit, `-`, and headers are untouched. `TOTAL_CALLS_RE`
+   guards summary parsing.
+3. **`format_calls`** cap suffix changed from `+N more` to
+   `Total Calls:N` (user-requested format; one consistent suffix for
+   both the 8-callee cap and the width trim).
+4. **`table_width()`**: `shutil.get_terminal_size().columns` when
+   `sys.stdout.isatty()`, else `None` - piped/redirected output skips
+   the trim so it stays deterministic and greppable. Passed at all six
+   print sites (both summary_table sites, both file_summary_table
+   sites, both inspect_table sites).
+
+All new code sits together around `render_table` (~line 1053 region).
+
+## Tests (test_asmdiff.py)
+
+- New `TestTableMaxWidth` (9 tests): trim-to-fit, fitting cell left
+  alone, merges existing `Total Calls:N` (does not recount), single
+  callee never dropped, dash untouched, `max_width=None` unchanged,
+  builder passthrough, `table_width()` tty/piped (via `mock.patch` on
+  `asmdiff.sys.stdout.isatty` / `asmdiff.shutil.get_terminal_size`).
+- Updated for new column order / suffix: `TestFormatCalls`
+  `test_long_list_capped`, `test_summary_table`,
+  `test_summary_table_loop_spans_column`,
+  `test_file_summary_totals_and_call_union`, both
+  `TestInspectRendering` inspect_table tests.
+- Suite: 191 tests, sole failure the KNOWN env-dependent
+  `TestShortAliases.test_p_is_pair` (global ~/.config/asmdiff.toml with
+  target esp32s3 short-circuits it; fails at HEAD too).
+
+## Docs
+
+README: all 8 example tables reordered; the truncation paragraph (ELF
+section, "Only labels the assembler types...") now documents
+`Total Calls:N`, the tty-only width trim, and the piped-output
+exemption; intro prose order updated. Module docstring summary line
+reordered to match. No flags or config keys changed, so
+`asmdiff.example.toml` / `EXAMPLE_CONFIG` are untouched (the
+byte-match unit test still applies to any future config edit).
+
+## Verification done
+
+- Full suite as above.
+- Real ELF (`~/esp-idf/S3-Amysynth/build/S3-Amysynth.elf`, config-derived
+  xtensa objdump), `--filter 'core_'`:
+  - piped: full capped lists, new column order, aligned.
+  - fake tty via `script -qec "stty cols 190 ..."`: all rows one line
+    except the designed first-callee-floor overflow (4 chars over).
+  - 110-col tty: fixed columns alone can exceed width when a loopy
+    function widens `loop spans`; calls floor at one callee - accepted
+    graceful degradation, only `calls` ever trims (scope decision).
+
+## Next steps
+
+1. Commit (user has not asked yet; suggested scope: asmdiff.py,
+   test_asmdiff.py, README.md in one commit - pure output-format
+   change, no behavior change to analysis).
+2. Optional follow-up the user explicitly deferred: making the
+   `loop spans` cells themselves friendlier (e.g. "2 ZOL + 3 br"
+   summary) - scoped OUT of this change ("layout only").

asmdiff-0.3.0/2026-07-10-reverb-session-feedback-handoff.md

@@ -0,0 +1,102 @@
+# Field feedback: S3-Amysynth reverb codegen session — handoff 2026-07-10
+
+Feedback from a real investigation, not a scripted test matrix. Workload:
+`stereo_reverb` in AMY's `delay.c` (ESP32-S3 project at `~/esp-idf/S3-Amysynth`,
+xtensa-esp-elf-gcc 15.2.0, ship `-O2` flags via `-db`), comparing four source
+variants: pre-optimization original (extracted from git history), the shipped
+token-paste locals-cache, a struct/`static inline` respelling, and a
+`restrict`-annotated original. Modes exercised: two-file `-a FUNC` compare,
+`--target` matrix, `-db` + `--flags-like`, host-compiler contrast runs.
+
+## State
+
+The tool answered every question the session asked, correctly. All findings
+below are UX/ergonomics, not correctness: in each case asmdiff computed the
+right thing and then made the caller dig for it. Ranked by time actually lost.
+
+## Findings
+
+### 1. Summary tables print last; no summaries-only mode
+Two-file compare with the default target set produced a 102 KB dump (three full
+side-by-side listings, esp32/s2/s3) with the `function/role/insns/loop
+spans/calls` table at the *end* of each target section. Every subsequent
+invocation was pre-piped through `grep -A4 "role.*insns"` to skip the listings.
+
+Repro: `asmdiff delay_macro.c delay_struct.c -a stereo_reverb -db --flags-like
+components/amy/src/delay.c` (no `--target`).
+
+Proposal: `--summary-only` (or print summaries before listings). For
+agent/scripted callers the table is the decision input; the listing is only
+pulled when a delta needs explaining. A `--json` summary emitter would serve
+the same callers.
+
+### 2. Doc drift: `host` target promised, absent from shipped config
+The skill/README text says ESP profiles "+ host" are pre-configured;
+`~/.config/asmdiff.toml` actually ships `gcc` and `clang`. `--target host`
+errors out. The error's target list is what rescued the session — good — but
+the drift costs one failed call per session that trusts the docs.
+
+Fix: add a `[host]` alias target to the example/default toml, or correct the
+README and the `~/.claude/skills/asmdiff` skill text (both say "host").
+
+### 3. `-db` on foreign-arch targets drops project include paths with the flags
+For host targets, `-db` correctly refuses to borrow xtensa flags ("compiling
+without its include/define flags") — but that also drops `-I`, so the compile
+dies on `fatal error: amy.h: No such file or directory`. Workaround was manual:
+`-- -I~/esp-idf/S3-Amysynth/components/amy/src`.
+
+Proposal: the project's own `-I` paths are target-portable even when its `-D`s
+are not. For foreign-arch targets, borrow `-I` only (skip `-D`), or offer
+`--db-includes`. Keep the current loud note either way — the refusal itself is
+right (see FIELD-TEST-REPORT Trap 1 for why silently borrowing would be worse).
+
+### 4. No per-span instruction mix (`--span-stats`)
+The decisive number of the session — loop body 96 loads / 31 stores vs 85 / 26,
+multiplies identical at 14 — required two rounds of hand-written awk over the
+listing, and the first attempt silently counted past the loop end into the
+epilogue. The tool's own doctrine is "weigh the span, not the function"; it
+should be able to weigh it. The 2026-07-07 ELF round hit the same wall (ad-hoc
+awk over objdump for loop tabulation), so this is a recurring gap.
+
+Proposal: `--span-stats` — per-span opcode histogram (loads / stores / mul /
+branch / other), per function, alongside the existing `span:count` column.
+
+### 5. Side-by-side pair listings don't collapse identical runs
+Two ~500-insn functions differing by ~5 instructions print ~1000 listing lines
+of which ~990 are identical pairs. Context-diff-style collapsing (keep N lines
+around changed hunks, elide the rest with a count) would turn the 102 KB dump
+from finding 1 into a few readable hunks. Interacts with finding 1: summary
+first, collapsed hunks second, full listing on request.
+
+### 6. Minor: missing-toolchain error could name the compiler
+`--target rp2350` with no ARM toolchain installed → "error: no usable compiler
+in the matrix". Accurate, but naming the miss ("arm-none-eabi-gcc: not found
+on PATH") makes the fix obvious.
+
+## Verified working this session (regression notes)
+
+- `--flags-like <db-file>` on out-of-tree copies: exact borrowed-flag parity
+  both sides — this closes FIELD-TEST-REPORT Trap 2 ("before/after on a project
+  source has no supported path") and its Trap 1 hazard for the copy workflow.
+- Two-file `-a FUNC` compare against a `git show <rev>:src/file.c` extraction:
+  frictionless; this is the natural "what did that upstream commit buy"
+  workflow.
+- Default target resolution + multi-target matrix from config: zero toolchain
+  path digging; glob `cc` patterns resolved and announced.
+- `span:count` + `calls` columns answered ZOL and libcall questions at a
+  glance.
+
+Session results usable as a future test corpus (esp32s3, ship -O2, AMY at
+v1.2.31): `stereo_reverb` original 437 insns / span 327; +`restrict` best
+effort 473 / 306; shipped locals-cache 509 / 290; struct respelling 504 / 289.
+Host: gcc -O3 467 = 467, clang -O3 443 = 443 (macro vs struct byte-count
+identical). Variant sources preserved in the session job dir
+(`~/.claude/jobs/b3de0cac/tmp/delay_{orig,restrict,macro,struct}.c`) — copy
+them into `demo/` or the test suite if wanted before that dir is cleaned.
+
+## Next steps
+
+1. Finding 1 (`--summary-only`) — smallest change, largest per-call saving.
+2. Finding 4 (`--span-stats`) — recurring need across two sessions.
+3. Finding 5 (collapse identical hunks) — pairs with 1.
+4. Findings 2, 3, 6 — config/doc/message fixes, each ~minutes.

asmdiff-0.1.7/README.md → asmdiff-0.3.0/PKG-INFO

@@ -1,7 +1,42 @@
+Metadata-Version: 2.4
+Name: asmdiff
+Version: 0.3.0
+Summary: Per-function assembly inspection and comparison, across a compiler matrix or from a shipped ELF
+Project-URL: Homepage, https://github.com/rt-rtos/asmdiff
+Project-URL: Repository, https://github.com/rt-rtos/asmdiff
+Author: Rasmus Tikkanen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arm,assembly,cfg,clang,cli,codegen,compiler,devtools,diff,disassembly,dsp,embedded,firmware,gcc,loop-analysis,objdump,riscv,static-analysis,xtensa
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
 # [asmdiff](https://pypi.org/project/asmdiff/) 
-## per-function assembly comparison for paired C implementations
+## per-function assembly inspection and comparison, across a compiler matrix or from a shipped ELF
+
+> asmdiff is a stdlib only command-line tool for comparing the generated assembly of individual C functions across implementations, compiler flags, compiler versions, and source revisions. It is intended for
+investigating compiler code generation rather than benchmarking runtime performance.
+
+<details>
+	
+<summary>Quickstart Example</summary>
+	
+[![asmdiff comparing gcc and clang assembly for paired C functions, with a fold-vs-libcall summary](demo/quickstart.gif)](demo/quickstart.gif)
+
+*Each function appears twice - `old_*` and `new_*`, the same routine
+before and after a rewrite - compiled across a gcc/clang matrix and diffed
+side by side. The summary's `insns` and `calls` columns are the payoff:
+`old_rt`'s 9-instruction `exp2f` call collapses to `new_rt`'s 2-instruction
+`ldexpf`. (Click to enlarge.)*
+
+---
 
-> asmdiff is a stdlib only command-line tool for comparing the generated assembly of individual C functions across implementations, compiler flags, compiler versions, and source revisions. It is intended for investigating compiler code generation rather than benchmarking runtime performance.
+</details>
 
 ### Try it yourself:
 
@@ -255,9 +290,10 @@ everywhere else; two things are ELF-specific:
   evidence is missing or the register is overwritten in between -
   a genuine function-pointer dispatch still reads as indirect.
 
-What this looks like on real firmware: the same binary's sequencer
-core (project code, not a synth library) surfaces three findings in
-one row scan.
+What this looks like on real firmware: this binary's sequencer path -
+here in the vendored AMY synth engine (`components/amy/src/sequencer.c`,
+with the divide sourced from `amy_sysclock()` in `api.c`) - surfaces
+three findings in one row scan.
 
 ```
 $ asmdiff build/S3-Amysynth.elf --filter 'sequencer_(process_tick|recompute|timer_callback)'
@@ -271,7 +307,12 @@ sequencer_process_tick$lto_priv$0    117    .L2e:96 .L48:85 .L8d:6  xQueueSemaph
 A timer callback pays a software float divide *and* a 64-bit
 `__udivdi3` inside its 41-instruction loop - the
 [silent software divide](#example-catching-a-silent-software-divide)
-pattern, caught in shipped firmware instead of a harness.
+pattern, caught in shipped firmware instead of a harness. asmdiff was
+built to hunt exactly this in AMY, and this callback was the payoff: the
+pairing was confirmed as both a codegen cost and an upstream correctness
+bug - `amy_sysclock()`'s `uint32_t` sample count wraps far sooner than
+its comment claims and loses precision on long uptimes - and is fixed
+locally with a PR pending to shorepine/amy.
 `sequencer_recompute`'s `__extendsfdf2 -> __divdf3 -> __muldf3` chain
 is the double-promotion smell (typically an unsuffixed `60.0`-style
 literal) on a chip whose FPU is single-precision only. And the
@@ -317,9 +358,11 @@ zero-overhead loops", the empirical rules (verified on esp-gcc 15.2,
 ```
 asmdiff SOURCE.c [SOURCE2.c | FUNC...] [--pair OLD:NEW]... [--across FUNC]...
            [--cc 'CC FLAGS']... [--target NAME]... [--config PATH]
-           [--compile-commands [PATH]] [--flags-like PATH]
+           [--compile-commands [PATH]] [--flags-like PATH] [--db-includes]
+           [--summary-only] [--collapse] [--span-stats]
            [--layout list|side-by-side] [-v] [-- EXTRA_FLAGS...]
 asmdiff FIRMWARE.elf [FUNC...] [--filter REGEX] [--objdump PATH]
+           [--summary-only] [--span-stats]
 ```
 
 | Option | Meaning |
@@ -335,6 +378,12 @@ asmdiff FIRMWARE.elf [FUNC...] [--filter REGEX] [--objdump PATH]
 | `--config PATH` | Config file to use. Default search: `asmdiff.toml` next to `SOURCE.c`, then in the current directory, then `~/.config/`. First hit wins. |
 | `-db, --compile-commands [PATH]` | Borrow each source's include/define flags from a `compile_commands.json`; with no `PATH`, walk up from the CWD checking each directory and its `build/` until the repository root. See [below](#borrowing-includes-from-compile_commandsjson). |
 | `--flags-like PATH` | A source with no `compile_commands` entry borrows the flags recorded for `PATH` — the way to compare a modified copy of a project source under its original's header environment. |
+| `--db-includes` | Borrow only the header-search paths from the database, dropping its defines, forced includes, and `-specs`/`--sysroot`; kept paths are re-emitted as `-idirafter` so they cannot shadow the host's own system headers. This is how a host target compiles a cross project's source. |
+| `-s`, `--summary-only` | Print only the summary/stats tables, suppressing every assembly listing (see [Shaping the output](#shaping-the-output-for-reading-vs-deciding)). |
+| `--json` | Emit the summary as JSON on stdout instead of tables — one record per function per compiler. Implies `--summary-only`; errors stay plain text on stderr. |
+| `--collapse` | In side-by-side listings, elide runs of identical line pairs, keeping 3 lines of context around each difference. |
+| `--span-stats` | Follow each stats table with a per-loop-span instruction mix: load/store/mul/branch/other counts per span. |
+| `--version` | Print the version and exit. |
 | `-v`, `--verbose` | On compile failure, print the full compiler command and complete error output. Default shows only the compiler, the source, and the first error lines. |
 | `-- FLAGS...` | Everything after a bare `--` is appended to *every* compiler invocation. |
 
@@ -358,9 +407,66 @@ asmdiff h.c -- -fno-math-errno
 ```
 
 Compilers missing from `PATH` are skipped with a warning; the run fails only
-if none are usable. Exit status is non-zero only for operational failures
-(compile error — the compiler's stderr is shown — unknown `--pair` name, no
-usable compiler). Differing assembly is the expected result, never an error.
+if none are usable, and that error names each missed binary
+(`no-such-gcc: not found on PATH`) so the fix is in the message, not in a
+warning that scrolled away. Exit status is non-zero only for operational
+failures (compile error — the compiler's stderr is shown — unknown `--pair`
+name, no usable compiler). Differing assembly is the expected result, never
+an error.
+
+## Shaping the output for reading vs deciding
+
+A two-file compare over a three-target matrix prints three full
+side-by-side listings with the summary table at the *end* of each — the
+right shape for reading an unfamiliar delta, and roughly 100 KB of the
+wrong shape when the table is all the decision needs. Three flags cut the
+output to purpose:
+
+- **`--summary-only`** (`-s`) keeps only the summary/stats tables. This is
+  the scripted/agent view: the table is the decision input, and a listing
+  is pulled with a second, narrower run only when a delta needs
+  explaining.
+- **`--collapse`** elides runs of identical line pairs in every
+  side-by-side listing, keeping 3 lines of context around each difference
+  plus a `... N identical lines ...` marker. Two ~500-instruction
+  functions differing by five instructions render as a few readable hunks
+  instead of ~1000 lines.
+- **`--span-stats`** follows each stats table with a per-loop-span
+  instruction mix, one row per span:
+
+  ```
+  function       span    insns  load  store  mul  branch  other
+  stereo_reverb  .L108   327    96    31     14    12     174
+  ```
+
+  This weighs the span rather than the whole function — the number that
+  actually decides a hot-loop comparison (is the rewrite trading loads
+  for stores? did the multiplies move?) without hand-counting a listing
+  and accidentally tallying past the loop end into the epilogue.
+  Buckets are by mnemonic (Xtensa, RISC-V, ARM) with an AT&T
+  memory-operand heuristic for x86; *branch* includes calls (outbound
+  calls are already itemised in the `calls` column), and anything the
+  tables don't know lands in *other*.
+
+All three combine with every compile mode; `--summary-only` and
+`--span-stats` also apply to ELF input.
+
+For scripted callers, `--json` replaces the tables entirely with one
+JSON document on stdout: a flat `results` list holding one record per
+function per compiler — `cc`, `tag` (source label in two-file runs),
+`role` (`baseline`/`candidate` in paired runs), `insns`, `loop_spans`,
+`calls`, and `span_stats` when `--span-stats` is given. Flat records
+keep it one `jq` expression away from any question the tables answer:
+
+```bash
+asmdiff old.c new.c -a stereo_reverb --json --span-stats \
+  | jq '.results[] | {role, insns, spans: .loop_spans}'
+```
+
+The top level carries `asmdiff` (version) and `mode`
+(`pairs`/`across`/`inspect`/`summary`/`elf`; ELF runs add the binary's
+path as `elf`). Warnings and errors stay plain text on stderr, so a
+failed run never emits half a document.
 
 ## Config file: named targets
 
@@ -532,9 +638,49 @@ Details that make it robust:
 - **`compile_commands` expands `~` and `$VARS`.** The `==` header always
   prints the resolved compiler command; run with `-- -v` if you want to see
   every include path the compiler actually received.
+- **`--db-includes` restricts the borrow to header-search paths**,
+  dropping `-D`/`-U`, forced includes, and `-specs`/`--sysroot`. Use it
+  when the *target* doesn't match the arch the database was built for —
+  host gcc given an ESP-IDF database would otherwise inherit
+  `-specs=picolibc.specs` and cross-only defines it cannot compile
+  with, yet still needs the project's include paths to find its
+  headers. The kept paths are re-emitted as `-idirafter`, searched
+  *after* the compiler's own system directories: ESP-IDF's include set
+  contains a libc-overlay directory (`esp_libc/platform_include`) whose
+  `stdio.h` would shadow the host's under plain `-I`; demoted, the
+  project's own headers still resolve and the host's libc wins.
 
 ### Auto-discovering the database
 
+<details>
+
+<summary>Real Project Example</summary>
+
+#### All Esp32 Xtensa toolchains in one call from the same compile_commands
+	
+Below, `-db` (short for `--compile-commands`) does this on a real ESP-IDF
+synth firmware: one `synth_core` effects source, compiled across the
+esp32 / esp32s2 / esp32s3 cross-toolchains in a single run, with each
+chip's include/define flags auto-borrowed from `build/compile_commands.json`
+so the component actually compiles. No `--target` and no path are given -
+the config's `default` names the three chips and `-db` walks up to find the
+database. Reading it left to right: the three `==` banners are the three
+toolchains; each table is that chip's per-function `insns` / loop spans /
+`calls`. The tell is in the `calls` column - the esp32-S2 (the one variant
+with no hardware FPU) picks up softfloat conversion libcalls
+`__floatsisf`, `__floatunsisf`, `__ltsf2` that its FPU-equipped siblings
+never emit, so the same source is measurably heavier there:
+
+[![asmdiff running a three-chip xtensa matrix (esp32/s2/s3) on one firmware source via -db](demo/esp32-matrix.gif)](demo/esp32-matrix.gif)
+
+*One source, three real chip toolchains, build flags borrowed
+automatically - the kind of comparison that otherwise needs three separate
+build trees. (Click to enlarge.)*
+
+---
+
+</details>
+
 When you run asmdiff from inside the project anyway, the path is
 redundant. Two opt-ins skip it:
 
@@ -550,6 +696,7 @@ asmdiff biquad.c --compile-commands            # same, for any matrix
 asmdiff biquad.c --compile-commands path/to/compile_commands.json
 ```
 
+
 Both walk up from the current directory, checking each level for
 `compile_commands.json` and then `build/compile_commands.json` (where
 CMake and idf.py leave it) — first hit wins. The walk stops at the
@@ -594,6 +741,11 @@ baseline (`../baseline/src/oscillators.c`), which is the same file under a
 path the database has never heard of. The absent-source error and the
 soft-miss note both point at this flag when a same-name entry exists.
 
+To contrast the same pair on a host compiler (does gcc-on-x86 make the
+same choice?), add `--db-includes`: the borrow then carries only the
+project's include paths, which are target-portable, and none of the
+cross-only defines or `-specs` a host gcc would choke on.
+
 ## Whole-file summary
 
 With no `--pair`, no `--across`, and no `old_*`/`new_*` functions to