docs: drop process labels and refresh the architecture and manual pages

Assisted-by: GLM 5.3
2026-09-19 23:49:27 +02:00
parent 7604a9443f
commit 3a73acb20a
19 changed files with 123 additions and 31 deletions
@@ -44,10 +44,10 @@ flowchart TD

 The lexer is the shared foundation: the parser builds the AST from it, the
 formatter re-spaces its tokens directly, and the language server uses it for
-semantic highlighting.  The phases follow a dependency chain: Phase 1 (static
-analysis) builds only on the AST, Phase 2 (the standalone assembler) emits
-object code, and Phases 3 (dynamic analysis) and 4 (the debugger) both consume
-the execution substrate that the assembler provides.
+semantic highlighting.  The packages follow a dependency chain: static analysis
+builds only on the AST, the standalone assembler emits object code, and both
+the dynamic analysis and the debugger consume the execution substrate the
+assembler provides.

 ## Packages

@@ -62,6 +62,7 @@ the execution substrate that the assembler provides.
 | `format` | canonical formatter over the token stream |
 | `lsp` | the language server |
 | `asm` | standalone assembler: encoders, image layout, object emitters |
+| `disasm` | disassembly backend over golang.org/x/arch |
 | `verify` | JIT execution, ABI checks, differential fuzzing |
 | `debug` | interactive ptrace debugger |
 | `cmd/gasm` | the CLI |
@@ -230,20 +231,20 @@ them from the standard LSP legend, so no editor-specific grammar is needed.

 ### `asm`

-The standalone assembler (Phase 2).  Its core is an amd64 instruction encoder:
+The standalone assembler.  Its core is an amd64 instruction encoder:
 a REX/ModR-M/SIB/displacement/immediate engine plus the scalar instruction set,
 with the Plan 9 operand order (source first) mapped onto the x86 encoding.
 Every encoding is validated by decoding it again with `golang.org/x/arch`, the
 one module dependency, which also backs the `gasm dis` listings.

-A **RISC-V encoder** (Phase 5, RV64IMAFDC + RVC compression) encodes the full
+A **RISC-V encoder** (RV64IMAFDC + RVC compression) encodes the full
 integer, atomic, float/double, FMA and CSR instruction sets with the MOV
 pseudo-instruction and SB/global symbol references (AUIPC pairs with
 R_RISCV_PCREL_HI20/LO12 relocations).  The encoder compresses eligible
 instructions to 16-bit RVC forms and is validated byte-for-byte against
 `GOARCH=riscv64 go tool asm`.

-A **LoongArch encoder** (Phase 5, LoongArch64) encodes the integer and
+A **LoongArch encoder** (LoongArch64) encodes the integer and
 floating-point instruction sets with the dual-form arithmetic mnemonics (3R
 vs 2RI12), the 16/21-bit branch families, the MOV pseudo-instruction and its
 constant materialisation (the dcon classification driving lu12i.w/ori/lu32i.d/
@@ -254,7 +255,7 @@ relocations).  Like the RISC-V encoder it is validated byte-for-byte against
 `GOARCH=loong64 go tool asm`, and its GOOBJ output is proven end-to-end by
 substituting it into a cross-compiled `go build` and linking with `cmd/link`.

-An **AArch64 encoder** (Phase 5, arm64) encodes the integer instruction set
+An **AArch64 encoder** (arm64) encodes the integer instruction set
 with the data-processing (shifted register and immediate forms), load/store
 (scaled unsigned immediate and unscaled9-bit immediate), conditional and
 unconditional branches, the MOV pseudo-instruction and its constant
@@ -389,7 +390,7 @@ compiled packages it references.

 ### `verify`

-The dynamic-analysis substrate (Phase 3).  It JIT-loads assembled images into
+The dynamic-analysis substrate.  It JIT-loads assembled images into
 executable memory and invokes them directly, enabling differential testing,
 runtime ABI checks and coverage profiling.

@@ -462,7 +463,7 @@ For non-interactive use, `--script` runs REPL commands from a file (or
 stdin) and exits, `--timeout` kills the debuggee when a run hangs (the
 watchdog is armed before the ptrace attach, so a sandboxed debuggee cannot
 block it), and `--cover` runs to completion with a breakpoint on every
-label and reports which blocks executed.
+instruction and reports which instructions executed and how often.

 ### Extending the toolkit

@@ -260,7 +260,7 @@ Usage: gasm debug <file.s> --func <name>
 | `-buf` | empty | buffer spec: `name:size:pattern[,name:size:pattern]` (zero, ones, seq or hex) |
 | `-args` | empty | file containing the ABI0 argument block |
 | `-script` | empty | run REPL commands from a file, one per line, and exit; `-` reads stdin |
