From 123a16e3468d172f05f2593c4051294a68b73b60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Balv=C3=ADn?= Date: Mon, 21 Sep 2026 18:33:05 +0200 Subject: [PATCH] docs(readme): state the documentation goal --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 3895d41..e0431e7 100644 --- a/README.md +++ b/README.md @@ -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: