gasm-sdk/docs/CLI.md

CLI Reference

Repository: sourcedock.dev/petrbalvin/gasm-devkit

gasm is a single binary with subcommands. Run gasm --help for an overview, or gasm <command> -h for a command's usage and flags.

Global Flags

Flag	Description
-h, --help	Show help
-V, --version	Print the version

gasm tokens <file>

Print the lexical token stream of FILE: position, token kind, and text, one token per line. FILE may be - to read standard input.

gasm parse <file>

Parse FILE and report syntax errors on stderr. On success, prints how many declarations and TEXT functions the file contains.

gasm fmt [-w|-l|-d] [path...]

Canonicalise the formatting of Plan 9 assembly sources: indentation, operand spacing, per-function mnemonic alignment, and blank-line layout.

Flag	Description
-w	Write result to the source file (default: print to stdout)
-l	List files whose formatting differs, one per line; write nothing
-d	Print a unified diff of the canonical formatting instead

With no arguments, or with a directory argument, every .s file below it is reformatted in place and the names of changed files are listed (go fmt style). . and _ directories are skipped.

gasm lint <file...>

Run static checks and print diagnostics as file:line:col: severity: message [code]. Exit status is non-zero when an error-severity diagnostic is found.

Flag	Description
-disable	Comma-separated rule codes to disable

Rules: unknown-instruction, operand-count, undefined-label, duplicate-label, missing-ret, missing-textflag-include, abi-argsize, unreachable-code, register-clobber, funcdata-pcdata, unused-label, invalid-textflag, stack-imbalance, register-width-mismatch, abi0-register-args, nonportable-register-name and unencodable-instruction.

gasm asm [--format raw|elf|goobj] [-p pkg] [-o out] <file>

Assemble FILE to machine code (amd64, arm64, riscv64, loong64).

Flag	Description
--format	Output format: raw (default), elf, goobj
-p	Package path (required for --format goobj)
-o	Write output to file (default: hex dump to stdout)

gasm dis [-a arch] <file>

Disassemble machine code to instruction text (via golang.org/x/arch).

With a .s file, the file is assembled first and the listing follows the real layout: one block per TEXT function, local labels printed at their offsets. The architecture comes from the file name suffix, or from -a. With any other file, or - for standard input, the bytes are disassembled linearly and -a selects the architecture (amd64, arm64, riscv64 or loong64).

Flag	Description
-a	Architecture for raw input without a _arch.s name

gasm verify [flags] <file.s>

Assemble FILE, map it into executable memory, and run dynamic checks.

Flag	Description
--ground-truth	Compare machine code byte-for-byte against go tool asm
--fuzz	Differential fuzz: JIT both gasm and go-tool-asm, compare outputs
-n	Fuzz iterations per function (default: 1000)
--abi	Run ABI-checking calls (sentinel registers + red zone)
--abi-n	Number of ABI check iterations with varied inputs (default: 100)
--profile	List basic-block structure per function
--smoke	Call each NOSPLIT function with zeroed args
--call <func>	Invoke a single function with --buf instead of the sweeps
--buf <spec>	Buffer spec for --call: name:size:pattern[,name:size:pattern]
--args <spec>	Scalar args for --call: name=value[,name=value] (decimal or 0x hex)
--repeat <n>	Number of times to repeat a --call invocation (default: 1)
--save-corpus <dir>	With --fuzz: write each failing input to DIR as replayable JSON
--replay <dir>	Re-run saved corpus entries (JSON in DIR), one child process per entry

The --fuzz mode runs each function in a subprocess; a partial function (e.g. a decoder that faults on malformed input) is reported as CRASH without killing the parent. Use --call with --buf to invoke partial functions with valid data instead.

The --call mode parses the // func signature, allocates the requested buffers (zero, ones, seq, or a hex blob), builds the ABI0 argument block with buffer pointers/lengths/capacities at the matching parameter offsets, and prints the arg block before and after the call, showing return values and any output written to the buffers. Scalar parameters are supplied with --args (decimal, or 0x hex) at their ABI0 offsets.

