3.1 KiB
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.md | 1 | registers, addressing, the frame and split check, families, relocations |
| ARM64.md | 1 | registers, the MOV load and store series, special operand orders, SIMD |
| RISCV64.md | 1 | registers and their constrained names, per class operand order, profiles, vector extension |
| LOONG64.md | 1 | registers, width suffixes, vector element syntax, atomics and barriers |
| INSTRUCTIONS-AMD64.md and the other three | 1 | generated per architecture inventory of every accepted mnemonic |
| STANDALONE.md | 3 | the language outside Go |
Status
The common-language core, the Go-embedded layer, all four per-architecture pages and the generated instruction appendices are written and verified. STANDALONE.md lands with the standalone compilation phase. The object format these pages feed is specified in GOOBJ.md.