docs: state the validation status and correct claims the material contradicts

Assisted-by: DeepSeek V4.1 Flash

docs/man/gasm-asm.1

@@ -20,13 +20,24 @@ flag selects what is written:
 self-consistent image;
 .B elf
 emits a relocatable object (.text/.data sections, a symbol table and
-one PC32 relocation per static-symbol reference) that links with the
+one relocation per static-symbol reference, in the architecture's own
+form: R_X86_64_PC32 on amd64, R_AARCH64_*, R_RISCV_* or R_LARCH_* on the
+others) that links with the
 system toolchain;
 .B goobj
 emits the Go toolchain's own object format, which cmd/link consumes
 directly (it requires
 .BR \-p ,
-the package path, and the installed Go toolchain).
+the package path, and the installed Go toolchain: the object preamble is
+captured from
+.B go tool asm
+and the format version from
+.BR "go version" ).
+.PP
+.B raw
+and
+.B elf
+need no toolchain at all.
 .PP
 Framed functions receive the stack-split guard and the trailing
 morestack block, byte-identical to the toolchain's output, so split
@@ -51,10 +62,10 @@ Exits 0 on success, 1 when parsing or assembly fails, and 2 on a usage
 error.
 .SH EXAMPLES
 .nf
-gasm asm \-o hello.bin hello_amd64.s               raw image
-gasm asm \-\-format elf \-o k.o k.s                 linkable ELF object
-gasm asm \-\-format goobj \-p pkg/path \-o k.o k.s   Go object for go build
-gasm asm \-GOARCH amd64 cpu_x86.s                  arch override
+gasm asm \-o hello.bin hello_amd64.s                      raw image
+gasm asm \-\-format elf \-o k.o k_amd64.s                  linkable ELF object
+gasm asm \-\-format goobj \-p pkg/path \-o k.o k_amd64.s   Go object for go build
+gasm asm \-GOARCH amd64 cpu_x86.s                         arch override
 .fi
 .SH SEE ALSO
 .BR gasm (1),

docs/man/gasm-audit-instructions.1

@@ -8,12 +8,17 @@ 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" ),
-known-but-unencodable names (the backlog) and go-only names (feature
-gaps).  The Go side is probed black-box with a battery of bare
-mnemonics, so the audit tracks whatever toolchain
+.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.
+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 ,

docs/man/gasm-debug.1

@@ -17,14 +17,16 @@ runs to completion with a breakpoint on every instruction and reports
 which executed and how often, the label-level coverage view.
 .SH REPL COMMANDS
 .TP
-.B break \fIlabel|addr\fR [\fBif \fIreg op val\fR]
-Set a breakpoint, optionally conditional on a register comparison
-(register against register or immediate).
+.B break \fIlabel|addr|line\fR [\fBif \fIreg op val|reg|*addr\fR], b
+Set a breakpoint at a label, an address or a source line number, optionally
+conditional on a register comparison: against a constant, against another
+register, or against the 8-byte word at
+.BR *addr .
 .TP
-.B delete \fIlabel|addr\fR
+.B delete \fIlabel|addr\fR, d
 Remove a breakpoint.
 .TP
-.B info break
+.B info break, info breakpoints, info b
 List all breakpoints.
 .TP
 .BR step " [" n ], " s

docs/man/gasm-diff.1

@@ -28,7 +28,7 @@ differs; a usage error exits 2.
 .SH EXAMPLES
 .nf
 gasm diff hello_amd64.s hello_amd64.s
-gasm diff \-\-map wideCopyAVX2=wideCopyAVX512 avx2.s avx512.s
+gasm diff \-\-map wideCopyAVX2=wideCopyAVX512 avx2_amd64.s avx512_amd64.s
 .fi
 .SH SEE ALSO
 .BR gasm (1),

docs/man/gasm-dis.1

@@ -28,7 +28,7 @@ Exits 0 on success, 1 when assembly or decoding fails, and 2 on a usage
 error.
 .SH EXAMPLES
 .nf
-gasm dis k.s                          assemble, then list each function
+gasm dis k_amd64.s                    assemble, then list each function
 gasm dis \-a amd64 \- < dump.bin        disassemble raw bytes from stdin
 .fi
 .SH SEE ALSO

