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:
- The common language (LANGUAGE, OPERANDS, DIRECTIVES, PREPROCESSOR): the syntax, operands, directives and preprocessing, the same on every target and meaningful without a Go runtime.
- 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 andgo vetchecks. - 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 | 1 | lexicon, statement structure, labels, literals, expressions |
| OPERANDS.md | 1 | operand grammar, pseudo-registers, addressing modes, symbol naming |
| DIRECTIVES.md | 1 | TEXT, DATA, GLOBL, FUNCDATA, PCDATA, PCALIGN and the function flags |
| PREPROCESSOR.md | 1 | #include, #define, #ifdef and friends, -D, -I |
| 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.