docs(readme): state the documentation goal

2026-09-21 18:35:27 +02:00
parent 9701812bee
commit 123a16e346
1 changed files with 32 additions and 0 deletions
@@ -157,6 +157,38 @@ been compiled and read, never executed. Its architecture-neutral units
 run under `go test ./...`, which the race workflow and a manual run
 perform; the default `just test` gate does not sweep `./debug/...`.
 ## The documentation goal
 The toolkit is the primary goal. The secondary one is documentation: a
 specification of the Plan 9 assembly language and of the GOOBJ object
 format that is 100 % complete, detailed enough to implement against,
 and written to a professional standard. These are the two subjects this
 project works with every day, and they are the two for which no usable
 documentation exists.
 Go documents the language on a single page, "A Quick Guide to Go's
 Assembler", which carries no section for loong64, one of the four
 architectures gasm supports, and covers a fraction of what each
 assembler accepts. What exists beyond it lives as comments inside the
 toolchain's internal source: per-architecture reference manuals for
 arm64, ppc64, riscv64 and loong64, written for the toolchain's own
 maintainers rather than for an outside reader, and none at all for
 amd64. GOOBJ fares worst of all. The format that `go build` consumes
 has no specification anywhere: it is described by a comment in an
 internal package, it is not a stable interface, and it can change with
 any toolchain release.
 The gap is therefore filled the only way it can be filled: by reverse
 engineering the toolchain itself, the same work the encoders already
 perform. Most of the documentation can come from nowhere else, and it
 is written as that knowledge is produced during development. It is
 verified the way the code is verified: an encoding documented here is
 one that differential tests against `go tool asm` confirm
 byte-for-byte, and a format field documented here is one the linker
 demonstrably reads. The result will live in this repository, so that
 Plan 9 assembly finally carries a reference its own tooling is built
 against.
 ## Direction
 The plan, in the order it is being worked: