asmdiff 0.3.3__tar.gz → 0.4.1__tar.gz

{asmdiff-0.3.3 → asmdiff-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: asmdiff
-Version: 0.3.3
+Version: 0.4.1
 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
@@ -76,6 +76,39 @@ the tool is a single stdlib-only file: `python3 asmdiff.py HARNESS.c`.
 Requires Python >= 3.8; `asmdiff.toml` config files need >= 3.11
 (stdlib `tomllib`).
 
+### Shell completion
+
+```bash
+asmdiff --install-completion        # bash, zsh or fish, taken from $SHELL
+```
+
+This writes a completion script into the directory your shell already
+autoloads from - `bash-completion`'s `completions/`,
+`~/.config/fish/completions/`, or `~/.zfunc/` - and never touches an rc
+file. A file asmdiff did not write is named and left alone rather than
+replaced. zsh reads `~/.zfunc` only once it is on `fpath`, so the command
+prints the two lines to add to `.zshrc` yourself:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+To keep everything in one rc file instead, `--completion SHELL` prints
+the script to stdout:
+
+```bash
+eval "$(asmdiff --completion bash)"   # in .bashrc
+```
+
+The flag list is read off the argument parser when the script is
+generated, so a script regenerated after an upgrade cannot drift from the
+tool. Completing `-t` offers the targets and groups from the config that
+run would resolve - a `--config PATH` already on the line is honoured -
+and a comma list is completed element by element. Each tab press starts
+Python and parses the config: fine for a `pip`, `pipx` or `uv tool`
+install, noticeably slow behind a cold `uvx` launcher.
+
 **Portability:** pure-stdlib Python with nothing intentionally
 platform-specific, developed and tested on Linux. On native Windows,
 `HOME` is usually unset, so replace `$HOME` with `$USERPROFILE` (or
@@ -100,10 +133,21 @@ Run:
 $ asmdiff myharness.c
 ```
 
-Output (gcc section shown, one per compiler):
+Output:
 
 ```
-== gcc -O3 ... ==
+cc#1: gcc -O3
+cc#2: clang -O3
+
+target  function   role       insns  loop spans  calls
+cc#1    old_scale  baseline   3      -           -
+cc#1    new_scale  candidate  3      -           ldexpf
+cc#1               delta      0      -           +ldexpf
+cc#2    old_scale  baseline   2      -           -
+cc#2    new_scale  candidate  2      -           ldexpf
+cc#2               delta      0      -           +ldexpf
+
+== cc#1 ==
 
 old_scale                                    | new_scale
 ---------------------------------------------+---------------------------------------------
@@ -111,21 +155,36 @@ endbr64                                      | endbr64
 mulss   .LC0(%rip), %xmm0                    | movl    $-5, %edi
 ret                                          | jmp     ldexpf@PLT
 
-function   role       insns  loop spans  calls
-old_scale  baseline   3      -           -
-new_scale  candidate  3      -           ldexpf
+== cc#2 ==
+
+old_scale                                    | new_scale
+---------------------------------------------+---------------------------------------------
+mulss   .LCPI0_0(%rip), %xmm0                | movl    $-5, %edi
+retq                                         | jmp     ldexpf@PLT
 ```
 
+Every run has the same three parts: a legend naming each row of the
+compiler matrix, one table covering the whole matrix, then the listings
+grouped under `== LABEL ==`. The label in the `target` column is the
+config target a row came from; the two fallback compilers here are
+unnamed, so they are numbered by their position in the matrix. A single
+unnamed row (one `--cc`) is its own label, and then the legend and the
+`target` column are both dropped - the blocks further down this README
+show both shapes.
+
 Read the `calls` column first: `-` means the construct lowered to inline
-instructions; a symbol name means a libcall. The side-by-side asm above it is
-the evidence.
+instructions; a symbol name means a libcall. The listings under the table
+are the evidence.
 
 The `loop spans` column reports `label:N` for every local label that some
 instruction branches back to: N instructions lie between the label and the
 last backward branch targeting it. Whole-function `insns` charges loop-hoisting
 changes for their one-time setup/writeback code; the span count is the part
 that repeats. Which span is your hot loop — and how often it runs — the
-listing and your source know, not the tool.
+listing and your source know, not the tool. A function with more than
+six spans shows the first six and a `+N more` tail, since past that the
+column stops being readable and the count is what is left to say;
+`--json` carries every span.
 
 A worked example is included — `asmdiff_example.c` reproduces the
 exp2f/ldexpf analysis for both constant and runtime shift amounts:
@@ -159,7 +218,10 @@ uint32_t new_elapsed_ms(uint64_t now, uint64_t then) {
 ```
 $ asmdiff elapsed.c --cc 'xtensa-esp32s3-elf-gcc -O2 -mlongcalls'
 
-== xtensa-esp32s3-elf-gcc -O2 -mlongcalls ==
+function        role       insns  loop spans  calls
+old_elapsed_ms  baseline   10     -           __udivdi3
+new_elapsed_ms  candidate  6      -           -
+                delta      -4     -           -__udivdi3
 
 old_elapsed_ms                               | new_elapsed_ms
 ---------------------------------------------+---------------------------------------------
@@ -173,12 +235,11 @@ sub     a11, a3, a11                         |
 call8   __udivdi3                            |
 mov.n   a2, a10                              |
 retw.n                                       |
-
-function        role       insns  loop spans  calls
-old_elapsed_ms  baseline   10     -           __udivdi3
-new_elapsed_ms  candidate  6      -           -
 ```
 
+One `--cc` row is its own label, so this run prints neither a legend nor
+a `target` column and the listing needs no `== LABEL ==` header.
+
 The candidate is six inline instructions ending in a multiply-high by
 the reciprocal constant in `.LC0`. The baseline hands the division to
 `__udivdi3` - a software divide loop whose cost the visible 10
@@ -198,11 +259,12 @@ the file - no harness, no pairing:
 
     $ asmdiff src/oscillators.c render_lut
 
-With one usable compiler you get the function's listing and a stats
-row; with exactly two (the default gcc + clang matrix) the listings
-appear side by side; with a bigger matrix each compiler gets its own
-block. `-l list` / `-l side-by-side` forces a presentation. Several
-function names can be given at once.
+With one usable compiler you get a stats row and the function's
+listing under it; with exactly two (the default gcc + clang matrix)
+the two listings are set side by side; with a bigger matrix the table
+covers the whole matrix and each row's listing follows under its own
+`== LABEL ==`. `-l list` / `-l side-by-side` forces a presentation.
+Several function names can be given at once.
 
 A bare name is inspected as a function; an argument that exists on
 disk is a second source file, and a path-looking argument that does
@@ -215,6 +277,9 @@ like this:
 ```
 $ asmdiff dsp_util.c apply_gain --cc 'xtensa-esp32s3-elf-gcc -O2 -mlongcalls'
 
+function    insns  loop spans  calls
+apply_gain  13     .L3_LEND:4  -
+
 apply_gain:
         entry   sp, 32
         wfr     f1, a4
@@ -232,9 +297,6 @@ apply_gain:
 .L3_LEND:
 .L1:
         retw.n
-
-function    insns  loop spans  calls
-apply_gain  13     .L3_LEND:4  -
 ```
 
 The span `.L3_LEND:4` is the four-instruction body of the Xtensa
@@ -277,18 +339,28 @@ everywhere else; two things are ELF-specific:
   targets, not labels, so in-function targets are rewritten to
   `.L<hex-offset>` labels (the offset from the function start - stable
   across rebuilds of an unchanged function, unlike link addresses). An
-  Xtensa zero-overhead loop's end address becomes `.L<off>_LEND`, so a
-  hardware loop is distinguishable from a branch loop in the `loop
-  spans` column at a glance: `render_lut` shipped its 32-instruction
-  body as a ZOL, `render_lut_cub` fell back to a 74-instruction
-  branch loop.
+  Xtensa zero-overhead loop's end address (a pi32v2 `rep` block's too)
+  becomes `.L<off>_LEND`, so a hardware loop is distinguishable from a
+  branch loop in the `loop spans` column at a glance: `render_lut`
+  shipped its 32-instruction body as a ZOL, `render_lut_cub` fell back
+  to a 74-instruction branch loop.
 - **`-mlongcalls` calls are resolved.** An out-of-range call survives
-  linking as `l32r a8, <lit>` + `callx8 a8`, which would otherwise
-  report a call to "a8". When the disassembly annotates the literal
-  with its value (`l32r a8, ... (40002274 <__divsf3>)`), the real
-  callee is reported instead. Calls stay register-named when the
-  evidence is missing or the register is overwritten in between -
-  a genuine function-pointer dispatch still reads as indirect.
+  linking as `l32r a8, <lit>` + `callx8 a8`, which has no callee name
+  of its own. When the disassembly annotates the literal with its
+  value (`l32r a8, ... (40002274 <__divsf3>)`), the real callee is
+  reported instead. When the evidence is missing or the register is
+  overwritten in between, the listing keeps the raw `callx8 a8` and
+  the `calls` column reports `indirect(a8)` - a genuine
+  function-pointer dispatch still reads as indirect, without the
+  register name masquerading as a symbol.
+- **Nearest-symbol noise is stripped.** objdump names every address
+  after the closest preceding symbol, so a literal pool word renders
+  as e.g. `l32r a8, <_stext+0x44> (<some_font_table+0x707ad9>)` - two
+  unrelated symbols decorating an address and a constant. Offset-form
+  annotations of foreign symbols become raw hex
+  (`l32r a8, 0x40370100 (0x3f8f5f80)`); bare-symbol annotations (a
+  real callee or object start) and offsets into the current function
+  itself are kept.
 
 What this looks like on real firmware: this binary's sequencer path -
 here in the vendored AMY synth engine (`components/amy/src/sequencer.c`,
@@ -301,7 +373,7 @@ $ asmdiff build/S3-Amysynth.elf --filter 'sequencer_(process_tick|recompute|time
 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
+sequencer_process_tick$lto_priv$0    117    .L2e:96 .L48:85 .L8d:6  xQueueSemaphoreTake, xQueueGenericSend, add_delta_to_queue, indirect(a8)
 ```
 
 A timer callback pays a software float divide *and* a 64-bit
@@ -318,8 +390,8 @@ is the double-promotion smell (typically an unsuffixed `60.0`-style
 literal) on a chip whose FPU is single-precision only. And the
 `$lto_priv$0` suffixes show LTO renaming the survivors, which is why
 `--filter` matters: you can't name symbols you don't know exist. The
-lone `a8` is a genuine function-pointer dispatch, reported as the
-register rather than guessed at.
+lone `indirect(a8)` is a genuine function-pointer dispatch, reported
+as such rather than guessed at.
 
 Functions LTO inlined away don't table at all, and the error says so
 usefully:
@@ -343,6 +415,22 @@ cue to pass a matching target.
 A whole firmware has over a thousand functions, so a bare ELF with no
 function names and no `--filter` is an error, not a thousand-row table.
 
+**Other toolchains.** Besides GNU objdump output, the JieLi pi32v2
+objdump's dialect is read (the AC79 family, e.g. the M-VAVE FM-1 and
+its open firmwares): bare `name:` headers, the space-padded byte column,
+`<sym+0x96 : addr >` targets and the decimal displacement before
+`call`/`goto` are normalised into the GNU shape, `.rodata` dumps are
+skipped, and the algebraic instruction form (`r5_r4 = r4 * r14 (s)`,
+`[r6+0] += r4`) is bucketed by shape for `--span-stats`. The
+toolchain's objdump sits beside its clang, so the bundled `pi32v2`
+profile (or any `--cc` naming that clang by path) derives it; otherwise
+pass `--objdump`. Compile mode works with
+`--cc '$JIELI_TOOLCHAIN/pi32v2/bin/clang -target pi32v2 -Os'`. The
+compiler does not emit the `rep` hardware loop from C, but vendor inline
+asm uses it (`rep n rN { ... }`); a `rep` block gets a span over its
+body, named `.L<off>_LEND` in ELF input like an Xtensa zero-overhead
+loop.
+
 If the question behind the sweep is "did my hot loops ship as
 zero-overhead loops", the empirical rules (verified on esp-gcc 15.2,
 `-O2`) are worth knowing before blaming the compiler:
