159 lines
6.2 KiB
Markdown
159 lines
6.2 KiB
Markdown
# CLI Reference
|
|
|
|
Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://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] [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) |
|
|
|
|
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`.
|
|
|
|
## `gasm asm [--format raw|elf|goobj] [-p pkg] [-o out] <file>`
|
|
|
|
Assemble FILE (amd64) to machine code.
|
|
|
|
| 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 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]` |
|
|
| `--repeat <n>` | Number of times to repeat a `--call` invocation (default: 1) |
|
|
|
|
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.
|
|
|
|
## `gasm debug --func <name> [--buf spec] <file.s>`
|
|
|
|
Interactive debugger for JIT-assembled amd64 functions. 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]` |
|
|
|
|
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 + YMM/XMM vector 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 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, diagnostics, and
|
|
semantic-token highlighting.
|