54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# 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).
|