@@ -357,12 +445,16 @@ 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]
+           [--target NAME]... [--cc 'CC FLAGS']... [--config PATH]
            [--compile-commands [PATH]] [--flags-like PATH] [--db-includes]
-           [--summary-only] [--collapse] [--span-stats]
+           [--filter REGEX] [--summary-only] [--collapse] [--span-stats]
+           [--cost] [--costs NAME] [--fail-on-growth] [--json] [--width N]
            [--layout list|side-by-side] [-v] [-- EXTRA_FLAGS...]
 asmdiff FIRMWARE.elf [FUNC...] [--filter REGEX] [--objdump PATH]
-           [-l list] [--summary-only] [--span-stats]
+           [-l list] [--summary-only] [--span-stats] [--cost] [--costs NAME]
+           [--json] [--width N]
+asmdiff --edit-config | --example-config | --list-targets | --version
+asmdiff --completion bash|zsh|fish | --install-completion [SHELL]
 ```
 
 | Option | Meaning |
@@ -371,18 +463,25 @@ asmdiff FIRMWARE.elf [FUNC...] [--filter REGEX] [--objdump PATH]
 | `-p, --pair OLD:NEW` | Compare two *different* functions within one compilation. Repeatable. Default: every `old_X` is auto-paired with its `new_X`; with no pairs at all, the whole-file summary is printed instead. |
 | `-a, --across FUNC` | Compare the *same* function across two compilations (see below). Repeatable. Mutually exclusive with `--pair`. |
 | `-l, --layout list\|side-by-side` | Force the inspect-mode presentation instead of the adaptive default (1 usable compiler lists, 2 go side by side, more list). With ELF input, `list` also prints `--filter` matches' listings. |
-| `--filter REGEX` | Also analyze every function whose name matches `REGEX` (`re.search`) — sweep a subsystem, or reach compiler-generated clones (`$constprop$0`, `.isra.0`), without naming each function. In compile modes matches are full peers of named functions (lenient when a match exists under only part of the matrix) and narrow the whole-file summary; in ELF mode matches appear in the stats table but are not listed in full — add `-l list` to print their listings too (a trailing note reminds you when listings were withheld). Not combinable with `--pair`/`--across`. |
+| `-f, --filter REGEX` | Also analyze every function whose name matches `REGEX` (`re.search`) — sweep a subsystem, or reach compiler-generated clones (`$constprop$0`, `.isra.0`), without naming each function. In compile modes matches are full peers of named functions (lenient when a match exists under only part of the matrix) and narrow the whole-file summary; in ELF mode matches appear in the stats table but are not listed in full — add `-l list` to print their listings too (a trailing note reminds you when listings were withheld). Not combinable with `--pair`/`--across`. |
 | `--objdump PATH` | Disassembler for ELF input. Default: derived from the first gcc in the matrix by swapping the trailing `gcc` for `objdump`, so `--target`/config globs locate it like they locate the compiler. |
 | `--cc 'CC FLAGS'` | One compiler invocation, command and flags in a single quoted string. Repeatable to build a matrix. |
-| `--target NAME` | A named target from the config file, resolved to a `--cc` entry. Repeatable; appended to the matrix after `--cc` entries. |
+| `-t, --target NAME` | A named target from the config file, resolved to a `--cc` entry. `NAME` may also be a `[groups]` entry, a comma-separated list, or a glob over target names (`-t 'esp32c*'`). Repeatable; appended to the matrix after `--cc` entries. See [Target groups](#target-groups). |
 | `--config PATH` | Config file to use. Default search: `asmdiff.toml` next to `SOURCE.c`, then in the current directory, then `~/.config/`. First hit wins. |
+| `--list-targets` | Print the resolved config's `default`, groups, cost profiles (name and `measured_on`), and targets (name and `cc`), then exit. No source file needed. |
 | `-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, omit 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. |
+| `--json` | Emit the summary as JSON on stdout instead of tables — one record per function per compiler, each carrying the `target` label of the matrix row it came from. Implies `--summary-only`; errors stay plain text on stderr. |
+| `-C, --collapse` | In side-by-side listings, omit runs of identical line pairs, keeping 3 lines of context around each difference. |
+| `--width N` | Column budget for tables and side-by-side listings. Default: the terminal's width, else `$COLUMNS`, else 120. `0` is unlimited, leaving the callee column untrimmed for a script to grep; a negative `N` is a usage error. |
+| `--span-stats` | Follow the stats table with a per-loop-span instruction mix: nesting depth and load/store/mul/div/branch/other counts per span. |
+| `--cost` | Add a `cost` column to the stats tables: the instruction classes of each function and the tier of every call site (`softfp`, `softfp-div`, `int-div`, `libm`, `mem`, `call`), with the sites a loop span holds counted apart. Counts only; a score appears when a profile prices them. See [Cost column](#cost-column). |
+| `--costs NAME` | Price the cost column with the config's `[costs.NAME]` profile on every matrix row, `--cc` rows and ELF input included; implies `--cost`. Overrides a `costs = "NAME"` the target names. See [Cost profiles](#cost-profiles). |
+| `--fail-on-growth` | Exit 3, naming each offender on stderr, if any candidate has more instructions than its baseline; exit 0 otherwise. Needs paired functions (`--pair`, auto-paired `old_X`/`new_X`, or `--across`). |
+| `--completion bash\|zsh\|fish` | Print a completion script for that shell on stdout and exit. Its flag list is read off the argument parser at generation time, so it cannot drift from the tool. See [Shell completion](#shell-completion). |
+| `--install-completion [SHELL]` | Write that script to the shell's own user completion directory and exit; no rc file is touched. `SHELL` defaults to the basename of `$SHELL`. An existing file is replaced only if asmdiff wrote it. |
 | `--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. |
@@ -409,45 +508,72 @@ asmdiff h.c -- -fno-math-errno
 Compilers missing from `PATH` are skipped with a warning; the run fails only
 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.
+warning that scrolled away. A row whose compile *fails* is dropped the same
+way: the remaining rows are compiled, their table and listings print, and
+the failing row's compiler output follows on stderr under its label
+(`error: [esp32s3] xtensa-esp32s3-elf-gcc failed on biquad.c`) once the
+run has printed everything it could. One broken target no longer costs
+you the others; the run still exits 1.
+
+| Status | Meaning |
+|---|---|
+| 0 | The run printed what was asked for. Differing assembly is the expected result, never an error. |
+| 1 | The tool failed: a compile error, an unknown `--pair` name, a config that does not load, no usable compiler in the matrix. |
+| 2 | argparse's usage error - an unknown flag, a missing value, a negative `--width`. |
+| 3 | `--fail-on-growth` found a candidate with more instructions than its baseline. |
 
 ## 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:
+Every run leads with the table: the legend, one summary table for the
+whole matrix, the `--span-stats` and provenance lines that belong to it,
+and then the listings, grouped per target under `== LABEL ==`. A
+two-file compare over a three-target matrix still prints three full
+side-by-side listings under that table, roughly 100 KB of them when the
+table was all the decision needed. Four 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
+  explaining. What is left is the legend, the table, and its footer.
+- **`--collapse`** (`-C`) 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
+  instead of ~1000 lines. Two sides that are equal line for line collapse
+  to their header with `(identical)` on the left title and no body at
+  all.
+
+  What it cannot collapse is the case where the two sides differ on every
+  line without differing in substance: a changed register allocation, a
+  reordered but equivalent schedule, one extra spill slot shifting every
+  offset. There is no identical run to elide, so the listing prints in
+  full. The summary table and `--span-stats` are the reading unit there:
+  the instruction classes, the calls, and the per-span mix say what
+  moved, where a line-by-line read of two differently allocated bodies
+  does not.
+- **`--span-stats`** follows the 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
+  function       span    depth  insns  load  store  mul  div  branch  other
+  stereo_reverb  .L108   0      327    96    31     14   0    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.
+  *depth* is how many other spans of the same function contain this
+  one, so an inner loop is told from the loop around it without reading
+  the listing ([How a span is found](#how-a-span-is-found)).
   Buckets are by mnemonic (Xtensa, RISC-V, ARM) with an AT&T
   memory-operand heuristic for x86; *branch* means any control
   transfer — conditional and unconditional branches, calls, and
   returns (outbound calls are already itemised by name in the `calls`
   column) — and anything the tables don't know lands in *other*.
+  *div* is a hardware divide or square root; a division done by a
+  libcall (`__divsf3`, `__udivdi3`) is a call, and the Xtensa FPU
+  divide sequence counts as the several instructions it is.
 
   Reading *branch* inside a span: a software loop's own backedge is
   one of them, because the span runs from the label to the last
@@ -460,21 +586,54 @@ output to purpose:
   show as *branch* falling while *insns* stays roughly flat, and a
   call appearing inside a hot span is the ZOL killer the `calls`
   column already flagged.
+- **`--cost`** adds a `cost` column to the stats tables saying what
+  each function is made of: the same instruction classes over the
+  whole body, and the tier of every call site with the sites a loop
+  span holds counted apart. `--costs NAME` prices those counts with a
+  measured profile from the config. Both are described under [Cost
+  column](#cost-column) below.
+
+All four combine with every compile mode; `--summary-only`,
+`--span-stats`, `--cost` and `--costs` also apply to ELF input.
 
-All three combine with every compile mode; `--summary-only` and
-`--span-stats` also apply to ELF input.
+Tables and side-by-side listings take their width from the terminal,
+falling back off one to `$COLUMNS` and then to 120 columns; `--width N`
+sets the budget directly, and `--width 0` means unlimited, which is the
+untrimmed callee column a script greps.
 
 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.
-There is no built-in jq subcommand and there won't be: the tool prints
-JSON on stdout, so a plain `| jq` pipe *is* the integration, and jq
-already does the filtering better than a wrapper flag could.
+function per compiler — `target` (the matrix row's label, the same
+string the table's `target` column prints), `cc`, `tag` (source label
+in two-file runs), `role` (`baseline`/`candidate` in paired runs),
+`insns`, `loop_spans` (each `{label, insns, depth}`), `calls`, `delta`
+(on candidate records), `cost` when `--cost` or `--costs` is given, and
+`span_stats` when `--span-stats` is given. An ELF run compiles nothing,
+so its records have no matrix row to name and carry neither `target`
+nor `cc`. Flat records keep it one `jq` expression away from any
+question the tables answer.
+
+The pairing questions the tool answers itself, because the pairing is
+its own: every summary table closes a pair with a `delta` row (signed
+instruction count, per-span `before -> after`, callees gained with `+`
+and lost with `-`, and under `--cost` the classes and tiers that
+moved), each candidate record carries the same as a `delta` object,
+and `--fail-on-growth` makes it an exit status:
+
+```bash
+# Fail the job when a rewrite that was meant to shrink did not
+asmdiff old.c new.c -a stereo_reverb -t esp32s3 --fail-on-growth -s
+```
+
+Exit 3 and one `growth: FUNC +N insns (BASELINE -> CANDIDATE)` line per
+offender on stderr if any candidate has more instructions than its
+baseline, exit 0 otherwise; status 1 is left meaning the tool itself
+failed and 2 is argparse's usage error, so a job can tell "grew" from
+"did not compile" from "misused the flags".
 
-A few recipes that cover the common questions:
+Arbitrary selection stays jq's: the tool prints JSON on stdout, so a
+plain `| jq` pipe *is* the integration, and jq does that filtering
+better than a wrapper flag could. A few recipes:
 
 ```bash
 # Instruction count per function per side, as a table
@@ -485,19 +644,14 @@ asmdiff old.c new.c --json \
 asmdiff old.c new.c --json \
   | jq '.results[] | select(.calls | length > 0) | {function, tag, calls}'
 
-# Per-function old→new instruction delta (regressions have a positive delta)
-asmdiff old.c new.c --json \
-  | jq -r '.results | group_by(.function)[] | select(length == 2)
-           | "\(.[0].function): \(.[0].insns) -> \(.[1].insns) (\(.[1].insns - .[0].insns))"'
-
-# Fail CI if any function grew, using jq's exit status
-asmdiff old.c new.c --json \
-  | jq -e '.results | group_by(.function)
-           | all(length < 2 or .[1].insns <= .[0].insns)' > /dev/null
-
 # The full record for one hot function, spans and all
 asmdiff old.c new.c -a stereo_reverb --json --span-stats \
   | jq '.results[] | {role, insns, spans: .loop_spans}'
+
+# Functions reaching a soft-float helper from inside a loop
+asmdiff old.c new.c --json --cost \
+  | jq '.results[] | select(.cost.tiers_in_loop.softfp > 0)
+        | {function, tag, in_loop: .cost.tiers_in_loop}'
 ```
 
 The top level carries `asmdiff` (version) and `mode`
@@ -505,6 +659,99 @@ The top level carries `asmdiff` (version) and `mode`
 path as `elf`). Warnings and errors stay plain text on stderr, so a
 failed run never emits half a document.
 
+### Cost column
+
+`--cost` adds a `cost` column before `calls`, saying what each function
+is made of rather than how many lines long it is:
+
+```
+$ asmdiff asmdiff_example.c --cost -s --cc 'gcc -O2'
+
+function   role       insns  loop spans  cost                                  calls
+old_const  baseline   3      -           mul:1 | br:1 | oth:1                  -
+new_const  candidate  3      -           br:1 | oth:2 | libm:1                 ldexpf
+           delta      0      -           mul:-1 | oth:+1 | libm:+1             +ldexpf
+old_rt     baseline   9      -           st:1 | mul:1 | br:2 | oth:5 | libm:1  exp2f
+new_rt     candidate  2      -           br:1 | oth:1 | libm:1                 ldexpf
+           delta      -7     -           st:-1 | mul:-1 | br:-1 | oth:-4       +ldexpf -exp2f
+```
+
+Instructions fall into the six classes `--span-stats` uses, abbreviated
+here (`ld`, `st`, `mul`, `div`, `br`, `oth`). Every call site is
+additionally tiered by the callee's name:
+
+| Tier | Callees |
+|---|---|
+| `softfp` | soft-float add, subtract, multiply, compare, convert: `__addsf3`, `__muldf3`, `__floatsidf`, `__aeabi_dmul`, `__aeabi_i2d` |
+| `softfp-div` | soft-float divide: `__divsf3`, `__divdf3`, `__aeabi_fdiv`, `__aeabi_ddiv` |
+| `int-div` | integer divide and modulo helpers: `__udivdi3`, `__moddi3`, `__aeabi_idivmod`, `__aeabi_uldivmod` |
+| `libm` | the math families, float and double: `sqrtf`, `sin`, `exp2f`, `ldexpf`, `pow`, `fmod` |
+| `mem` | `memcpy`, `memset`, `memmove`, `memcmp` |
+| `call` | everything else, `indirect(<reg>)` included |
+
+The libgcc and the ARM EABI spelling of one helper land in the same
+tier, so a `__muldf3` target and a `__aeabi_dmul` target read alike. A
+name no pattern knows lands in `call`, where the `calls` column already
+spells it out.
+
+Each tier is followed by how many of its call sites a loop span holds -
+`softfp:3 (2 in loop)` - since a soft-float helper reached once per
+iteration is a different finding from one on an error path. The counts
+are per call site, not per distinct callee: two calls to `__muldf3`
+count twice, where the `calls` column names it once.
+
+The delta row's cost cell lists only what moved. A tier whose count
+came through the rewrite unchanged is absent from it even when the
+callee changed: `old_rt` and `new_rt` above each hold one `libm` call,
+so the cell says nothing about `libm` while the `calls` column carries
+the swap as `+ldexpf -exp2f`. The two cells are read together.
+
+With a profile (`--costs NAME`, or a target's `costs = "NAME"`), the
+cell opens with a score and the number of instructions and call sites
+no weight covered, and the table is followed by the line saying where
+the weights came from:
+
+```
+score 399 (1 unweighted) | ld:40 | st:12 | mul:14 | ...
+...
+costs: esp32s3-iram - ESP32-S3 rev 0.2, code in IRAM, esp-15.2.0 libgcc; esp_cpu_get_cycle_count harness, median of 1000 runs
+```
+
+The weights behind that score are the commented template in
+`asmdiff --example-config`, not a measurement; no measured profile
+ships with the tool, and [Cost profiles](#cost-profiles) below is how
+one is written. The delta row leads with the signed score. A cell is
+capped at 56 characters and closes with `...` when the mix does not fit
+(as it does here), so the table stays aligned; `--json` carries all of
+it:
+
+```json
+"cost": {
+  "classes": {"load": 40, "store": 12, "mul": 14, "div": 1,
+              "branch": 9, "other": 61},
+  "tiers": {"softfp": 3, "call": 1},
+  "tiers_in_loop": {"softfp": 2},
+  "score": 399,
+  "unweighted": 1,
+  "profile": {"name": "esp32s3-iram",
+              "measured_on": "ESP32-S3 rev 0.2, code in IRAM, ...",
+              "method": "esp_cpu_get_cycle_count harness, ..."}
+}
+```
+
+`classes` always carries all six keys. `tiers` and `tiers_in_loop` list
+only what the function reaches, so `.cost.tiers.softfp` on a function
+with no soft-float is `null` rather than `0` - `// 0` in the jq
+expression if you want a number. Without a profile, `score` and
+`profile` are `null` and `unweighted` is every instruction and call
+site the function has. Candidate records also gain `delta.cost`
+(`classes`, `tiers`, `score`), again signed and again only what moved.
+
+ELF input takes `--cost` and `--costs` like a compile run does. A
+target's `costs = "NAME"` is not consulted there: nothing is compiled,
+so no matrix row stands behind the binary's instructions. Name the
+profile with `--costs`.
+
 ## Config file: named targets
 
 Retyping a cross-compiler path and ten flags per run is the enemy of actually
@@ -532,8 +779,9 @@ flags = ["-O2", "-DMY_FEATURE", "-I$HOME/project/components/dsp/include"]
 survives toolchain upgrades (`esp-14` → `esp-15`) without editing. A
 pattern matching several installed toolchains resolves to the highest
 version-sorted one — numerically, so `esp-15` beats `esp-9` — and the
-choice is printed to stderr; the `==` header in the output always shows
-the fully resolved command that actually ran. No match is an error. Pin
+choice is printed to stderr; the legend line above the table always
+shows the fully resolved command that actually ran, so the short
+`target` label never hides which binary it was. No match is an error. Pin
 the exact directory instead when reproducibility matters more than
 convenience. Flags expand `$VARS` only (no globbing).
 
@@ -542,16 +790,122 @@ shapes:
 
 ```bash
 asmdiff h.c                                  # config default target(s)
-asmdiff h.c --target esp32s3 --target host      # two-target matrix
-asmdiff h.c --across f --target esp32s3 --cc 'gcc -O2'  # mix freely
+asmdiff h.c -t esp32s3 -t host               # two-target matrix
+asmdiff h.c -t esp32s3,host                  # same, as a comma list
+asmdiff h.c --across f -t esp32s3 --cc 'gcc -O2'  # mix freely
+asmdiff --list-targets                       # what does my config define?
 ```
 
 A config placed next to your harness files travels with them: any invocation
-naming a source in that directory finds it, from any CWD. `default` may be a
-single name or a list (a whole default matrix). The
-included `asmdiff.example.toml` is a starting point. If a flag or include
-path must vary per machine, that's what per-machine config files are for —
-nothing lives in the tool.
+naming a source in that directory finds it, from any CWD.
+
+`default` takes whatever `-t` takes: a target name, a `[groups]` name, a
+comma list, a glob over target names, or an array mixing those
+(`default = ["native", "esp32s3"]`). A name it cannot resolve is the
+same error `-t` would give. One idiom worth knowing is the one-member
+group: `[groups] ship = ["esp32s3"]` with `default = "ship"` gives the
+standing matrix a name of its own, so widening the run later is editing
+the group rather than every `default` and script that mentions the
+target.
+
+The included `asmdiff.example.toml` is a starting point. If a flag or
+include path must vary per machine, that's what per-machine config files
+are for — nothing lives in the tool.
+
+### Target groups
+
+A `[groups]` table names matrices of targets so a whole family runs
+from one `-t`, without editing `default`:
+
+```toml
+[groups]
+riscv32-esp = ["esp32c3", "esp32c6", "esp32h2", "esp32p4"]
+native = ["gcc", "clang"]
+```
+
+```bash
+asmdiff h.c -t riscv32-esp        # four RISC-V targets
+asmdiff h.c -t native -t esp32s3  # a group plus a single target
+asmdiff h.c -t 'esp32c*'          # glob over target names (quote it)
+```
+
+A `-t` value is resolved as an exact target name first, then as a group
+name, then as a glob (`*`, `?`, `[...]`) over target names in config
+order. A group naming an undefined target, or an empty group, is an
+error. `--list-targets` prints what the resolved config defines.
+
+### Cost profiles
+
+A `[costs.NAME]` table holds measured weights and where they were
+measured. `--cost` alone counts; with a profile in hand it also scores:
+
+```toml
+[costs.esp32s3-iram]
+measured_on = "ESP32-S3 rev 0.2, code in IRAM, esp-15.2.0 libgcc"
+method = "esp_cpu_get_cycle_count harness, median of 1000 runs"
+other = 1
+load = 2
+store = 1
+mul = 2
+div = 20
+branch = 2
+softfp = 60
+softfp-div = 200
+int-div = 40
+"__muldf3" = 90
+
+[esp32s3]
+cc = "..."
+flags = ["-O2", "-mlongcalls"]
+costs = "esp32s3-iram"
+```
+
+A key's value decides what it is. A number is a weight, keyed by an
+instruction class (`load`, `store`, `mul`, `div`, `branch`, `other`),
+a libcall tier (`softfp`, `softfp-div`, `int-div`, `libm`), or a call
+symbol in quotes (`"__muldf3" = 90`). A string is provenance:
+`measured_on` and `method` are required and the load fails naming the
+one that is missing, and any further string key is kept and printed
+after them. Anything else is an error naming the key. `mem` and `call`
+are refused a weight, since a `memcpy`'s cost is its size argument and
+an unknown callee's is its body, neither of which the assembly shows;
+both stay counted and land in the unweighted total. `extends = "OTHER"`
+copies another profile's weights before this table's own apply, one
+level deep - a chain is an error.
+
+Weights resolve in this order. An instruction costs its class weight,
+or counts as unweighted. A call site costs its callee's own weight
+where the profile names that symbol, else its tier's weight, else it
+counts as unweighted. The score is therefore always printed with the
+number of instructions and call sites it left out. It is an integer
+while every weight is; one fractional weight anywhere rounds the total
+to a decimal.
+
+Which profile a row uses: `--costs NAME` sets it for every matrix row
+and is the only route for a `--cc` row, which has no target to read one
+from; otherwise each target brings the one its `costs = "NAME"` names,
+so a two-target matrix scores each target under its own. A name that
+does not resolve fails before the first compile. `--list-targets`
+prints the profiles a config defines, with their `measured_on`.
+
+What a score claims, and what it does not:
+
+- **A weight is a static issue cost.** Dual issue, pipeline stalls,
+  cache and flash-fetch latency, and the operand-dependence of helpers
+  like `__divdf3` are not in it. Two scores that differ by a few
+  percent say nothing.
+- **Scores compare within one target.** Cycle costs differ per core,
+  per memory placement, and per libgcc build, so a score under
+  `esp32s3-iram` and a score under some other profile are two different
+  units. That is why the provenance line prints under every scored
+  table.
+- **Depth is reported, not multiplied.** A span at depth 2 scores like
+  one at depth 0; the trip count is not in the assembly. `--span-stats`
+  gives the depth and the per-span mix, and the weighing is yours.
+
+No measured profile ships with the tool. `asmdiff --example-config`
+carries the template above as comments, with the fields a reader needs
+in order to judge how approximate the numbers are.
 
 ### Bundled ESP profiles
 
@@ -578,7 +932,10 @@ flags = ["-O2", "-march=rv32imac_zicsr_zifencei", "-mabi=ilp32"]
 A profile is nothing more than a curated group of targets — the `esp-*`
 glob finds the toolchains `idf_tools.py install` left in `~/.espressif`
 (the newest, by the version-sort rule above, when several are
-installed), and setting `default` to the group runs it as one matrix:
+installed). The example config defines each profile as a `[groups]`
+entry, so `-t riscv32-esp` or `-t xtensa-esp` runs it as one matrix and
+`-t esp` runs every ESP chip; set `default` to a group's list to make it
+the no-argument matrix:
 
 ```toml
 default = ["esp32c3", "esp32c6", "esp32h2", "esp32p4"]
@@ -672,7 +1029,7 @@ Details that make it robust:
 - **Absent source is an error**, not a silent empty flag set — otherwise
   you'd just hit the missing-header failure this feature exists to prevent.
   The message flags a same-basename entry recorded under a different path.
-- **`compile_commands` expands `~` and `$VARS`.** The `==` header always
+- **`compile_commands` expands `~` and `$VARS`.** The legend line 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**,
@@ -739,10 +1096,25 @@ Both walk up from the current directory, checking each level for
 CMake and idf.py leave it) — first hit wins. The walk stops at the
 repository root (the first directory with a `.git`), so running from any
 depth of component directory finds the project database, but an unrelated
-one further up the filesystem is never picked up. Finding nothing is an
-error: discovery is opt-in, so if you asked for it, silence would be a
-lie. It is never on by default — a target without `compile_commands` and
-no `--compile-commands` flag borrows nothing.
+one further up the filesystem is never picked up. It is never on by
+default — a target without `compile_commands` and no
+`--compile-commands` flag borrows nothing.
+
+The two opt-ins differ in what happens when the walk finds nothing:
+
+- **A bare `--compile-commands` is an error.** You asked for a database
+  in this run and there is none; compiling anyway would silently drop
+  the flags you came for.
+- **`compile_commands = true` in a target is a note.** The config
+  describes where that target is usually compiled, not what this run
+  is. A harness file compiled from a directory with no `build/` under
+  it gets `target [esp32s3]: no compile_commands.json found near the
+  current directory; compiling without borrowed flags` on stderr and
+  compiles with the target's own `cc`/`flags`, which is what a
+  standalone harness wants.
+
+`compile_commands = "PATH"` naming a database that is not there stays an
+error under both: a path that does not resolve is a typo, not a context.
 
 The precedence is what you'd hope: a target that names its own
 `compile_commands` path always keeps it; `--compile-commands` (with or
@@ -787,25 +1159,23 @@ cross-only defines or `-specs` a host gcc would choke on.
 
 With no `--pair`, no `--across`, and no `old_*`/`new_*` functions to
 auto-pair, the tool prints what it parsed instead of erroring: every
-function's counts plus a file total. With two files, one block per file:
+function's counts plus a file total. With two files, a leading `file`
+column tells the two apart inside the one table:
 
 ```
 $ asmdiff old/delay.c new/delay.c
 
-== xtensa-esp32s3-elf-gcc -O2 ... ==
-
--- old/delay.c --
-
-function         insns  loop spans  calls
-stereo_reverb    437    .L108:327   -
-...
-TOTAL (13 functions)  956   -   malloc_caps, free, ...
-
--- new/delay.c --
-...
-TOTAL (13 functions)  1028  -   malloc_caps, free, ...
+file         function              insns  loop spans  calls
+old/delay.c  stereo_reverb         437    .L108:327   -
+old/delay.c  ...
+old/delay.c  TOTAL (13 functions)  956    -           malloc_caps, free, ...
+new/delay.c  ...
+new/delay.c  TOTAL (13 functions)  1028   -           malloc_caps, free, ...
 ```
 
+Over a matrix of several targets a `target` column leads the `file` one,
+so the whole run is still one table.
+
 The TOTAL row is a coarse sanity check — did this refactor move the file's
 weight, did a call appear that shouldn't have? It sums parsed function
 bodies only (no literal pools, data, or alignment), so it is not a size
@@ -814,13 +1184,15 @@ 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
-`..., 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.
+`..., ... (N total)` (the leading `...` marks the elision, so the
+marker never reads as one more callee); real firmware dispatch
+functions call dozens of distinct symbols and would otherwise make
+rows thousands of characters wide. Rows are additionally trimmed to the
+column budget - the terminal, else `$COLUMNS`, else 120: callees are
+dropped from the end of the `calls` column (never the first one) behind
+the same `... (N total)` marker, so every row stays on one line.
+`--width 0` turns the trim off and keeps the full capped list, which is
+the shape to pipe into a grep.
 
 ## Comparing the same function across two builds (`--across`)
 
@@ -852,6 +1224,11 @@ asmdiff src/filters.c --across dsps_biquad_f32_ansi \
 cc#1: gcc -Os
 cc#2: gcc -O3
 
+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     -
+                             delta      +30    32 -> 54    -SMULR6
+
 == cc#1 vs cc#2 ==
 
 dsps_biquad_f32_ansi [cc#1]                  | dsps_biquad_f32_ansi [cc#2]
@@ -880,10 +1257,6 @@ addl    %eax, %edx                           | sarl    $11, %r12d
 movl    %r14d, %r11d                         | sarl    $11, %ebp
 call    SMULR6                               | leal    1024(%rax), %edx
   [... 60 rows omitted ...]
-
-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
@@ -892,8 +1265,8 @@ the listing shows why — `SMULR6` inlined into the loop body, vector setup
 around it. Whether that trade is good is your call.)
 
 The output prints a legend mapping `cc#N` tags to the full compiler
-invocations, then one section per baseline/candidate pairing. Runnable
-against the bundled example file:
+invocations, then the table, then one listing section per
+baseline/candidate pairing. Runnable against the bundled example file:
 
 ```
 $ asmdiff asmdiff_example.c --across new_rt --cc 'gcc -O0' --cc 'gcc -O3'
@@ -901,6 +1274,11 @@ $ asmdiff asmdiff_example.c --across new_rt --cc 'gcc -O0' --cc 'gcc -O3'
 cc#1: gcc -O0
 cc#2: gcc -O3
 
+function       role       insns  loop spans  calls
+new_rt [cc#1]  baseline   13     -           ldexpf
+new_rt [cc#2]  candidate  2      -           ldexpf
+               delta      -11    -           -
+
 == cc#1 vs cc#2 ==
 
 new_rt [cc#1]                                | new_rt [cc#2]
@@ -918,15 +1296,12 @@ movd    %eax, %xmm0                          |
 call    ldexpf@PLT                           |
 leave                                        |
 ret                                          |
-
-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
-worktree, a branch checkout, or a patched copy). Each compiler in the matrix
-gets its own section:
+worktree, a branch checkout, or a patched copy). Every compiler in the
+matrix lands in the one table under its own `target` label, and each
+gets its own listing section:
 
 ```bash
 git worktree add ../baseline main
@@ -978,8 +1353,10 @@ The summary makes the trade-off immediate:
 function                              role       insns  calls
 exp2_lut [amy-baseline/log2_exp2.c]   baseline   65     exp2f
 exp2_lut [amy/log2_exp2.c]            candidate  59     ldexpf
+                                      delta      -6     +ldexpf -exp2f
 log2_lut [amy-baseline/log2_exp2.c]   baseline   58     -
 log2_lut [amy/log2_exp2.c]            candidate  64     ldexpf
+                                      delta      +6     +ldexpf
 ```
 
 The runtime site improves (a leaner libcall replaces `exp2f` + multiply),
@@ -1000,6 +1377,8 @@ probed the same way.
    x86 (`call`, `jmp` tail calls), ARM (`bl`, `blx`), RISC-V (`call`,
    `tail`, `jal`), and Xtensa (`call0/4/8/12`, `callx*`, `j`). Local-label
    branches and register-indirect x86 jumps are not counted as calls.
+   Register-indirect call mnemonics (`callx8 a8`, single-operand `jalr`,
+   `blx r3`) are reported as `indirect(<reg>)`.
 4. Loop spans come from label references alone — no mnemonic tables, no
    control-flow analysis. The next section walks through it.
 
@@ -1033,6 +1412,16 @@ into that label's single span. Nested labels report separately — the
 outer span simply contains the inner one. Forward references (loop exits
 like `jle .L24`) are ignored.
 
+Containment is what the `depth` column of `--span-stats` reports: a
+span's depth is the number of other spans of the same function that
+start at or before it and end at or after it. An outermost loop is
+depth 0, a loop nested in it 1, and a span at depth 1 runs its body
+once per iteration of the span at depth 0. Two labels covering exactly
+the same lines (one loop body reached by two edges) contain each other
+under no reading, so both keep the depth of whatever encloses them.
+Depth is a nesting fact and nothing more - the trip count is not in the
+assembly, so nothing in the tool multiplies a count by it.
+
 The one arch-specific case is Xtensa zero-overhead loops, where the
 hardware — not a branch — repeats the body, and the `loop` instruction
 names its *end* label, forward:
@@ -1045,6 +1434,9 @@ names its *end* label, forward:
     retw.n
 ```
 
+pi32v2's `rep` hardware loop (`rep .Ltmp8 r7` in `-S` output, `rep 6 r7 {`
+in objdump) is the same case, with its body ending at the named label.
+
 That is the entire mechanism. There is no CFG, no trip count, and no
 notion of "the" loop: a backward `goto` produces a span exactly like a
 `for` loop, and an unrolled loop's span is the unrolled body. The column
