.TH GASM-AUDIT-INSTRUCTIONS 1 "2026-09-21" "gasm" "User Commands"
.SH NAME
gasm-audit-instructions \- diff the encoder against the Go toolchain, or measure a corpus
.SH SYNOPSIS
.B gasm audit\-instructions [\-\-corpus [\fIdir\fR]] [\-\-list] [\-I dir] [amd64|arm64|riscv64|loong64]
.SH DESCRIPTION
Compare the gasm encoder for the given architecture (default amd64)
against
.B go tool asm
and print the diff: superset encodings (gasm-only, shippable via
.BR "gasm asm \-\-format goobj" )
and known-but-unencodable names (the backlog).  The Go side is probed
black-box one bare mnemonic at a time, so the audit tracks whatever
toolchain
.B go env GOROOT
provides; the gasm side answers from the encoder table on amd64 and from
trial assembly over a battery of operand shapes elsewhere.  Names
.B go tool asm
knows and gasm does not cannot be enumerated by probing, because Go's
table is visible only through names already in the gasm table; the report
closes with a note saying so rather than listing them.
.PP
With
.BR \-\-corpus ,
the audit changes shape: it assembles every
.I .s
file under the given directory (default GOROOT/src) with the gasm
encoder only, no toolchain probing.  A file whose name carries a
recognisable _arch suffix is attempted for that architecture; a file
without one is attempted for all four, exactly as a GOARCH build would
compile it.  The report gives the headline number (files that assemble
for every target architecture), the per-architecture pass rates and the
most common failure reasons, which drive the encodability backlog by
frequency rather than by table order.  A run over GOROOT takes under a
second.
.SH OPTIONS
.TP
.B \-\-corpus [\fIdir\fR]
Assemble a corpus of .s files and report pass rates and failure
reasons.
.TP
.B \-\-list
With
.BR \-\-corpus ,
print every failing file with its failure reason, per architecture,
instead of one representative file per reason.
.TP
.B \-I \fIdir\fR
Directory to search for #include files; may be repeated, searched in
order after the source directory.  A corpus run whose files include
toolchain headers (such as GOROOT/pkg/include) needs it, the same -I a
toolchain comparison takes.
.SH EXIT STATUS
The mnemonic-diff mode reports through its output and exits 0; a failed
probe or an unknown architecture exits non-zero.
.SH EXAMPLES
.nf
gasm audit\-instructions amd64
gasm audit\-instructions \-\-corpus
gasm audit\-instructions \-\-corpus "$(go env GOROOT)/src/crypto"
.fi
.SH SEE ALSO
.BR gasm (1),
.BR gasm\-asm (1)