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

Assisted-by: DeepSeek V4.1 Flash

cmd/gasm/audit.go

@@ -40,10 +40,13 @@ func cmdAuditInstructions(args []string) error {
 	fs := newCommand("audit-instructions", "gasm audit-instructions [--corpus [dir]] [amd64|arm64|riscv64|loong64]", `
 Compare the gasm encoder for the given architecture (default amd64) against
 go tool asm and print the diff: superset encodings (gasm-only, shippable via
-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 `+"`go env GOROOT`"+`
-provides.
+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 `+"`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 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.
 
 With --corpus the audit changes shape: it assembles every .s file under the
 given directory (default GOROOT/src) with the gasm encoder only, no
@@ -109,7 +112,7 @@ the encodability backlog by frequency rather than by table order.
 
 	w := os.Stdout
 	fmt.Fprintf(w, "gasm table (%s, families excluded): %d mnemonics\n", archName, len(names))
-	fmt.Fprintf(w, "gasm encodable: %d   go tool asm recognized: %d\n", len(shared)+len(superset), countTrue(goKnown))
+	fmt.Fprintf(w, "gasm encodable: %d   go tool asm recognised: %d\n", len(shared)+len(superset), countTrue(goKnown))
 	fmt.Fprintf(w, "shared: %d\n", len(shared))
 	fmt.Fprintf(w, "\nSuperset encodings (gasm-only; ship via gasm asm --format goobj):\n")
 	for _, n := range superset {

cmd/gasm/debug_linux.go

@@ -24,9 +24,10 @@ function in a traced subprocess (ptrace), then provides a REPL for
 single-stepping, breakpoints, register and memory inspection.
 
 REPL commands:
-  break <label|addr> [if <reg> <op> <val>]
+  break <label|addr|line> [if <reg> <op> <val|reg|*addr>]
                        set a breakpoint, optionally conditional on a
-                       register comparison (reg-reg or reg-immediate)
+                       comparison of one register against a constant,
+                       another register, or the 8-byte word at *addr
   delete <label|addr>  remove a breakpoint
   info break           list all breakpoints
   step [n], s          single-step n instructions (default 1)

cmd/gasm/main.go

@@ -486,10 +486,13 @@ func cmdAsm(args []string) int {
 With -o the output is written to a file instead.  The --format flag selects
 what is written: raw (the default) concatenates the functions and the data
 section into one self-consistent image; elf emits a relocatable object
-(.text/.data sections, a symbol table and one PC32 relocation per
-static-symbol reference) that links with the system toolchain; goobj emits
-the Go toolchain's own object format, which cmd/link consumes directly (it
-requires -p, the package path, and the installed Go toolchain).
+(.text/.data sections, a symbol table and 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; goobj emits the Go toolchain's own object format, which
+cmd/link consumes directly (it requires -p, the package path, and the
+installed Go toolchain: the object preamble is captured from go tool asm
+and the format version from go version).
 `)
 	out := fs.String("o", "", "write the output to this file")
 	format := fs.String("format", "raw", "output format: raw (concatenated image), elf or goobj (Go object)")
@@ -793,8 +796,8 @@ func cmdProfile(args []string) int {
 	flagSet := newCommand("profile", "gasm profile <file.s>", `
 Show the basic-block structure of functions in an assembly file.
 Lists each function's labels, their offsets, and the block boundaries.
-This is the static structure; for runtime execution counts, use
-gasm verify --fuzz which exercises the code paths.
+This is the static structure; for runtime execution counts use
+gasm debug --cover, and for input coverage gasm verify --fuzz.
 `)
 	flagSet.Parse(args)
 	if flagSet.NArg() != 1 {
@@ -1033,7 +1036,8 @@ With -profile, the static basic-block structure is listed for each function.
 
 With -call, a single function is invoked with user-supplied buffers (-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.
+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 -save-corpus (and -fuzz), every input that crashes or mismatches is
 written to the directory as replayable JSON.  -replay re-runs saved