From 23b3d3e152d583cbe8f9cc147cbd12b3bb1b32c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Balv=C3=ADn?= Date: Wed, 5 Aug 2026 21:15:05 +0200 Subject: [PATCH] docs: fold development changes into v0.29.0, document --call/--buf/--map --- CHANGELOG.md | 42 ++++++++++++++++++++++-------------------- README.md | 2 ++ docs/ARCHITECTURE.md | 8 +++++++- docs/cli.md | 41 ++++++++++++++++++++++++++++++++++++++--- 4 files changed, 69 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1435fa1..8808504 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index a5f37a8..fe5c410 100644 --- a/README.md +++ b/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 ``` diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5f827ba..796c542 100644 --- a/docs/ARCHITECTURE.md +++ b/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 --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` diff --git a/docs/cli.md b/docs/cli.md index 7abc3a6..1090ebe 100644 --- a/docs/cli.md +++ b/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 ` | Invoke a single function with `--buf` instead of the sweeps | +| `--buf ` | Buffer spec for `--call`: `name:size:pattern[,name:size:pattern]` | +| `--repeat ` | 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 ` +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 [--buf spec] ` 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 ` | 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,...] ` + +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 ` + +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