petrbalvin/gasm-sdk
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 36 Wiki Activity

docs: sync README, CHANGELOG and docs with the current state

Browse Source
This commit is contained in:
petrbalvin
2026-08-30 10:44:18 +02:00
parent 6c1c8d9d96
commit 56f8babbce
7 changed files with 407 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CLI.md
+35 -8
View File
@@ -48,7 +48,9 @@ an error-severity diagnostic is found.
Rules: `unknown-instruction`, `operand-count`, `undefined-label`,
`duplicate-label`, `missing-ret`, `missing-textflag-include`,
`abi-argsize`, `unreachable-code`, `register-clobber`,
`funcdata-pcdata`.
`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>`
@@ -75,6 +77,7 @@ Assemble FILE, map it into executable memory, and run dynamic checks.
| `--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) |
The `--fuzz` mode runs each function in a subprocess; a partial function
@@ -85,18 +88,23 @@ 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.
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.
## `gasm debug --func <name> [--buf spec] <file.s>`
## `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`).
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 breakpoints on every label and report which blocks executed |
REPL commands:
@@ -146,6 +154,23 @@ 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`
Compare the gasm amd64 encoder 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.
## `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
@@ -154,5 +179,7 @@ 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.
Provides: completion, hover, document symbols, diagnostics, semantic
tokens, go-to-definition, find references, rename, document formatting,
inlay hints, code actions, signature help, document highlights, and
workspace symbol search.