-| `-timeout` | 0 | kill the debuggee after this duration, for headless `-script` runs |
+| `-timeout` | 0 | kill the debuggee after this duration, for headless `-script` runs; a timeout exits 3 |
 | `-cover` | off | run to completion with a breakpoint on every instruction and report which executed |

 The debugger spawns the debuggee from the `gasm` binary on `$PATH`, so install
@@ -447,6 +447,7 @@ version control.
 | `0` | success |
 | `1` | a failure the program detected: a parse or assembly error, an error-severity lint diagnostic, a mismatch in `verify`, a file that cannot be read |
 | `2` | the arguments were wrong: a missing or extra argument, an unknown command or format, an invalid `--map` pair |
+| `3` | `debug --timeout` killed the debuggee |

 ## Examples

@@ -38,6 +38,8 @@ Every recipe in the `justfile`, and what it does.
 | `just clean` | removes the build artefacts, `bin/` and `coverage.out` |
 | `just install` | builds, then copies the binary into `bindir` (`~/.local/bin`); `gasm debug` needs an installed binary, because it spawns the debuggee from `$PATH` |
 | `just uninstall` | removes the installed binary from `bindir` |
+| `just install-man` | installs the man pages under `docs/man` into `~/.local/share/man/man1` (`MANDIR` overrides), gzip-compressed; not a gate |
+| `just uninstall-man` | removes the installed man pages |
 | `just run` | runs the CLI with `go run -buildvcs=true`; the recipe takes no arguments, so flags go through the package instead |
 | `just dev` | the same as `run`; the project has no watcher to add |
 | `just gen` | regenerates the `arch` instruction tables from the Go toolchain source; not a gate |
@@ -1,4 +1,4 @@
-.TH GASM-ASM 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-ASM 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-asm \- assemble Plan 9 assembly without the Go toolchain
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-AUDIT-INSTRUCTIONS 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-AUDIT-INSTRUCTIONS 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-audit-instructions \- diff the encoder against the Go toolchain, or measure a corpus
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-DEBUG 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-DEBUG 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-debug \- interactive source-level debugger for JIT-assembled functions
 .SH SYNOPSIS
@@ -98,10 +98,12 @@ Run REPL commands from a file (one per line) and exit; - reads stdin.
 .TP
 .B \-timeout \fIduration\fR
 Kill the debuggee after this duration (e.g. 30s); for headless --script
-runs.
+runs; a timeout exits 3.
 .SH EXIT STATUS
-Exits 0 when the scripted session completes and 1 when the debuggee
-crashes or a check fails; the debugger is Linux-only.
+Exits 0 when the scripted session completes, 1 when the debuggee crashes
+or a check fails, and 3 when
+.B \-\-timeout
+kills the debuggee; the debugger is Linux-only.
 .SH EXAMPLES
 .nf
 gasm debug \-\-func name k.s
@@ -1,4 +1,4 @@
-.TH GASM-DIFF 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-DIFF 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-diff \- compare the machine code of two assembly files
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-DIS 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-DIS 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-dis \- disassemble machine code to instruction text
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-FMT 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-FMT 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-fmt \- canonicalise the formatting of Plan 9 assembly sources
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-LINT 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-LINT 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-lint \- run the static checks over assembly files
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-LSP 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-LSP 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-lsp \- run the Plan 9 assembly language server
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-PARSE 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-PARSE 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-parse \- parse an assembly file and report syntax errors
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-PROFILE 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-PROFILE 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-profile \- show the basic-block structure of functions
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-SCAFFOLD 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-SCAFFOLD 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-scaffold \- generate a differential test skeleton for a kernel file
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-TOKENS 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM-TOKENS 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm-tokens \- print the lexical token stream of an assembly file
 .SH SYNOPSIS
@@ -1,4 +1,4 @@
-.TH GASM-VERIFY 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.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
@@ -1,4 +1,4 @@
-.TH GASM 1 "2026-09-19" "gasm 0.33.0" "User Commands"
+.TH GASM 1 "2026-09-19" "gasm" "User Commands"
 .SH NAME
 gasm \- developer tooling for Go's Plan 9 assembler
 .SH SYNOPSIS
@@ -82,7 +82,8 @@ Show the command overview.
 Print the version the toolchain recorded at build time.
 .SH EXIT STATUS
 Exits 0 on success, 1 when a command fails, and 2 on a usage error.  An
-unknown command exits 2.
+unknown command exits 2; \fBgasm debug\fR exits 3 when \-\-timeout kills
+the debuggee.
 .SH SEE ALSO
 .BR gasm\-asm (1),
 .BR gasm\-fmt (1),