gasm-sdk/README.md

Plan 9 assembly tooling, inside and outside Go

Warning: this is an experiment. gasm-devkit is under active development and is not stable. The version is 0.x.x: commands, flags, output formats and behaviour can change without warning at any time. A 1.0.0 release is light years away. Nothing in this document is a stability promise. For all of that, this is not a paper project: gasm is already in active use and is tested on real assembly work. Only amd64 is validated on real hardware; the other three architectures run under emulation (Validation status).

GAsm is Go's Plan 9 assembler, and Go ships it without tooling: there is no formatter, no linter and no debugger for .s files, and no assembler that works without a Go installation. Developers write assembly blind, validate it by benchmark, and debug it by print statement. gasm-devkit is the missing toolkit: a single, self-contained binary, gasm, that serves both purposes.

• Help develop Plan 9 assembly. Formatting, linting, disassembly, dynamic verification, a source-level debugger and a language server, for .s files in Go programs.
• Use Plan 9 assembly outside the Go toolchain. gasm asm encodes on its own and writes raw images or linkable ELF objects with DWARF5 debug sections, with no Go installation in the loop; the Go toolchain's own GOOBJ format, which go build consumes in place of the toolchain's output, needs the installed toolchain.

Why Plan 9 assembly

Plan 9 assembly is the quiet triumph of the field. One syntax across every architecture Go builds for: the same source-first operand order, the same four pseudo-registers, the same frame convention, whether the target is x86, ARM, RISC-V or LoongArch. Learn it once and you can read a kernel on any of them.

Compare the alternatives. Intel syntax and AT&T syntax disagree on the one question every instruction answers, which operand is the source and which is the destination, so half the world writes it one way, half the other, and every assembly programmer carries both in their head forever. GNU as settles the argument with directives that switch dialects mid-file (.intel_syntax noprefix), a percent sign on every register and a dollar on every immediate: punctuation that carries nothing the operand order did not already say. And the x86 family fragments again underneath: NASM is not MASM is not GAS, each with its own directive zoo and macro language, so every project picks a dialect and every reader learns a different one by accident.

Plan 9 assembly has none of it. Registers are bare names. Memory is one notation, offset(base), extended by an index and a scale when the instruction needs it. Arguments arrive named and offset-checked: x+0(FP) is the argument x, on every architecture, and go vet polices the offsets against the Go prototype.

AT&T (GNU as):   movq %rax, -16(%rbp)
Plan 9 (Go):     MOVQ AX, total-16(SP)

The same lines, but only one of them tells you what the number is for. The syntax is uppercase, regular and boring, which is the highest compliment a language for machine code can earn. gasm-devkit exists to give that syntax the tooling it deserves.

Features

