docs(asm): open the assembly language reference

Assisted-by: GLM 5.3 Flash
2026-09-21 19:49:04 +02:00
parent 95025be1bc
commit 837231c068
8 changed files with 667 additions and 2 deletions
@@ -0,0 +1,53 @@
+# The Plan 9 assembly language
+
+This directory is the reference for the Plan 9 assembly language as the Go
+toolchain and gasm accept it, written to be complete enough to implement
+against. It exists because no such reference exists upstream: Go documents
+the language on a single page, and the rest of the knowledge lives in the
+toolchain's source and in the practice of reading it.
+
+Every page carries the same conformance statement: which layer of the system
+it describes, which toolchain release it was verified against, and how the
+claims were checked. Pages in this directory are verified against Go 1.27.1
+and against gasm's own differential test suite, which compares gasm's
+behaviour with `go tool asm` byte for byte and output for output.
+
+## The three layers
+
+The reference deliberately separates three layers, because their rules have
+different owners and different lifetimes:
+
+1. **The common language** (LANGUAGE, OPERANDS, DIRECTIVES,
+   PREPROCESSOR): the syntax, operands, directives and preprocessing, the
+   same on every target and meaningful without a Go runtime.
+2. **The Go-embedded layer** (RUNTIME): everything that exists only because
+   the code runs inside a Go program: the ABI0 contract, generated wrappers,
+   `go_asm.h`, the garbage collector annotations and `go vet` checks.
+3. **The standalone layer** (STANDALONE, planned with the standalone
+   compilation phase): using the language outside Go, through gasm's ELF
+   output and the extended instruction set, where the toolchain offers no
+   ground truth and execution testing is the only verification.
+
+A rule stated in layer 1 holds on every target. A rule stated in layer 2
+says which part of the Go machinery imposes it. Nothing in layer 3 changes
+layers 1 or 2; it extends them.
+
+## Pages
+
+| Page | Layer | Contents |
+|---|---|---|
+| [LANGUAGE.md](LANGUAGE.md) | 1 | lexicon, statement structure, labels, literals, expressions |
+| [OPERANDS.md](OPERANDS.md) | 1 | operand grammar, pseudo-registers, addressing modes, symbol naming |
+| [DIRECTIVES.md](DIRECTIVES.md) | 1 | TEXT, DATA, GLOBL, FUNCDATA, PCDATA, PCALIGN and the function flags |
+| [PREPROCESSOR.md](PREPROCESSOR.md) | 1 | `#include`, `#define`, `#ifdef` and friends, `-D`, `-I` |
+| [RUNTIME.md](RUNTIME.md) | 2 | ABI0, prototypes, `go_asm.h`, `funcdata.h`, `go vet` |
+| AMD64, ARM64, RISCV64, LOONG64 | 1, 3 | per architecture: registers, conventions, addressing, instruction families and the generated instruction appendices |
+| STANDALONE.md | 3 | the language outside Go |
+
+## Status
+
+The common-language core and the Go-embedded layer are written and verified.
+The four per-architecture pages and their generated instruction appendices
+follow, architecture by architecture; STANDALONE.md lands with the standalone
+compilation phase. The object format these pages feed is specified in
+[GOOBJ.md](../GOOBJ.md).