# 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).