• Front end. A hand-written lexer and an error-tolerant parser produce a typed AST with source positions; gasm tokens and gasm parse expose them directly.
• Formatter. gasm fmt canonicalises indentation, operand spacing, per-function mnemonic alignment and blank-line layout: gofmt for assembly, operating recursively on directories the way go fmt does. -l lists files whose formatting differs and -d prints a unified diff.
• Linter. gasm lint runs 18 conservative static checks, among them undefined-label, abi-argsize (declared argument area vs the // func signature), register-clobber (Go ABI register liveness over the control-flow graph), stack-imbalance, abi0-register-args and unencodable-instruction.
• Standalone assembler. gasm asm encodes all four architectures without the Go toolchain and writes raw images or linkable ELF objects (with DWARF5 debug sections) with no Go installation needed, or the Go toolchain's own GOOBJ format, which needs the installed toolchain and which go build consumes in place of the toolchain's output. Framed functions get the stack-split guard and the morestack block, byte-identical to the toolchain's, so split functions link too. The assembler preprocesses like the toolchain (#define, #include with -I, #ifdef), generates go_asm.h from the package's Go files, and carries PCALIGN, the LOCK/REP prefixes and the literal-data pseudo-ops.
• Disassembler. gasm dis lists a .s file's functions at their real offsets after assembling, or disassembles raw bytes from a file or stdin.
• Dynamic verification. gasm verify JIT-loads assembled functions into executable memory: smoke calls, ABI checks (sentinel registers, red-zone canary), differential fuzzing against the go tool asm build, and byte-for-byte ground-truth comparison of the machine code.
• Debugger. gasm debug is a source-level ptrace debugger with breakpoints (optionally conditional), hardware watchpoints, register and memory inspection, and headless script runs that report instruction and label coverage.
• Language server. gasm lsp serves completion, hover, document symbols, push and pull diagnostics, semantic-token highlighting, go-to-definition, find references, rename, formatting, inlay hints, code actions, signature help, document highlights, workspace symbol search, #include document links and folding ranges over stdio; definition, references and rename work across every open document.
• Comparators and audits. gasm diff compares the machine code of two assembly files byte-for-byte, gasm profile shows basic-block structure, gasm audit-instructions diffs the encoder against the installed toolchain, and gasm scaffold generates a differential test skeleton for a kernel.

Architecture support

Four architectures, the four that matter in practice:

Architecture	GOARCH	File suffix	Instructions recognised
AMD64	amd64	_amd64.s	1600 + common opcodes + traditional aliases
ARM64	arm64	_arm64.s	645 + common opcodes
RISC-V	riscv64	_riscv64.s	992 + common opcodes
LoongArch	loong64	_loong64.s	808 + common opcodes

"Common opcodes" are the instructions shared by every architecture (RET, JMP, NOP, CALL, TEXT, FUNCDATA, PCDATA, ...). AMD64 additionally carries the traditional conditional-jump spellings (JZ, JNZ, JA, JC, ...) that the assembler accepts as aliases. The tables are generated from the Go toolchain's own assembler source (just gen refreshes them), so every mnemonic the real assembler accepts is recognised; what the encoder can emit today is narrower, and a recognised but unencodable instruction is reported as an explicit error, never as a wrong byte.

The same measurement runs over GOROOT's whole assembly corpus: gasm audit-instructions --corpus reports 291 of 353 attemptable files (82.4 %) assembling for every target architecture today (files named for other Go ports are counted but never attempted), with the top failure reasons per architecture; the number moves with every release.

Validation status

Only amd64 is validated on real hardware. The other three architectures are validated under qemu-user emulation, because the project owns no arm64, riscv64 or loong64 machine, and emulation is the only substitute available for the hardware. The distinction matters and is stated rather than implied: everything below is a claim about what has actually been executed.

Layer	amd64	arm64, riscv64, loong64
Encoding: byte-for-byte against go tool asm	native hardware	native hardware (the toolchain cross-assembles any GOARCH on any host)
Execution: JIT calls, ABI checks, differential fuzzing	native hardware	qemu-user emulation
Debugger: ptrace tracing, breakpoints, watchpoints, coverage	native hardware	emulation cannot run ptrace; the layer compiles and its architecture-neutral units run under go test ./..., nothing more

Consequences, stated plainly. An emulator is a model of a CPU, not the CPU: instruction semantics are implemented in software and can differ from silicon in ways a test suite does not reveal. A kernel that passes under qemu-user is therefore not proven correct on real hardware, and a discrepancy found on real hardware is a defect in gasm, reported like any other. Encoding parity is the exception: the byte comparison against the toolchain runs on the host for every architecture, so no emulator stands between the claim and the evidence. The debugger is the weakest case: on the three emulated architectures its per-architecture ptrace code has been compiled and read, never executed. Its architecture-neutral units run under go test ./..., which the race workflow and a manual run perform; the default just test gate does not sweep ./debug/....

The documentation goal

The toolkit is the primary goal. The secondary one is documentation: a specification of the Plan 9 assembly language and of the GOOBJ object format that is 100 % complete, detailed enough to implement against, and written to a professional standard. These are the two subjects this project works with every day, and they are the two for which no usable documentation exists.

Go documents the language on a single page, "A Quick Guide to Go's Assembler", which carries no section for loong64, one of the four architectures gasm supports, and covers a fraction of what each assembler accepts. What exists beyond it lives as comments inside the toolchain's internal source: per-architecture reference manuals for arm64, ppc64, riscv64 and loong64, written for the toolchain's own maintainers rather than for an outside reader, and none at all for amd64. GOOBJ fares worst of all. The format that go build consumes has no specification anywhere: it is described by a comment in an internal package, it is not a stable interface, and it can change with any toolchain release.

The gap is therefore filled the only way it can be filled: by reverse engineering the toolchain itself, the same work the encoders already perform. Most of the documentation can come from nowhere else, and it is written as that knowledge is produced during development. It is verified the way the code is verified: an encoding documented here is one that differential tests against go tool asm confirm byte-for-byte, and a format field documented here is one the linker demonstrably reads. The work has begun: docs/GOOBJ.md specifies the object file format completely, and docs/asm/README.md opens the language reference with its common core. The per-architecture pages follow.

Direction

The plan, in the order it is being worked:

• Extended instruction support. Two layers. First, encoding coverage for every mnemonic the Go toolchain itself accepts, closed in order of how often real code needs each instruction; gasm audit-instructions measures the gap. Second, the larger work: an extended instruction set the toolchain does not know at all. The toolchain-derived tables stay generated and untouched; only the extended instructions are hand-maintained, with their own spellings and encoders, verified by execution (on real hardware for amd64, under emulation for the rest, per the validation status above) because the toolchain offers no ground truth to compare against. The gaps exist on every architecture, amd64 included.
• Full GOOBJ and ELF compilation. The destination is a complete, standalone compilation path: linkable ELF objects for consumers outside Go, and GOOBJ objects that go build links directly. Through GOOBJ, a Go program will be able to use machine instructions that the Go toolchain itself does not support; through ELF, Plan 9 assembly becomes usable outside Go entirely.
• Platforms: Linux and FreeBSD. Linux is supported today on all four architectures and is where the binary builds. FreeBSD follows: the JIT's executable-memory mapping and the ptrace debugger layer are the two pieces of porting work. Other unix systems may follow those two.
• Four architectures, no more. amd64, arm64, riscv64 and loong64. No others are planned.

Install

Prebuilt binaries for linux/amd64, linux/arm64, linux/riscv64 and linux/loong64 are on the releases page. From source (Go 1.27.1):

go install sourcedock.dev/petrbalvin/gasm-devkit/cmd/gasm@latest

Or from a repository checkout:

just install

The installed binary reports the version the toolchain recorded: the tag on a tagged checkout, a pseudo-version naming the commit below one.

Quick start

cat > hello_amd64.s <<'EOF'
#include "textflag.h"

// func add(a, b int) int
TEXT ·add(SB), NOSPLIT, $0-24
	MOVQ a+0(FP), AX
	ADDQ b+8(FP), AX
	MOVQ AX, ret+16(FP)
	RET
EOF

gasm lint hello_amd64.s                         # static checks
gasm asm -o hello.bin hello_amd64.s             # assemble to a raw image
gasm verify --call add --args a=2,b=3 hello_amd64.s   # JIT-call it with arguments

Usage

gasm fmt                                # reformat every .s below here, like go fmt
gasm fmt    -w kernel_amd64.s           # canonicalise one file in place
gasm fmt    -l *.s                      # list files whose formatting differs
gasm fmt    -d kernel_amd64.s           # print a unified diff instead
gasm lint   *.s                         # static checks
gasm asm --format elf -o k.o k.s        # assemble to a linkable ELF object
gasm asm --format goobj -p pkg/path -o k.o k.s   # Go object, consumed by go build
gasm dis k.s                            # assemble, then list each function
gasm dis -a amd64 - < dump.bin          # disassemble raw bytes from stdin
gasm verify --ground-truth k.s          # byte-for-byte vs go tool asm
gasm verify --fuzz k.s                  # differential fuzz vs the go tool asm build
gasm debug --func name k.s              # interactive debugger
gasm debug --func name --script cmds.txt --timeout 30s k.s   # headless run
gasm debug --func name --cover k.s      # instruction and label coverage
gasm diff a.s b.s                       # compare machine code byte-for-byte
gasm diff --map wideCopyAVX2=wideCopyAVX512 avx2.s avx512.s
gasm profile k.s                        # show basic-block structure
gasm audit-instructions                 # encoder vs go tool asm name diff
gasm scaffold differential k.s          # generate a differential test skeleton

Run gasm --help for the command overview and gasm <command> -h for a command's flags. docs/CLI.md is the full reference.

Editor integration

gasm lsp speaks the Language Server Protocol over standard input/output, so any LSP-capable editor can use it: point your editor's LSP client at the binary and associate it with .s files. Syntax highlighting is delivered as LSP semantic tokens, so no editor-specific grammar is required. The server infers the target architecture from the file-name suffix (_amd64.s / _arm64.s / _riscv64.s / _loong64.s).

Development

just build        # compile, zero errors and zero warnings
just test         # the suite, no cache, the 80 % coverage floor
just gates        # build, fmt-check, vet, test, race: the definition of done
just fmt          # gofmt the tree
just gen          # regenerate the instruction tables from the Go toolchain

See CONTRIBUTING.md for the development workflow and docs/DEVELOPMENT.md for setup details and every recipe.

Documentation

• docs/CLI.md: full command reference
• man pages: just install-man installs gasm(1) and one page per command except version, which is documented inside gasm(1) instead, into ~/.local/share/man (MANDIR overrides); just uninstall-man removes them
• docs/ARCHITECTURE.md: components and data flow
• docs/GOOBJ.md: the GOOBJ object file format specification
• docs/asm/: the Plan 9 assembly language reference
• docs/DEVELOPMENT.md: development setup and recipes
• CHANGELOG.md: release history

Licence

BSD-3-Clause; see LICENSE.

Copyright © 2026 Petr Balvín