asmdiff 0.2.0__tar.gz → 0.3.0__tar.gz

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.2.0 → asmdiff-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asmdiff
-Version: 0.2.0
+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
@@ -358,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 |
@@ -376,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. |
 
@@ -399,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
 
@@ -573,6 +638,17 @@ 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
 
@@ -665,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

{asmdiff-0.2.0 → asmdiff-0.3.0}/README.md

@@ -340,9 +340,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 |
@@ -358,6 +360,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. |
 
@@ -381,9 +389,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
 
@@ -555,6 +620,17 @@ 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
 
@@ -647,6 +723,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

{asmdiff-0.2.0 → asmdiff-0.3.0}/asmdiff.example.toml

@@ -26,6 +26,12 @@ flags = [
 cc = "clang"
 flags = ["-O3", "-Wall", "-Wextra"]
 
+# The name the docs use for "your native compiler" (--target host): an
+# alias of [gcc] kept as its own table so the examples work verbatim.
+[host]
+cc = "gcc"
+flags = ["-O3", "-Wall", "-Wextra"]
+
 # cc values may use ~, $VARS, and glob patterns.  A glob that matches
 # several installed toolchains resolves to the highest version-sorted
 # one (announced on stderr); pin the exact esp-NN directory instead if