The --save-corpus mode records the logical arguments (buffer contents and scalars, not raw pointers) of every failing fuzz input as JSON. --replay rebuilds a live argument block from each entry and calls it in its own child process, reporting OK, CRASH (reproduced) or FAIL per entry and exiting non-zero when any entry fails.

gasm debug [--func <name>] [--buf spec] [--script file] <file.s>

Interactive debugger for JIT-assembled functions (amd64, arm64, riscv64, loong64). Requires a compiled binary on $PATH (not go run).

Flag	Description
--func	Function to debug (required)
--buf	Buffer spec: name:size:pattern[,name:size:pattern]
--args <file>	File containing the ABI0 argument block
--script <file>	Run REPL commands from a file (one per line) and exit; - reads stdin
--timeout <dur>	Kill the debuggee after this duration (e.g. 30s); for headless --script runs
--cover	Run to completion with a breakpoint on every instruction; report which executed, how often, and which labels were reached

REPL commands:

Command	Description
break <label|addr> [if <reg> <op> <val>]	Set a breakpoint, optionally conditional
delete <label|addr>	Remove a breakpoint
info break	List all breakpoints
step [n], s	Single-step n instructions
next, n	Step over CALL
finish, fin	Run until the function returns
continue, c	Run until breakpoint, watchpoint or exit
disas [n], u	Disassemble n instructions at PC
regs	Print general-purpose + vector/FP registers
where	Show source line and nearest label at PC
stack	Show stack near RSP (return address + ABI0 args)
bt, backtrace	Backtrace (current frame + return address)
x [addr] [len]	Hex-dump memory
w <addr> <val...>	Write bytes to memory
set <reg> <value>	Set a register
watch <addr> [r|w] [size]	Set a hardware watchpoint (write by default)
unwatch [<slot>]	Clear one or all watchpoints
labels, l	List function labels and offsets
help, h, ?	Show command help
quit, q	Kill the debuggee and exit

gasm diff [--map old=new,...] <file1.s> <file2.s>

Compare the machine code produced by assembling two files. Shows which functions differ and the first few differing bytes. Useful for verifying that two implementations produce identical code, or for tracking encoding changes between Go assembler versions.

Flag	Description
--map	Comma-separated old=new pairs to match functions with different names

Without --map, functions are paired by exact name. With --map, a function named old in the first file is compared against the function named new in the second file (e.g. --map wideCopyAVX2=wideCopyAVX512 pairs AVX2 and AVX-512 variants regardless of suffix).

gasm profile <file.s>

Show the basic-block structure of functions in an assembly file. Lists each function's labels, their offsets, and the block boundaries. This is the static structure; for runtime execution counts, use gasm verify --fuzz which exercises the code paths.

gasm audit-instructions [amd64|arm64|riscv64|loong64]

Compare the gasm encoder for the given architecture (default amd64) against the installed go tool asm and print the diff: superset encodings (gasm-only spellings, shippable via gasm asm --format goobj), known-but-unencodable names (the encoder backlog) and go-only names (feature gaps). The Go side is probed black-box with a battery of operand shapes per mnemonic, so the audit tracks whatever toolchain go env GOROOT provides. On non-amd64 architectures the backlog is an over-approximation: a name counts as encodable only when a probe shape assembles cleanly, so a name whose real forms the battery misses lands in the backlog.

gasm scaffold differential <file.s>

Print a differential test skeleton for every // func signature in FILE. The generated test seeds random states, drives the kernel and a portable reference (<name>Portable), and compares outputs byte-for-byte. Write the reference bodies, place the file in the kernel's package, and run it in CI.

gasm lsp

Run the language server over standard input/output (JSON-RPC 2.0 with Content-Length framing). Point an LSP-capable editor at the binary and associate it with .s files. The target architecture is inferred from the file-name suffix (_amd64.s, _arm64.s, _riscv64.s, _loong64.s).

Provides: completion, hover, document symbols, push and pull diagnostics, semantic tokens, go-to-definition, find references, rename, document formatting, inlay hints, code actions, signature help, document highlights, workspace symbol search, #include document links, and folding ranges for function bodies.