118 lines
3.5 KiB
Groff
118 lines
3.5 KiB
Groff
.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 (all but loong64, which
|
|
is ground-truth only for now).
|
|
.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.
|
|
.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 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.s
|
|
gasm verify \-\-fuzz \-n 500 k.s
|
|
.fi
|
|
.SH SEE ALSO
|
|
.BR gasm (1),
|
|
.BR gasm\-asm (1),
|
|
.BR gasm\-debug (1)
|