@@ -1063,6 +1455,11 @@ misreadings to avoid are few and predictable:
   cost more than the rest of the function. Treat the count as a *size*
   and *structure* fact - a call appearing, a loop body growing, a
   softfloat sequence materializing - and measure time on the target.
+  `--cost` splits the same body into instruction classes and libcall
+  tiers, so that one `__udivdi3` line reads as an `int-div` call
+  instead of as one more instruction; a `[costs.NAME]` profile prices
+  those counts in measured cycles, which is still a static issue cost
+  and still not a measurement of your program.
 
 - **The cost of a call is in the callee.** The listing shows only the
   call site. The `-O3` version of `new_rt` above is two instructions,
@@ -1071,7 +1468,9 @@ misreadings to avoid are few and predictable:
 
 - **Weigh the span, not the function.** One instruction added inside a
   loop that runs per sample outweighs twenty added to setup code. The
-  whole-function count charges both the same.
+  whole-function count charges both the same; `--span-stats` gives the
+  per-span mix and its nesting depth, and `--cost` counts the call
+  sites a span holds apart from the rest.
 
 - **Bigger is often faster.** Unrolling and vectorization raise every
   count on purpose - the `-Os` vs `-O3` biquad above is bigger by every
@@ -1122,15 +1521,19 @@ standard library, and contains no project-specific constants. To port:
   supported — on a Mac, compare inside a Linux container or with a
   cross-toolchain.
 - Call detection is a mnemonic heuristic. Register-indirect calls through a
