2026-09-19 23:49:27 +02:00
|
|
|
.TH GASM-AUDIT-INSTRUCTIONS 1 "2026-09-19" "gasm" "User Commands"
|
2026-09-19 21:18:43 +02:00
|
|
|
.SH NAME
|
|
|
|
|
gasm-audit-instructions \- diff the encoder against the Go toolchain, or measure a corpus
|
|
|
|
|
.SH SYNOPSIS
|
2026-09-20 14:25:47 +02:00
|
|
|
.B gasm audit\-instructions [\-\-corpus [\fIdir\fR]] [\-I dir] [amd64|arm64|riscv64|loong64]
|
2026-09-19 21:18:43 +02:00
|
|
|
.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
|
2026-09-20 01:40:51 +02:00
|
|
|
.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
|
2026-09-19 21:18:43 +02:00
|
|
|
.B go env GOROOT
|
2026-09-20 01:40:51 +02:00
|
|
|
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.
|
2026-09-19 21:18:43 +02:00
|
|
|
.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.
|
2026-09-20 14:25:47 +02:00
|
|
|
.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.
|
2026-09-19 21:18:43 +02:00
|
|
|
.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)
|
