docs: fold development changes into v0.29.0, document --call/--buf/--map
This commit is contained in:
+22
-20
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
+38
-3
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user