asmdiff 0.1.0__py3-none-any.whl

asmdiff-0.1.0.dist-info/METADATA

@@ -0,0 +1,743 @@
+Metadata-Version: 2.4
+Name: asmdiff
+Version: 0.1.0
+Summary: Compare per-function assembly between paired C implementations
+Project-URL: Homepage, https://github.com/rt-rtos/asmdiff
+Project-URL: Repository, https://github.com/rt-rtos/asmdiff
+Author: Rasmus Tikkanen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: assembly,clang,codegen,compiler,disassembly,gcc
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# asmdiff 
+## per-function assembly comparison for paired C implementations
+
+> asmdiff is a command-line tool for comparing the generated assembly of individual C functions across implementations, compiler flags, compiler versions, and source revisions. It is intended for investigating compiler code generation rather than benchmarking runtime performance.
+
+`asmdiff.py` answers one question fast: **when I rewrite a C construct, what
+does the compiler actually emit - before and after?** It compiles a small
+harness file across a matrix of compilers, extracts each variant function's
+assembly, and prints side-by-side listings plus a summary of instruction
+counts, outbound calls, and loop spans.
+
+Compilers and flags are configured per project through named targets in an
+`asmdiff.toml` file — the tool itself has no project-specific defaults and
+parses any GNU-as ELF assembly.
+  
+Its home use case: checking whether an expression that used to constant-fold
+(e.g. `x * exp2f(5)` → one multiply) turns into a library call (e.g.
+`ldexpf(x, 5)` → `jmp ldexpf@PLT`) after a "cleanup". That distinction is
+invisible in source review and decisive on hot paths.
+
+## Quick start
+
+Write a harness with your two versions as `old_*` / `new_*` function pairs:
+
+```c
+/* myharness.c */
+#include <math.h>
+float old_scale(float x) { return x * exp2f(-5); }
+float new_scale(float x) { return ldexpf(x, -5); }
+```
+
+Run:
+
+```
+$ asmdiff.py myharness.c
+```
+
+Output (gcc section shown, one per compiler):
+
+```
+== gcc -O3 ... ==
+
+old_scale                                    | new_scale
+---------------------------------------------+---------------------------------------------
+endbr64                                      | endbr64
+mulss   .LC0(%rip), %xmm0                    | movl    $-5, %edi
+ret                                          | jmp     ldexpf@PLT
+
+function   role       insns  calls   loop spans
+old_scale  baseline   3      -       -
+new_scale  candidate  3      ldexpf  -
+```
+
+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.
+
+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.
+
+A worked example is included — `asmdiff_example.c` reproduces the
+exp2f/ldexpf analysis for both constant and runtime shift amounts:
+
+```
+$ asmdiff.py asmdiff_example.c
+```
+
+## Command reference
+
+```
+asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
+           [--cc 'CC FLAGS']... [--target NAME]... [--config PATH]
+           [-- EXTRA_FLAGS...]
+```
+
+| Option | Meaning |
+|---|---|
+| `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. |
+| `--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. |
+| `--across FUNC` | Compare the *same* function across two compilations (see below). Repeatable. Mutually exclusive with `--pair`. |
+| `--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. |
+| `-- FLAGS...` | Everything after a bare `--` is appended to *every* compiler invocation. |
+
+With no `--cc` and no `--target`, the config file's top-level
+`default` target(s) are used; without a config file, plain `gcc -O3` and
+`clang -O3`. The tool's own advice applies: compile at the flags your
+project ships with — put them in a target.
+
+Examples:
+
+```bash
+# Explicit pairs, default compilers
+asmdiff.py h.c --pair biquad_v1:biquad_v2 --pair svf_v1:svf_v2
+
+# Cross-compilers: quote command and flags together
+asmdiff.py h.c --cc 'xtensa-esp32s3-elf-gcc -O2 -mlongcalls' \
+               --cc 'riscv32-esp-elf-gcc -O2'
+
+# Try a flag variant across the whole default matrix
+asmdiff.py 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.
+
+## Config file: named targets
+
+Retyping a cross-compiler path and ten flags per run is the enemy of actually
+looking at assembly. A TOML config (stdlib `tomllib`, Python ≥ 3.11) names
+each compiler+flags combination once:
+
+```toml
+# asmdiff.toml — next to your harnesses, in CWD, or in ~/.config/
+default = "s3-amy"          # target(s) used when no --cc/--target is given
+
+[s3-amy]                     # production-like ESP32-S3 codegen
+cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
+flags = [
+  "-O2", "-DAMY_USE_FIXEDPOINT", "-DNDEBUG",
+  "-Wno-strict-aliasing", "-mlongcalls",
+  "-I$HOME/project/components/amy/src",
+]
+
+[host-fixed]                 # same defines on host gcc
+cc = "gcc"
+flags = ["-O2", "-DAMY_USE_FIXEDPOINT", "-I$HOME/amy/src"]
+```
+
+`cc` values expand `~` and `$VARS` and may be glob patterns, so a config
+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
+the exact directory instead when reproducibility matters more than
+convenience. Flags expand `$VARS` only (no globbing).
+
+A target is exactly a saved `--cc` entry — nothing else changes. Useful
+shapes:
+
+```bash
+asmdiff.py h.c                                  # config default target(s)
+asmdiff.py h.c --target s3-amy --target host-fixed   # two-target matrix
+asmdiff.py h.c --across f --target s3-amy --cc 'gcc -O2'  # mix freely
+```
+
+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.
+
+## Whole-file summary
+
+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:
+
+```
+$ asmdiff.py old/delay.c new/delay.c
+
+== xtensa-esp32s3-elf-gcc -O2 ... ==
+
+-- old/delay.c --
+
+function         insns  calls        loop spans
+stereo_reverb    437    -            .L108:327
+...
+TOTAL (13 functions)  956   malloc_caps, free, ...  -
+
+-- new/delay.c --
+...
+TOTAL (13 functions)  1028  malloc_caps, free, ...  -
+```
+
+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
+measurement, and per-function rows are where the real information is.
+
+## Comparing the same function across two builds (`--across`)
+
+`--pair` needs both variants to coexist in one compilation. Real changes
+usually don't look like that: the "old" and "new" versions are the same
+function under different flags, defines, or file revisions. `--across FUNC`
+covers both shapes:
+
+**One file, two (or more) `--cc` entries** — flag/define variants. The first
+entry is the baseline; each later entry is compared against it:
+
+```bash
+# Did dropping fixed-point change the biquad's codegen?
+asmdiff.py src/filters.c --across dsps_biquad_f32_ansi \
+    --cc 'gcc -O3 -DMY_FIXED_CONFIG' --cc 'gcc -O3'
+
+# gcc vs clang on the same function
+asmdiff.py src/filters.c --across dsps_biquad_f32_ansi \
+    --cc 'gcc -O3' --cc 'clang -O3'
+```
+```bash
+# Size vs Performance Optimizations
+asmdiff.py src/filters.c --across dsps_biquad_f32_ansi \
+    --cc 'gcc -Os' --cc 'gcc -O2'
+
+```
+
+```
+cc#1: gcc -Os
+cc#2: gcc -O3
+
+== cc#1 vs cc#2 ==
+
+dsps_biquad_f32_ansi [cc#1]                  | dsps_biquad_f32_ansi [cc#2]
+---------------------------------------------+---------------------------------------------
+endbr64                                      | endbr64
+movl    (%r8), %r11d                         | movdqu  (%r8), %xmm0
+movl    8(%r8), %r10d                        | pushq   %r13
+pushq   %r15                                 | pushq   %r12
+xorl    %r9d, %r9d                           | pshufd  $255, %xmm0, %xmm1
+pushq   %r14                                 | pushq   %rbp
+movl    4(%r8), %r15d                        | movd    %xmm1, %ebp
+pushq   %r13                                 | movdqa  %xmm0, %xmm1
+movl    12(%r8), %r13d                       | pushq   %rbx
+pushq   %r12                                 | punpckhdq       %xmm0, %xmm1
+movl    %edx, %r12d                          | movd    %xmm1, %r10d
+pushq   %rbp                                 | pshufd  $85, %xmm0, %xmm1
+movq    %rsi, %rbp                           | testl   %edx, %edx
+pushq   %rbx                                 | jle     .L24
+movq    %rdi, %rbx                           | movslq  %edx, %rdx
+.L27:                                        | movd    %xmm1, %r12d
+cmpl    %r9d, %r12d                          | movd    %xmm0, %r11d
+jle     .L30                                 | movq    %rsi, %r9
+movl    (%rbx,%r9,4), %r14d                  | leaq    (%rdi,%rdx,4), %rbx
+movl    (%rcx), %edi                         | movq    %rdi, %rsi
+movl    %r14d, %esi                          | jmp     .L25
+call    SMULR6                               | .L26:
+movl    4(%rcx), %edi                        | movl    %eax, %r10d
+movl    %r11d, %esi                          | movl    %edi, %r11d
+movl    %eax, %edx                           | .L25:
+call    SMULR6                               | movl    4(%rcx), %eax
+movl    8(%rcx), %edi                        | movl    (%rsi), %edi
+movl    %r15d, %esi                          | addl    $1024, %r12d
+movl    %r11d, %r15d                         | addl    $1024, %ebp
+addl    %eax, %edx                           | sarl    $11, %r12d
+movl    %r14d, %r11d                         | sarl    $11, %ebp
+call    SMULR6                               | leal    1024(%rax), %edx
+movl    12(%rcx), %edi                       | leal    1024(%r11), %eax
+movl    %r10d, %esi                          | sarl    $11, %eax
+addl    %eax, %edx                           | sarl    $11, %edx
+call    SMULR6                               | leal    1024(%rdi), %r13d
+movl    16(%rcx), %edi                       | imull   %eax, %edx
+movl    %r13d, %esi                          | movl    (%rcx), %eax
+movl    %r10d, %r13d                         | sarl    $11, %r13d
+subl    %eax, %edx                           | addl    $1024, %eax
+call    SMULR6                               | sarl    $11, %eax
+movl    %eax, %esi                           | addl    $1, %edx
+movl    %edx, %eax                           | imull   %r13d, %eax
+subl    %esi, %eax                           | sarl    %edx
+movl    %eax, 0(%rbp,%r9,4)                  | addl    $1, %eax
+movl    %eax, %r10d                          | sarl    %eax
+incq    %r9                                  | addl    %eax, %edx
+jmp     .L27                                 | movl    8(%rcx), %eax
+.L30:                                        | addl    $1024, %eax
+popq    %rbx                                 | sarl    $11, %eax
+movl    %r15d, 4(%r8)                        | imull   %r12d, %eax
+xorl    %eax, %eax                           | leal    1024(%r10), %r12d
+popq    %rbp                                 | sarl    $11, %r12d
+popq    %r12                                 | addl    $1, %eax
+movl    %r13d, 12(%r8)                       | sarl    %eax
+movl    %r11d, (%r8)                         | addl    %edx, %eax
+popq    %r13                                 | movl    12(%rcx), %edx
+movl    %r10d, 8(%r8)                        | addl    $1024, %edx
+popq    %r14                                 | sarl    $11, %edx
+popq    %r15                                 | imull   %r12d, %edx
+ret                                          | movl    %r11d, %r12d
+                                             | addl    $1, %edx
+                                             | sarl    %edx
+                                             | subl    %edx, %eax
+                                             | movl    16(%rcx), %edx
+                                             | addl    $1024, %edx
+                                             | sarl    $11, %edx
+                                             | imull   %ebp, %edx
+                                             | movl    %r10d, %ebp
+                                             | addl    $1, %edx
+                                             | addq    $4, %rsi
+                                             | addq    $4, %r9
+                                             | sarl    %edx
+                                             | subl    %edx, %eax
+                                             | movl    %eax, -4(%r9)
+                                             | cmpq    %rsi, %rbx
+                                             | jne     .L26
+                                             | movd    %eax, %xmm1
+                                             | movd    %r10d, %xmm2
+                                             | movd    %edi, %xmm0
+                                             | movd    %r11d, %xmm3
+                                             | punpckldq       %xmm2, %xmm1
+                                             | punpckldq       %xmm3, %xmm0
+                                             | punpcklqdq      %xmm1, %xmm0
+                                             | .L24:
+                                             | popq    %rbx
+                                             | xorl    %eax, %eax
+                                             | popq    %rbp
+                                             | movups  %xmm0, (%r8)
+                                             | popq    %r12
+                                             | popq    %r13
+                                             | ret
+
+function                     role       insns  calls   loop spans
+dsps_biquad_f32_ansi [cc#1]  baseline   59     SMULR6  .L27:32
+dsps_biquad_f32_ansi [cc#2]  candidate  89     -       .L26:54
+```
+
+(The columns describe, they don't rank: here `-O2` is bigger by every
+count, and only 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:
+
+```
+$ asmdiff.py asmdiff_example.c --across new_rt --cc 'gcc -O0' --cc 'gcc -O3'
+
+cc#1: gcc -O0
+cc#2: gcc -O3
+
+== cc#1 vs cc#2 ==
+
+new_rt [cc#1]                                | new_rt [cc#2]
+---------------------------------------------+---------------------------------------------
+endbr64                                      | endbr64
+pushq   %rbp                                 | jmp     ldexpf@PLT
+movq    %rsp, %rbp                           |
+subq    $16, %rsp                            |
+movss   %xmm0, -4(%rbp)                      |
+movl    %edi, -8(%rbp)                       |
+movl    -8(%rbp), %edx                       |
+movl    -4(%rbp), %eax                       |
+movl    %edx, %edi                           |
+movd    %eax, %xmm0                          |
+call    ldexpf@PLT                           |
+leave                                        |
+ret                                          |
+
+function       role       insns  calls   loop spans
+new_rt [cc#1]  baseline   13     ldexpf  -
+new_rt [cc#2]  candidate  2      ldexpf  -
+```
+
+**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:
+
+```bash
+git worktree add ../baseline main
+asmdiff.py ../baseline/src/filters.c src/filters.c \
+    --across dsps_biquad_f32_ansi
+```
+
+Here the tags in the output are the two file paths (shortened to their
+distinct suffix) instead of `cc#N` — the worked example in the next section
+shows a full result of this shape.
+
+Because C quote-includes (`#include "amy.h"`) resolve relative to the
+including file first, each tree picks up **its own** headers automatically —
+so a change made in a header (a macro, a typedef) is compared by pointing
+`--across` at any `.c` file that uses it, without touching that `.c` file.
+
+## Worked example: exp2f vs ldexpf in shorepine/AMY sources
+
+Suppose the proposal is to change AMY's float-mode shift macros in
+`src/amy_fixedpoint.h` from `(s) * exp2f(b)` to `ldexpf((s), (b))`. No
+harness needed — compare the real functions the macros expand into:
+
+```bash
+# 1. A pristine baseline tree (any ref works)
+git worktree add ../amy-baseline HEAD
+
+# 2. The macros in question only exist in the float build, so enable it in
+#    BOTH trees: comment out `#define AMY_USE_FIXEDPOINT` in src/amy.h
+#    (it is hardcoded there).
+
+# 3. In the working tree only, apply the candidate change in
+#    src/amy_fixedpoint.h:
+#      #define SHIFTR(s, b) ldexpf((s), -(b))
+#      #define SHIFTL(s, b) ldexpf((s), (b))
+
+# 4. Compare real functions containing both kinds of shift site:
+asmdiff.py ../amy-baseline/src/log2_exp2.c src/log2_exp2.c \
+    --across exp2_lut --across log2_lut --cc 'gcc -O3 -Wall'
+
+# 5. Clean up
+git worktree remove ../amy-baseline
+```
+
+`src/log2_exp2.c` is a good probe because it contains both site kinds:
+`exp2_lut` shifts by a **runtime** amount, `log2_lut` by **constants**.
+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
+log2_lut [amy-baseline/log2_exp2.c]   baseline   58     -
+log2_lut [amy/log2_exp2.c]            candidate  64     ldexpf
+```
+
+The runtime site improves (a leaner libcall replaces `exp2f` + multiply),
+but the constant site regresses: baseline `log2_lut` had **no** calls —
+`exp2f(±1)` folds to a multiply — while the candidate now pays a `ldexpf`
+libcall inside its normalisation loop. Any other `.c` file whose hot
+functions use the macros (`filters.c`, `oscillators.c`, `delay.c`) can be
+probed the same way.
+
+## How it works
+
+1. Each compiler runs with `-S` to emit assembly text.
+2. Function bodies are sliced out between the function's label and its
+   `.size` directive (or the next function label). CFI/section/alignment
+   directives, comments, and compiler bracketing labels are stripped;
+   instructions and meaningful local labels (loop targets) are kept.
+3. Instruction counts and outbound calls come from a mnemonic scan covering
+   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.
+4. Loop spans come from label references alone — no mnemonic tables, no
+   control-flow analysis. The next section walks through it.
+
+### How a span is found
+
+The parser sees only the cleaned `-S` text of one function: instructions
+and local labels, as line positions rather than addresses. Two passes:
+
+1. Record the position of every local label line (`.L2:`).
+2. Scan each instruction's operands for label-shaped tokens (`.L…`). A
+   token counts only if that label exists **inside this function body**.
+   That one rule filters out literal-pool references — `mulss .LC0(%rip)`,
+   `l32r a8, .LC44` — because `.LC*` labels are emitted in data sections
+   outside the body and are never in the label map.
+
+An instruction that references a label *above* itself is a backward
+branch, whatever its mnemonic (`jne`, `bne`, `bnez.n`, `jnz` — the tool
+never needs to know). The span runs from the label to the last such
+branch, inclusive:
+
+```
+.L2:                    ─┐
+    addl  $1, %eax       │
+    cmpl  $8, %eax       │  span ".L2:3"
+    jne   .L2           ─┘  backward reference
+    ret                     outside the span
+```
+
+Several back-edges to one label (a `continue` plus the loop bottom) merge
+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.
+
+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:
+
+```
+    loopgt a3, .L5          runs once; not part of the span
+    addi.n a2, a2, 1    ─┐
+    s32i.n a2, a4, 0    ─┘  span ".L5:2"
+.L5:
+    retw.n
+```
+
+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
+states where the compiler laid out a repeatable region — nothing more.
+
+No verdicts are printed. The tool reports facts; whether a libcall on that
+path — or an instruction inside a span rather than outside it — matters is
+your judgment.
+
+## Writing good harnesses
+
+- Give variants **runtime arguments** for anything that is runtime in the
+  real code, and **literals** for anything that is compile-time constant
+  there. The fold-vs-libcall answer depends on exactly this.
+- Keep functions non-`static` so the compiler must emit them standalone.
+- Compile at the **flags your project ships with** — a construct that folds
+  at `-O3 -ffast-math` may not fold at plain `-O3`. Encode them once as a
+  config target and make it the `default`.
+- Beware of over-synthetic harnesses: a function whose whole body is the
+  construct can tail-call (`jmp f`) where real surrounding code would
+  `call f` and continue. Same libcall either way, but instruction counts
+  read differently.
+
+## Porting to another project
+
+The tool is one stdlib-only Python 3 file with no imports outside the
+standard library, and contains no project-specific constants. To port:
+
+1. Copy this directory (or just `asmdiff.py`).
+2. Write an `asmdiff.toml` for the new project's toolchain and flags
+   (start from `asmdiff.example.toml`) and drop it next to your
+   harnesses, in your working directory, or in `~/.config/`.
+3. Run the self-tests: `python3 test_asmdiff.py -v` (no compiler needed).
+
+## Limitations
+
+- Parses **GNU-as ELF** assembly (`gcc`, `clang`, and GNU cross-compilers
+  targeting ELF). macOS Mach-O asm (`_name` labels, no `.size`) is not
+  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.
+- 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.
+- 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
+  name. Unrolled or versioned loops (common at `-O3`) appear as several
+  spans or as one large span; the tool reports what it sees and does not
+  reassemble them into a source-level loop.
+  read the raw `-S` output by hand
+
+  ---
+## pretend FAQ
+### Why not just run objdump by hand?
+
+The two commands above (steps 4–5) replace a manual workflow with real
+friction at every step. Walking through it end to end on a single,
+one-sided example — did `x * exp2f(-5)` fold to a multiply, or did
+`ldexpf(x, n)` become a libcall — shows where the effort goes.
+
+**1. Compile to an object, remembering every project flag by hand.**
+
+```bash
+gcc -O3 -Wall -Wno-strict-aliasing -Wextra -Wno-unused-parameter \
+    -Wpointer-arith -Wno-float-conversion -Wno-missing-declarations \
+    -DAMY_WAVETABLE -Isrc -c src/log2_exp2.c -o /tmp/candidate.o
+```
+
+Drop one flag (say `-Wno-float-conversion`) and nothing errors — the build
+just quietly takes a different codegen path, and the comparison you're
+about to make is invalid without telling you so. Repeat this for the
+baseline tree with its own `-I`, and again for every extra compiler you
+want in the matrix.
+
+**2. Disassemble the function out of the object.**
+
+```bash
+objdump -dr --no-show-raw-insn -M no-aliases /tmp/candidate.o
+```
+
+For a libcall site (`ldexpf(x, n)` with a runtime `n`), the real output is:
+
+```
+0000000000000000 <g>:
+   0:	endbr64
+   4:	jmp    9 <g+0x9>
+			5: R_X86_64_PLT32	ldexpf-0x4
+```
+
+The call target isn't in the instruction — `jmp 9 <g+0x9>` points at an
+unresolved stub inside the same function. The actual symbol, `ldexpf`, only
+shows up in the relocation line underneath, and you have to know to cross-
+reference it by hand. Compare that to `gcc -S`, which prints the symbol
+inline because it hasn't been through a linker/relocation step yet:
+
+```
+g:
+	endbr64
+	jmp	ldexpf@PLT
+```
+
+That's why asmdiff compiles with `-S` instead of going through `objdump` on
+a linked object — the thing you're looking for (is this a libcall, and to
+what) is already text, not a relocation entry you have to decode.
+
+**3. Strip the noise objdump adds that `-S` doesn't.** Every instruction
+line carries a leading address and (unless `--no-show-raw-insn` is passed)
+raw opcode bytes; there's a `file format elf64-x86-64` banner, a
+`Disassembly of section .text:` header, and an address-annotated function
+label instead of a bare one. None of it is informative for a codegen diff,
+all of it has to be deleted by hand before two functions are readable
+side by side — and it has to be deleted from **every** file in the
+comparison, four of them for the two-function/two-tree case above.
+
+**4. Diff the cleaned pair.** `diff -y --width=100 old.txt new.txt` aligns
+by content match, not position — once the two versions diverge even
+slightly it starts pairing unrelated lines, and it has no header row to
+label which side is which. `asmdiff` prints its own aligned columns
+(`side_by_side()`) with the two function names as headers, and never loses
+the pairing because it doesn't try to align by content — it just walks
+both lists in lockstep.
+
+**5. Count instructions and classify calls by hand.** Grep for `call`/`jmp`
+in the cleaned text, then manually exclude the ones that are really local
+branches (`jmp 4011a0 <exp2_lut+0x40>`) rather than calls to another
+symbol — the exact distinction `CALL_RE` in `asmdiff.py` encodes once so
+you don't re-derive it per function. Then hand-build a table from four
+separate counts.
+
+**6. Do all of the above again per compiler.** asmdiff's default matrix is
+gcc *and* clang; by hand that's every step above, twice.
+
+For the full worked example — two functions, two trees, one compiler —
+the manual version is roughly: 2 compiles (with hand-retyped flags) → 4
+`objdump`/relocation-lookup passes → noise-stripped by hand on 4 files →
+2 `diff -y` runs that don't survive drift → manual instruction counts and
+call classification on 4 files → a hand-assembled summary table. The
+`asmdiff.py` version is the one command already shown above. Neither
+workflow can skip understanding *why* the two functions differ — that part
+is still your judgment — but everything upstream of that judgment, where a
+dropped flag or a misread relocation silently invalidates the comparison,
+is what the tool removes.
+
+### Why not just run gcc -S by hand?
+
+`-S` output sidesteps the relocation-decoding problem above — call targets
+are already symbolic text, no PLT stub to resolve. That removes step 2 of
+the objdump workflow. It does not remove the rest.
+
+**1. Compile to text instead of an object** — same flags, same risk of a
+silently dropped one:
+
+```bash
+gcc -O3 -Wall -Wno-strict-aliasing -Wextra -Wno-unused-parameter \
+    -Wpointer-arith -Wno-float-conversion -Wno-missing-declarations \
+    -DAMY_WAVETABLE -Isrc -S src/log2_exp2.c -o /tmp/log2_exp2.s
+```
+
+**2. Find where the function starts and ends in the `.s` file.** The real
+output for `exp2_lut` in this repo (current build, `AMY_USE_FIXEDPOINT`
+on):
+
+```
+exp2_lut:
+.LFB71:
+	.cfi_startproc
+	endbr64
+	movl	%edi, %edx
+	leaq	2+exp2_fxpt_lutable(%rip), %rcx
+	...
+	ret
+	.cfi_endproc
+.LFE71:
+	.size	exp2_lut, .-exp2_lut
+```
+
+There's no `objdump`-style address column to strip, but you still have to
+find the boundary by hand: the function starts at a column-0 label
+(`exp2_lut:`, not `.LFB71:` — that's a bracketing label, not the function),
+and ends at its `.size` directive — which only gcc reliably emits; on a
+compiler that doesn't, you'd fall back to "next function label", which is
+exactly the two-case rule `extract_functions()` implements once instead of
+you re-deriving it per file.
+
+**3. Strip compiler furniture — but not indiscriminately.** `.cfi_*`,
+`.LFB`/`.LFE` bracket labels, and `.p2align` carry no information. A local
+`.L`-numbered label sometimes does, though, and you can't tell which
+without reading the body. `log2_lut` in the same file:
+
+```
+log2_lut:
+.LFB70:
+	.cfi_startproc
+	endbr64
+	xorl	%eax, %eax
+	cmpl	$8388607, %edi
+	jg	.L9
+	.p2align 4,,10
+	.p2align 3
+.L3:
+	addl	%edi, %edi
+	subl	$1, %eax
+	cmpl	$8388607, %edi
+	jle	.L3
+	cmpl	$16777215, %edi
+	jle	.L11
+	.p2align 4,,10
+	.p2align 3
+.L5:
+	sarl	%edi
+	addl	$1, %eax
+.L9:
+	cmpl	$16777215, %edi
+	jg	.L5
+.L11:
+	...
+```
+
+`.L3`, `.L5`, `.L9`, `.L11` are live loop targets — `jg .L9` and `jle .L3`
+jump to them. A quick-and-dirty cleanup pass like `grep -v '^\.'` (strip
+every line starting with a dot) deletes those labels along with the
+`.p2align` noise sitting right next to them, and now the function has
+dangling jumps to labels that no longer exist — silently wrong, not an
+error. The correct rule is "drop this specific set of directives and this
+specific set of *bracketing* labels, keep everything else" — which is a
+narrower, easier-to-get-wrong rule than it looks, and it's what `NOISE`
+and `NOISE_LABEL` encode once in `asmdiff.py` instead of per file.
+
+**4. Everything downstream is unchanged from the objdump case:** pair the
+two cleaned functions up for reading, count instructions, classify
+`call`/`jmp` lines as libcalls vs. local branches, repeat per function,
+per file, per compiler, and assemble a summary table by hand.
+
+So `-S` over `objdump` buys back exactly one step — the call target is
+already a name, not a relocation to look up — and leaves the rest of the
+manual pipeline (locate, strip correctly, pair, count, classify, tally,
+multiplied by every function/tree/compiler in the matrix) in place. That
+remaining pipeline is `extract_functions()`, `analyze()`,
+`side_by_side()`, and `summary_table()` in `asmdiff.py` — written once,
+instead of re-derived by hand every time someone wants to answer "did this
+still fold?"
+

asmdiff-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+asmdiff.py,sha256=iqpMyirSUYH2hWfYZwGnmxlYFTh8lNL-EceTV6S84dY,22885
+asmdiff-0.1.0.dist-info/METADATA,sha256=ovEO3ftLKesG4zJ0xG0S94Krnt4k2O1XzR5Gpr7dVaU,32701
+asmdiff-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+asmdiff-0.1.0.dist-info/entry_points.txt,sha256=bVeIyjLm3KgWALbgRSeQo16pZ89GXZZ4sFTSWJUMdTI,41
+asmdiff-0.1.0.dist-info/licenses/LICENSE,sha256=Y8JW9wzNeVnfyw62X3qC9cuwZCv_U67rNSF9QUE0HJs,1072
+asmdiff-0.1.0.dist-info/RECORD,,

asmdiff-0.1.0.dist-info/WHEEL

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

asmdiff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+asmdiff = asmdiff:main

asmdiff-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rasmus Tikkanen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asmdiff.py

@@ -0,0 +1,575 @@
+#!/usr/bin/env python3
+"""Compare per-function assembly between paired C implementations.
+
+Compiles a harness C file across a matrix of compilers, extracts each
+variant function's assembly from the -S output, and prints side-by-side
+listings plus a summary of instruction counts, outbound calls, and loop
+spans (instructions between a local label and its last backward branch).
+Automates fold-vs-libcall analysis when evaluating micro-optimisations
+(e.g. "does this still compile to one instruction, or is it a libcall?").
+
+Usage:
+    tools/asmdiff/asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]...
+                             [--across FUNC]... [--cc 'CC FLAGS']...
+                             [--target NAME]... [--config PATH]
+                             [-- EXTRA_FLAGS...]
+
+Three modes:
+  --pair OLD:NEW  compares two different functions within one compilation
+                  (with no --pair, old_X/new_X names auto-pair).
+  --across FUNC   compares the SAME function across two compilations:
+                  either one file under two --cc entries (flag/define
+                  variants), or two source files (before/after versions)
+                  under each compiler in the matrix.
+  (neither)       whole-file summary: per-function counts plus a file
+                  total, for one file or side by side for two.
+
+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`.
+Flags after a bare `--` are appended to every compiler invocation.
+"""
+import argparse
+import glob
+import hashlib
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+from itertools import zip_longest
+from pathlib import Path
+
+try:
+    import tomllib  # Python >= 3.11; config files are optional without it
+except ModuleNotFoundError:
+    tomllib = None
+
+DEFAULT_COMPILERS = ["gcc", "clang"]
+FALLBACK_FLAGS = "-O3"
+CONFIG_NAME = "asmdiff.toml"
+
+# A label at column 0 that is not a local (.L*) label starts a function.
+FUNC_LABEL = re.compile(r"^([A-Za-z_][\w$.]*):")
+# Assembler directives that carry no information worth reading.
+NOISE = re.compile(
+    r"^\s*\.(cfi_|p2align|align\b|loc\b|file\b|text\b|globl\b|global\b|"
+    r"type\b|section\b|ident\b|weak\b|hidden\b|addrsig|build_version)"
+)
+# Compiler-generated bracketing labels that add nothing (.LFB0:, .Lfunc_end0:).
+NOISE_LABEL = re.compile(r"^\.(LFB|LFE|Lfunc_begin|Lfunc_end)\d*:")
+
+
+def extract_functions(asm_text):
+    """Map function name -> cleaned asm lines from compiler -S output.
+
+    A function body runs from its column-0 label to the matching .size
+    directive (gcc and clang both emit one on ELF) or the next function
+    label.  Comment lines, CFI/section/alignment directives, and
+    compiler bracketing labels are dropped; instructions and meaningful
+    local labels (loop targets) are kept, whitespace-stripped.
+    """
+    funcs = {}
+    current = None
+    for raw in asm_text.splitlines():
+        m = FUNC_LABEL.match(raw)
+        if m:
+            current = m.group(1)
+            funcs[current] = []
+            continue
+        if current is None:
+            continue
+        if re.match(r"^\s*\.size\b", raw):
+            current = None
+            continue
+        line = raw.strip()
+        if not line or line.startswith(("#", "//")):
+            continue
+        if NOISE.match(line) or NOISE_LABEL.match(line):
+            continue
+        funcs[current].append(line)
+    return funcs
+
+
+# Direct-call / tail-call mnemonics across x86 (call, jmp), ARM (bl, blx),
+# RISC-V (call, tail, jal), and Xtensa (call0/4/8/12, callx*, j).  Longest
+# alternatives first so e.g. "callx8" is not consumed as "call".  The
+# symbol must be the sole/final operand (optionally @PLT-suffixed), so
+# multi-operand forms like "jal ra, exp2f" don't report the register.
+CALL_RE = re.compile(
+    r"^(?:callx\d+|call\d*|callq|jalr|jal|jmp|blx|bl|tail|j)\s+"
+    r"([A-Za-z_][\w$.]*)(?:@[\w.]+)?\s*(?:[#;].*)?$"
+)
+
+
+def analyze(lines):
+    """Return (instruction_count, called_symbols) for cleaned asm lines.
+
+    A call is a call/tail-call mnemonic whose first operand looks like a
+    symbol name — local labels (.L*) and %-registers never match, so
+    branches inside the function are not counted.
+    """
+    insns = 0
+    calls = []
+    for line in lines:
+        if line.endswith(":"):
+            continue
+        insns += 1
+        m = CALL_RE.match(line)
+        if m:
+            sym = m.group(1)
+            if sym not in calls:
+                calls.append(sym)
+    return insns, calls
+
+
+# A local-label operand (branch target, zero-overhead loop end).  Literal
+# pool labels (.LC0) also match, but they are emitted outside function
+# bodies, so they never appear in the label map built from a body.
+LABEL_REF = re.compile(r"\.L[\w$.]+")
+
+
+def loop_spans(lines):
+    """Return [(label, insns)] spans for cleaned asm lines.
+
+    A span is the run of instructions from a local label to the last
+    instruction that references it from below — a backward branch, which
+    is what a compiled loop looks like on every target the tool parses.
+    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.
+    """
+    label_at = {ln[:-1]: i for i, ln in enumerate(lines)
+                if ln.endswith(":")}
+    spans = {}
+    for i, ln in enumerate(lines):
+        if ln.endswith(":"):
+            continue
+        mnem = ln.split(None, 1)[0]
+        for ref in LABEL_REF.findall(ln):
+            if ref not in label_at:
+                continue
+            j = label_at[ref]
+            if j < i:                       # label above: backward branch
+                lo, hi = j, i
+            elif mnem.startswith("loop"):   # Xtensa: end label below
+                lo, hi = i + 1, j - 1
+            else:
+                continue
+            if ref in spans:                # several edges to one label
+                lo = min(lo, spans[ref][0])
+                hi = max(hi, spans[ref][1])
+            spans[ref] = (lo, hi)
+    result = []
+    for ref, (lo, hi) in sorted(spans.items(), key=lambda kv: kv[1]):
+        insns = sum(1 for ln in lines[lo:hi + 1] if not ln.endswith(":"))
+        result.append((ref, insns))
+    return result
+
+
+def auto_pairs(names):
+    """Pair old_X with new_X for every X present in both."""
+    names = list(names)
+    return [(n, "new_" + n[4:]) for n in names
+            if n.startswith("old_") and "new_" + n[4:] in names]
+
+
+def find_config(explicit, sources):
+    """Locate the config file; first hit wins, no merging.
+
+    Order: --config PATH, then asmdiff.toml next to the first source
+    file (a harness directory can carry its own targets), then the
+    current directory, then ~/.config/asmdiff.toml.
+    """
+    if explicit:
+        path = Path(explicit)
+        if not path.is_file():
+            sys.exit(f"error: config file not found: {explicit}")
+        return path
+    for candidate in (Path(sources[0]).resolve().parent / CONFIG_NAME,
+                      Path.cwd() / CONFIG_NAME,
+                      Path.home() / ".config" / CONFIG_NAME):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_config(path):
+    """Parse a TOML config: one [table] per target, optional top-level
+    `default` naming the target(s) to run when no --cc/--target is given."""
+    if tomllib is None:
+        sys.exit(f"error: {path} exists but this Python has no tomllib "
+                 "(config files need Python >= 3.11)")
+    try:
+        with open(path, "rb") as fh:
+            return tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        sys.exit(f"error: {path}: {exc}")
+
+
+def _version_key(path):
+    """Sort key that orders embedded numbers numerically, so
+    esp-15.2.0 ranks above esp-9.1.0 (lexical order would not)."""
+    return [(0, int(tok)) if tok.isdigit() else (1, tok)
+            for tok in re.split(r"(\d+)", path)]
+
+
+def resolve_cc(cc, name):
+    """Expand ~, $VARS, and glob patterns in a target's cc value.
+
+    A pattern like .../xtensa-esp-elf/esp-*/bin/...-gcc keeps the config
+    toolchain-version agnostic.  If it matches several installed
+    toolchains the highest version-sorted one is used, and the choice is
+    printed so it is never silent; no match is an error.
+    """
+    expanded = os.path.expandvars(os.path.expanduser(cc))
+    if not any(ch in expanded for ch in "*?["):
+        return expanded
+    matches = sorted(glob.glob(expanded), key=_version_key)
+    if not matches:
+        sys.exit(f"error: target [{name}]: cc pattern matched nothing: "
+                 + expanded)
+    if len(matches) > 1:
+        print(f"target [{name}]: cc pattern matched {len(matches)} "
+              f"toolchains, using {matches[-1]}", file=sys.stderr)
+    return matches[-1]
+
+
+def target_command(config, name, config_path):
+    """Resolve a named [target] table to one 'CC FLAGS' matrix entry."""
+    entry = (config or {}).get(name)
+    if not isinstance(entry, dict):
+        known = sorted(k for k, v in (config or {}).items()
+                       if isinstance(v, dict))
+        sys.exit(f"error: no [{name}] target in "
+                 f"{config_path or 'any config file'}"
+                 + ("; targets: " + ", ".join(known) if known
+                    else "; no targets defined"))
+    cc = entry.get("cc")
+    if not isinstance(cc, str):
+        sys.exit(f'error: target [{name}] needs cc = "compiler"')
+    flags = entry.get("flags", [])
+    if isinstance(flags, str) or not all(isinstance(f, str) for f in flags):
+        sys.exit(f"error: target [{name}]: flags must be an array of strings")
+    flags = [os.path.expandvars(f) for f in flags]
+    return shlex.join([resolve_cc(cc, name), *flags])
+
+
+def build_matrix(cc_args, target_args, config, config_path):
+    """Resolve the compiler matrix.
+
+    --cc strings verbatim, then --target entries, in that order.  With
+    neither, the config's `default` (a target name or list of names);
+    with no config or no default, plain gcc/clang at -O3.
+    """
+    entries = list(cc_args)
+    entries += [target_command(config, name, config_path)
+                for name in target_args]
+    if entries:
+        return entries
+    default = (config or {}).get("default")
+    if default:
+        names = [default] if isinstance(default, str) else list(default)
+        return [target_command(config, name, config_path) for name in names]
+    return [f"{cc} {FALLBACK_FLAGS}" for cc in DEFAULT_COMPILERS]
+
+
+def asm_output_name(cc_cmd, harness):
+    """Filesystem-safe .s name for one (compiler, source) compilation.
+
+    The readable slug of a compiler command can exceed NAME_MAX when the
+    command embeds absolute toolchain/include paths; long slugs are
+    truncated and kept unique with a short hash of the full command.
+    """
+    tag = re.sub(r"\W+", "_", cc_cmd)
+    if len(tag) > 64:
+        tag = tag[:53] + "_" + hashlib.sha1(cc_cmd.encode()).hexdigest()[:10]
+    return tag + "_" + Path(harness).stem + ".s"
+
+
+def compile_to_asm(cc_cmd, extra_flags, harness, out_dir):
+    """Run one compiler to -S; return the asm text.
+
+    Returns None (with a warning) if the compiler is not on PATH.
+    Exits with the compiler's stderr on a compile failure.
+    """
+    argv = shlex.split(cc_cmd)
+    if shutil.which(argv[0]) is None:
+        print(f"warning: {argv[0]} not found on PATH, skipping",
+              file=sys.stderr)
+        return None
+    out_s = Path(out_dir) / asm_output_name(cc_cmd, harness)
+    cmd = argv + list(extra_flags) + ["-S", "-o", str(out_s), str(harness)]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        sys.exit(f"error: compile failed: {' '.join(cmd)}\n{proc.stderr}")
+    return out_s.read_text()
+
+
+def side_by_side(left, right, ltitle, rtitle, width=44):
+    """Two-column view of a pair's asm lines."""
+    rows = [f"{ltitle:<{width}} | {rtitle}",
+            f"{'-' * width}-+-{'-' * width}"]
+    for l, r in zip_longest(left, right, fillvalue=""):
+        l = l.expandtabs(8)[:width]
+        r = r.expandtabs(8)[:width]
+        rows.append(f"{l:<{width}} | {r}")
+    return "\n".join(rows)
+
+
+def render_table(rows):
+    """Column-aligned text for a list of equal-length string tuples."""
+    widths = [max(len(row[i]) for row in rows) for i in range(len(rows[0]))]
+    return "\n".join(
+        "  ".join(cell.ljust(w) for cell, w in zip(row, widths)).rstrip()
+        for row in rows)
+
+
+def format_spans(spans):
+    return " ".join(f"{label}:{n}" for label, n in spans) or "-"
+
+
+def summary_table(pairs, funcs):
+    """Instruction counts, outbound calls, and loop spans per pair member."""
+    rows = [("function", "role", "insns", "calls", "loop spans")]
+    for old, new in pairs:
+        for name, role in ((old, "baseline"), (new, "candidate")):
+            insns, calls = analyze(funcs[name])
+            rows.append((name, role, str(insns),
+                         ", ".join(calls) or "-",
+                         format_spans(loop_spans(funcs[name]))))
+    return render_table(rows)
+
+
+def file_summary_table(funcs):
+    """Per-function counts plus a whole-file total row.
+
+    The total sums instruction counts over every function parsed from
+    the -S output and unions their outbound calls — a coarse A/B sanity
+    check, not a code-size measurement (literal pools, data, and
+    alignment are not included).
+    """
+    rows = [("function", "insns", "calls", "loop spans")]
+    total_insns, all_calls = 0, []
+    for name, lines in funcs.items():
+        insns, calls = analyze(lines)
+        total_insns += insns
+        for sym in calls:
+            if sym not in all_calls:
+                all_calls.append(sym)
+        rows.append((name, str(insns), ", ".join(calls) or "-",
+                     format_spans(loop_spans(lines))))
+    rows.append((f"TOTAL ({len(funcs)} functions)", str(total_insns),
+                 ", ".join(all_calls) or "-", "-"))
+    return render_table(rows)
+
+
+def file_tags(a, b):
+    """Shortest distinct labels for two source paths in across-mode output."""
+    pa, pb = Path(a), Path(b)
+    if pa.name != pb.name:
+        return pa.name, pb.name
+    ta = f"{pa.parent.name}/{pa.name}"
+    tb = f"{pb.parent.name}/{pb.name}"
+    if ta != tb:
+        return ta, tb
+    return str(a), str(b)
+
+
+def report_across(fn_names, left_funcs, right_funcs, left_tag, right_tag):
+    """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})
+    if missing:
+        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"))
+    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()
+    print(summary_table(pairs, decorated))
+
+
+def run_across(sources, matrix, fn_names, extra_flags, tmp):
+    """--across mode: same function, two compilations.
+
+    Two source files: compare fileA's FUNC vs fileB's FUNC under each
+    compiler in the matrix.  One source file: compare FUNC between the
+    first --cc entry (baseline) and each subsequent entry.
+    """
+    if len(sources) == 2:
+        ran_any = False
+        for cc_cmd in matrix:
+            sides = []
+            for src in sources:
+                asm = compile_to_asm(cc_cmd, extra_flags, src, tmp)
+                if asm is None:
+                    break
+                sides.append(extract_functions(asm))
+            if len(sides) < 2:
+                continue
+            ran_any = True
+            print(f"\n== {cc_cmd} ==\n")
+            report_across(fn_names, sides[0], sides[1],
+                          *file_tags(sources[0], sources[1]))
+        if not ran_any:
+            sys.exit("error: no usable compiler in the matrix")
+        return 0
+
+    usable = []
+    for idx, cc_cmd in enumerate(matrix, start=1):
+        asm = compile_to_asm(cc_cmd, extra_flags, sources[0], tmp)
+        if asm is not None:
+            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)
+    return 0
+
+
+def run_summary(sources, matrix, extra_flags, tmp):
+    """No pairs to compare: whole-file summary, one block per file."""
+    tags = (file_tags(*sources) if len(sources) == 2
+            else [Path(sources[0]).name])
+    ran_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))
+        if len(sections) < len(sources):
+            continue
+        ran_any = True
+        print(f"\n== {cc_cmd} ==")
+        for tag, funcs in zip(tags, sections):
+            if len(sections) > 1:
+                print(f"\n-- {tag} --")
+            print()
+            print(file_summary_table(funcs) if funcs
+                  else "(no functions found)")
+    if not ran_any:
+        sys.exit("error: no usable compiler in the matrix")
+    return 0
+
+
+def run_pairs(source, matrix, pair_specs, extra_flags, tmp):
+    """--pair mode: two different functions within one compilation.
+
+    With no --pair and no old_X/new_X functions to auto-pair, falls
+    back to the whole-file summary for this compilation.
+    """
+    ran_any = False
+    for cc_cmd in matrix:
+        asm = compile_to_asm(cc_cmd, extra_flags, source, tmp)
+        if asm is None:
+            continue
+        ran_any = True
+        funcs = extract_functions(asm)
+        pairs = ([tuple(p.split(":", 1)) for p in pair_specs]
+                 or auto_pairs(funcs))
+        if not pairs:
+            print(f"\n== {cc_cmd} ==\n")
+            print(file_summary_table(funcs) if funcs
+                  else "(no functions found)")
+            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))
+        print(f"\n== {cc_cmd} ==\n")
+        for old, new in pairs:
+            print(side_by_side(funcs[old], funcs[new], old, new))
+            print()
+        print(summary_table(pairs, funcs))
+    if not ran_any:
+        sys.exit("error: no usable compiler in the matrix")
+    return 0
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    extra_flags = []
+    if "--" in argv:
+        cut = argv.index("--")
+        argv, extra_flags = argv[:cut], argv[cut + 1:]
+
+    parser = argparse.ArgumentParser(
+        description=(__doc__ or "").partition("\n")[0],
+        epilog="Flags after a bare -- are appended to every compiler "
+               "invocation, e.g.: asmdiff.py h.c -- -fno-math-errno")
+    parser.add_argument("sources", nargs="+", metavar="SOURCE.c",
+                        help="C file to compile; give two files with "
+                             "--across to compare versions of a function")
+    parser.add_argument("--pair", action="append", default=[],
+                        metavar="OLD:NEW",
+                        help="compare two functions within one compilation "
+                             "(repeatable); default: auto-pair old_X/new_X")
+    parser.add_argument("--across", action="append", default=[],
+                        metavar="FUNC",
+                        help="compare the same function across two "
+                             "compilations (repeatable): one file + two "
+                             "--cc entries, or two files")
+    parser.add_argument("--cc", action="append", default=[],
+                        metavar="'CC FLAGS'",
+                        help="compiler and flags as one string (repeatable); "
+                             "default: config default target, else gcc and "
+                             "clang at " + FALLBACK_FLAGS)
+    parser.add_argument("--target", action="append", default=[],
+                        metavar="NAME",
+                        help="named [table] from the config file, resolved "
+                             "to a --cc entry (repeatable; appended to the "
+                             "matrix after --cc entries)")
+    parser.add_argument("--config", metavar="PATH",
+                        help=f"config file; default search: {CONFIG_NAME} "
+                             "next to SOURCE.c, in the current directory, "
+                             "then in ~/.config/")
+    args = parser.parse_args(argv)
+
+    if len(args.sources) > 2:
+        parser.error("at most two source files may be given")
+    if args.across and args.pair:
+        parser.error("--across and --pair are mutually exclusive")
+    if len(args.sources) == 2 and args.pair:
+        parser.error("--pair compares within one file; "
+                     "use --across FUNC for two files")
+    config_path = find_config(args.config, args.sources)
+    config = load_config(config_path) if config_path else None
+    matrix = build_matrix(args.cc, args.target, config, config_path)
+    if args.across and len(args.sources) == 1 and len(matrix) < 2:
+        parser.error("--across on one file needs at least two --cc entries")
+    for spec in args.pair:
+        if ":" not in spec:
+            parser.error(f"--pair expects OLD:NEW, got {spec!r}")
+
+    with tempfile.TemporaryDirectory(prefix="asmdiff") as tmp:
+        if args.across:
+            return run_across(args.sources, matrix, args.across,
+                              extra_flags, tmp)
+        if len(args.sources) == 2:
+            return run_summary(args.sources, matrix, extra_flags, tmp)
+        return run_pairs(args.sources[0], matrix, args.pair,
+                         extra_flags, tmp)
+
+
+if __name__ == "__main__":
+    sys.exit(main())