docs: add the full documentation surface — AGENTS, CONTRIBUTING, cli and development references
Assisted-by: DeepSeek V4 Flash
This commit is contained in:
@@ -2,6 +2,8 @@
|
||||
|
||||
How gasm-devkit is put together and why.
|
||||
|
||||
Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
|
||||
|
||||
## Design goals
|
||||
|
||||
1. **A real AST, not a grammar hack.** The linter, analyser, assembler and
|
||||
@@ -309,6 +311,18 @@ The `gasm verify` CLI subcommand exposes this: it loads a file, reports the
|
||||
available functions and (with `-smoke`) calls each NOSPLIT function with zeroed
|
||||
arguments to confirm the trampoline round-trips.
|
||||
|
||||
### `debug`
|
||||
|
||||
The interactive debugger (Phase 4, linux/amd64). It launches the target
|
||||
function in a child process that maps the JIT code, calls
|
||||
`PTRACE_TRACEME`, and stops; the parent attaches via ptrace and controls
|
||||
execution. Breakpoints are patched as INT3 bytes through `/proc/pid/mem`
|
||||
(PTRACE_PEEKTEXT is unreliable with Go's multi-threaded runtime).
|
||||
The child pins its goroutine to the OS thread with `runtime.LockOSThread`
|
||||
so the traced thread is the one executing JIT code. The REPL provides
|
||||
single-step, register inspection, label resolution, and breakpoint
|
||||
management.
|
||||
|
||||
## Extension points
|
||||
|
||||
- **New architecture:** add an entry to the generator in `_gen`, run
|
||||
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# 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|macho|goobj] [-p pkg] [-o out] <file>`
|
||||
|
||||
Assemble FILE (amd64) to machine code.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--format` | Output format: `raw` (default), `elf`, `macho`, `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) |
|
||||
| `--profile` | List basic-block structure per function |
|
||||
| `--smoke` | Call each NOSPLIT function with zeroed args |
|
||||
|
||||
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 `--ground-truth` for decoders.
|
||||
|
||||
## `gasm debug --func <name> <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) |
|
||||
|
||||
REPL commands:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `break <label\|addr>` | Set a breakpoint |
|
||||
| `step [n]` | Single-step n instructions |
|
||||
| `continue` | Run until next breakpoint or exit |
|
||||
| `regs` | Print general-purpose registers |
|
||||
| `x [addr] [len]` | Hex-dump memory |
|
||||
| `labels` | List function labels and offsets |
|
||||
| `quit` | Kill the debuggee and exit |
|
||||
|
||||
## `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.
|
||||
@@ -0,0 +1,108 @@
|
||||
# Development Guide
|
||||
|
||||
Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Go** 1.26+ with `toolchain go1.26.5`
|
||||
- **just** — the command runner; every task below is a just recipe
|
||||
- No external dependencies beyond the Go toolchain
|
||||
|
||||
## Quick Start
|
||||
|
||||
```sh
|
||||
git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
|
||||
cd gasm-devkit
|
||||
just install # go mod download
|
||||
just build # go vet + gofmt — must pass with zero output
|
||||
just test # full suite, race detector, 80 % coverage gate
|
||||
```
|
||||
|
||||
## Just Recipes
|
||||
|
||||
### `just build`
|
||||
|
||||
Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
|
||||
the minimum bar before any commit.
|
||||
|
||||
### `just test`
|
||||
|
||||
```sh
|
||||
go test -race -count=1 -coverprofile=coverage.out ./...
|
||||
```
|
||||
|
||||
Plus an `awk` gate that fails if total coverage is below 80 %.
|
||||
|
||||
### `just fmt`
|
||||
|
||||
```sh
|
||||
gofmt -w .
|
||||
```
|
||||
|
||||
Run after editing any Go source. The output must be idempotent.
|
||||
|
||||
### `just run -- <args>`
|
||||
|
||||
Runs the CLI via `go run` with the version string stamped:
|
||||
|
||||
```sh
|
||||
just run -- lint kernel_amd64.s
|
||||
just run -- fmt -w kernel_amd64.s
|
||||
just run -- verify --ground-truth kernel_amd64.s
|
||||
```
|
||||
|
||||
### `just install-bin`
|
||||
|
||||
Installs the `gasm` binary into `$GOBIN` with the release version
|
||||
embedded via `-ldflags "-X main.version=..."`.
|
||||
|
||||
### `just gen`
|
||||
|
||||
Regenerates the architecture instruction tables in `arch/` by parsing
|
||||
the Go toolchain's own assembler source
|
||||
(`$GOROOT/src/cmd/internal/obj/<arch>/anames.go`). Requires a Go
|
||||
installation. Output is committed — no runtime dependency on the
|
||||
toolchain.
|
||||
|
||||
### `just uninstall`
|
||||
|
||||
Removes `coverage.out`, the `gasm` binary, and `*.test` artefacts.
|
||||
|
||||
## Running Individual Tests
|
||||
|
||||
```sh
|
||||
go test -run TestVexGroundTruth ./asm/
|
||||
go test -run TestDifferentialLZ4Fuzz ./verify/
|
||||
go test -run TestFLACDecorrelate ./verify/
|
||||
go test -run TestGOObjectLinkAndRun ./asm/
|
||||
```
|
||||
|
||||
## Debugger Note
|
||||
|
||||
`gasm debug` spawns a child process from the binary on `$PATH`. It does
|
||||
not work with `go run` — install first:
|
||||
|
||||
```sh
|
||||
just install-bin
|
||||
gasm debug --func decodeBlockAVX2 path/to/kernel_amd64.s
|
||||
```
|
||||
|
||||
## Project Layout
|
||||
|
||||
```
|
||||
cmd/gasm/ CLI entry point (subcommands)
|
||||
token/ Lexical token kinds and positions
|
||||
lexer/ Hand-written scanner
|
||||
ast/ Abstract syntax tree
|
||||
parser/ Line-oriented parser
|
||||
arch/ Register and instruction tables (generated)
|
||||
lint/ Static analysis rules
|
||||
format/ Canonical formatter
|
||||
lsp/ Language Server Protocol server
|
||||
asm/ Standalone assembler, encoder, object emitters
|
||||
verify/ JIT execution, differential testing, ABI checks
|
||||
debug/ Interactive ptrace debugger (linux/amd64)
|
||||
_gen/ Instruction table generator
|
||||
testdata/ Test fixtures
|
||||
docs/ Architecture, development, CLI reference
|
||||
```
|
||||
Reference in New Issue
Block a user