.TH GASM-VERIFY 1 "2026-09-19" "gasm" "User Commands"
.SH NAME
gasm-verify \- JIT-assemble a file and run dynamic checks against it
.SH SYNOPSIS
.B gasm verify [\-smoke] [\-abi] [\-fuzz] [\-ground\-truth] [\-profile] [\-call] <file.s>
.SH DESCRIPTION
Assemble FILE, map it into executable memory and report the available
functions.  This confirms the assembled image is self-consistent (no
unresolved external symbols) and executable, the prerequisite for
dynamic testing.
.PP
With
.BR \-smoke ,
each NOSPLIT function is called with a zeroed argument block to confirm
the JIT trampoline works end-to-end.  This is safe only for functions
that tolerate nil pointers and zero lengths in their arguments.
.PP
With
.BR \-abi ,
each function is called with sentinel values in the registers the Go
ABI fixes across calls (the frame pointer and the goroutine pointer)
plus a canary below SP; violations are reported.  JIT-based checks run
when the host matches the file's architecture, on all four architectures.
.PP
With
.BR \-fuzz ,
each function with a
.B //\ func
signature is differentially fuzzed against the go-tool-asm version in a
subprocess (so a crash on a partial function is reported, not fatal).
.PP
With
.BR \-ground\-truth ,
the assembled machine code is compared byte-for-byte against
.B go tool asm
(relocation sites masked), reporting any encoding drift.
.PP
With
.BR \-profile ,
the static basic-block structure is listed for each function.
.PP
With
.BR \-call ,
a single function is invoked with user-supplied buffers
.RB ( \-buf )
instead of the smoke/abi/fuzz sweeps.  Useful for partial functions
(e.g. decoders) that crash on random input but should succeed on valid
data.  The function named must be NOSPLIT: a function with a stack frame
is refused with a diagnostic and exits 1.
.PP
With
.B \-save\-corpus
(and
.BR \-fuzz ),
every input that crashes or mismatches is written to the directory as
replayable JSON.
.B \-replay
re-runs saved entries against the kernel, one child process per entry,
so an input that crashed the original run crashes only the child: the
report says whether each entry reproduces.
.SH OPTIONS
.TP
.B \-abi
Run ABI-checking calls (sentinel registers and red zone).
.TP
.B \-abi\-n \fIn\fR
Number of ABI check iterations with varied inputs; the default is 100.
.TP
.B \-args \fIspec\fR
Scalar args for -call: name=value[,name=value] (decimal or 0x hex).
.TP
.B \-buf \fIspec\fR
Buffer spec for -call: name:size:pattern[,name:size:pattern] where
pattern is zero, ones, seq, or hex.
.TP
.B \-call \fIname\fR
Call a single NOSPLIT function with -buf instead of the sweeps.
.TP
.B \-fuzz
Differential fuzz: JIT both the gasm and the go-tool-asm versions and
compare outputs.
.TP
.B \-ground\-truth
Compare machine code byte-for-byte against go tool asm.
.TP
.B \-n \fIn\fR
Number of fuzz iterations per function; the default is 1000.
.TP
.B \-profile
List basic-block structure per function.
.TP
.B \-repeat \fIn\fR
Number of times to repeat a -call invocation; the default is 1.
.TP
.B \-replay \fIdir\fR
Replay saved corpus entries (JSON files in this directory) against the
kernel.
.TP
.B \-save\-corpus \fIdir\fR
With -fuzz: write each failing input to this directory as replayable
JSON.
.TP
.B \-smoke
Call each NOSPLIT function with zeroed args.
.SH EXIT STATUS
Exits 0 when every requested check passes and 1 when any check fails;
a file that cannot be assembled exits 1 and a usage error exits 2.
.SH EXAMPLES
.nf
gasm verify \-\-call add \-\-args a=2,b=3 hello_amd64.s
gasm verify \-\-ground\-truth k_amd64.s
gasm verify \-\-fuzz \-n 500 k_amd64.s
.fi
.SH SEE ALSO
.BR gasm (1),
.BR gasm\-asm (1),
.BR gasm\-debug (1)