172 lines
8.0 KiB
Markdown
172 lines
8.0 KiB
Markdown
# gasm-devkit
|
|
|
|
Developer tooling for **GAsm**, Go's built-in Plan 9 assembler.
|
|
|
|
Go ships an assembler but no tooling for it: there is no syntax highlighting,
|
|
no autocomplete, no linter, no static analyser, no formatter, no standalone
|
|
assembler and no debugger for `.s` files. 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 brings proper
|
|
developer tooling to Plan 9 assembly on amd64, arm64, riscv64 and loong64.
|
|
|
|
## 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 frame 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, linkable ELF objects (with DWARF5
|
|
debug sections) or the Go toolchain's own GOOBJ format, 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.
|
|
- **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 with label-level 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.
|
|
- **Complete instruction coverage.** The instruction tables are generated
|
|
from the Go toolchain's own assembler source, so the toolkit recognises
|
|
every mnemonic the real assembler accepts; `just gen` refreshes them.
|
|
|
|
### Architecture support
|
|
|
|
| Architecture | GOARCH | File suffix | Instructions recognised |
|
|
|--------------|-------------|--------------|---------------------------------------------|
|
|
| AMD64 | `amd64` | `_amd64.s` | 1600 + common opcodes + traditional aliases |
|
|
| ARM64 | `arm64` | `_arm64.s` | 538 + common opcodes |
|
|
| RISC-V | `riscv64` | `_riscv64.s` | 961 + common opcodes |
|
|
| LoongArch | `loong64` | `_loong64.s` | 799 + 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. Regenerating the tables is one
|
|
command (`just gen`) and requires only a Go installation; the committed output
|
|
has no runtime dependency on the toolchain.
|
|
|
|
## Install
|
|
|
|
Prebuilt binaries for linux/amd64, linux/arm64, linux/riscv64 and
|
|
linux/loong64 are on the
|
|
[releases page](https://sourcedock.dev/petrbalvin/gasm-devkit/releases).
|
|
From source (Go 1.27 or later):
|
|
|
|
```sh
|
|
go install sourcedock.dev/petrbalvin/gasm-devkit/cmd/gasm@latest
|
|
```
|
|
|
|
Or from a repository checkout:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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 # which labels did execution reach?
|
|
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](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
|
|
|
|
```sh
|
|
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](CONTRIBUTING.md) for the development workflow and
|
|
[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for setup details and every
|
|
recipe.
|
|
|
|
## Documentation
|
|
|
|
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): components and data flow
|
|
- [docs/CLI.md](docs/CLI.md): full command reference
|
|
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md): development setup and recipes
|
|
- [docs/DECISIONS.md](docs/DECISIONS.md): deferred design decisions
|
|
- [CHANGELOG.md](CHANGELOG.md): release history
|
|
|
|
## Licence
|
|
|
|
BSD-3-Clause; see [LICENSE](LICENSE).
|
|
|
|
Copyright © 2026 [Petr Balvín](https://petrbalvin.org)
|