asmdiff 0.1.6__tar.gz → 0.2.0__tar.gz

asmdiff-0.2.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.1.6/README.md → asmdiff-0.2.0/PKG-INFO

@@ -1,7 +1,42 @@
+Metadata-Version: 2.4
+Name: asmdiff
+Version: 0.2.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:
 
@@ -12,7 +47,7 @@
 does the compiler actually emit - before and after?** It compiles a small
 harness file across a matrix of compilers, extracts each variant function's
 assembly, and prints side-by-side listings plus a summary of instruction
-counts, outbound calls, and loop spans.
+counts, loop spans, and outbound calls.
 
 Compilers and flags are configured per project through named targets in an
 `asmdiff.toml` file, and any GNU-as ELF assembly is parsed.
@@ -76,9 +111,9 @@ endbr64                                      | endbr64
 mulss   .LC0(%rip), %xmm0                    | movl    $-5, %edi
 ret                                          | jmp     ldexpf@PLT
 
-function   role       insns  calls   loop spans
-old_scale  baseline   3      -       -
-new_scale  candidate  3      ldexpf  -
+function   role       insns  loop spans  calls
+old_scale  baseline   3      -           -
+new_scale  candidate  3      -           ldexpf
 ```
 
 Read the `calls` column first: `-` means the construct lowered to inline
@@ -139,9 +174,9 @@ call8   __udivdi3                            |
 mov.n   a2, a10                              |
 retw.n                                       |
 
-function        role       insns  calls      loop spans
-old_elapsed_ms  baseline   10     __udivdi3  -
-new_elapsed_ms  candidate  6      -          -
+function        role       insns  loop spans  calls
+old_elapsed_ms  baseline   10     -           __udivdi3
+new_elapsed_ms  candidate  6      -           -
 ```
 
 The candidate is six inline instructions ending in a multiply-high by
@@ -198,8 +233,8 @@ apply_gain:
 .L1:
         retw.n
 
-function    insns  calls  loop spans
-apply_gain  13     -      .L3_LEND:4
+function    insns  loop spans  calls
+apply_gain  13     .L3_LEND:4  -
 ```
 
 The span `.L3_LEND:4` is the four-instruction body of the Xtensa
@@ -228,11 +263,11 @@ $ asmdiff build/S3-Amysynth.elf --filter '^render_' # stats table only
 ```
 
 ```
-function                    insns  calls               loop spans
-render_lut_cub              98     -                   .L32:74
-render_lut                  51     -                   .L7e_LEND:32
-render_external_audio_in    32     -                   .L52_LEND:10
-render_partial              112    exp2f, __divsf3, ...  .L66:31
+function                    insns  loop spans    calls
+render_lut_cub              98     .L32:74       -
+render_lut                  51     .L7e_LEND:32  -
+render_external_audio_in    32     .L52_LEND:10  -
+render_partial              112    .L66:31       exp2f, __divsf3, ...
 ```
 
 (Four of the eleven matched rows shown.) The columns are the same as
@@ -255,23 +290,29 @@ 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)'
 
-function                             insns  calls                                                           loop spans
-sequencer_timer_callback$lto_priv$0  77     __divsf3, __udivdi3                                             .L21:41
-sequencer_recompute                  46     __extendsfdf2, __divdf3, __muldf3, __fixunsdfsi, __divsf3       -
-sequencer_process_tick$lto_priv$0    117    xQueueSemaphoreTake, xQueueGenericSend, add_delta_to_queue, a8  .L2e:96 .L48:85 .L8d:6
+function                             insns  loop spans              calls
+sequencer_timer_callback$lto_priv$0  77     .L21:41                 __divsf3, __udivdi3
+sequencer_recompute                  46     -                       __extendsfdf2, __divdf3, __muldf3, __fixunsdfsi, __divsf3
+sequencer_process_tick$lto_priv$0    117    .L2e:96 .L48:85 .L8d:6  xQueueSemaphoreTake, xQueueGenericSend, add_delta_to_queue, a8
 ```
 
 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
@@ -535,6 +576,35 @@ Details that make it robust:
 
 ### 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 +620,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
@@ -607,14 +678,14 @@ $ asmdiff old/delay.c new/delay.c
 
 -- old/delay.c --
 
-function         insns  calls        loop spans
-stereo_reverb    437    -            .L108:327
+function         insns  loop spans  calls
+stereo_reverb    437    .L108:327   -
 ...
-TOTAL (13 functions)  956   malloc_caps, free, ...  -
+TOTAL (13 functions)  956   -   malloc_caps, free, ...
 
 -- new/delay.c --
 ...
-TOTAL (13 functions)  1028  malloc_caps, free, ...  -
+TOTAL (13 functions)  1028  -   malloc_caps, free, ...
 ```
 
 The TOTAL row is a coarse sanity check — did this refactor move the file's
@@ -625,8 +696,13 @@ measurement, and per-function rows are where the real information is.
 Only labels the assembler types as functions are listed — global data
 (string constants, state structs, lookup tables) gets column-0 labels too
 but is not code. A `calls` list longer than 8 symbols is truncated to
-`..., +N more`; real firmware dispatch functions call dozens of distinct
-symbols and would otherwise make rows thousands of characters wide.
+`..., Total Calls:N`; real firmware dispatch functions call dozens of
+distinct symbols and would otherwise make rows thousands of characters
+wide. When stdout is a terminal, rows are additionally trimmed to the
+terminal width: callees are dropped from the end of the `calls` column
+(never the first one) behind the same `Total Calls:N` summary, so every
+row stays on one line. Piped or redirected output skips the width trim
+and keeps the full capped list, so it stays stable and greppable.
 
 ## Comparing the same function across two builds (`--across`)
 
@@ -687,9 +763,9 @@ movl    %r14d, %r11d                         | sarl    $11, %ebp
 call    SMULR6                               | leal    1024(%rax), %edx
   [... 60 rows omitted ...]
 
-function                     role       insns  calls   loop spans
-dsps_biquad_f32_ansi [cc#1]  baseline   59     SMULR6  .L27:32
-dsps_biquad_f32_ansi [cc#2]  candidate  89     -       .L26:54
+function                     role       insns  loop spans  calls
+dsps_biquad_f32_ansi [cc#1]  baseline   59     .L27:32     SMULR6
+dsps_biquad_f32_ansi [cc#2]  candidate  89     .L26:54     -
 ```
 
 (The listing is abridged here; the tool prints all 92 rows. The columns
@@ -725,9 +801,9 @@ call    ldexpf@PLT                           |
 leave                                        |
 ret                                          |
 
-function       role       insns  calls   loop spans
-new_rt [cc#1]  baseline   13     ldexpf  -
-new_rt [cc#2]  candidate  2      ldexpf  -
+function       role       insns  loop spans  calls
+new_rt [cc#1]  baseline   13     -           ldexpf
+new_rt [cc#2]  candidate  2      -           ldexpf
 ```
 
 **Two files** — before/after versions of a source file (e.g. from a git

asmdiff-0.1.6/PKG-INFO → asmdiff-0.2.0/README.md

@@ -1,25 +1,24 @@
-Metadata-Version: 2.4
-Name: asmdiff
-Version: 0.1.6
-Summary: Compare per-function assembly between paired C implementations
-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:
 
@@ -30,7 +29,7 @@ Description-Content-Type: text/markdown
 does the compiler actually emit - before and after?** It compiles a small
 harness file across a matrix of compilers, extracts each variant function's
 assembly, and prints side-by-side listings plus a summary of instruction
-counts, outbound calls, and loop spans.
+counts, loop spans, and outbound calls.
 
 Compilers and flags are configured per project through named targets in an
 `asmdiff.toml` file, and any GNU-as ELF assembly is parsed.
@@ -94,9 +93,9 @@ endbr64                                      | endbr64
 mulss   .LC0(%rip), %xmm0                    | movl    $-5, %edi
 ret                                          | jmp     ldexpf@PLT
 
-function   role       insns  calls   loop spans
-old_scale  baseline   3      -       -
-new_scale  candidate  3      ldexpf  -
+function   role       insns  loop spans  calls
+old_scale  baseline   3      -           -
+new_scale  candidate  3      -           ldexpf
 ```
 
 Read the `calls` column first: `-` means the construct lowered to inline
@@ -157,9 +156,9 @@ call8   __udivdi3                            |
 mov.n   a2, a10                              |
 retw.n                                       |
 
-function        role       insns  calls      loop spans
-old_elapsed_ms  baseline   10     __udivdi3  -
-new_elapsed_ms  candidate  6      -          -
+function        role       insns  loop spans  calls
+old_elapsed_ms  baseline   10     -           __udivdi3
+new_elapsed_ms  candidate  6      -           -
 ```
 
 The candidate is six inline instructions ending in a multiply-high by
@@ -216,8 +215,8 @@ apply_gain:
 .L1:
         retw.n
 
-function    insns  calls  loop spans
-apply_gain  13     -      .L3_LEND:4
+function    insns  loop spans  calls
+apply_gain  13     .L3_LEND:4  -
 ```
 
 The span `.L3_LEND:4` is the four-instruction body of the Xtensa
@@ -246,11 +245,11 @@ $ asmdiff build/S3-Amysynth.elf --filter '^render_' # stats table only
 ```
 
 ```
-function                    insns  calls               loop spans
-render_lut_cub              98     -                   .L32:74
-render_lut                  51     -                   .L7e_LEND:32
-render_external_audio_in    32     -                   .L52_LEND:10
-render_partial              112    exp2f, __divsf3, ...  .L66:31
+function                    insns  loop spans    calls
+render_lut_cub              98     .L32:74       -
+render_lut                  51     .L7e_LEND:32  -
+render_external_audio_in    32     .L52_LEND:10  -
+render_partial              112    .L66:31       exp2f, __divsf3, ...
 ```
 
 (Four of the eleven matched rows shown.) The columns are the same as
@@ -273,23 +272,29 @@ 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)'
 
-function                             insns  calls                                                           loop spans
-sequencer_timer_callback$lto_priv$0  77     __divsf3, __udivdi3                                             .L21:41
-sequencer_recompute                  46     __extendsfdf2, __divdf3, __muldf3, __fixunsdfsi, __divsf3       -
-sequencer_process_tick$lto_priv$0    117    xQueueSemaphoreTake, xQueueGenericSend, add_delta_to_queue, a8  .L2e:96 .L48:85 .L8d:6
+function                             insns  loop spans              calls
+sequencer_timer_callback$lto_priv$0  77     .L21:41                 __divsf3, __udivdi3
+sequencer_recompute                  46     -                       __extendsfdf2, __divdf3, __muldf3, __fixunsdfsi, __divsf3
+sequencer_process_tick$lto_priv$0    117    .L2e:96 .L48:85 .L8d:6  xQueueSemaphoreTake, xQueueGenericSend, add_delta_to_queue, a8
 ```
 
 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
@@ -553,6 +558,35 @@ Details that make it robust:
 
 ### 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:
 
@@ -568,6 +602,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
@@ -625,14 +660,14 @@ $ asmdiff old/delay.c new/delay.c
 
 -- old/delay.c --
 
-function         insns  calls        loop spans
-stereo_reverb    437    -            .L108:327
+function         insns  loop spans  calls
+stereo_reverb    437    .L108:327   -
 ...
-TOTAL (13 functions)  956   malloc_caps, free, ...  -
+TOTAL (13 functions)  956   -   malloc_caps, free, ...
 
 -- new/delay.c --
 ...
-TOTAL (13 functions)  1028  malloc_caps, free, ...  -
+TOTAL (13 functions)  1028  -   malloc_caps, free, ...
 ```
 
 The TOTAL row is a coarse sanity check — did this refactor move the file's
@@ -643,8 +678,13 @@ measurement, and per-function rows are where the real information is.
 Only labels the assembler types as functions are listed — global data
 (string constants, state structs, lookup tables) gets column-0 labels too
 but is not code. A `calls` list longer than 8 symbols is truncated to
-`..., +N more`; real firmware dispatch functions call dozens of distinct
-symbols and would otherwise make rows thousands of characters wide.
+`..., Total Calls:N`; real firmware dispatch functions call dozens of
+distinct symbols and would otherwise make rows thousands of characters
+wide. When stdout is a terminal, rows are additionally trimmed to the
+terminal width: callees are dropped from the end of the `calls` column
+(never the first one) behind the same `Total Calls:N` summary, so every
+row stays on one line. Piped or redirected output skips the width trim
+and keeps the full capped list, so it stays stable and greppable.
 
 ## Comparing the same function across two builds (`--across`)
 
@@ -705,9 +745,9 @@ movl    %r14d, %r11d                         | sarl    $11, %ebp
 call    SMULR6                               | leal    1024(%rax), %edx
   [... 60 rows omitted ...]
 
-function                     role       insns  calls   loop spans
-dsps_biquad_f32_ansi [cc#1]  baseline   59     SMULR6  .L27:32
-dsps_biquad_f32_ansi [cc#2]  candidate  89     -       .L26:54
+function                     role       insns  loop spans  calls
+dsps_biquad_f32_ansi [cc#1]  baseline   59     .L27:32     SMULR6
+dsps_biquad_f32_ansi [cc#2]  candidate  89     .L26:54     -
 ```
 
 (The listing is abridged here; the tool prints all 92 rows. The columns
@@ -743,9 +783,9 @@ call    ldexpf@PLT                           |
 leave                                        |
 ret                                          |
 
-function       role       insns  calls   loop spans
-new_rt [cc#1]  baseline   13     ldexpf  -
-new_rt [cc#2]  candidate  2      ldexpf  -
+function       role       insns  loop spans  calls
+new_rt [cc#1]  baseline   13     -           ldexpf
+new_rt [cc#2]  candidate  2      -           ldexpf
 ```
 
 **Two files** — before/after versions of a source file (e.g. from a git