docs/man/gasm-fmt.1

@@ -41,6 +41,13 @@ List files whose formatting differs from gasm's.
 .TP
 .B \-w
 Write the result to the source file.
+.SH EXIT STATUS
+Exits 0 on success, 1 when a path cannot be read or written, and 2 on a
+usage error (combining
+.B \-l
+and
+.BR \-d ,
+or an unknown flag).
 .SH EXAMPLES
 .nf
 gasm fmt                                reformat every .s below here

docs/man/gasm-lint.1

@@ -33,7 +33,11 @@ The function can fall off its end without a terminator.
 TEXT flags are used without including textflag.h.
 .TP
 .B abi-argsize
-The declared frame or argument size disagrees with the
+The declared argument area (the
+.I \-args
+part of
+.IR $frame\-args )
+disagrees with the
 .B //\ function
 signature.
 .TP
@@ -52,7 +56,8 @@ FUNCDATA and PCDATA indices are malformed.
 A label no jump reaches.
 .TP
 .B invalid-textflag
-A TEXT flag combination the toolchain rejects.
+An unknown TEXT or GLOBL flag, reported one flag at a time; numeric flags
+are accepted as textflag.h constants.
 .TP
 .B stack-imbalance
 The function does not restore the stack pointer on every path.
@@ -61,11 +66,18 @@ The function does not restore the stack pointer on every path.
 An operand register has the wrong width for the instruction.
 .TP
 .B abi0-register-args
-A call passes arguments in registers where ABI0 expects the stack
-frame.
+A function whose
+.B //\ function
+parameters are never read from their
+.IR name+offset(FP)
+frame slots, which usually means the body takes its arguments from
+registers instead.
 .TP
 .B nonportable-register-name
-A register spelling that does not exist on the target architecture.
+An amd64 register alias gasm accepts but
+.B go tool asm
+rejects (the RAX/EAX family); the canonical spelling is named in the
+diagnostic.
 .TP
 .B unencodable-instruction
 The mnemonic is known to the table but the encoder cannot assemble it

docs/man/gasm-profile.1

@@ -6,9 +6,10 @@ gasm-profile \- show the basic-block structure of functions
 .SH DESCRIPTION
 Show the basic-block structure of functions in an assembly file: each
 function's labels, their offsets, and the block boundaries.  This is
-the static structure; for runtime execution counts, use
-.BR "gasm verify \-fuzz" ,
-which exercises the code paths.
+the static structure; for runtime execution counts use
+.BR "gasm debug \-\-cover" ,
+and for input coverage
+.BR "gasm verify \-\-fuzz" .
 .SH EXIT STATUS
 Exits 0 on success and 1 when the file cannot be assembled.
 .SH SEE ALSO

docs/man/gasm-verify.1

@@ -45,7 +45,8 @@ 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.
+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
@@ -73,7 +74,7 @@ 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.
+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
@@ -107,8 +108,8 @@ 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
+gasm verify \-\-ground\-truth k_amd64.s
+gasm verify \-\-fuzz \-n 500 k_amd64.s
 .fi
 .SH SEE ALSO
 .BR gasm (1),

docs/man/gasm.1

@@ -17,11 +17,15 @@ bundles a lexer, parser, formatter, linter, standalone assembler and
 language server for Plan 9 assembly into one self-contained binary.  It
 serves two purposes: it brings developer tooling to the
 .I .s
-files of Go programs, and it assembles Plan 9 assembly without the Go
-toolchain at all, to raw images, linkable ELF objects with DWARF5 debug
-sections, or the Go toolchain's own GOOBJ format, which
+files of Go programs, and it assembles Plan 9 assembly to raw images or
+linkable ELF objects with DWARF5 debug sections without the Go toolchain at
+all, plus the Go toolchain's own GOOBJ format, which
 .B go build
-consumes directly.
+consumes directly.  GOOBJ is the one format that needs the toolchain
+installed: the object preamble is captured from
+.B go tool asm
+and the format version from
+.BR "go version" .
 .PP
 Four architectures are covered: amd64 (including VEX/AVX2 and
 EVEX/AVX-512), arm64, riscv64 (RV64IMAFDC and RVC) and loong64.  The