docs: fold development changes into v0.29.0, document --call/--buf/--map

CHANGELOG.md

@@ -9,31 +9,13 @@ and this project adheres to [Conventional Commits](https://www.conventionalcommi
 
 Unreleased changes on the `development` branch.
 
-### Added
-
-- **`gasm diff --map`** — compare functions whose names differ between files
-  (e.g. `--map wideCopyAVX2=wideCopyAVX512` pairs AVX2 and AVX-512 variants
-  regardless of suffix). Unmapped functions fall back to the original name match.
-- **`gasm verify --call`** — invoke a single function with user-supplied buffers
-  (`--buf name:size:pattern`) instead of the smoke/abi/fuzz sweeps. Patterns:
-  `zero`, `ones`, `seq`, or a hex blob. Useful for partial functions (e.g.
-  decoders) that crash on random input but should succeed on valid data.
-  The arg block is printed before and after the call, showing return values.
-- **`gasm verify --ground-truth`** now documented in `--help` (was already a flag,
-  just missing from the help text).
-
-### Fixed
-
-- **Signature parser** — grouped Go parameters like `dst, src []byte` are now
-  parsed correctly (both get type `[]byte`). Previously the first name was
-  treated as its own type (`dst` with size 8), causing wrong ABI0 arg-block
-  layout in both `verify --call` and the fuzzer.
-
 ## [0.29.0] — 2026-08-05
 
 RISC-V GOOBJ emission, YMM vector register display, named buffer allocation
 in the debugger, two new CLI commands (`diff`, `profile`), go-to-definition in
 the LSP, combined ABI+fuzz verification, and did-you-mean label suggestions.
+A `--map` flag for `diff` and `--call`/`--buf` flags for `verify` extend the
+new CLI commands. A signature-parser fix corrects grouped Go parameters.
 
 ### Added
 
@@ -57,11 +39,31 @@ the LSP, combined ABI+fuzz verification, and did-you-mean label suggestions.
   a crash or mismatch for reproducibility.
 - **ABI + fuzz combined** — `gasm verify --fuzz` now runs ABI checks (sentinel
   registers, canary, stack bounds) alongside differential fuzz testing.
+- **`gasm diff --map`** — compare functions whose names differ between files
+  (e.g. `--map wideCopyAVX2=wideCopyAVX512` pairs AVX2 and AVX-512 variants
+  regardless of suffix). Unmapped functions fall back to the original name match.
+- **`gasm verify --call`** — invoke a single function with user-supplied buffers
+  (`--buf name:size:pattern`) instead of the smoke/abi/fuzz sweeps. Patterns:
+  `zero`, `ones`, `seq`, or a hex blob. Useful for partial functions (e.g.
+  decoders) that crash on random input but should succeed on valid data.
+  The arg block is printed before and after the call, showing return values.
+- **`gasm verify --ground-truth`** now documented in `--help` (was already a flag,
+  just missing from the help text).
+
+### Fixed
+
+- **Signature parser** — grouped Go parameters like `dst, src []byte` are now
+  parsed correctly (both get type `[]byte`). Previously the first name was
+  treated as its own type (`dst` with size 8), causing wrong ABI0 arg-block
+  layout in both `verify --call` and the fuzzer.
 
 ### Verified
 
 - RISC-V GOOBJ output links correctly with the Go toolchain.
 - `gasm diff` detects byte-level differences in real assembly kernels.
+- `gasm diff --map` pairs AVX2 and AVX-512 kernels by mapped name.
+- `gasm verify --call` invokes `wideCopyAVX2` and `decodeBlockAVX2` with
+  user-supplied buffers; the decoder returns its error code instead of crashing.
 - LSP go-to-definition resolves labels across functions and files.
 - Debugger YMM display confirmed on AVX2-capable hardware.
 

README.md

@@ -335,8 +335,10 @@ gasm lint   *.s                     # static checks
 gasm asm --format elf -o k.o k.s    # assemble to a linkable ELF object
 gasm verify kernel_amd64.s           # JIT-load and report functions
 gasm verify --ground-truth k.s      # byte-for-byte vs go tool asm
+gasm verify --call decodeBlockAVX2 --buf src:64:hex...,dst:256:zero k.s
 gasm debug --func name k.s           # interactive debugger
 gasm diff a.s b.s                    # compare machine code byte-for-byte
+gasm diff --map wideCopyAVX2=wideCopyAVX512 avx2.s avx512.s
 gasm profile k.s                     # show basic-block structure
 ```
 

docs/ARCHITECTURE.md

@@ -323,7 +323,13 @@ ABI checks (sentinel registers, canary, stack bounds) with differential fuzz
 testing, comparing the JIT-assembled kernel against the portable Go reference
 bit-for-bit while verifying the ABI contract on every iteration.  When a fuzz
 iteration crashes or mismatches, `FuzzResult.CrashInput` stores the exact input
-for reproducibility.
+for reproducibility.  `gasm verify --call <func> --buf name:size:pattern`
+invokes a single function with user-supplied buffers (patterns: zero, ones,
+seq, or hex), printing the ABI0 argument block before and after the call —
+useful for partial functions (e.g. decoders) that crash on random input but
+should succeed on valid data.  `gasm verify --ground-truth` compares the
+assembled machine code byte-for-byte against `go tool asm` (relocation sites
+masked), reporting any encoding drift.
 
 ### `debug`
 

docs/cli.md

@@ -70,14 +70,25 @@ Assemble FILE, map it into executable memory, and run dynamic checks.
 | `--fuzz` | Differential fuzz: JIT both gasm and go-tool-asm, compare outputs |
 | `-n` | Fuzz iterations per function (default: 1000) |
 | `--abi` | Run ABI-checking calls (sentinel registers + red zone) |
+| `--abi-n` | Number of ABI check iterations with varied inputs (default: 100) |
 | `--profile` | List basic-block structure per function |
 | `--smoke` | Call each NOSPLIT function with zeroed args |
+| `--call <func>` | Invoke a single function with `--buf` instead of the sweeps |
+| `--buf <spec>` | Buffer spec for `--call`: `name:size:pattern[,name:size:pattern]` |
+| `--repeat <n>` | Number of times to repeat a `--call` invocation (default: 1) |
 
 The `--fuzz` mode runs each function in a subprocess; a partial function
 (e.g. a decoder that faults on malformed input) is reported as
-`CRASH` without killing the parent. Use `--ground-truth` for decoders.
+`CRASH` without killing the parent. Use `--call` with `--buf` to invoke
+partial functions with valid data instead.
 
-## `gasm debug --func <name> <file.s>`
+The `--call` mode parses the `// func` signature, allocates the requested
+buffers (`zero`, `ones`, `seq`, or a hex blob), builds the ABI0 argument
+block with buffer pointers/lengths/capacities at the matching parameter
+offsets, and prints the arg block before and after the call — showing
+return values and any output written to the buffers.
+
+## `gasm debug --func <name> [--buf spec] <file.s>`
 
 Interactive debugger for JIT-assembled amd64 functions. Requires a
 compiled binary on `$PATH` (not `go run`).
@@ -85,6 +96,7 @@ compiled binary on `$PATH` (not `go run`).
 | Flag | Description |
 |------|-------------|
 | `--func` | Function to debug (required) |
+| `--buf` | Buffer spec: `name:size:pattern[,name:size:pattern]` |
 
 REPL commands:
 
@@ -93,11 +105,34 @@ REPL commands:
 | `break <label\|addr>` | Set a breakpoint |
 | `step [n]` | Single-step n instructions |
 | `continue` | Run until next breakpoint or exit |
-| `regs` | Print general-purpose registers |
+| `regs` | Print general-purpose + YMM/XMM vector registers |
 | `x [addr] [len]` | Hex-dump memory |
 | `labels` | List function labels and offsets |
 | `quit` | Kill the debuggee and exit |
 
+## `gasm diff [--map old=new,...] <file1.s> <file2.s>`
+
+Compare the machine code produced by assembling two files. Shows which
+functions differ and the first few differing bytes. Useful for verifying
+that two implementations produce identical code, or for tracking encoding
+changes between Go assembler versions.
+
+| Flag | Description |
+|------|-------------|
+| `--map` | Comma-separated `old=new` pairs to match functions with different names |
+
+Without `--map`, functions are paired by exact name. With `--map`, a
+function named `old` in the first file is compared against the function
+named `new` in the second file (e.g. `--map wideCopyAVX2=wideCopyAVX512`
+pairs AVX2 and AVX-512 variants regardless of suffix).
+
+## `gasm profile <file.s>`
+
+Show the basic-block structure of functions in an assembly file. Lists
+each function's labels, their offsets, and the block boundaries. This is
+the static structure; for runtime execution counts, use `gasm verify
+--fuzz` which exercises the code paths.
+
 ## `gasm lsp`
 
 Run the language server over standard input/output (JSON-RPC 2.0 with