asmdiff 0.2.0__py3-none-any.whl → 0.3.3__py3-none-any.whl

{asmdiff-0.2.0.dist-info → asmdiff-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: asmdiff
-Version: 0.2.0
+Version: 0.3.3
 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]
+           [-l list] [--summary-only] [--span-stats]
 ```
 
 | Option | Meaning |
@@ -368,14 +370,20 @@ asmdiff FIRMWARE.elf [FUNC...] [--filter REGEX] [--objdump PATH]
 | `SOURCE.c` | C file to compile — a purpose-built harness or a real project source. A second file may be given: with `--across` to compare a function, without it for a whole-file A/B summary. Bare names after the file are functions to inspect (see [Quick inspect](#quick-inspect-one-function-no-comparison)). An ELF binary (any name — detected by magic bytes) switches to [ELF input](#elf-input-what-actually-shipped-after-lto) instead of compiling. |
 | `-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). Inspect mode only. |
-| `--filter REGEX` | ELF input only: also analyze every function whose name matches `REGEX` (`re.search`) — sweep a subsystem without naming each function. Matches appear in the stats table but are not listed in full. |
+| `-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`. |
 | `--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. |
 | `--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, 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. |
+| `--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,103 @@ 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* 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*.
+
+  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
+  backward branch inclusive. A Xtensa zero-overhead loop instead
+  encloses only the body between `loop` and its end label, so the loop
+  machinery contributes zero and any branch counted there is real
+  per-iteration control flow — early exits, per-sample `if`/`else`,
+  wrap-around checks. Track it across variants: branches replaced by
+  conditional moves (`movnez`, `csel`, `cmov` — counted under *other*)
+  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.
+
+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.
+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.
+
+A few recipes that cover the common questions:
+
+```bash
+# Instruction count per function per side, as a table
+asmdiff old.c new.c --json \
+  | jq -r '.results[] | "\(.tag)\t\(.function)\t\(.insns)"'
+
+# Only the functions that emit libcalls (soft-float, __divdi3, memcpy…)
+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}'
+```
+
+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 +675,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 +778,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.3.3.dist-info/RECORD

@@ -0,0 +1,6 @@
+asmdiff.py,sha256=epHsHBHi0ApOcrhbAFG1beAU1dBA5Qo9t7ui1gOfKoM,89342
+asmdiff-0.3.3.dist-info/METADATA,sha256=arU-JzHKkh751x0M9NBp2Sc9RueiD_fGDVA-tDoZ-u4,63100
+asmdiff-0.3.3.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+asmdiff-0.3.3.dist-info/entry_points.txt,sha256=bVeIyjLm3KgWALbgRSeQo16pZ89GXZZ4sFTSWJUMdTI,41
+asmdiff-0.3.3.dist-info/licenses/LICENSE,sha256=Y8JW9wzNeVnfyw62X3qC9cuwZCv_U67rNSF9QUE0HJs,1072
+asmdiff-0.3.3.dist-info/RECORD,,

{asmdiff-0.2.0.dist-info → asmdiff-0.3.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any

asmdiff.py

@@ -13,24 +13,34 @@ Usage:
                              [--pair OLD:NEW]... [--across FUNC]...
                              [--cc 'CC FLAGS']... [--target NAME]...
                              [--config PATH] [--compile-commands [PATH]]
-                             [--flags-like PATH]
-                             [--layout list|side-by-side] [-v]
+                             [--flags-like PATH] [--db-includes]
+                             [--filter REGEX] [--summary-only]
+                             [--collapse] [--span-stats]
+                             [--json] [--layout list|side-by-side] [-v]
                              [-- EXTRA_FLAGS...]
     tools/asmdiff/asmdiff.py FIRMWARE.elf [FUNC...] [--filter REGEX]
-                             [--objdump PATH]
-    tools/asmdiff/asmdiff.py --edit-config | --example-config
+                             [--objdump PATH] [--layout list]
+                             [--summary-only] [--span-stats] [--json]
+    tools/asmdiff/asmdiff.py --edit-config | --example-config | --version
 
 Five modes:
   SOURCE.c FUNC   inspect: print the named function's assembly, no
                   comparison.  One usable compiler prints a listing
                   plus a stats row, exactly two print side by side,
                   more print one block per compiler; --layout forces
-                  list or side-by-side.
+                  list or side-by-side.  --filter REGEX selects
+                  matching functions as full peers of named ones
+                  (compiler-generated clones included; lenient when a
+                  match exists under only part of the matrix), and in
+                  summary mode narrows the table.
   FIRMWARE.elf    ELF input (detected by magic bytes): disassemble a
                   linked binary through the toolchain's objdump and
                   run named and/or --filter REGEX matched functions
                   through the same analyzers - post-LTO/link reality
-                  instead of single-TU codegen.  objdump comes from
+                  instead of single-TU codegen.  Named functions are
+                  listed in full; --filter matches are summarized
+                  only, unless -l list asks for their listings too.
+                  objdump comes from
                   --objdump PATH or the first gcc in the matrix
                   (trailing gcc swapped for objdump); Xtensa
                   -mlongcalls call sequences are resolved to their
@@ -44,6 +54,14 @@ Five modes:
   (neither)       whole-file summary: per-function counts plus a file
                   total, for one file or side by side for two.
 
+Four flags shape the output: --summary-only prints only the stats
+tables, --collapse elides identical runs in side-by-side listings
+keeping context around each difference, --span-stats follows each
+stats table with a per-loop-span instruction mix (load/store/mul/
+branch/other counts; branch includes calls), and --json replaces the
+tables with one JSON document of per-function records (implies
+--summary-only) for scripted callers.
+
 Compilers come from --cc strings, from named targets in an asmdiff.toml
 config file (--target NAME), from the config's `default` entry, or —
 failing all of those — plain `gcc -O3` and `clang -O3`.
@@ -62,7 +80,11 @@ the CWD up to the repository root, and its build/ subdirectory; a source
 absent from a database found that way is compiled without borrowed flags
 (with a note) rather than being an error.  --flags-like PATH lets such a
 source borrow the flags recorded for PATH, so a modified copy compares
-against its original under one header environment.
+against its original under one header environment.  --db-includes limits
+any borrow to the header-search paths, re-emitted as -idirafter so they
+cannot shadow the host's own system headers: a host target can then
+compile a cross project's source without inheriting cross-only defines,
+-specs, or a libc-overlay include directory.
 """
 import argparse
 import difflib
@@ -84,6 +106,10 @@ try:
 except ModuleNotFoundError:
     tomllib = None
 
+# Single source of truth for the package version: pyproject.toml reads
+# it from here (hatchling dynamic version).
+__version__ = "0.3.3"
+
 DEFAULT_COMPILERS = ["gcc", "clang"]
 FALLBACK_FLAGS = "-O3"
 CONFIG_NAME = "asmdiff.toml"
@@ -120,6 +146,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
@@ -213,6 +245,13 @@ _CC_DB_EQ_FLAGS = ("-specs", "--specs", "--sysroot")
 _DB_CACHE = {}
 _MISS_NOTED = set()
 _BORROW_NOTED = set()
+# --db-includes: borrow only the header-search paths from the database.
+# A project's -I paths are valid on any target; its -D defines, forced
+# includes, and -specs/--sysroot are tied to the arch the database was
+# built for — this is how a host target compiles a cross project's
+# source without inheriting cross-only flags.
+DB_INCLUDES = False
+_DB_SEARCH_PATH_FLAGS = ("-I", "-iquote", "-isystem", "-idirafter")
 # --flags-like PATH: a source with no database entry borrows the flags
 # recorded for PATH.  This is how a modified copy of a project source gets
 # the same header environment as its original, so an --across between them
@@ -383,6 +422,32 @@ def load_compile_commands(path):
     return data
 
 
+def _borrowed(flags):
+    """Apply --db-includes to one borrowed flag list: keep the
+    header-search pairs (-I/-iquote/-isystem/-idirafter PATH), drop
+    defines, forced includes, and driver-level flags.  Identity when
+    the option is off.
+
+    Kept paths are re-emitted as -idirafter — searched AFTER the
+    compiler's own system directories — because a cross project's
+    include set can overlay libc headers (ESP-IDF ships an esp_libc/
+    platform_include whose stdio.h would otherwise shadow the host's);
+    project-only headers still resolve, the host's libc wins.
+    """
+    if not DB_INCLUDES:
+        return flags
+    kept, i = [], 0
+    while i < len(flags):
+        f = flags[i]
+        if f in _CC_DB_PATH_FLAGS:              # split "-I path" pair
+            if f in _DB_SEARCH_PATH_FLAGS:
+                kept += ["-idirafter", flags[i + 1]]
+            i += 2
+        else:                                   # -DFOO / -specs=... token
+            i += 1
+    return kept
+
+
 def compile_commands_flags(db_path, source, missing_ok=False):
     """Header/define flags for ``source`` taken from a compile_commands.json.
 
@@ -401,7 +466,7 @@ def compile_commands_flags(db_path, source, missing_ok=False):
     want = Path(source).resolve()
     flags, name_seen = _lookup_entry(entries, want)
     if flags is not None:
-        return flags
+        return _borrowed(flags)
     if FLAGS_LIKE:
         like = Path(FLAGS_LIKE).resolve()
         like_flags, _ = _lookup_entry(entries, like)
@@ -413,7 +478,7 @@ def compile_commands_flags(db_path, source, missing_ok=False):
             _BORROW_NOTED.add(key)
             print(f"note: {source} not in {db_path}; borrowing the flags "
                   f"recorded for {FLAGS_LIKE}", file=sys.stderr)
-        return like_flags
+        return _borrowed(like_flags)
     suggest = ("; --flags-like PATH can borrow another entry's flags"
                if name_seen else "")
     if missing_ok:
@@ -685,8 +750,8 @@ def analyze(lines):
 LABEL_REF = re.compile(r"\.L[\w$.]+")
 
 
-def loop_spans(lines):
-    """Return [(label, insns)] spans for cleaned asm lines.
+def loop_span_ranges(lines):
+    """Return [(label, lo, hi)] line-index ranges for loop spans.
 
     A span is the run of instructions from a local label to the last
     instruction that references it from below — a backward branch, which
@@ -694,9 +759,7 @@ def loop_spans(lines):
     Xtensa zero-overhead loops (loop/loopnez/loopgt) reference their END
     label instead; there the span is the instructions the loop encloses.
     Spans are reported in order of appearance, one per label; nested
-    labels yield nested spans.  The count states how many instructions
-    lie in the span — nothing about trip count or hotness, which the
-    reader must judge from the source.
+    labels yield nested spans.
     """
     label_at = {ln[:-1]: i for i, ln in enumerate(lines)
                 if ln.endswith(":")}
@@ -719,13 +782,129 @@ def loop_spans(lines):
                 lo = min(lo, spans[ref][0])
                 hi = max(hi, spans[ref][1])
             spans[ref] = (lo, hi)
+    return [(ref, lo, hi) for ref, (lo, hi)
+            in sorted(spans.items(), key=lambda kv: kv[1])]
+
+
+def loop_spans(lines):
+    """Return [(label, insns)] spans for cleaned asm lines.
+
+    The count states how many instructions lie in the span — nothing
+    about trip count or hotness, which the reader must judge from the
+    source.
+    """
     result = []
-    for ref, (lo, hi) in sorted(spans.items(), key=lambda kv: kv[1]):
+    for ref, lo, hi in loop_span_ranges(lines):
         insns = sum(1 for ln in lines[lo:hi + 1] if not ln.endswith(":"))
         result.append((ref, insns))
     return result
 
 
+# --span-stats buckets, by mnemonic table.  Covers the targets the tool
+# routinely meets: Xtensa, RISC-V, and ARM by exact (or dot-stripped)
+# mnemonic; x86 AT&T by the memory-operand heuristic in classify_insn,
+# since there loads and stores are mostly spellings of mov.
+_LOAD_MNEMONICS = frozenset("""
+    l8ui l16ui l16si l32i l32i.n l32r l32e l32ai lsi lsiu lsx lsxu
+    lb lbu lh lhu lw lwu ld flw fld c.lw c.lwsp c.ld c.ldsp c.flw c.fld
+    ldr ldrb ldrh ldrsb ldrsh ldrd ldm ldmia vldr vldm
+    pop popl popq
+""".split())
+_STORE_MNEMONICS = frozenset("""
+    s8i s16i s32i s32i.n s32e s32ri s32c1i ssi ssiu ssx ssxu
+    sb sh sw sd fsw fsd c.sw c.swsp c.sd c.sdsp c.fsw c.fsd
+    str strb strh strd stm stmia vstr vstm
+    push pushl pushq
+""".split())
+# Any multiply, including multiply-accumulate and FP forms (mull,
+# mulsh, mula.dd.*, fmadd.s, vmla.f32, imull, mulss, ...).
+_MUL_PREFIXES = ("mul", "imul", "fmul", "fmadd", "fmsub", "fnmadd",
+                 "fnmsub", "madd", "msub", "mla", "mls", "smul", "umul",
+                 "smla", "umla", "vmul", "vmla", "vmls", "vfma", "vfms")
+_BRANCH_MNEMONICS = frozenset("""
+    beq bne blt bge bltu bgeu beqz bnez beqi bnei blti bgei bltui bgeui
+    bbci bbsi bbc bbs bany bnone ball bnall bt bf
+    blez bgez bltz bgtz bgt ble bgtu bleu
+    b bl bx blx cbz cbnz bcs bcc bmi bpl bvs bvc bhi bls bal
+    jr jal jalr ret retw tail
+    c.j c.jr c.jal c.jalr c.beqz c.bnez
+""".split())
+
+
+def classify_insn(line):
+    """Bucket one cleaned instruction: load/store/mul/branch/other.
+
+    Branch means any control transfer, calls included (a span's
+    outbound calls are already itemised in the calls column).  For
+    mnemonics no table knows, an AT&T-style memory operand decides
+    load (source side) vs store (destination, the last operand);
+    lea and alignment nops are excluded from that heuristic first.
+    """
+    parts = line.split(None, 1)
+    mnem = parts[0].lower()
+    rest = parts[1] if len(parts) > 1 else ""
+    base = mnem.split(".", 1)[0]
+    if mnem in _LOAD_MNEMONICS or base in _LOAD_MNEMONICS:
+        return "load"
+    if mnem in _STORE_MNEMONICS or base in _STORE_MNEMONICS:
+        return "store"
+    if base.startswith(_MUL_PREFIXES):
+        return "mul"
+    if mnem in _BRANCH_MNEMONICS or base in _BRANCH_MNEMONICS:
+        return "branch"
+    if base.startswith(("j", "call", "loop")):
+        return "branch"
+    if base.startswith(("lea", "nop")):
+        return "other"
+    if "(" in rest:
+        depth, cut = 0, -1
+        for i, ch in enumerate(rest):
+            if ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth -= 1
+            elif ch == "," and depth == 0:
+                cut = i
+        return "store" if "(" in rest[cut + 1:] else "load"
+    return "other"
+
+
+_MIX_KEYS = ("load", "store", "mul", "branch", "other")
+
+
+def span_mix(lines):
+    """[{label, insns, load, store, mul, branch, other}] per loop span
+    of one function — the data behind --span-stats, table and JSON."""
+    result = []
+    for label, lo, hi in loop_span_ranges(lines):
+        body = [ln for ln in lines[lo:hi + 1] if not ln.endswith(":")]
+        counts = dict.fromkeys(_MIX_KEYS, 0)
+        for ln in body:
+            counts[classify_insn(ln)] += 1
+        entry = {"label": label, "insns": len(body)}
+        entry.update(counts)
+        result.append(entry)
+    return result
+
+
+def span_stats_table(fn_names, funcs, max_width=None):
+    """Per-span instruction mix for the named functions.
+
+    One row per loop span: how many of its instructions load, store,
+    multiply, or branch.  This weighs the span the way the doctrine
+    asks — the hand-written awk this replaces kept counting past the
+    loop end into the epilogue.
+    """
+    rows = [("function", "span", "insns") + _MIX_KEYS]
+    for name in fn_names:
+        for mix in span_mix(funcs[name]):
+            rows.append((name, mix["label"], str(mix["insns"]))
+                        + tuple(str(mix[k]) for k in _MIX_KEYS))
+    if len(rows) == 1:
+        return "(no loop spans)"
+    return render_table(rows, max_width)
+
+
 def auto_pairs(names):
     """Pair old_X with new_X for every X present in both."""
     names = list(names)
@@ -941,10 +1120,62 @@ def build_matrix(cc_args, target_args, config, config_path, db_arg=None,
 
 # --verbose: print full compiler command lines and untrimmed stderr.
 VERBOSE = False
+# --summary-only: print the stats tables and skip every listing.  The
+# tables are the decision input; a listing is pulled on a second run
+# when a delta needs explaining.
+SUMMARY_ONLY = False
+# --span-stats: follow each stats table with the per-loop-span
+# instruction mix (see span_stats_table).
+SPAN_STATS = False
+# --json: collect summary records here instead of printing tables;
+# None means normal table output.  main() dumps the collected list.
+JSON_OUT = None
+
+
+def span_stats_block(fn_names, funcs):
+    """Print the per-span mix table after a stats table when
+    --span-stats is on; a silent no-op otherwise."""
+    if SPAN_STATS and JSON_OUT is None:
+        print()
+        print(span_stats_table(fn_names, funcs, table_width()))
+
+
+def json_record(name, lines, cc=None, tag=None, role=None):
+    """One --json result: a summary-table row as data.  cc is the
+    resolved compiler command, tag the source/side label of a two-file
+    comparison, role baseline/candidate for paired rows; each is
+    omitted where the mode has no such notion."""
+    insns, calls = analyze(lines)
+    rec = {"function": name}
+    if cc is not None:
+        rec["cc"] = str(cc)
+    if tag is not None:
+        rec["tag"] = tag
+    if role is not None:
+        rec["role"] = role
+    rec["insns"] = insns
+    rec["loop_spans"] = [{"label": label, "insns": n}
+                         for label, n in loop_spans(lines)]
+    rec["calls"] = calls
+    if SPAN_STATS:
+        rec["span_stats"] = span_mix(lines)
+    return rec
 # Without --verbose, a failed compile shows this many stderr lines — enough
 # for the include chain plus the first error, which is the actionable part.
 MAX_STDERR_LINES = 20
 
+# Compilers skipped because their binary was missing, in matrix order.
+# The final no-usable-compiler error repeats them (via _skipped_suffix)
+# so the fix is visible in the error itself, not only in an earlier
+# stderr warning that may have scrolled away.
+_SKIPPED_CCS = []
+
+
+def _skipped_suffix():
+    """" (cc: not found on PATH; ...)" naming every skipped compiler,
+    empty when nothing was skipped."""
+    return f" ({'; '.join(_SKIPPED_CCS)})" if _SKIPPED_CCS else ""
+
 
 def _compile_failure(cmd, stderr):
     """Exit for a failed compile.
@@ -989,6 +1220,9 @@ def compile_to_asm(cc_cmd, extra_flags, harness, out_dir):
     if shutil.which(argv[0]) is None:
         print(f"warning: {argv[0]} not found on PATH, skipping",
               file=sys.stderr)
+        miss = f"{argv[0]}: not found on PATH"
+        if miss not in _SKIPPED_CCS:
+            _SKIPPED_CCS.append(miss)
         return None
     db = getattr(cc_cmd, "compile_commands", None)
     db_flags = (compile_commands_flags(
@@ -1039,14 +1273,53 @@ def mangled_pair_hint(names):
     return any(MANGLED_PAIR.match(n) for n in names)
 
 
-def side_by_side(left, right, ltitle, rtitle, width=44):
-    """Two-column view of a pair's asm lines."""
+# --collapse keeps this many line pairs of context around each
+# differing pair; longer identical runs are elided with a count.
+COLLAPSE_CONTEXT = 3
+# --collapse: elide identical runs in side-by-side listings.
+COLLAPSE = False
+
+
+def side_by_side(left, right, ltitle, rtitle, width=44, collapse=False):
+    """Two-column view of a pair's asm lines.
+
+    With collapse, runs of identical line pairs shrink to the
+    COLLAPSE_CONTEXT pairs around each difference plus an elision
+    marker — two ~500-insn functions differing by a handful of
+    instructions render as a few hunks instead of ~1000 lines.  The
+    sides are aligned first (difflib), not paired by position: an
+    inserted instruction gets a gap opposite it instead of desyncing
+    every following pair.
+    """
     rows = [f"{ltitle:<{width}} | {rtitle}",
             f"{'-' * width}-+-{'-' * width}"]
-    for l, r in zip_longest(left, right, fillvalue=""):
+    if collapse:
+        pairs = []
+        matcher = difflib.SequenceMatcher(a=left, b=right, autojunk=False)
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+            pairs += zip_longest(left[i1:i2], right[j1:j2], fillvalue="")
+        keep = [False] * len(pairs)
+        for i, (l, r) in enumerate(pairs):
+            if l != r:
+                for j in range(max(0, i - COLLAPSE_CONTEXT),
+                               min(len(pairs), i + COLLAPSE_CONTEXT + 1)):
+                    keep[j] = True
+    else:
+        pairs = list(zip_longest(left, right, fillvalue=""))
+        keep = [True] * len(pairs)
+    elided = 0
+    for (l, r), kept in zip(pairs, keep):
+        if not kept:
+            elided += 1
+            continue
+        if elided:
+            rows.append(f"    ... {elided} identical lines ...")
+            elided = 0
         l = l.expandtabs(8)[:width]
         r = r.expandtabs(8)[:width]
         rows.append(f"{l:<{width}} | {r}")
+    if elided:
+        rows.append(f"    ... {elided} identical lines ...")
     return "\n".join(rows)
 
 
@@ -1187,7 +1460,8 @@ def file_tags(a, b):
     return str(a), str(b)
 
 
-def report_across(fn_names, left_funcs, right_funcs, left_tag, right_tag):
+def report_across(fn_names, left_funcs, right_funcs, left_tag, right_tag,
+                  ccs=(None, None)):
     """Side-by-side + summary for the same functions from two compilations."""
     missing = sorted({f for f in fn_names
                       if f not in left_funcs or f not in right_funcs})
@@ -1195,15 +1469,25 @@ def report_across(fn_names, left_funcs, right_funcs, left_tag, right_tag):
         sys.exit("error: function(s) not in asm: " + ", ".join(missing)
                  + f"; {left_tag} has: " + (", ".join(left_funcs) or "none")
                  + f"; {right_tag} has: " + (", ".join(right_funcs) or "none"))
+    if JSON_OUT is not None:
+        for f in fn_names:
+            JSON_OUT.append(json_record(f, left_funcs[f], cc=ccs[0],
+                                        tag=left_tag, role="baseline"))
+            JSON_OUT.append(json_record(f, right_funcs[f], cc=ccs[1],
+                                        tag=right_tag, role="candidate"))
+        return
     decorated, pairs = {}, []
     for f in fn_names:
         lt, rt = f"{f} [{left_tag}]", f"{f} [{right_tag}]"
         decorated[lt], decorated[rt] = left_funcs[f], right_funcs[f]
         pairs.append((lt, rt))
-    for lt, rt in pairs:
-        print(side_by_side(decorated[lt], decorated[rt], lt, rt))
-        print()
+    if not SUMMARY_ONLY:
+        for lt, rt in pairs:
+            print(side_by_side(decorated[lt], decorated[rt], lt, rt,
+                               collapse=COLLAPSE))
+            print()
     print(summary_table(pairs, decorated, table_width()))
+    span_stats_block([n for p in pairs for n in p], decorated)
 
 
 def run_across(sources, matrix, fn_names, extra_flags, tmp):
@@ -1227,10 +1511,13 @@ def run_across(sources, matrix, fn_names, extra_flags, tmp):
             ran_any = True
             tags = mark_db_misses(cc_cmd, sources,
                                   file_tags(sources[0], sources[1]))
-            print(f"\n== {cc_cmd} ==\n")
-            report_across(fn_names, sides[0], sides[1], *tags)
+            if JSON_OUT is None:
+                print(f"\n== {cc_cmd} ==\n")
+            report_across(fn_names, sides[0], sides[1], *tags,
+                          ccs=(cc_cmd, cc_cmd))
         if not ran_any:
-            sys.exit("error: no usable compiler in the matrix")
+            sys.exit("error: no usable compiler in the matrix"
+                     + _skipped_suffix())
         return 0
 
     usable = []
@@ -1240,43 +1527,78 @@ def run_across(sources, matrix, fn_names, extra_flags, tmp):
             usable.append((f"cc#{idx}", cc_cmd, extract_functions(asm)))
     if len(usable) < 2:
         sys.exit("error: --across needs at least two usable compilers "
-                 "in the matrix")
-    print()
-    for tag, cc_cmd, _ in usable:
-        print(f"{tag}: {cc_cmd}")
-    base_tag, _, base_funcs = usable[0]
-    for tag, _, funcs in usable[1:]:
-        print(f"\n== {base_tag} vs {tag} ==\n")
-        report_across(fn_names, base_funcs, funcs, base_tag, tag)
+                 "in the matrix" + _skipped_suffix())
+    if JSON_OUT is None:
+        print()
+        for tag, cc_cmd, _ in usable:
+            print(f"{tag}: {cc_cmd}")
+    base_tag, base_cc, base_funcs = usable[0]
+    for tag, cc_cmd, funcs in usable[1:]:
+        if JSON_OUT is None:
+            print(f"\n== {base_tag} vs {tag} ==\n")
+        report_across(fn_names, base_funcs, funcs, base_tag, tag,
+                      ccs=(base_cc, cc_cmd))
     return 0
 
 
-def run_summary(sources, matrix, extra_flags, tmp):
-    """No pairs to compare: whole-file summary, one block per file."""
+def _compile_filter(filter_regex):
+    """Compile a --filter regex, exiting with a clean error on a bad one."""
+    try:
+        return re.compile(filter_regex)
+    except re.error as exc:
+        sys.exit(f"error: bad --filter regex: {exc}")
+
+
+def run_summary(sources, matrix, extra_flags, tmp, filter_regex=None):
+    """No pairs to compare: whole-file summary, one block per file.
+
+    --filter narrows each file's table to matching functions - the
+    subsystem view of a big TU, same selection idea as ELF mode.
+    """
+    pattern = _compile_filter(filter_regex) if filter_regex else None
     tags = (file_tags(*sources) if len(sources) == 2
             else [Path(sources[0]).name])
     ran_any = False
+    matched_any = False
     for cc_cmd in matrix:
         sections = []
         for src in sources:
             asm = compile_to_asm(cc_cmd, extra_flags, src, tmp)
             if asm is None:
                 break
-            sections.append(extract_functions(asm))
+            funcs = extract_functions(asm)
+            if pattern is not None:
+                funcs = {n: v for n, v in funcs.items() if pattern.search(n)}
+            sections.append(funcs)
         if len(sections) < len(sources):
             continue
         ran_any = True
+        matched_any = matched_any or any(sections)
         shown = (mark_db_misses(cc_cmd, sources, tags)
                  if len(sources) == 2 else tags)
-        print(f"\n== {cc_cmd} ==")
+        if JSON_OUT is None:
+            print(f"\n== {cc_cmd} ==")
         for tag, funcs in zip(shown, sections):
+            if JSON_OUT is not None:
+                JSON_OUT.extend(
+                    json_record(name, lines, cc=cc_cmd,
+                                tag=tag if len(sections) > 1 else None)
+                    for name, lines in funcs.items())
+                continue
             if len(sections) > 1:
                 print(f"\n-- {tag} --")
             print()
             print(file_summary_table(funcs, table_width()) if funcs
-                  else "(no functions found)")
+                  else ("(no functions match --filter)" if pattern is not None
+                        else "(no functions found)"))
+            if funcs:
+                span_stats_block(list(funcs), funcs)
     if not ran_any:
-        sys.exit("error: no usable compiler in the matrix")
+        sys.exit("error: no usable compiler in the matrix"
+                 + _skipped_suffix())
+    if pattern is not None and not matched_any:
+        sys.exit(f"error: --filter {filter_regex!r} matched no function "
+                 "in any compilation")
     return 0
 
 
@@ -1300,46 +1622,93 @@ def run_pairs(source, matrix, pair_specs, extra_flags, tmp):
                 print('note: C++ mangling defeats old_*/new_* auto-pairing; '
                       'declare the pairs extern "C" or use --pair with the '
                       'mangled names', file=sys.stderr)
+            if JSON_OUT is not None:
+                JSON_OUT.extend(json_record(name, lines, cc=cc_cmd)
+                                for name, lines in funcs.items())
+                continue
             print(f"\n== {cc_cmd} ==\n")
             print(file_summary_table(funcs, table_width()) if funcs
                   else "(no functions found)")
+            if funcs:
+                span_stats_block(list(funcs), funcs)
             continue
         missing = sorted({n for p in pairs for n in p if n not in funcs})
         if missing:
             sys.exit("error: function(s) not in asm: "
                      + ", ".join(missing)
                      + "; functions seen: " + ", ".join(funcs))
+        if JSON_OUT is not None:
+            for old, new in pairs:
+                JSON_OUT.append(json_record(old, funcs[old], cc=cc_cmd,
+                                            role="baseline"))
+                JSON_OUT.append(json_record(new, funcs[new], cc=cc_cmd,
+                                            role="candidate"))
+            continue
         print(f"\n== {cc_cmd} ==\n")
-        for old, new in pairs:
-            print(side_by_side(funcs[old], funcs[new], old, new))
-            print()
+        if not SUMMARY_ONLY:
+            for old, new in pairs:
+                print(side_by_side(funcs[old], funcs[new], old, new,
+                                   collapse=COLLAPSE))
+                print()
         print(summary_table(pairs, funcs, table_width()))
+        span_stats_block([n for p in pairs for n in p], funcs)
     if not ran_any:
-        sys.exit("error: no usable compiler in the matrix")
+        sys.exit("error: no usable compiler in the matrix"
+                 + _skipped_suffix())
     return 0
 
 
-def run_inspect(source, matrix, fn_names, layout, extra_flags, tmp):
+def run_inspect(source, matrix, fn_names, layout, extra_flags, tmp,
+                filter_regex=None):
     """Inspect mode: print named functions' assembly, no comparison.
 
     The presentation adapts to how many matrix entries compiled: one
     gives a plain listing with a stats table, exactly two give the
     --across side-by-side, more give one block per compiler.  --layout
     forces list or side-by-side instead.
+
+    --filter adds every matching function as a full peer of the named
+    ones - the way to reach compiler-generated clones ($constprop$0,
+    .isra.0) whose exact names only the -S output knows.  Named
+    functions must exist under every compiler; filter matches are
+    lenient and appear only where that compiler emitted them, since a
+    clone existing under one compiler but not another is a finding,
+    not an error.
     """
+    pattern = _compile_filter(filter_regex) if filter_regex else None
     usable = []
     for idx, cc_cmd in enumerate(matrix, start=1):
         asm = compile_to_asm(cc_cmd, extra_flags, source, tmp)
         if asm is not None:
             usable.append((f"cc#{idx}", cc_cmd, extract_functions(asm)))
     if not usable:
-        sys.exit("error: no usable compiler in the matrix")
+        sys.exit("error: no usable compiler in the matrix"
+                 + _skipped_suffix())
     for _, cc_cmd, funcs in usable:
         missing = sorted({f for f in fn_names if f not in funcs})
         if missing:
             sys.exit("error: function(s) not in asm: " + ", ".join(missing)
                      + f" under {cc_cmd}; functions seen: "
                      + ", ".join(funcs))
+    matched = []
+    if pattern is not None:
+        union = {}
+        for _, _, funcs in usable:
+            union.update(dict.fromkeys(funcs))
+        matched = [n for n in union
+                   if pattern.search(n) and n not in fn_names]
+        if not matched and not fn_names:
+            sys.exit(f"error: --filter {filter_regex!r} matched no function "
+                     f"in {source}")
+
+    def selected(funcs):
+        return list(fn_names) + [m for m in matched if m in funcs]
+
+    if JSON_OUT is not None:
+        for _, cc_cmd, funcs in usable:
+            JSON_OUT.extend(json_record(name, funcs[name], cc=cc_cmd)
+                            for name in selected(funcs))
+        return 0
     if layout == "side-by-side" and len(usable) < 2:
         sys.exit("error: --layout side-by-side needs at least two usable "
                  "compilers in the matrix")
@@ -1352,16 +1721,27 @@ def run_inspect(source, matrix, fn_names, layout, extra_flags, tmp):
         base_tag, _, base_funcs = usable[0]
         for tag, _, funcs in usable[1:]:
             print(f"\n== {base_tag} vs {tag} ==\n")
-            report_across(fn_names, base_funcs, funcs, base_tag, tag)
+            both = list(fn_names) + [m for m in matched
+                                     if m in base_funcs and m in funcs]
+            report_across(both, base_funcs, funcs, base_tag, tag)
+            one_sided = [m for m in matched
+                         if (m in base_funcs) != (m in funcs)]
+            if one_sided:
+                print("\nnote: --filter match(es) present under only one "
+                      "compiler, not compared: " + ", ".join(one_sided)
+                      + " - inspect with -l list")
         return 0
     for _, cc_cmd, funcs in usable:
+        sel = selected(funcs)
         if len(usable) > 1:
             print(f"\n== {cc_cmd} ==")
-        for name in fn_names:
-            print()
-            print(listing(name, funcs[name]))
+        if not SUMMARY_ONLY:
+            for name in sel:
+                print()
+                print(listing(name, funcs[name]))
         print()
-        print(inspect_table(fn_names, funcs, table_width()))
+        print(inspect_table(sel, funcs, table_width()))
+        span_stats_block(sel, funcs)
     return 0
 
 
@@ -1392,7 +1772,7 @@ def run_objdump(objdump, elf):
     return proc.stdout
 
 
-def run_elf(elf, fn_names, filter_regex, objdump):
+def run_elf(elf, fn_names, filter_regex, objdump, list_matches=False):
     """ELF mode: disassemble one linked binary and run the selected
     functions through the same analyzers as -S output.
 
@@ -1400,7 +1780,12 @@ def run_elf(elf, fn_names, filter_regex, objdump):
     of existence, and only the linked ELF shows whether its loops
     survived as zero-overhead loops inside the caller.  Named functions
     are listed in full; --filter matches are summarized in the stats
-    table only, since a match can cover hundreds of functions.
+    table only, since a match can cover hundreds of functions - unless
+    list_matches (-l list) asks for their listings too, the way to see
+    the assembly when only the filter's spelling of a mangled name is
+    known.  When filter matches go unlisted, a trailing note says so:
+    a summary that looks complete but silently withholds the listings
+    costs the caller a detour through raw objdump.
     """
     funcs = extract_functions_objdump(run_objdump(objdump, elf))
     missing = [f for f in fn_names if f not in funcs]
@@ -1411,20 +1796,28 @@ def run_elf(elf, fn_names, filter_regex, objdump):
                  + ("; close matches: " + ", ".join(hints) if hints else ""))
     selected = list(fn_names)
     if filter_regex:
-        try:
-            pattern = re.compile(filter_regex)
-        except re.error as exc:
-            sys.exit(f"error: bad --filter regex: {exc}")
+        pattern = _compile_filter(filter_regex)
         selected += [n for n in funcs
                      if pattern.search(n) and n not in fn_names]
         if not selected:
             sys.exit(f"error: --filter {filter_regex!r} matched no function "
                      f"among the {len(funcs)} in {elf}")
-    for name in fn_names:
-        print()
-        print(listing(name, funcs[name]))
+    if JSON_OUT is not None:
+        JSON_OUT.extend(json_record(name, funcs[name]) for name in selected)
+        return 0
+    listed = selected if list_matches else fn_names
+    if not SUMMARY_ONLY:
+        for name in listed:
+            print()
+            print(listing(name, funcs[name]))
     print()
     print(inspect_table(selected, funcs, table_width()))
+    span_stats_block(selected, funcs)
+    unlisted = len(selected) - len(listed)
+    if unlisted and not SUMMARY_ONLY:
+        print(f"\nnote: {unlisted} --filter match(es) summarized without "
+              "listings; add -l list for their assembly, or name a "
+              "function after the ELF")
     return 0
 
 
@@ -1456,12 +1849,18 @@ def main(argv=None):
     parser.add_argument("-l", "--layout", choices=["list", "side-by-side"],
                         help="force the inspect presentation instead of "
                              "adapting to the matrix (1 usable compiler "
-                             "lists, 2 go side by side, more list)")
+                             "lists, 2 go side by side, more list); with "
+                             "ELF input, 'list' also prints --filter "
+                             "matches' listings")
     parser.add_argument("--filter", metavar="REGEX",
-                        help="ELF input only: also analyze every function "
-                             "whose name matches REGEX (re.search) - the "
-                             "way to sweep a whole subsystem without "
-                             "naming each function")
+                        help="also analyze every function whose name "
+                             "matches REGEX (re.search) - sweep a "
+                             "subsystem, or reach compiler-generated "
+                             "clones, without naming each function. In "
+                             "ELF input matches are summarized only (see "
+                             "-l list); in compile modes they are full "
+                             "peers of named functions. Not with "
+                             "--pair/--across")
     parser.add_argument("--objdump", metavar="PATH",
                         help="disassembler for ELF input; default: derived "
                              "from the first gcc in the matrix by swapping "
@@ -1487,6 +1886,14 @@ def main(argv=None):
                         help=f"config file; default search: {CONFIG_NAME} "
                              "next to SOURCE.c, in the current directory, "
                              "then in ~/.config/")
+    parser.add_argument("--db-includes", action="store_true",
+                        help="borrow only the header-search paths from the "
+                             "database (re-emitted as -idirafter, so they "
+                             "never shadow the host's system headers), "
+                             "dropping its defines, forced includes, and "
+                             "-specs/--sysroot - lets a host/foreign-arch "
+                             "target resolve a cross project's headers "
+                             "without inheriting cross-only flags")
     parser.add_argument("--flags-like", metavar="PATH",
                         help="when a source has no compile_commands entry, "
                              "borrow the include/define flags recorded for "
@@ -1502,14 +1909,45 @@ def main(argv=None):
                         help="print the built-in example config (the "
                              "repository's asmdiff.example.toml) to stdout, "
                              "ready to redirect into a config file")
+    parser.add_argument("--span-stats", action="store_true",
+                        help="follow each stats table with a per-loop-span "
+                             "instruction mix (load/store/mul/branch/other "
+                             "counts) - weighs the span instead of the "
+                             "whole function")
+    parser.add_argument("--collapse", action="store_true",
+                        help="in side-by-side listings, elide runs of "
+                             "identical line pairs, keeping "
+                             f"{COLLAPSE_CONTEXT} lines of context around "
+                             "each difference - near-identical functions "
+                             "render as a few hunks")
+    parser.add_argument("--json", action="store_true",
+                        help="emit the summary as JSON on stdout instead "
+                             "of tables: one record per function per "
+                             "compiler (insns, loop spans, calls; span "
+                             "mix with --span-stats).  Implies "
+                             "--summary-only; errors stay plain text on "
+                             "stderr")
+    parser.add_argument("-s", "--summary-only", action="store_true",
+                        help="print only the summary/stats tables, "
+                             "suppressing every assembly listing - the "
+                             "scripted-caller view (pull a listing with a "
+                             "second run when a delta needs explaining)")
+    parser.add_argument("--version", action="version",
+                        version=f"asmdiff {__version__}")
     parser.add_argument("-v", "--verbose", action="store_true",
                         help="on compile failure, print the full compiler "
                              "command and complete error output instead of "
                              "the first lines")
     args = parser.parse_args(argv)
-    global VERBOSE, FLAGS_LIKE
+    global VERBOSE, FLAGS_LIKE, SUMMARY_ONLY, COLLAPSE, SPAN_STATS
+    global DB_INCLUDES, JSON_OUT
     VERBOSE = args.verbose
     FLAGS_LIKE = args.flags_like
+    SUMMARY_ONLY = args.summary_only or args.json
+    COLLAPSE = args.collapse
+    SPAN_STATS = args.span_stats
+    DB_INCLUDES = args.db_includes
+    JSON_OUT = [] if args.json else None
 
     if args.example_config:
         sys.stdout.write(EXAMPLE_CONFIG)
@@ -1524,9 +1962,13 @@ def main(argv=None):
         if len(sources) > 1:
             parser.error("ELF input analyzes one binary; a second file "
                          "cannot be combined with it")
-        if args.pair or args.across or args.layout:
-            parser.error("--pair/--across/--layout compare compilations; "
+        if args.pair or args.across:
+            parser.error("--pair/--across compare compilations; "
                          "an ELF is disassembled, not compiled")
+        if args.layout == "side-by-side":
+            parser.error("-l side-by-side compares compilations; with ELF "
+                         "input use -l list to also print --filter "
+                         "matches' listings")
         if not fn_names and not args.filter:
             parser.error("a whole ELF has too many functions to table; "
                          "name functions after the file or select them "
@@ -1542,9 +1984,18 @@ def main(argv=None):
                 sys.exit("error: no gcc in the matrix to derive an objdump "
                          "from (" + "; ".join(matrix) + "); pass --objdump "
                          "PATH or a gcc-based --cc/--target")
-        return run_elf(sources[0], fn_names, args.filter, objdump)
-    if args.filter or args.objdump:
-        parser.error("--filter/--objdump apply to ELF input only")
+        status = run_elf(sources[0], fn_names, args.filter, objdump,
+                         list_matches=args.layout == "list")
+        if JSON_OUT is not None:
+            print(json.dumps({"asmdiff": __version__, "mode": "elf",
+                              "elf": sources[0], "results": JSON_OUT},
+                             indent=2))
+        return status
+    if args.objdump:
+        parser.error("--objdump applies to ELF input only")
+    if args.filter and (args.pair or args.across):
+        parser.error("--filter selects functions to inspect or summarize; "
+                     "--pair/--across name their functions explicitly")
     if len(sources) > 2:
         parser.error("at most two source files may be given")
     if fn_names and len(sources) == 2:
@@ -1553,9 +2004,9 @@ def main(argv=None):
     if fn_names and (args.pair or args.across):
         parser.error("bare function names (inspect) cannot be combined "
                      "with --pair or --across")
-    if args.layout and not fn_names:
+    if args.layout and not fn_names and not args.filter:
         parser.error("--layout only applies when inspecting functions "
-                     "(SOURCE.c FUNC ...)")
+                     "(SOURCE.c FUNC ... or --filter REGEX)")
     if args.across and args.pair:
         parser.error("--across and --pair are mutually exclusive")
     if len(sources) == 2 and args.pair:
@@ -1572,16 +2023,27 @@ def main(argv=None):
             parser.error(f"--pair expects OLD:NEW, got {spec!r}")
 
     with tempfile.TemporaryDirectory(prefix="asmdiff") as tmp:
-        if fn_names:
-            return run_inspect(sources[0], matrix, fn_names, args.layout,
+        if fn_names or (args.filter and len(sources) == 1):
+            mode = "inspect"
+            status = run_inspect(sources[0], matrix, fn_names, args.layout,
+                                 extra_flags, tmp,
+                                 filter_regex=args.filter)
+        elif args.across:
+            mode = "across"
+            status = run_across(sources, matrix, args.across,
+                                extra_flags, tmp)
+        elif len(sources) == 2:
+            mode = "summary"
+            status = run_summary(sources, matrix, extra_flags, tmp,
+                                 filter_regex=args.filter)
+        else:
+            mode = "pairs"
+            status = run_pairs(sources[0], matrix, args.pair,
                                extra_flags, tmp)
-        if args.across:
-            return run_across(sources, matrix, args.across,
-                              extra_flags, tmp)
-        if len(sources) == 2:
-            return run_summary(sources, matrix, extra_flags, tmp)
-        return run_pairs(sources[0], matrix, args.pair,
-                         extra_flags, tmp)
+    if JSON_OUT is not None:
+        print(json.dumps({"asmdiff": __version__, "mode": mode,
+                          "results": JSON_OUT}, indent=2))
+    return status
 
 
 if __name__ == "__main__":

asmdiff-0.2.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-asmdiff.py,sha256=cJrdwqqlG4ejalcvBHlSSSCylFRVIAKNYmKsiaCIer4,68504
-asmdiff-0.2.0.dist-info/METADATA,sha256=Gxk-QQA7YDZsmB0WPq2lKHJIg1FxZIuWIkz8TyYotKc,56049
-asmdiff-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-asmdiff-0.2.0.dist-info/entry_points.txt,sha256=bVeIyjLm3KgWALbgRSeQo16pZ89GXZZ4sFTSWJUMdTI,41
-asmdiff-0.2.0.dist-info/licenses/LICENSE,sha256=Y8JW9wzNeVnfyw62X3qC9cuwZCv_U67rNSF9QUE0HJs,1072
-asmdiff-0.2.0.dist-info/RECORD,,