-  loaded address (other than x86 `jmp *reg`) can be reported as a call to
-  the register's name (e.g. Xtensa `callx8 a10`), which errs toward
-  visibility rather than silence. ELF input narrows this: `-mlongcalls`
-  sequences are resolved to their real callee when objdump's literal
-  annotation names one; genuine function-pointer dispatch still reads
-  as a register.
-- Columns truncate long instruction lines to keep pairs aligned; when a
-  line matters, widen it via the `width` parameter of `side_by_side()` or
-  read the raw `-S` output by hand.
+  loaded address (other than x86 `jmp *reg`) are reported as
+  `indirect(<reg>)` (e.g. Xtensa `callx8 a10` -> `indirect(a10)`), which
+  errs toward visibility rather than silence. ELF input narrows this:
+  `-mlongcalls` sequences are resolved to their real callee when objdump's
+  literal annotation names one; genuine function-pointer dispatch still
+  reads as indirect.
+- Side-by-side columns truncate long instruction lines to keep pairs
+  aligned, and drop a trailing assembler comment (clang's `# TAILCALL`,
+  `# 8-byte Reload`) before truncating, so the operands survive at half
+  a terminal's width. An ARM `#4` immediate has no space after the hash
+  and is untouched. Each side gets half the column budget, so `--width`
+  widens them; `-l list`, the single-column listings and `--json` keep
+  the line as extracted, comment included.
 - Loop spans are layout facts, not loop analysis. Label numbers are
   compiler-assigned, so a baseline's `.L27` and a candidate's `.L26` may
   or may not be "the same" loop — match them through the listing, not by