chore: prepare release v0.32.0

Assisted-by: GLM 5.3 Flash

.gitea/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
 
       - uses: actions/setup-go@v6
         with:
-          go-version: "1.26"
+          go-version: "1.27"
 
       - name: Download dependencies
         run: go mod download

.gitea/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
 
       - uses: actions/setup-go@v6
         with:
-          go-version: "1.26"
+          go-version: "1.27"
 
       - name: Download dependencies
         run: go mod download
@@ -41,7 +41,7 @@ jobs:
 
       - uses: actions/setup-go@v6
         with:
-          go-version: "1.26"
+          go-version: "1.27"
 
       - name: Download dependencies
         run: go mod download
@@ -84,7 +84,7 @@ jobs:
 
       - uses: actions/setup-go@v6
         with:
-          go-version: "1.26"
+          go-version: "1.27"
 
       - name: Download dependencies
         run: go mod download

.gitignore

@@ -1,3 +1,8 @@
+# Metadata (always first, per repo convention)
+.idea/
+.zcode/
+.mimocode/
+
 # Binaries
 /gasm
 /bin/
@@ -7,9 +12,13 @@
 coverage.out
 *.test
 
-# Editor detritus
-*.swp
-.DS_Store
+# Crash dumps
+core
+core.*
+*.core
 
 # Scratch / temporary work
 _scratch/
+
+# ZCode workspace
+.zcode

AGENTS.md

@@ -1,119 +0,0 @@
-# AGENTS.md — gasm-devkit
-
-Repository rules for AI agents and contributors. Read before modifying any
-code in this repository.
-
-## AI Contribution Policy
-
-AI agents may assist with code, documentation, tests, and review in this
-repository. All AI-assisted changes must:
-
-- Follow the code style and conventions in this file.
-- Include the trailer `Assisted-by: <model-name>` in every commit message.
-- Not commit directly to `main` — work on `development`.
-- Pass the full Definition of Done before any commit.
-
-## Workflow
-
-- **Branching.** `development` is the working branch. `main` is
-  release-only: merge from `development`, then tag. Never commit directly
-  to `main`.
-- **Release procedure.**
-  1. Bump `version` in `justfile` and `cmd/gasm/main.go`.
-  2. Update `CHANGELOG.md` with a new `## [X.Y.Z] — YYYY-MM-DD` section.
-  3. Update `README.md` and `docs/ARCHITECTURE.md` if user-visible
-     behaviour changed.
-  4. Run the Definition of Done (below).
-  5. Commit on `development`.
-  6. `git checkout main && git merge --ff-only development`.
-  7. `git tag vX.Y.Z`.
-  8. `git checkout development`.
-  9. `GOBIN=~/.local/bin just install-bin`.
-
-## Commit Messages
-
-Conventional Commits, subject line only, imperative mood, lowercase after
-the colon:
-
-```
-feat(asm): add EVEX gather and scatter with VSIB addressing
-```
-
-Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
-`chore`, `ci`, `build`, `revert`.
-
-Every commit ends with exactly one trailer, using the model that
-assisted with the change:
-
-```
-Assisted-by: <model-name>
-```
-
-Replace `<model-name>` with the actual model (e.g. `DeepSeek V4 Pro`).
-
-No body, no footers, no trailing period on the subject.
-
-## Code Style
-
-Language: Go 1.26 (`toolchain go1.26.5`).
-
-### Formatter
-
-`gofmt` — zero diff. Run `just fmt` before committing.
-
-### Linter
-
-`go vet` — zero warnings. Run `just build` before committing.
-
-### Tests
-
-`go test -race -count=1 ./...` — all green, coverage ≥ 80 % (hard gate,
-enforced by `just test`).
-
-### Dependencies
-
-- **Production code:** standard library only. No third-party imports in
-  shipped code.
-- **Test code:** `golang.org/x/arch` is the sole test dependency (decode
-  oracle for round-trip validation). It is never linked into the binary.
-- **No cgo, no C, no external toolchains, no JavaScript.**
-
-### Error Handling
-
-Explicit `if err != nil`. Wrap with `fmt.Errorf("context: %w", err)`.
-No panics outside `main`. The one exception: the JIT trampoline's
-`recover`-guarded decoder hot path, which converts bounds panics to
-sentinel errors.
-
-### Assembly
-
-Plan 9 syntax (Go's assembler dialect). Hand-written — no code generators
-except `_gen/gen.go` for instruction tables (which parses the Go
-toolchain source). Every instruction table is committed; no runtime
-dependency on the Go toolchain.
-
-### File Naming
-
-- `_amd64.s`, `_arm64.s`, `_riscv64.s`, `_loong64.s` for
-  architecture-specific assembly.
-- `_linux_amd64.go` for platform-specific Go files.
-- `_test.go` suffix for test files.
-
-## Definition of Done
-
-A task is not complete until all of these pass:
-
-1. `just build` — `go vet` + `gofmt` check, zero errors, zero warnings.
-2. `just test` — full suite with `-race`, coverage ≥ 80 %.
-3. `just fmt` — produces no diff.
-4. Diagnostics — zero warnings across the project.
-5. Non-trivial changes reviewed.
-
-## Licence
-
-BSD-3-Clause. Every source file carries the SPDX header:
-
-```
-// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
-// SPDX-License-Identifier: BSD-3-Clause
-```

CHANGELOG.md

@@ -7,7 +7,195 @@ and this project adheres to [Conventional Commits](https://www.conventionalcommi
 
 ## [development]
 
-Unreleased changes on the `development` branch.
+### Added
+
+-
+
+## [0.32.0] — 2026-08-31
+
+### Added
+
+- **Multi-architecture debugger.**  `gasm debug` carries
+  per-architecture ptrace register access, disassemblers
+  (`golang.org/x/arch`), register display, FP register views and
+  stop-info handlers for arm64, riscv64 and loong64, and the REPL is
+  arch-neutral.  Sessions are runtime-validated on amd64; the other
+  hosts execute through the now-working JIT trampolines, but their
+  ptrace loops have not seen hardware yet.
+- **Headless debugging.**  `gasm debug --script` runs REPL commands from a
+  file (or stdin) and exits; `--timeout` kills the debuggee when a run
+  hangs, with the watchdog armed before the ptrace attach.
+- **Conditional breakpoints.**  `break <label> if <reg> <op> <val>` now also
+  compares two registers (`break loop if RAX > RBX`), not only a register
+  against an immediate.
+- **Instruction-level coverage.**  `gasm debug --cover` now sets a
+  breakpoint on every instruction (walked by disassembly length), counts
+  the hits per instruction and reports the executed instructions with
+  their hit counts, with the label coverage derived from the same run.
+  Expect the run to slow to ptrace speed.
+- **FP register display on riscv64 and loong64.**  The debugger `regs`
+  command shows the 32 FP registers plus fcsr (and fcc on loong64) via
+  `PTRACE_GETREGSET`.
+- **JIT execution trampolines.**  `verify.Call` now works on all four
+  architectures via hand-written assembly trampolines
+  (`trampoline_{arm64,riscv64,loong64}.s`) that save the Go stack, switch
+  to a prepared stack, and branch to the JIT function.
+- **ABI checks on arm64, riscv64 and loong64.**  `gasm verify -abi` and
+  the ABI half of `-fuzz` now cover the non-amd64 architectures via
+  per-architecture checked trampolines: sentinels planted in the
+  registers the Go ABI fixes across calls (arm64 `R29`/`R28`, riscv64
+  `X27`, loong64 `R22`; amd64 keeps `BP`/`R14`) are verified on return
+  and the saved registers restored before Go code resumes, with the
+  below-SP canary on every architecture.  loong64 kernels are verified
+  through the toolchain-comparison path only, pending hardware
+  validation of their trampoline.  `verify.Load` assembles each file
+  with the encoder its name suffix calls for.  The `ABIReport` fields
+  are the architecture-neutral `FPClobbered` and `GClobbered`.
+- **Hardware watchpoints on all architectures.**  arm64 uses DBGWVR/DBGWCR
+  via `PTRACE_SETREGSET` with `NT_ARM_HW_BREAK`; riscv64 and loong64 use
+  `PTRACE_POKEUSER` to access trigger/debug registers.
+- **Cross-package GOOBJ resolution on arm64 and loong64.**
+  `AssembleFileARM64` and `AssembleFileLOONG64` mark external
+  relocations and populate `img.Externals`, so GOOBJ output from those
+  architectures resolves cross-package symbols like amd64 and riscv64
+  already do.
+- **`gasm verify --args`.**  Scalar arguments (`name=value`, decimal or
+  `0x` hex) can now be supplied to a `--call` invocation alongside `--buf`
+  buffers, closing the gap where only buffers could be supplied.
+- **Fuzz corpus save and replay.**  `gasm verify --fuzz --save-corpus dir`
+  records every input that crashes or mismatches as replayable JSON (buffer
+  contents and scalars, not raw pointers), and `gasm verify --replay dir`
+  re-runs the saved entries against the kernel in isolated child processes,
+  reporting whether each one reproduces.
+- **`gasm audit-instructions`.**  Black-box diff of a gasm encoder
+  against the installed `go tool asm`, for amd64, arm64, riscv64 and
+  loong64 (`gasm audit-instructions <arch>`): superset encodings
+  (gasm-only, shippable via `gasm asm --format goobj`),
+  known-but-unencodable names (the backlog) and go-only names
+  (feature gaps).
+- **`gasm scaffold differential`.**  Prints a differential test skeleton
+  for every `// func` signature in a kernel file: random seed states, the
+  kernel call and a portable reference (`<name>Portable`), compared
+  byte-for-byte.
+- **LSP: find references** (`textDocument/references`).
+- **LSP: rename symbol** (`textDocument/rename`).
+- **LSP: document formatting** (`textDocument/formatting`) using the
+  `format` package for canonical gofmt-style output.
+- **LSP: inlay hints** (`textDocument/inlayHint`): frame size hints after
+  the TEXT directive's argument area.
+- **LSP: workspace symbol search** (`workspace/symbol`): substring search
+  over the TEXT functions and GLOBL/DATA symbols of every open document.
+- **LSP: code actions.**  Quick fixes for `missing-ret` (insert the RET)
+  and `unused-label` (remove the label) diagnostics.
+- **LSP: signature help** (`textDocument/signatureHelp`): the callee's
+  `// func` signature while the cursor is on a `CALL`.
+- **LSP: document highlights**: every reference to the function or label
+  under the cursor is highlighted.
+- **LSP: pull diagnostics** (`textDocument/diagnostic`), **#include
+  document links** (resolved against the document directory, then
+  `$GOROOT/pkg/include`, so `textflag.h` opens) and **folding ranges**
+  (one collapsible region per TEXT function body).
+- **Lint: `unused-label` rule.**  Flags labels that are defined but never
+  referenced by any jump (Hint severity).
+- **Lint: `invalid-textflag` rule.**  Flags TEXT/GLOBL flags not in the
+  known set from `textflag.h` (Warning severity).
+- **Lint: `stack-imbalance` rule.**  Tracks SP changes and flags if the
+  net delta at RET does not match the declared frame size.
+- **Lint: `register-width-mismatch` rule.**  Flags amd64 operands whose
+  register width does not match the width the mnemonic suffix prescribes
+  (for example a 32-bit register in a `MOVQ`).
+- **Lint: `abi0-register-args` rule.**  Flags kernels whose `// func`
+  parameters are never read from the FP frame (for example arguments read
+  from registers instead), which pass every test today and break on a
+  toolchain upgrade.  Shipped with the Go assembler's operand-width model.
+- **Lint: `nonportable-register-name` rule.**  Flags the `RAX`/`EAX`-style
+  register aliases gasm accepts but `go tool asm` rejects, so files using
+  them only link through the gasm GOOBJ path.
+- **Lint: `unencodable-instruction` rule.**  Flags mnemonics the
+  architecture table knows but the encoder cannot yet emit, at edit time
+  instead of at assembly time.
+- **Lint: `reserved-register-write` rule.**  Flags writes to arm64 R18,
+  the platform-reserved register the ABI checks cannot observe at runtime
+  and the Go assembler cannot even spell.  Reads and macro-using files
+  are exempt.
+- **DWARF5 debug sections in ELF output.**  All four ELF emitters now emit
+  `.debug_abbrev`, `.debug_info`, `.debug_line`, and `.debug_line_str`
+  sections, enabling `addr2line` and GDB/LLDB source-level debugging, and
+  the amd64 emitter adds a `.debug_frame` CFI section for stack unwinding.
+- **amd64: legacy SSE and conversion coverage.**  The encoder now handles
+  the legacy (non-VEX) SSE packed binaries and immediate shuffles, the
+  legacy SSE integer instructions and `BSWAP`, the scalar and packed
+  double conversions (`CVTSS2SD`, `CVTSD2SS`, `CVTPS2PD`, `CVTPD2PS`) and
+  the prefetch hints.
+- **amd64: `VPCMP` and the full opmask set.**  The EVEX compare with an
+  opmask destination and the remaining opmask-register instructions are
+  encoded, byte for byte against the Go assembler.
+
+### Changed
+
+- **Parallel verify sweeps.**  The `-smoke` and `-abi` per-function checks
+  now run in parallel instead of sequentially.
+
+### Fixed
+
+- **Reliable ptrace sessions.**  The debugger no longer mistakes runtime
+  signal-delivery-stops (a Go tracee reports SIGURG preemption to the
+  tracer) for its launch barrier, runs every ptrace request on the thread
+  that forked the debuggee (requests from another thread fail with
+  ESRCH), prefers the debuggee's reported code base over an RWX scan, and
+  single-steps over a hit breakpoint so resuming cannot re-trap on the
+  same instruction.  A ptrace integration test
+  (`debug/ptrace_integration_test.go`) drives a real session end to end.
+- **arm64 BL relocation.**  `BL sym(SB)` now records a `RelArm64Branch`
+  relocation instead of emitting a bare instruction with no relocation.
+- **GOOBJ R_ADDRARM64 constant.**  Corrected from 9 (`R_CALLARM64`) to 3
+  (`R_ADDRARM64`).
+- **Subprocess-isolated smoke and ABI sweeps.**  A function that faults
+  during the `-smoke` or `-abi` sweep is reported without killing the
+  parent; each sweep runs in a child process.
+- **`BSF`, `BSR` and `POPCNT` encodings.**  Corrected to the bytes
+  `go tool asm` emits.
+- **`MOVQ` immediates.**  Compressed to the toolchain's imm32 forms.
+- **Frame adjustments of 128 to 255 bytes.**  Now use the imm8 `ADDQ`
+  stack adjustment.
+- **amd64 encoding parity.**  A broad pass aligned the remaining encoder
+  outputs and operand strictness with `go tool asm`.
+- **asm help text.**  Updated to list arm64 as a supported architecture.
+
+## [0.31.1] — 2026-08-20
+
+### Fixed
+
+- **Version stamp.** The v0.31.0 release binary reported itself as `0.30.0`
+  because the version variables in `justfile` and `cmd/gasm/main.go` were not
+  bumped during the release commit.
+
+## [0.31.0] — 2026-08-20
+
+The arm64 encoder (Phase 5 — complete) ships with ELF64 and GOOBJ emission,
+verified byte-for-byte against `GOARCH=arm64 go tool asm` and linked into a
+real `go build`.  The encoder covers the full integer instruction set, FP
+arithmetic, conditional select, CRC32, and the MOV pseudo-instruction with
+bitmask immediate encoding.  The project now requires Go 1.27.
+
+### Added
+
+- **arm64 encoder (Phase 5 — complete).**  `gasm asm` can now assemble `_arm64.s`
+  files: the AArch64 integer instruction set with the MOV pseudo-instruction and
+  its immediate-constant expansions (MOVZ/MOVN/MOVK for wide immediates, ORR with
+  logical bitmask encoding for values like `$1`), data-processing (shifted
+  register and immediate forms), load/store (scaled unsigned and unscaled9-bit
+  immediate), conditional and unconditional branches, FP/SP frame mapping,
+  SB/global symbol references (ADRP+ADD pairs with `R_ADDRARM64` relocations),
+  jump chain folding, and ELF64 emission (`gasm asm --format elf`).  Ground-truth
+  verification against `GOARCH=arm64 go tool asm` matches byte-for-byte.  Phase 5
+  (the other architectures — RISC-V, LoongArch, arm64) is now complete.
+
+### Changed
+
+- **Go 1.27 required.**  The project now requires Go 1.27 (`toolchain go1.27.0`).
+  The `R_DWTXTADDR_U4` relocation type is detected at runtime for backward
+  compatibility.
 
 ## [0.30.0] — 2026-08-13
 
@@ -166,20 +354,13 @@ new CLI commands. A signature-parser fix corrects grouped Go parameters.
   prevent GC from collecting heap objects whose addresses were passed to JIT
   code via `unsafe.Pointer`; all verify tests pass 100/100 under `-race`.
 
-### Cleaned up
+### Changed
 
 - **Removed external kernel test dependencies** — the verify test suite no
   longer references production kernels from the separate go-libraries project.
   The remaining test suite uses only `testdata/verify/*.s` kernels, which are
   part of this repository.  Coverage is identical locally and in CI (80.3 %).
 
-### Verified
-
-- `gasm diff` detects byte-level differences; `--map` pairs differently-named
-  functions for comparison.
-- `gasm verify --call` invokes functions with user-supplied buffers; the arg
-  block is printed before and after the call, showing return values.
-- LSP go-to-definition resolves labels across functions and files.
 
 ## [0.28.0] — 2026-08-03
 
@@ -211,10 +392,6 @@ ground-truth verification against `GOARCH=riscv64 go tool asm`.
 - RVC: C.LDSP/C.SDSP/FLDSP/FSDSP immediate encoding now matches Go toolchain
   (bit-interleaved format).
 
-### Verified
-
-- 118 RISC-V tests, asm coverage 83.3%.
-- Ground-truth: C.LDSP, C.SDSP, C.FLDSP, C.FSDSP byte-exact vs Go toolchain.
 
 ## [0.27.0] — 2026-08-01
 
@@ -247,7 +424,7 @@ area bit-for-bit.
   analyze, autocorr) pass; partial functions (decoders that fault on malformed
   input) should use `--ground-truth` instead.
 
-### Known limitation
+### Fixed
 
 `--fuzz` crashes the process for partial functions (e.g. LZ4 decoders) whose
 over-copy paths read past the buffer on random garbage input.  Subprocess
@@ -310,11 +487,6 @@ The remaining go-flac encoder kernels join the differential suite.
   frames: the four zigzag-fold entropy sums compared against the scalar
   loop).
 
-### Verified
-
-- `gasm fmt` doc-comment indentation confirmed correct: comments before
-  every TEXT are at column 0 (the RET-detection logic handles multi-exit
-  functions).
 
 ## [0.21.0] — 2026-07-26
 
@@ -352,7 +524,7 @@ test corpus exercises.
   argument blocks and collect distinct output fingerprints (the result
   words); reports path diversity as a lower bound on code coverage.
 
-### Note
+### Changed
 
 INT3-based per-block hit counting was prototyped but deferred: Go's runtime
 signal management (sigaltstack, handler re-installation) makes raw
@@ -417,11 +589,6 @@ toolchain.
   known-answer LZ4 blocks decode bit-for-bit, wide copies of 0–1024 bytes
   match, malformed input returns the correct error codes.
 
-### Verified
-
-- `just test` (race, 84.6 % total coverage, verify 82.2 %).
-- `gasm verify` on both go-lz4 kernels: all functions JIT-load and
-  smoke-test clean.
 
 ## [0.16.0] — 2026-07-21
 
@@ -547,13 +714,6 @@ Go assembler.
   (`DATA mask<>+8(SB)/8, $0x800f…`) parse as unsigned and keep their bit
   pattern, instead of being rejected as non-integer.
 
-### Verified
-
-- End-to-end: a gasm-emitted GOOBJ swapped into a `go build` in place of
-  the toolchain's assembly object links and runs with output identical to
-  the baseline binary (stack-argument calls and a `GLOBL` relocation
-  resolved by the Go linker).  All 17 go-flac AVX2 kernel functions emit as
-  a GOOBJ that `go tool nm` reads back with every symbol intact.
 
 ## [0.11.0] — 2026-07-16
 
@@ -577,7 +737,7 @@ objects.
   `GLOBL` in the file defines no longer aborts assembly — it is recorded
   as an external relocation (`Image.Externals`, `FuncLayout.Relocs`) and
   becomes an undefined global symbol in the object output.  The raw image
-  format (`--format raw`, the default) still reports them: only an object
+  s (`--format raw`, the default) still reports them: only an object
   file can represent a reference the linker must resolve.
 
 ### Changed
@@ -612,7 +772,7 @@ verified byte for byte against the Go assembler.
   arithmetic, the unpacks, VMOVDDUP and the conversions all accept the
   explicit K1–K7 operand and the `.Z` suffix the way Go writes them.
 
-### Documented
+### Changed
 
 - VCVTPS2PD follows the Go assembler's encoding, which omits the F3
   mandatory prefix (VEX.pp / EVEX.pp = 00) that Intel's maps prescribe; the
@@ -620,15 +780,6 @@ verified byte for byte against the Go assembler.
   gasm reproduces it exactly (and round-trips through the x86 decoder, which
   shares the convention).
 
-### Verified
-
-- 58 new ground-truth cases — every instruction extracted from the Go
-  toolchain's own assembly (go build + an executable-segment dump), checked
-  byte for byte and round-tripped through the decoder, covering disp8×N for
-  the scalar (×8/×4), duplication (×8/×32/×64) and conversion (×8/×16/×32)
-  memory operands, the 5-bit register fields and the masked/zeroing P2
-  byte.  All four go-flac/go-lz4 kernels still assemble byte-identically
-  and lint clean.
 
 ## [0.9.0] — 2026-07-14
 
@@ -687,7 +838,7 @@ The formatter behaves like `go fmt` and canonicalises block separation.
 
 ### Changed
 
-- `format`: canonical blank-line layout — a new block (a label, `TEXT` or
+- `s`: canonical blank-line layout — a new block (a label, `TEXT` or
   `GLOBL`) is preceded by exactly one blank line, neither more nor less.
   Comments leading a block stay with it (the blank line goes before them),
   stacked labels share their block, the function's first label keeps hugging
@@ -722,7 +873,7 @@ the encoder learns the legacy SSE moves.
   *first* operand on arm64, riscv64 and loong64; Plan 9 spelling puts it last
   on every architecture Go supports.  The def/use and save/restore
   classification on those architectures was inverted.
-- `format`: a comment that follows a `RET` (typically the next function's doc
+- `s`: a comment that follows a `RET` (typically the next function's doc
   comment) is no longer indented as if it were still inside the finished
   function body.
 
@@ -764,13 +915,6 @@ the Go toolchain, completing the production-kernel coverage.
 - `asm`: the VEX encoder now rejects vector register indices 16–31 instead of
   encoding a truncated (wrong) register.
 
-### Verified
-
-- All 10 functions of the go-flac `avx512_amd64.s` kernel assemble
-  byte-identically to the Go toolchain's machine code (the disp32 of the one
-  `VMOVDQU32 idx16(SB), Z13` load is linker-filled in Go and resolved within
-  gasm's own image — checked to reach the right constant bytes).  The AVX2
-  kernel's 17 functions remain byte-identical.
 
 ## [0.4.0] — 2026-07-09
 
@@ -791,13 +935,6 @@ machine code byte for byte.
 - `gasm asm` prints the data section and symbol map alongside the functions
   and writes the whole image (code + data) with `-o`.
 
-### Verified
-
-- All 17 functions of the go-flac `avx2_amd64.s` kernel assemble
-  byte-identically to the Go toolchain's machine code; the only differing
-  bytes are the displacements of the two `VMOVDQU mask24<>(SB), X15` loads,
-  which the Go linker fills at link time and gasm resolves within its own
-  image (checked to reach the right constant bytes).
 
 ## [0.3.0] — 2026-07-08
 
@@ -909,7 +1046,7 @@ Initial release — the Phase 1 foundation.
   Zero error-severity diagnostics across the 90-file Go runtime corpus and the
   production go-flac kernels (the `register-clobber` audit additionally reports
   the go-flac kernels' unsaved callee-saved register use for review).
-- `format`: an idempotent canonical formatter (operand spacing and per-function
+- `s`: an idempotent canonical formatter (operand spacing and per-function
   mnemonic alignment) that preserves comments and round-trips through the
   parser.
 - `lsp`: a Language Server Protocol server over stdio providing completion,

CONTRIBUTING.md

@@ -1,101 +1,107 @@
 # Contributing to gasm-devkit
 
-## Prerequisites
+Thanks for contributing to gasm-devkit.
 
-- Go 1.26 or later (`toolchain go1.26.5`)
-- `just` command runner
-- A Linux host on amd64, arm64, riscv64 or loong64
+## Development setup
 
-## Development Setup
+Requirements: Go 1.27 or later, the [just](https://github.com/casey/just)
+command runner, and a Linux host on amd64, arm64, riscv64 or loong64.
 
 ```sh
 git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
 cd gasm-devkit
 just install        # download module dependencies
 just build          # go vet + gofmt check
-just test           # full test suite with race detector
+just test           # full suite, race detector, 80 % coverage gate
 ```
 
-## Commands
+## Workflow
 
-Every just recipe:
+1. Branch from `development`; never commit directly to `main` (`main` is
+   release-only: merge from `development`, then tag).
+2. Commit with [Conventional Commits](https://www.conventionalcommits.org/):
+   `type(scope): description`: subject line only, imperative mood,
+   lowercase after the colon, no trailing dot.  Allowed types: `feat`,
+   `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`,
+   `build`, `revert`.  The only line after the subject is the trailer:
+   `Assisted-by: <model-name>`.  No `Co-Authored-By`, no `Signed-off-by`,
+   no other trailers.
+3. Record every user-visible change in `CHANGELOG.md` under
+   `## [development]` (categories: Added, Changed, Fixed, Removed,
+   Security).
+4. Add or update tests; coverage must stay **at or above 80 %** (hard
+   gate, enforced by CI).
+5. Update the documentation when behaviour, flags or the public surface
+   change.
+6. Open a pull request against `development`.
 
-| Recipe | What it does |
-|--------|-------------|
-| `just` | List all recipes |
-| `just install` | `go mod download` |
-| `just build` | `go vet ./...` + `gofmt -l .` check — zero errors required |
-| `just test` | `go test -race -count=1 -coverprofile=coverage.out ./...` + 80 % coverage gate |
-| `just fmt` | `gofmt -w .` |
-| `just run -- lint file.s` | Run the CLI with `go run` (args after `--`) |
-| `just install-bin` | Install `gasm` into `$GOBIN` with the release version stamped |
-| `just gen` | Regenerate `arch/*_gen.go` instruction tables from the Go toolchain |
-| `just uninstall` | Remove build artefacts (`coverage.out`, `gasm`, `*.test`) |
+Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`;
+CI builds and publishes the binaries for all four architectures.
 
-## Running a Single Test
+## Code style
+
+`gofmt` and `go vet` via `just fmt` / `just build`; both must pass with
+zero output; `go fix -diff ./...` must report nothing on touched packages.
+
+- Standard library only in production code; `golang.org/x/arch` is used
+  in tests only (round-trip decoding) and is never linked into the `gasm`
+  binary.
+- No cgo, no C, no external toolchains at runtime.
+- Explicit `if err != nil`; errors wrapped with
+  `fmt.Errorf("context: %w", err)`; no panics outside `main`.
+- The parser, lexer and formatter are hand-written; the `arch` instruction
+  tables are generated only via `_gen/gen.go` (`just gen`), never edited.
+
+## Running a single test
 
 ```sh
 go test -run TestVexGroundTruth ./asm/
-go test -run TestDifferentialLZ4Fuzz ./verify/
+go test -run TestGroundTruthBasic ./verify/
+go test -run TestGOObjectLinkAndRun ./asm/
+go test -run TestFuzzWideCopy ./verify/
 ```
 
-## Testing the Debugger
+The interactive debugger (`gasm debug`) requires a compiled binary on
+`$PATH`; `go run` does not work for the traced child process.  Install
+first with `just install-bin`.
 
-The interactive debugger (`gasm debug`) requires a compiled binary —
-`go run` does not work for the child process. Install first:
+## CI (Gitea Actions)
 
-```sh
-just install-bin
-gasm debug --func add testdata/verify/basic_amd64.s
-```
+Workflows live in `.gitea/workflows/` and run on self-hosted runners:
 
-## Code Style
+| Workflow | Trigger | What it does |
+|----------|---------|--------------|
+| Test | push / PR to `development` | gofmt check, `go vet`, `go test -race`, 80 % coverage gate |
+| Release | tag `v*` | cross-compiles binaries for linux/{amd64,arm64,riscv64,loong64} and publishes the Gitea release |
 
-See [AGENTS.md](AGENTS.md) for the full style guide. Key points:
+The Definition of Done (`just build` + `just test` + `just fmt`) must
+still pass locally before pushing.
 
-- `gofmt` — zero diff.
-- `go vet` — zero warnings.
-- Standard library only in production code; `golang.org/x/arch` in tests.
-- No cgo, no C, no JavaScript.
-- Hand-written Plan 9 assembly; tables generated only via `_gen/gen.go`.
+## AI Contribution Policy
 
-## Branches and Releases
+AI tools are welcome as productivity aids.  What matters is that
+contributions remain understandable, reviewable, and genuinely useful.
 
-- `development` is the working branch.
-- `main` is release-only: `git merge --ff-only development`, then `git tag vX.Y.Z`.
-- Conventional Commits: `feat(asm): add EVEX gather and scatter`.
-- Every commit ends with `Assisted-by: <model-name>`.
+- **Disclose AI use.**  If you used AI to draft or generate any part of a
+  commit, issue, pull request, or code review, say so clearly.
+- **Commit messages:** end every commit with exactly one trailer:
+  `Assisted-by: <model-name>` (e.g. `Assisted-by: GLM 5.3`).
+- **Pull requests and issues:** attribute AI assistance in one trailing
+  line, e.g. `_Assisted-by: GLM 5.3_`.  Do not paste it into the PR
+  description as a section.
+- **Take responsibility.**  You remain accountable for the accuracy,
+  completeness, and intent of everything you submit.
+- **Review before marking ready.**  Read AI-generated diffs carefully, run
+  them locally, and add or update tests where appropriate.
+- **Preferred models.**  Prefer open-weight models with transparent
+  training data: **GLM**, **DeepSeek**, and **MiMo**.
 
-## CI
-
-CI runs on every push to `development` and on pull requests:
-
-- **Test** (`test.yml`) — `gofmt` check, `go vet`, `go test -race` and the
-  80 % coverage gate.
-- **Release** (`release.yml`) — cross-compiles release binaries for
-  linux/{amd64,arm64,riscv64,loong64} on version tags and publishes them.
-
-The Definition of Done (`just build` + `just test` + `just fmt`) must still
-pass locally before pushing.
-
-## AI-Assisted Contributions
-
-AI agents may assist with code, documentation, tests, and review. All
-AI-assisted changes must:
-
-- Include the trailer `Assisted-by: <model-name>` in the commit message
-  (e.g. `Assisted-by: DeepSeek V4 Pro`).
-- Follow the [AGENTS.md](AGENTS.md) rules.
-- Pass the Definition of Done before committing.
-
-Attribute agent authorship in issues and pull requests on one trailing
-line:
-
-```
-_Assisted-by: Qwen 3.8 Max_
-```
-
-## Questions
+## Reporting bugs
 
 Open an issue at
-[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit/issues).
+[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit/issues)
+with the version (`gasm --version`), OS and architecture, the exact
+command, the full output, and the expected versus actual behaviour.
+
+**Security issues:** email **opensource@petrbalvin.org** instead of opening
+a public issue.

README.md

@@ -1,370 +1,158 @@
 # gasm-devkit
 
-Developer tooling for **GAsm** — Go's built-in Plan 9 assembler.
+Developer tooling for **GAsm**, Go's built-in Plan 9 assembler.
 
-[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
-
-Go ships an assembler but no tooling for it.  There is no syntax highlighting,
+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.
+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.
 
-gasm-devkit is the missing toolkit.  It is a single, self-contained binary —
-`gasm` — that brings proper developer tooling to Plan 9 assembly:
+## Features
 
-```
-gasm tokens   dump the lexical token stream
-gasm parse    parse and report syntax errors
-gasm fmt      canonicalise formatting (gofmt for assembly)
-gasm lint     static checks
-gasm lsp      language server (completion, hover, symbols, diagnostics, highlighting)
-gasm asm      standalone assembler                  (Phase 2)
-gasm verify   dynamic analysis & verification       (Phase 3)
-gasm debug    source-level debugger                 (Phase 4)
-gasm diff     compare machine code of two .s files
-gasm profile  show basic-block structure of functions
-```
+- **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.
+- **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.
+- **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.
+- **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.
 
-> **Status: Phase 4 — done, Phase 5 underway.**  Phase 1 (the language
-> foundation, linter, formatter and language server) shipped in v0.1.0;
-> Phase 2 (the standalone assembler — the full amd64 instruction set plus
-> ELF and GOOBJ object emission) in v0.12.0; Phase 3 (dynamic
-> analysis — JIT execution, differential testing, ABI checks and coverage
-> profiling) in v0.25.0; Phase 4 (interactive debugger — ptrace-based,
-> breakpoints, watchpoints, stepping, vector register display, named buffer
-> allocation) in v0.27.0; RISC-V encoder (RV64IMAFDC + RVC, ELF emission,
-> ground-truth, GOOBJ) in v0.28.0–v0.29.0; LoongArch encoder (the full
-> instruction set with the MOV expansions, ELF and GOOBJ emission, and
-> ground-truth verification) after v0.29.0.  See [Roadmap](#roadmap).
+### Architecture support
 
-## Architecture support
-
-gasm-devkit targets every architecture Go's assembler speaks.  The instruction
-tables are **generated from the Go toolchain's own assembler source**
-(`cmd/internal/obj/<arch>`), so gasm-devkit recognises *every* mnemonic the
-real assembler accepts — not a hand-maintained subset that drifts and rots.
-
-| 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               |
+| 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
+`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.
+...) 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.
 
-## Supported Platforms
+## Install
 
-The toolkit runs on Linux.  All four Linux architectures are supported as
-hosts — amd64, arm64, riscv64 and loong64 — and the release matrix
-cross-compiles the same four targets.
+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):
 
-**FreeBSD support is planned for a future release.**
+```sh
+go install sourcedock.dev/petrbalvin/gasm-devkit/cmd/gasm@latest
+```
 
-## Roadmap
+Or from a repository checkout, with the development version stamped:
 
-The work is delivered in four phases.  Each phase is completed and hardened
-before the next begins.  The ordering follows a dependency chain: understand
-the code statically (Phase 1), make it runnable (Phase 2), then run it and
-observe or control it (Phases 3–4).
-
-### Phase 1 — language foundation, editor tooling and static analysis · *done*
-
-Everything needed to read, understand, check, format and highlight GAsm —
-without executing it.
-
-| Capability | Status |
-|------------|--------|
-| Lexer — permissive, position-aware scanner for all four architectures | done |
-| Parser — line-oriented, error-tolerant, full AST with source positions | done |
-| Instruction + register tables for amd64, arm64, riscv64, loong64 (generated, complete) | done |
-| Linter — `unknown-instruction`, `operand-count`, `undefined-label`, `duplicate-label`, `missing-ret`, `missing-textflag-include`, `abi-argsize`, `unreachable-code`, `register-clobber`, `funcdata-pcdata` | done |
-| Formatter — idempotent, comment-preserving, per-function alignment; a `RET` terminates the body for indentation, so the next function's doc comment stays at column 0; exactly one blank line before every block (label, `TEXT`, `GLOBL`) and runs of blanks collapsed; directory / no-argument mode reformats every `.s` in place, `go fmt`-style | done |
-| Language server — completion, hover, document symbols, diagnostics, semantic-token highlighting | done |
-| CLI — `gasm tokens / parse / fmt / lint / lsp` | done |
-| Real-world validation against production AVX2 / AVX-512 kernels | done |
-| Lint hardening — zero false positives across the Go runtime corpus (90 files, all four architectures): macro-invocation handling, branch aliases (`B`/`BL`/`JAL`), addressing suffixes (`.P`/`.W`), terminal `UNDEF` | done |
-| Static analysis — `abi-argsize` (argument/result area computed from the `// func` signature under Go's ABI0 layout and checked against the TEXT declaration) and `unreachable-code` (dead code after `RET`, suppressed where reachability is undecidable: PC-relative jumps, register-indirect branches, `#ifdef`) | done |
-| Static analysis — register liveness (CFG construction + per-instruction def/use + iterative backward dataflow) driving `register-clobber`, calibrated to the **Go ABI** (not System V): flags writes to the registers Go fixes across calls — the frame pointer and the goroutine pointer (`R14` on amd64, `R28`/`R29` on arm64, `X27` on riscv64, `R22` on loong64, plus the OS-reserved `R18` on arm64) — that are never saved/restored; the goroutine pointer is reported only when the function can reach the runtime (not `NOSPLIT`, or makes calls), matching how the runtime's own assembly uses it. `funcdata-pcdata` structural validation of `FUNCDATA`/`PCDATA` operands and indices | done |
-
-> **Limitation — macros.** gasm-devkit reads `.s` source as written; it does
-> **not** run the C preprocessor, so `#define` macros are not expanded.  Files
-> that use macros (the runtime's `asm_*.s`, `race_*.s`, `sys_*.s`, …) parse
-> cleanly, and macro *invocations* are recognised and never flagged, but the
-> `undefined-label` and `missing-ret` heuristics are suppressed in macro-using
-> files because labels a macro defines are invisible without expansion.  Full
-> macro expansion is future work (it pairs naturally with the Phase 2
-> assembler).  Hand-written, macro-free kernels — such as everything in
-> `go-libraries` — are analysed in full.
-
-### Phase 2 — standalone assembler · *done*
-
-Assembly without the Go toolchain in the loop.
-
-- **`gasm asm`:** a standalone assembler that turns a `.s` file into machine
-  code directly — pure Go, no `go build`, no external toolchain.  Useful for
-  fast iteration, for environments without a full Go installation, and as the
-  execution substrate that Phases 3 and 4 build on.
-
-Done so far:
-
-- An amd64 (x86-64) **instruction encoder** — REX/ModR-M/SIB/displacement/
-  immediate machinery and the scalar instruction set (MOV, the ALU group, TEST,
-  LEA, INC/DEC/NEG/NOT, shifts, IMUL and IMUL3, PUSH/POP, JMP/CALL/Jcc,
-  CMOVcc, SETcc, LZCNT/TZCNT, the sign/zero-extending moves — MOVBLZX and
-  friends, MOVLQSX — and CVTSL2SD/CVTSQ2SD), validated by round-tripping
-  every encoding through `golang.org/x/arch`'s decoder and byte-for-byte
-  against the Go assembler.
-- An **assembler** that drives the parser's AST into the encoder with local-
-  label resolution — jumps start in the short (rel8) form and expand to rel32
-  when the displacement does not fit, and jump-to-jump chains are folded the
-  way the Go toolchain folds them — so `gasm asm <file>` emits machine code
-  for each `TEXT` function.
-- **File-level assembly with static data** — `GLOBL`/`DATA` symbols are laid
-  out in a data section behind the code and references to them (`mask<>(SB)`)
-  are encoded RIP-relative with the displacement resolved within the image,
-  so the output is self-consistent and position-independent.  References to
-  symbols no `GLOBL` in the file defines are recorded as relocations and
-  carried into the object-file output.
-- **GOOBJ emission** — `gasm asm --format goobj -p <pkgpath>` writes the Go
-  toolchain's own object format (the one `cmd/link` consumes directly), so
-  gasm-assembled kernels drop into a `go build` without the Go assembler:
-  the functions as non-package symbols, `GLOBL` data, one `FuncInfo` per
-  function and the pc-value tables (`pcsp` with the real prologue/epilogue
-  stack deltas, `pcfile`, `pcline`, `pcinline`).  Verified end-to-end by
-  swapping a gasm-emitted object into a `go build` in place of the
-  toolchain's, linking and running — bit-identical behaviour.
-- **Object-file emission** — `gasm asm --format elf` writes a relocatable
-  object (a `.text` and a `.data` section, a symbol table — file-local `<>`
-  symbols local, the rest global — and one `R_X86_64_PC32` relocation per
-  static-symbol reference) that links with the system toolchain: external
-  references resolve against undefined symbols, file-local ones against the
-  data section.  Verified end-to-end by linking a gasm-emitted object with
-  a C driver and running it.  RISC-V uses the equivalent `R_RISCV_PCREL_HI20`
-  / `R_RISCV_PCREL_LO12_I` pair for AUIPC+JAL/JALR sequences.
-- **`FP`/`SP` frame mapping** — the pseudo-registers are translated onto the
-  hardware stack pointer (`x+N(FP)` → `(N+8)(SP)` for a zero frame, `(N+frame+
-  16)(SP)` with a frame pointer; locals via `x-N(SP)`), and the Go-style
-  prologue/epilogue is generated for functions with a frame.  The output is
-  **byte-identical to the Go assembler** for these cases (verified against
-  `go tool objdump`).
-- **SIMD (VEX / AVX2)** — the VEX prefix machinery (2-byte C5 and 3-byte C4)
-  with XMM/YMM vector registers, validated by round-trip decoding **and**
-  byte-for-byte against the Go assembler's machine code, across eight operand
-  forms: the three-operand NDS form (VPADDD/Q, VPSUBD/Q, VPXOR, VPOR, VPAND/N,
-  VPCMPEQD, VPCMPGTQ, VPUNPCK*, VPMULLD, VPMULDQ, VPSHUFB, VPACKSSDW,
-  VPERMD), the two-operand reg/rm form (VPMOVSXWD/DQ, VPMOVZXDQ,
-  VPBROADCASTD/Q, VPMOVMSKB, VMOVMSKPS, VCVTDQ2PD), the immediate-shift and
-  variable-count shifts (VPSLLD/Q, VPSRAD, VPSRLD/Q with an immediate or an
-  XMM/memory count), the immediate shuffle (VPSHUFD, VPERMQ), the
-  three-operand-plus-immediate form (VSHUFPD, VPERM2I128, VINSERTI128), the
-  lane extract (VEXTRACTI128, VEXTRACTF128), the direction-sensitive moves
-  (VMOVDQU, VMOVUPD, VMOVD, VMOVQ, VMOVSD), the no-operand VZEROUPPER, and
-  the floating-point set: the packed double arithmetic
-  (VADDPD/VSUBPD/VMULPD/VDIVPD/VMINPD/VMAXPD), the unpacks
-  (VUNPCKHPD/VUNPCKLPD), the scalar SD and SS operations, VMOVDDUP, the
-  width-changing conversions (VCVTDQ2PS, VCVTPS2PD, VCVTDQ2PD and the
-  VCVTPD2DQX/Y / VCVTTPD2DQX/Y spellings, whose VEX.L follows the wider
-  source) and VFMADD231PD.
-- **SIMD (EVEX / AVX-512)** — the four-byte EVEX prefix with the 5-bit
-  register fields (Z0–Z31, X/Y 16–31), opmask registers (K0–K7 as operands
-  and mask destinations, KMOVW, KTESTW) and the compressed disp8×N
-  displacement, covering every AVX-512 instruction the go-flac kernels use:
-  VPXORD/Q, VPADDD, VPSUBD/Q, VPUNPCK*DQ, VPMULLD/Q, VPERMD, VPSLLD/VPSRAD/
-  VPSRAQ, VALIGND, VPCMPEQD (with a K destination), VMOVDQU32, VMOVUPD,
-  VCVTQQ2PD, VPMOVSXDQ, the narrowing stores VPMOVDW/VPMOVQD, the lane
-  extracts VEXTRACTI64X4/VEXTRACTF64X4, VFMADD231PD, VADDPD, VMULPD,
-  VMOVDQU64 and the broadcasts VPBROADCASTD/Q from a GPR or memory, plus the
-  wider AVX-512 F/BW integer set (VPADDB/W, VPSUBB/W, VPANDD/Q/ND/NQ, VPMULLW,
-  VPMIN*/VPMAX* for B/W/D/Q elements, signed and unsigned, VPAVGB/W, the variable
-  shifts VPSLLV*/VPSRLV*/VPSRAV*, VMOVDQU8/16), the common floating-point
-  and conversion set (the packed double and single arithmetic
-  VADD/VSUB/VMUL/VDIV/VMIN/VMAX PD and PS, the scalar SD/SS operations —
-  whose EVEX forms exist for masked and zeroing use — the VUNPCK{L,H}PD
-  unpacks, VMOVDDUP, VMOVSLDUP/VMOVSHDUP and the VCVT* conversions), and
-  the wider AVX-512 set: ternary logic (VPTERNLOGD/Q), lane shuffles,
-  inserts and extracts (VSHUF{F,I}{32,64}X{2,4}, the VINSERT*/VEXTRACT*
-  {F,I}{32,64}X{2,4,8} family, VPALIGNR), compares with an opmask
-  destination (VCMPPD/PS/SD/SS), the permutes (VPERMB/W, VPERMI2/T2
-  D/Q/PD), the wider integer families (VPMADDWD/UBSW, VPMULHUW, VPACK*,
-  VPABS*, the VPROL*/VPROR* rotates and the word shifts), expand/compress
-  (VEXPAND*/VCOMPRESS*, VPEXPAND*/VPCOMPRESS*), the broadcasts
-  (VPBROADCASTB/W, VBROADCASTSS/SD), the opmask instructions (KAND/KOR/
-  KXNOR/KADD/KUNPCK/KNOT/KSHIFTL/KORTEST, KMOVQ), the aligned moves
-  (VMOVAPS/APD, VMOVDQA32/64, VMOVSS) and the remaining extending and
-  narrowing moves, the floating-point helper and conversion tail
-  (VRCP14*, VRSQRT14*, VGETEXP*, VGETMANT*, VSCALEF*, VRNDSCALE*,
-  VREDUCE*, VFIXUPIMM*, VRANGE*, VFPCLASS* with a K destination, and the
-  VCVT* conversions VCVTQQ2PS, VCVTPD2QQ/UQQ, VCVTPS2QQ, VCVTUDQ2PD/PS,
-  VCVTPH2PS, VCVTPS2PH), and gather/scatter with VSIB addressing
-  (VGATHER*/VPGATHER* in both the VEX mask-register spelling and the EVEX
-  K-mask spelling — where the L'L field follows the VSIB index — plus
-  VSCATTER*/VPSCATTER*).  The EVEX mnemonic suffixes the Go assembler
-  accepts are honoured: rounding modes (.RN_SAE, .RD_SAE, .RU_SAE,
-  .RZ_SAE), suppress-all-exceptions (.SAE) and memory broadcast (.BCST,
-  with the element-sized disp8×N), each combinable with the .Z zeroing
-  suffix.  Masking is supported the way
-  Go writes it — an explicit K1–K7 operand placed among the operands, and a
-  `.Z` mnemonic suffix for zeroing.
-- **Legacy SSE moves** — `MOVOU`/`MOVO` (the Plan 9 names for MOVDQU/MOVDQA),
-  `MOVUPS`/`MOVAPS`/`MOVUPD`/`MOVAPD` and the scalar `MOVSD`/`MOVSS`.
-- **Both go-flac kernels — all 17 AVX2 and all 10 AVX-512 functions —
-  assemble byte-identically to the Go toolchain's machine code**; the only
-  differing bytes are the displacements of the static-constant loads, which
-  the Go linker fills at link time and gasm resolves within its own image
-  (verified to reach the right constant bytes).
-
-Remaining for Phase 2:
-
-- External (cross-package) symbol references in the GOOBJ output —
-  **deferred** with a recorded decision and three options; see
-  [`docs/DEFERRED.md`](docs/DEFERRED.md).  Single-package objects (no
-  cross-package references) work today, which covers the production
-  kernels.  With that item deferred, the amd64 instruction set — scalar,
-  VEX/AVX2 and the full EVEX/AVX-512 set including GPR-interchanging
-  conversions — is complete, and RISC-V encoding (RV64IMAFDC + RVC)
-  including ELF and GOOBJ emission is complete.
-
-### Phase 3 — dynamic analysis · *done*
-
-Run the code and check what static analysis cannot.  The oracle is the
-portable Go implementation every kernel is derived from.
-
-- **`gasm verify`:**
-	  - **JIT execution substrate** — *done.*  Assemble the kernel, map it into
-	    executable memory (`syscall.Mmap`, W^X) and call it through an ABI0
-	    trampoline; pure Go, no cgo, no external toolchain.
-	  - **Differential testing** — *done.*  The JIT-assembled kernel is fuzzed
-	    against a portable Go reference, comparing the result bit-for-bit;
-	    the automated form of the project's bit-identical contract.
-	  - **Runtime ABI checks** — *done.*  The ABI-checking trampoline sets
-	    sentinels in BP and R14, verifies they survive the call, and fills a
-	    128-byte red-zone canary below SP.
-	  - **Coverage / basic-block profiling** — *done.*  Static block enumeration
-	    from the assembler's label map plus multi-input path-diversity
-	    measurement: how many observationally distinct execution paths a
-	    test corpus exercises.
-
-### Phase 4 — debugger · *done*
-
-- **`gasm debug`:** single-step a GAsm function, inspect registers (including
-  YMM vector registers), set breakpoints and watchpoints on addresses, write
-  memory, allocate and fill named buffers, disassemble at PC, and trace the
-  source-line mapping — the interactive counterpart to Phase 3's execution
-  substrate.
-  - ptrace-based debuggee subprocess (PTRACE_TRACEME + LockOSThread), entry
-    breakpoint (auto-run to function start), single-step, register inspection
-    (GPR + YMM/XMM via PTRACE_GETFPREGS), label resolution, breakpoint
-    management via `/proc/pid/mem`, named buffer allocation with pattern
-    filling (`--buf`), interactive REPL with conditional breakpoints, four
-    hardware watchpoints (DR0–DR3), step-over-CALL, run-to-return, backtrace,
-    memory read/write, disassembly at PC (x86asm), and source-line ↔ offset
-    mapping.
-
-### Phase 5 — the other architectures · *in progress*
-
-- **RISC-V encoding — done.**  RV64IMAFDC instruction set, RVC compression,
-  MOV pseudo-instruction, SB/global symbols (AUIPC pairs), ELF64 and GOOBJ
-  emission, and ground-truth verification against `go tool asm`.
-- **LoongArch encoding — done.**  The LoongArch64 instruction set with the
-  MOV pseudo-instruction and its immediate-constant expansions, FP/SP frame
-  handling, SB/global symbol references (pcalau12i pairs), ELF64 and GOOBJ
-  emission, and ground-truth verification against `go tool asm` — the emitted
-  GOOBJ links into a real `go build` for `GOARCH=loong64`.
-- **Remaining:** arm64 encoding, plus the same encode-and-verify treatment
-  (instruction tables already generated from the toolchain).
-
-## Principles
-
-- **Pure Go and GAsm only.**  No C, no cgo, no external toolchains, no native
-  binaries, no JavaScript runtimes.  The parser is hand-written; there is no
-  parser generator.
-- **Self-contained.**  The toolkit's production code depends only on the
-  standard library; one binary, no runtime data files.  The single module
-  dependency, `golang.org/x/arch`, is used **only in tests** to validate the
-  instruction encoder by round-trip decoding — it is never linked into the
-  `gasm` binary.
-- **Linux-only.**  Runs natively on amd64, arm64, riscv64 and loong64 Linux
-  hosts; the release matrix cross-compiles the same four targets.  Latest
-  stable Go only.
-- **No vendor lock-in.**  The integration surface is the Language Server
-  Protocol and a command-line interface — both open standards.  No cloud
-  service, no proprietary API, no dependence on any one editor's internals.
-- **Complete and verifiable.**  Instruction coverage is generated from the
-  assembler's own source and regenerated on demand, so it cannot silently fall
-  behind the toolchain.
-
-## Components
-
-| Package | Purpose |
-|---------|---------|
-| `token` | Lexical token kinds and source positions. |
-| `lexer` | Hand-written scanner for Plan 9 assembly. |
-| `ast` | The abstract syntax tree. |
-| `parser` | Line-oriented, error-tolerant parser producing the AST. |
-| `arch` | amd64, arm64, riscv64 and loong64 register files and instruction tables. |
-| `lint` | Conservative static checks. |
-| `format` | A canonical formatter — `gofmt` for assembly. |
-| `asm` | The standalone assembler: amd64, RISC-V and LoongArch encoders, linker, object-file emitters (ELF, GOOBJ). |
-| `verify` | JIT execution substrate for dynamic analysis, combined ABI+fuzz differential testing (Phase 3). |
-| `debug` | Interactive ptrace debugger with GPR/YMM register display and named buffer allocation (Phase 4). |
-| `lsp` | Language Server Protocol server. |
-| `cmd/gasm` | The `gasm` binary tying it all together. |
-| `_gen` | The generator that rebuilds the instruction tables from the Go toolchain. |
-
-See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the design rationale and
-data flow, and [`docs/DEFERRED.md`](docs/DEFERRED.md) for design decisions
-deliberately postponed (with the analysis needed to pick them up again).
+```sh
+just install-bin
+```
 
 ## Quick start
 
 ```sh
-just install     # download dependencies (there are none)
-just build       # go vet + gofmt check — zero errors, zero warnings
-just test        # full suite, race detector, 80 % coverage gate
-just fmt         # gofmt the tree
-just gen         # regenerate the instruction tables from the Go toolchain
+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
 ```
 
-Install the binary and use it:
+## Usage
 
 ```sh
-just install-bin                    # installs gasm into $GOBIN
-
-gasm --help                         # overview of commands and flags
-gasm tokens kernel_amd64.s          # dump the token stream
-gasm parse  kernel_amd64.s          # parse, report syntax errors
-gasm fmt    -w kernel_amd64.s       # canonicalise in place
-gasm fmt                            # reformat every .s below here, like go fmt
-gasm lint   *.s                     # static checks
-gasm asm --format elf -o k.o k.s    # assemble to a linkable ELF object
-gasm verify kernel_amd64.s           # JIT-load and report functions
-gasm verify --ground-truth k.s      # byte-for-byte vs go tool asm
-gasm verify --call decodeBlockAVX2 --buf src:64:hex...,dst:256:zero k.s
-gasm debug --func name k.s           # interactive debugger
-gasm diff a.s b.s                    # compare machine code byte-for-byte
+gasm fmt                                # reformat every .s below here, like go fmt
+gasm fmt    -w kernel_amd64.s           # canonicalise one file in place
+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 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 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
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow,
-[docs/cli.md](docs/cli.md) for the command reference, and
-[docs/development.md](docs/development.md) for setup and recipes.
+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
+### 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
+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
+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 install      # download module dependencies
+just build        # go vet + gofmt check, zero errors and zero warnings
+just test         # full suite, race detector, 80 % coverage gate
+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 — the same licence as Go itself.  See [`LICENSE`](LICENSE).
+BSD-3-Clause — see [LICENSE](LICENSE).
+
+Copyright © 2026 [Petr Balvín](https://petrbalvin.org)

arch/amd64.go

@@ -270,6 +270,8 @@ func amd64Curated() []Instr {
 		"VMINPD", "VMINPS", "VMINSD", "VMINSS", "VMAXPD", "VMAXPS", "VMAXSD", "VMAXSS",
 		"VXORPD", "VXORPS", "VANDPD", "VANDPS", "VANDNPD", "VANDNPS", "VORPD", "VORPS",
 		"VUNPCKHPD", "VUNPCKLPD", "VUNPCKHPS", "VUNPCKLPS",
+		"PSHUFD", "PSHUFHW", "PSHUFLW", "SHUFPS", "SHUFPD",
+		"UNPCKLPS", "UNPCKHPS", "UNPCKLPD", "UNPCKHPD",
 		"VSQRTPD", "VSQRTPS", "VSQRTSD", "VSQRTSS", "VRSQRTPS", "VRCPPS",
 		"VCMPPD", "VCMPPS", "VCMPSD", "VCMPSS",
 	} {

asm/aarch64_goobj_test.go

@@ -0,0 +1,178 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// TestGOObjectAARCH64Structure checks the basic structure of the emitted
+// AArch64 GOOBJ: the preamble, the magic, the block offsets and the
+// non-package symbol definitions.
+func TestGOObjectAARCH64Structure(t *testing.T) {
+	f, errs := parser.Parse("k_arm64.s", `
+#include "textflag.h"
+
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOVD a+0(FP), R4
+	MOVD b+8(FP), R5
+	ADD R5, R4, R4
+	MOVD R4, ret+16(FP)
+	RET
+`)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	obj, err := img.GOObjectAARCH64("testpkg", "k_arm64.s")
+	if err != nil {
+		t.Fatalf("GOObjectAARCH64: %v", err)
+	}
+
+	// Check preamble.
+	idx := strings.Index(string(obj), "\n!\n")
+	if idx < 0 {
+		t.Fatal("missing preamble separator")
+	}
+	preamble := string(obj[:idx])
+	if !strings.HasPrefix(preamble, "go object") {
+		t.Errorf("preamble = %q, want 'go object ...'", preamble)
+	}
+
+	// Check GOOBJ magic.
+	magicIdx := idx + 3
+	if magicIdx+8 > len(obj) || string(obj[magicIdx:magicIdx+8]) != "\x00go120ld" {
+		t.Error("missing GOOBJ magic")
+	}
+
+	// The object should contain the function's code.
+	if len(img.Code) == 0 {
+		t.Error("no code generated")
+	}
+}
+
+// TestGOObjectAARCH64Link does an end-to-end link test: it cross-compiles a
+// Go program for arm64, substitutes the gasm-produced object into the package
+// archive, re-links with cmd/link, and verifies the symbol appears in the
+// resulting binary.  The binary is not executed (no arm64 host or qemu).
+// Skipped when no Go toolchain is available.
+func TestGOObjectAARCH64Link(t *testing.T) {
+	goBin, err := exec.LookPath("go")
+	if err != nil {
+		t.Skip("no Go toolchain available")
+	}
+	dir := t.TempDir()
+	asmSrc := `#include "textflag.h"
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOVD a+0(FP), R4
+	MOVD b+8(FP), R5
+	ADD R5, R4, R4
+	MOVD R4, ret+16(FP)
+	RET
+`
+	if err := os.WriteFile(filepath.Join(dir, "main_arm64.s"), []byte(asmSrc), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	mainSrc := `package main
+
+func add(a, b int64) int64
+
+func main() {
+	if add(20, 22) != 42 {
+		panic("bad add")
+	}
+}
+`
+	if err := os.WriteFile(filepath.Join(dir, "main.go"), []byte(mainSrc), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "go.mod"), []byte("module a64link\n\ngo 1.21\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Capture the cross build (GOARCH=arm64): the package archive and the
+	// link line.
+	build := exec.Command(goBin, "build", "-x", "-work", "-o", filepath.Join(dir, "prog"), ".")
+	build.Dir = dir
+	build.Env = append(os.Environ(), "GOARCH=arm64")
+	buildLog, err := build.CombinedOutput()
+	if err != nil {
+		t.Fatalf("baseline build: %v\n%s", err, buildLog)
+	}
+	var work, linkLine, asmObj string
+	for line := range strings.SplitSeq(string(buildLog), "\n") {
+		switch {
+		case strings.HasPrefix(line, "WORK="):
+			work = strings.TrimPrefix(line, "WORK=")
+		case strings.Contains(line, "/asm ") && strings.Contains(line, "main_arm64.s") && !strings.Contains(line, "-gensymabis"):
+			asmObj = fieldAfter(line, "-o")
+		case strings.Contains(line, "/link ") && strings.Contains(line, "-importcfg"):
+			linkLine = line
+		}
+	}
+	if work == "" || asmObj == "" {
+		t.Skipf("could not parse build log (work=%q asmObj=%q)", work, asmObj)
+	}
+	defer os.RemoveAll(work)
+
+	// Expand $WORK in the object path.
+	asmObj = strings.ReplaceAll(asmObj, "$WORK", work)
+
+	// Read the toolchain-produced object and assemble the same source with gasm.
+	src, err := os.ReadFile(filepath.Join(dir, "main_arm64.s"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	f, errs := parser.Parse("main_arm64.s", string(src))
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	gasmObj, err := img.GOObjectAARCH64("a64link", "main_arm64.s")
+	if err != nil {
+		t.Fatalf("GOObjectAARCH64: %v", err)
+	}
+
+	// Replace the toolchain-produced object with gasm's.
+	if err := os.WriteFile(asmObj, gasmObj, 0o644); err != nil {
+		t.Fatalf("write gasm object: %v", err)
+	}
+
+	// Re-link.
+	if linkLine == "" {
+		t.Skip("could not find link command in build log")
+	}
+	// Expand $WORK in the link command.
+	linkLine = strings.ReplaceAll(linkLine, "$WORK", work)
+	linkCmd := exec.Command("bash", "-c", "cd "+dir+" && "+linkLine)
+	linkCmd.Env = append(os.Environ(), "GOARCH=arm64")
+	if out, err := linkCmd.CombinedOutput(); err != nil {
+		t.Fatalf("re-link with gasm object: %v\n%s", err, out)
+	}
+
+	// Verify the binary exists and contains the symbol.
+	binPath := filepath.Join(dir, "prog")
+	if _, err := os.Stat(binPath); err != nil {
+		t.Fatalf("binary not found: %v", err)
+	}
+	binData, err := os.ReadFile(binPath)
+	if err != nil {
+		t.Fatalf("read binary: %v", err)
+	}
+	if !strings.Contains(string(binData), "add") && !strings.Contains(string(binData), "a64link") {
+		t.Error("binary does not contain expected symbol")
+	}
+}

asm/arm64_encode.go

@@ -0,0 +1,687 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+// arm64 (AArch64) instruction encoding.
+//
+// The encoder is data-driven: each mnemonic maps to an instruction format and
+// an opcode constant, and the format selects the bit layout.  The opcode
+// constants and formats are transcribed from the Go toolchain's own arm64
+// backend (cmd/internal/obj/arm64), so the emitted bytes match `go tool asm`
+// exactly — the ground-truth oracle for the verify suite.
+//
+// All AArch64 instructions are 32 bits, little-endian.  The formats used here
+// (per the ARM Architecture Reference Manual):
+//
+//	DP-shifted-reg  sf<<31 | op<<30 | S<<29 | 0x0b<<24 | shift<<22 | 0<<21 | Rm<<16 | imm6<<10 | Rn<<5 | Rd
+//	DP-immediate    sf<<31 | op<<30 | S<<29 | 0x11<<24 | imm12<<10 | Rn<<5 | Rd
+//	Logical-imm     sf<<31 | opc<<29 | 0x24<<23 | N<<22 | immr<<16 | imms<<10 | Rn<<5 | Rd
+//	Move-wide       sf<<31 | opc<<29 | 0x25<<23 | hw<<21 | imm16<<5 | Rd
+//	Load/store      size<<30 | 0x7<<27 | V<<26 | opc<<22 | imm12<<10 | Rn<<5 | Rt
+//	LDST-unscaled   size<<30 | 0x7<<27 | V<<26 | opc<<22 | 0<<12 | imm9<<5 | Rt  (actually imm9<<12 | Rn<<5 | Rt)
+//	LDST-pair       opc<<30 | 0x5<<27 | V<<26 | L<<22 | imm7<<15 | Rt2<<10 | Rn<<5 | Rt
+//	Branch-imm      0<<31 | 0x5<<26 | imm26          (B)
+//	Branch-imm      1<<31 | 0x5<<26 | imm26          (BL)
+//	Branch-cond     0x2A<<25 | imm19<<5 | cond        (B.cond)
+//	Uncond-branch   0x6B<<25 | opc<<21 | Rn<<5 | Rd   (BR/BLR/RET)
+//	ADR/ADRP        p<<31 | 0x10<<24 | immlo<<29 | immhi<<5 | Rd
+
+// arm64RegNum returns the 5-bit register number for an AArch64 register name:
+// R0–R30 (integer), F0–F31 (floating point), and the ABI aliases the
+// runtime's assembly uses.  Returns -1 for an unrecognised name.
+func arm64RegNum(name string) int {
+	switch name {
+	case "R0":
+		return 0
+	case "R1":
+		return 1
+	case "R2":
+		return 2
+	case "R3":
+		return 3
+	case "R4":
+		return 4
+	case "R5":
+		return 5
+	case "R6":
+		return 6
+	case "R7":
+		return 7
+	case "R8":
+		return 8
+	case "R9":
+		return 9
+	case "R10":
+		return 10
+	case "R11":
+		return 11
+	case "R12":
+		return 12
+	case "R13":
+		return 13
+	case "R14":
+		return 14
+	case "R15":
+		return 15
+	case "R16":
+		return 16
+	case "R17":
+		return 17
+	case "R18":
+		return 18
+	case "R19":
+		return 19
+	case "R20":
+		return 20
+	case "R21":
+		return 21
+	case "R22":
+		return 22
+	case "R23":
+		return 23
+	case "R24":
+		return 24
+	case "R25":
+		return 25
+	case "R26", "REGCTXT", "CTXT":
+		return 26
+	case "R27", "REGTMP", "TMP":
+		return 27
+	case "R28", "REGG", "g":
+		return 28
+	case "R29", "FP":
+		return 29
+	case "R30", "LR", "LINK":
+		return 30
+	case "R31", "ZR":
+		return 31
+	case "SP":
+		return 31 // SP and ZR share encoding 31; context determines meaning
+	}
+	// F0–F31.
+	if len(name) >= 1 && name[0] == 'F' {
+		n := 0
+		for i := 1; i < len(name); i++ {
+			if name[i] < '0' || name[i] > '9' {
+				return -1
+			}
+			n = n*10 + int(name[i]-'0')
+		}
+		if n <= 31 {
+			return n
+		}
+	}
+	return -1
+}
+
+// ---- format helpers ----
+
+// a64wordLE encodes a uint32 as 4 little-endian bytes.
+func a64wordLE(w uint32) []byte {
+	return []byte{byte(w), byte(w >> 8), byte(w >> 16), byte(w >> 24)}
+}
+
+// a64WordsLE concatenates one or more instruction words as little-endian bytes.
+func a64WordsLE(ws ...uint32) []byte {
+	var out []byte
+	for _, w := range ws {
+		out = append(out, a64wordLE(w)...)
+	}
+	return out
+}
+
+// ---- data-processing (immediate) ----
+
+// a64AddSub encodes an ADD/SUB (immediate) instruction:
+// sf<<31 | op<<30 | S<<29 | 0x11<<24 | sh<<22 | imm12<<10 | Rn<<5 | Rd.
+func a64AddSub(sf, op, S, sh, imm12, rn, rd uint32) uint32 {
+	return sf<<31 | op<<30 | S<<29 | 0x11<<24 | sh<<22 | imm12<<10 | rn<<5 | rd
+}
+
+// ---- move wide ----
+
+// a64MoveWide encodes a MOVZ/MOVK/MOVN instruction:
+// sf<<31 | opc<<29 | 0x25<<23 | hw<<21 | imm16<<5 | Rd.
+func a64MoveWide(sf, opc, hw, imm16, rd uint32) uint32 {
+	return sf<<31 | opc<<29 | 0x25<<23 | hw<<21 | imm16<<5 | rd
+}
+
+// ---- load/store (unsigned immediate, scaled) ----
+
+// a64LSU encodes a load/store register (unsigned immediate, scaled):
+// size<<30 | 0x39<<24 | V<<26 | opc<<22 | imm12<<10 | Rn<<5 | Rt.
+// (0x39<<24 encodes bits 29:24 = 111001, the scaled unsigned offset form.)
+func a64LSU(size, V, opc, imm12, rn, rt uint32) uint32 {
+	return size<<30 | 0x39<<24 | V<<26 | opc<<22 | imm12<<10 | rn<<5 | rt
+}
+
+// ---- load/store (unscaled immediate) ----
+
+// a64LSUnscaled encodes a load/store register (unscaled immediate, 9-bit signed):
+// size<<30 | 0x7<<27 | V<<26 | opc<<22 | 0<<12 | imm9<<12 | Rn<<5 | Rt.
+// Note: the 0<<24 distinguishes unscaled from the pre/post-index forms.
+func a64LSUnscaled(size, V, opc int, imm9 int32, rn, rt int) uint32 {
+	return uint32(size)<<30 | 7<<27 | uint32(V)<<26 | uint32(opc)<<22 |
+		(uint32(imm9)&0x1FF)<<12 | uint32(rn&31)<<5 | uint32(rt&31)
+}
+
+// ---- load/store pair ----
+
+// a64LSP encodes a load/store pair instruction (signed offset):
+// opc<<30 | 0x5<<27 | V<<26 | 2<<23 | L<<22 | imm7<<15 | Rt2<<10 | Rn<<5 | Rt.
+// opc: 0=32-bit, 1=reserved, 2=64-bit.  V: 0=integer, 1=FP/SIMD.
+// L: 0=store, 1=load.  imm7 is the signed scaled offset (÷8 for 64-bit pairs).
+func a64LSP(opc, V, L uint32, imm7 int32, rt2, rn, rt uint32) uint32 {
+	return opc<<30 | 5<<27 | V<<26 | 2<<23 | L<<22 | (uint32(imm7)&0x7F)<<15 | rt2<<10 | rn<<5 | rt
+}
+
+// ---- branches ----
+
+// a64Branch encodes an unconditional branch (B/BL):
+// op<<31 | 0x5<<26 | imm26.
+func a64Branch(op uint32, imm26 int32) uint32 {
+	return op<<31 | 5<<26 | (uint32(imm26) & 0x03FFFFFF)
+}
+
+// a64BranchCond encodes a conditional branch (B.cond):
+// 0x2A<<25 | imm19<<5 | cond.
+func a64BranchCond(imm19 int32, cond uint32) uint32 {
+	return 0x2A<<25 | (uint32(imm19)&0x7FFFF)<<5 | cond&0xF
+}
+
+// a64UncondBranch encodes an unconditional branch register (BR/BLR/RET):
+// 0x6B<<25 | opc<<21 | 0x1F<<16 | Rn<<5 | Rd.
+// opc: 0=BR, 1=BLR, 2=RET. For RET, Rn defaults to LR(30).
+func a64UncondBranch(opc, rn, rd uint32) uint32 {
+	return 0x6B<<25 | opc<<21 | 0x1F<<16 | rn<<5 | rd
+}
+
+// ---- ADR/ADRP ----
+
+// a64ADR encodes an ADR instruction (p=0) or ADRP instruction (p=1):
+// p<<31 | immlo<<29 | 0x10<<24 | immhi<<5 | Rd.
+func a64ADR(p uint32, immhi int32, immlo uint32, rd uint32) uint32 {
+	return p<<31 | immlo<<29 | 0x10<<24 | (uint32(immhi)&0x7FFFF)<<5 | rd
+}
+
+// ---- system ----
+
+// a64NOP encodes a NOP: 0xd503201f.
+const a64NOP uint32 = 0xd503201f
+
+// a64BRK encodes a BRK instruction: 0xd4200000 | imm16<<5.
+func a64BRK(imm16 uint32) uint32 {
+	return 0xd4200000 | imm16<<5
+}
+
+// ---- condition codes ----
+
+const (
+	a64CondEQ = 0x0
+	a64CondNE = 0x1
+	a64CondCS = 0x2
+	a64CondHS = 0x2
+	a64CondCC = 0x3
+	a64CondLO = 0x3
+	a64CondMI = 0x4
+	a64CondPL = 0x5
+	a64CondVS = 0x6
+	a64CondVC = 0x7
+	a64CondHI = 0x8
+	a64CondLS = 0x9
+	a64CondGE = 0xa
+	a64CondLT = 0xb
+	a64CondGT = 0xc
+	a64CondLE = 0xd
+)
+
+// arm64CondMap maps Go assembler condition mnemonics to AArch64 condition codes.
+var arm64CondMap = map[string]uint32{
+	"EQ": a64CondEQ,
+	"NE": a64CondNE,
+	"CS": a64CondCS,
+	"HS": a64CondHS,
+	"CC": a64CondCC,
+	"LO": a64CondLO,
+	"MI": a64CondMI,
+	"PL": a64CondPL,
+	"VS": a64CondVS,
+	"VC": a64CondVC,
+	"HI": a64CondHI,
+	"LS": a64CondLS,
+	"GE": a64CondGE,
+	"LT": a64CondLT,
+	"GT": a64CondGT,
+	"LE": a64CondLE,
+}
+
+// ---- instruction format tags ----
+
+type a64Format uint8
+
+const (
+	a64FDPSR         a64Format = iota // data-processing (shifted register): ADD, SUB, AND, ORR, EOR, etc.
+	a64FDPIR                          // data-processing (immediate): ADD/SUB $imm
+	a64FLogImm                        // logical (immediate): AND/ORR/EOR $imm
+	a64FMovWide                       // move wide: MOVZ, MOVN, MOVK
+	a64FLSU                           // load/store (unsigned immediate, scaled)
+	a64FLSUnscaled                    // load/store (unscaled immediate)
+	a64FLSPair                        // load/store pair
+	a64FBranch                        // unconditional branch (B/BL)
+	a64FBranchCond                    // conditional branch (B.cond)
+	a64FUncondBranch                  // unconditional branch register (BR/BLR/RET)
+	a64FADR                           // ADR/ADRP
+	a64FEXTR                          // EXTR
+	a64FBitfield                      // bitfield: BFI/BFXIL/SBFM/UBFM/BFM
+	a64FSystem                        // system: NOP, BRK, etc.
+	a64FFP3                           // FP 3-operand (Rm, Rn, Rd): FADD, FSUB, FMUL, FDIV, etc.
+	a64FFPUnary                       // FP unary (Rn, Rd): FMOV, FABS, FNEG, FSQRT, FCVT, FRINT*
+	a64FFP4                           // FP 4-operand FMA (Ra, Rm, Rn, Rd): FMADD, FMSUB, etc.
+	a64FFPCmp                         // FP compare (Rm, Rn): FCMP, FCMPE
+	a64FFPCCmp                        // FP conditional compare (Rm, Rn, nzcv, cond): FCCMP, FCCMPE
+	a64FFPCvt                         // FP↔integer conversion: FCVTZS, SCVTF, etc.
+	a64FFPSel                         // FP conditional select (Rm, Rn, Rd, cond): FCSEL
+	a64FFMovGR                        // FMOV between GP and FP registers
+	a64FCRC32                         // CRC32
+	a64FCSEL                          // conditional select: CSEL, CSINC, CSINV, CSNEG
+	a64FExcl                          // exclusive load/store: LDXR, STXR, LDAXR, STLXR
+	a64FLSE                           // LSE atomics: LDADD, CAS, SWP
+	a64FSIMD3                         // SIMD 3-operand: VADD, VSUB, VMUL
+)
+
+// a64Enc is one instruction's encoding: its bit layout (format) and the
+// opcode constant, positioned at its exact bit range.
+type a64Enc struct {
+	format a64Format
+	op     uint32 // the pre-positioned opcode bits
+}
+
+// a64InstrTable maps AArch64 mnemonics (as the Go assembler spells them) to
+// their encoding.  The base integer, memory, floating-point and SIMD
+// instruction sets are covered.
+var a64InstrTable = map[string]a64Enc{}
+
+func init() {
+	// ---- data-processing (shifted register) ----
+	// Format: sf<<31 | op<<30 | S<<29 | 0x0b<<24 | shift<<22 | Rm<<16 | imm6<<10 | Rn<<5 | Rd
+	dpsr := map[string]uint32{
+		// Add/Sub
+		"ADD":   1<<31 | 0<<30 | 0<<29 | 0x0b<<24, // sf=1, op=0, S=0 (64-bit default)
+		"ADDW":  0<<31 | 0<<30 | 0<<29 | 0x0b<<24, // sf=0
+		"ADDS":  1<<31 | 0<<30 | 1<<29 | 0x0b<<24,
+		"ADDSW": 0<<31 | 0<<30 | 1<<29 | 0x0b<<24,
+		"SUB":   1<<31 | 1<<30 | 0<<29 | 0x0b<<24,
+		"SUBW":  0<<31 | 1<<30 | 0<<29 | 0x0b<<24,
+		"SUBS":  1<<31 | 1<<30 | 1<<29 | 0x0b<<24,
+		"SUBSW": 0<<31 | 1<<30 | 1<<29 | 0x0b<<24,
+		// Logical (shifted register)
+		"AND":   1<<31 | 0<<29 | 0x0a<<24,
+		"ANDW":  0<<31 | 0<<29 | 0x0a<<24,
+		"BIC":   1<<31 | 0<<29 | 0x0a<<24 | 1<<21,
+		"BICW":  0<<31 | 0<<29 | 0x0a<<24 | 1<<21,
+		"ORR":   1<<31 | 1<<29 | 0x0a<<24,
+		"ORRW":  0<<31 | 1<<29 | 0x0a<<24,
+		"ORN":   1<<31 | 1<<29 | 0x0a<<24 | 1<<21,
+		"ORNW":  0<<31 | 1<<29 | 0x0a<<24 | 1<<21,
+		"EOR":   1<<31 | 2<<29 | 0x0a<<24,
+		"EORW":  0<<31 | 2<<29 | 0x0a<<24,
+		"EON":   1<<31 | 2<<29 | 0x0a<<24 | 1<<21,
+		"EONW":  0<<31 | 2<<29 | 0x0a<<24 | 1<<21,
+		"ANDS":  1<<31 | 3<<29 | 0x0a<<24,
+		"ANDSW": 0<<31 | 3<<29 | 0x0a<<24,
+		"BICS":  1<<31 | 3<<29 | 0x0a<<24 | 1<<21,
+		"BICSW": 0<<31 | 3<<29 | 0x0a<<24 | 1<<21,
+		// Shift
+		"LSL":  1<<31 | 0<<29 | 0x0a<<24, // alias of UBFM
+		"LSLW": 0<<31 | 0<<29 | 0x0a<<24,
+		"LSR":  1<<31 | 0<<29 | 0x0a<<24,
+		"LSRW": 0<<31 | 0<<29 | 0x0a<<24,
+		"ASR":  1<<31 | 0<<29 | 0x0a<<24,
+		"ASRW": 0<<31 | 0<<29 | 0x0a<<24,
+		"ROR":  1<<31 | 0<<29 | 0x0a<<24,
+		"RORW": 0<<31 | 0<<29 | 0x0a<<24,
+		// Multiply
+		"MADD":  1<<31 | 0<<29 | 0x1b<<24 | 0<<21,
+		"MADDW": 0<<31 | 0<<29 | 0x1b<<24 | 0<<21,
+		"MSUB":  1<<31 | 0<<29 | 0x1b<<24 | 1<<21,
+		"MSUBW": 0<<31 | 0<<29 | 0x1b<<24 | 1<<21,
+		// Divide
+		"SDIV":  1<<31 | 0<<29 | 0x0d<<24,
+		"SDIVW": 0<<31 | 0<<29 | 0x0d<<24,
+		"UDIV":  1<<31 | 0<<29 | 0x0d<<24 | 1<<10,
+		"UDIVW": 0<<31 | 0<<29 | 0x0d<<24 | 1<<10,
+		// CRC
+		"CRC32B": 0<<31 | 0<<29 | 0x1b<<24 | 4<<10,
+		"CRC32H": 0<<31 | 0<<29 | 0x1b<<24 | 5<<10,
+		"CRC32W": 0<<31 | 0<<29 | 0x1b<<24 | 6<<10,
+		"CRC32X": 1<<31 | 0<<29 | 0x1b<<24 | 7<<10,
+		// Conditional select
+		"CSEL":   1<<31 | 0<<29 | 0x1d<<24 | 0<<10,
+		"CSELW":  0<<31 | 0<<29 | 0x1d<<24 | 0<<10,
+		"CSINC":  1<<31 | 0<<29 | 0x1d<<24 | 1<<10,
+		"CSINCW": 0<<31 | 0<<29 | 0x1d<<24 | 1<<10,
+		"CSINV":  1<<31 | 0<<29 | 0x1d<<24 | 2<<10,
+		"CSINVW": 0<<31 | 0<<29 | 0x1d<<24 | 2<<10,
+		"CSNEG":  1<<31 | 0<<29 | 0x1d<<24 | 3<<10,
+		"CSNEGW": 0<<31 | 0<<29 | 0x1d<<24 | 3<<10,
+	}
+	for m, op := range dpsr {
+		a64InstrTable[m] = a64Enc{format: a64FDPSR, op: op}
+	}
+
+	// Aliases that map to the same encoding as their target.
+	a64InstrTable["CMP"] = a64Enc{format: a64FDPSR, op: dpsr["SUBS"]}
+	a64InstrTable["CMPW"] = a64Enc{format: a64FDPSR, op: dpsr["SUBSW"]}
+	a64InstrTable["CMN"] = a64Enc{format: a64FDPSR, op: dpsr["ADDS"]}
+	a64InstrTable["CMNW"] = a64Enc{format: a64FDPSR, op: dpsr["ADDSW"]}
+	a64InstrTable["TST"] = a64Enc{format: a64FDPSR, op: dpsr["ANDS"]}
+	a64InstrTable["TSTW"] = a64Enc{format: a64FDPSR, op: dpsr["ANDSW"]}
+	a64InstrTable["NEG"] = a64Enc{format: a64FDPSR, op: dpsr["SUB"]}
+	a64InstrTable["NEGW"] = a64Enc{format: a64FDPSR, op: dpsr["SUBW"]}
+	a64InstrTable["NEGS"] = a64Enc{format: a64FDPSR, op: dpsr["SUBS"]}
+	a64InstrTable["MVN"] = a64Enc{format: a64FDPSR, op: dpsr["ORN"]}
+	a64InstrTable["MVNW"] = a64Enc{format: a64FDPSR, op: dpsr["ORNW"]}
+	a64InstrTable["MOV"] = a64Enc{format: a64FDPSR, op: dpsr["ORR"]}
+	a64InstrTable["MOVW"] = a64Enc{format: a64FDPSR, op: dpsr["ORRW"]}
+
+	// ---- data-processing (immediate) ----
+	// ADD/SUB $imm, Rn, Rd
+	a64InstrTable["ADDImm"] = a64Enc{format: a64FDPIR, op: 1<<31 | 0<<30 | 0<<29 | 0x11<<24}
+	a64InstrTable["ADDWImm"] = a64Enc{format: a64FDPIR, op: 0<<31 | 0<<30 | 0<<29 | 0x11<<24}
+	a64InstrTable["SUBImm"] = a64Enc{format: a64FDPIR, op: 1<<31 | 1<<30 | 0<<29 | 0x11<<24}
+	a64InstrTable["SUBWImm"] = a64Enc{format: a64FDPIR, op: 0<<31 | 1<<30 | 0<<29 | 0x11<<24}
+	a64InstrTable["ADDSImm"] = a64Enc{format: a64FDPIR, op: 1<<31 | 0<<30 | 1<<29 | 0x11<<24}
+	a64InstrTable["SUBSImm"] = a64Enc{format: a64FDPIR, op: 1<<31 | 1<<30 | 1<<29 | 0x11<<24}
+
+	// ---- move wide ----
+	// MOVZ/MOVN/MOVK
+	a64InstrTable["MOVZ"] = a64Enc{format: a64FMovWide, op: 1<<31 | 2<<29 | 0x25<<23}
+	a64InstrTable["MOVZW"] = a64Enc{format: a64FMovWide, op: 0<<31 | 2<<29 | 0x25<<23}
+	a64InstrTable["MOVN"] = a64Enc{format: a64FMovWide, op: 1<<31 | 0<<29 | 0x25<<23}
+	a64InstrTable["MOVNW"] = a64Enc{format: a64FMovWide, op: 0<<31 | 0<<29 | 0x25<<23}
+	a64InstrTable["MOVK"] = a64Enc{format: a64FMovWide, op: 1<<31 | 3<<29 | 0x25<<23}
+	a64InstrTable["MOVKW"] = a64Enc{format: a64FMovWide, op: 0<<31 | 3<<29 | 0x25<<23}
+
+	// ---- ADR/ADRP ----
+	a64InstrTable["ADR"] = a64Enc{format: a64FADR, op: 0}
+	a64InstrTable["ADRP"] = a64Enc{format: a64FADR, op: 1}
+
+	// ---- load/store (unsigned immediate) ----
+	a64InstrTable["MOVD"] = a64Enc{format: a64FLSU, op: 3<<30 | 7<<27 | 1<<22}          // LDR 64-bit
+	a64InstrTable["MOVWU"] = a64Enc{format: a64FLSU, op: 2<<30 | 7<<27 | 1<<22}         // LDR 32-bit unsigned
+	a64InstrTable["MOVHU"] = a64Enc{format: a64FLSU, op: 1<<30 | 7<<27 | 1<<22}         // LDRH unsigned
+	a64InstrTable["MOVBU"] = a64Enc{format: a64FLSU, op: 0<<30 | 7<<27 | 1<<22}         // LDRB unsigned
+	a64InstrTable["MOVW"] = a64Enc{format: a64FLSU, op: 2<<30 | 7<<27 | 2<<22}          // LDRSW (signed 32→64)
+	a64InstrTable["MOVH"] = a64Enc{format: a64FLSU, op: 1<<30 | 7<<27 | 2<<22}          // LDRSH (signed half)
+	a64InstrTable["MOVB"] = a64Enc{format: a64FLSU, op: 0<<30 | 7<<27 | 2<<22}          // LDRSB (signed byte)
+	a64InstrTable["FMOVS"] = a64Enc{format: a64FLSU, op: 2<<30 | 7<<27 | 1<<26 | 1<<22} // FLDR 32-bit FP
+	a64InstrTable["FMOVD"] = a64Enc{format: a64FLSU, op: 3<<30 | 7<<27 | 1<<26 | 1<<22} // FLDR 64-bit FP
+
+	// Store opcodes (load ^ (1<<22)):
+	// STR 64-bit: size=3, V=0, opc=00 → 3<<30 | 7<<27 | 0<<22
+	// STR 32-bit: size=2, V=0, opc=00 → 2<<30 | 7<<27 | 0<<22
+	// STRH:      size=1, V=0, opc=00 → 1<<30 | 7<<27 | 0<<22
+	// STRB:      size=0, V=0, opc=00 → 0<<30 | 7<<27 | 0<<22
+
+	// ---- branches ----
+	a64InstrTable["B"] = a64Enc{format: a64FBranch, op: 0<<31 | 5<<26}
+	a64InstrTable["BL"] = a64Enc{format: a64FBranch, op: 1<<31 | 5<<26}
+
+	// Conditional branches.
+	condBranches := map[string]uint32{
+		"BEQ": 0x0, "BNE": 0x1, "BCS": 0x2, "BHS": 0x2,
+		"BCC": 0x3, "BLO": 0x3, "BMI": 0x4, "BPL": 0x5,
+		"BVS": 0x6, "BVC": 0x7, "BHI": 0x8, "BLS": 0x9,
+		"BGE": 0xa, "BLT": 0xb, "BGT": 0xc, "BLE": 0xd,
+	}
+	for name, cond := range condBranches {
+		a64InstrTable[name] = a64Enc{format: a64FBranchCond, op: 0x2A<<25 | cond}
+	}
+
+	// Unconditional branch register (BR/BLR/RET).
+	a64InstrTable["BR"] = a64Enc{format: a64FUncondBranch, op: 0x6B<<25 | 0<<21}
+	a64InstrTable["BLR"] = a64Enc{format: a64FUncondBranch, op: 0x6B<<25 | 1<<21}
+	a64InstrTable["RET"] = a64Enc{format: a64FUncondBranch, op: 0x6B<<25 | 2<<21}
+
+	// ---- system ----
+	a64InstrTable["NOP"] = a64Enc{format: a64FSystem, op: a64NOP}
+	a64InstrTable["NOOP"] = a64Enc{format: a64FSystem, op: a64NOP}
+	a64InstrTable["BRK"] = a64Enc{format: a64FSystem, op: 0xd4200000}
+	a64InstrTable["UNDEF"] = a64Enc{format: a64FSystem, op: a64BRK(0)}
+
+	// ---- EXTR ----
+	a64InstrTable["EXTR"] = a64Enc{format: a64FEXTR, op: 1<<31 | 0x27<<23 | 1<<22}
+	a64InstrTable["EXTRW"] = a64Enc{format: a64FEXTR, op: 0<<31 | 0x27<<23 | 0<<22}
+
+	// ---- bitfield ----
+	a64InstrTable["BFM"] = a64Enc{format: a64FBitfield, op: 1<<31 | 1<<29 | 0x26<<23 | 1<<22}
+	a64InstrTable["BFMW"] = a64Enc{format: a64FBitfield, op: 0<<31 | 1<<29 | 0x26<<23 | 0<<22}
+	a64InstrTable["SBFM"] = a64Enc{format: a64FBitfield, op: 1<<31 | 0<<29 | 0x26<<23 | 1<<22}
+	a64InstrTable["SBFMW"] = a64Enc{format: a64FBitfield, op: 0<<31 | 0<<29 | 0x26<<23 | 0<<22}
+	a64InstrTable["UBFM"] = a64Enc{format: a64FBitfield, op: 1<<31 | 2<<29 | 0x26<<23 | 1<<22}
+	a64InstrTable["UBFMW"] = a64Enc{format: a64FBitfield, op: 0<<31 | 2<<29 | 0x26<<23 | 0<<22}
+	a64InstrTable["BFI"] = a64Enc{format: a64FBitfield, op: 1<<31 | 2<<29 | 0x26<<23 | 1<<22}
+	a64InstrTable["BFIW"] = a64Enc{format: a64FBitfield, op: 0<<31 | 2<<29 | 0x26<<23 | 0<<22}
+	a64InstrTable["BFXIL"] = a64Enc{format: a64FBitfield, op: 1<<31 | 1<<29 | 0x26<<23 | 1<<22}
+	a64InstrTable["BFXILW"] = a64Enc{format: a64FBitfield, op: 0<<31 | 1<<29 | 0x26<<23 | 0<<22}
+
+	// ---- FP 3-operand (Rm, Rn, Rd): FADD, FSUB, FMUL, FDIV, FMAX, FMIN, FNMUL ----
+	fp3 := map[string]uint32{
+		"FADDS": 0x1e202800, "FADDD": 0x1e602800,
+		"FSUBS": 0x1e203800, "FSUBD": 0x1e603800,
+		"FMULS": 0x1e200800, "FMULD": 0x1e600800,
+		"FDIVS": 0x1e201800, "FDIVD": 0x1e601800,
+		"FMAXS": 0x1e204800, "FMAXD": 0x1e604800,
+		"FMINS": 0x1e205800, "FMIND": 0x1e605800,
+		"FMAXNMS": 0x1e206800, "FMAXNMD": 0x1e606800,
+		"FMINNMS": 0x1e207800, "FMINNMD": 0x1e607800,
+		"FNMULS": 0x1e208800, "FNMULD": 0x1e608800,
+	}
+	for m, op := range fp3 {
+		a64InstrTable[m] = a64Enc{format: a64FFP3, op: op}
+	}
+
+	// ---- FP unary (Rn, Rd): FMOV reg-reg, FABS, FNEG, FSQRT, FCVT, FRINT* ----
+	fp1 := map[string]uint32{
+		"FMOVS": 0x1e204000, "FMOVD": 0x1e604000,
+		"FABSS": 0x1e20c000, "FABSD": 0x1e60c000,
+		"FNEGS": 0x1e214000, "FNEGD": 0x1e614000,
+		"FSQRTS": 0x1e21c000, "FSQRTD": 0x1e61c000,
+		"FCVTSD": 0x1e22c000, "FCVTDS": 0x1e624000,
+		"FRINTNS": 0x1e244000, "FRINTND": 0x1e644000,
+		"FRINTPS": 0x1e24c000, "FRINTPD": 0x1e64c000,
+		"FRINTMS": 0x1e254000, "FRINTMD": 0x1e654000,
+		"FRINTZS": 0x1e25c000, "FRINTZD": 0x1e65c000,
+		"FRINTAS": 0x1e264000, "FRINTAD": 0x1e664000,
+		"FRINTXS": 0x1e274000, "FRINTXD": 0x1e674000,
+		"FRINTIS": 0x1e27c000, "FRINTID": 0x1e67c000,
+	}
+	for m, op := range fp1 {
+		a64InstrTable[m] = a64Enc{format: a64FFPUnary, op: op}
+	}
+
+	// ---- FP 4-operand FMA (Ra, Rm, Rn, Rd) ----
+	fp4 := map[string]uint32{
+		"FMADDS": 0x1f000000, "FMADDD": 0x1f400000,
+		"FMSUBS": 0x1f008000, "FMSUBD": 0x1f408000,
+		"FNMADDS": 0x1f200000, "FNMADDD": 0x1f600000,
+		"FNMSUBS": 0x1f208000, "FNMSUBD": 0x1f608000,
+	}
+	for m, op := range fp4 {
+		a64InstrTable[m] = a64Enc{format: a64FFP4, op: op}
+	}
+
+	// ---- FP compare (Rm, Rn or #0, Rn) ----
+	fpcmp := map[string]uint32{
+		"FCMPS": 0x1e202000, "FCMPD": 0x1e602000,
+		"FCMPES": 0x1e202010, "FCMPED": 0x1e602010,
+	}
+	for m, op := range fpcmp {
+		a64InstrTable[m] = a64Enc{format: a64FFPCmp, op: op}
+	}
+
+	// ---- FP conditional compare (Rm, Rn, #nzcv, cond) ----
+	fpccmp := map[string]uint32{
+		"FCCMPS": 0x1e200400, "FCCMPD": 0x1e600400,
+		"FCCMPES": 0x1e200410, "FCCMPED": 0x1e600410,
+	}
+	for m, op := range fpccmp {
+		a64InstrTable[m] = a64Enc{format: a64FFPCCmp, op: op}
+	}
+
+	// ---- FP conditional select (Rm, Rn, Rd, cond) ----
+	a64InstrTable["FCSELS"] = a64Enc{format: a64FFPSel, op: 0x1e200c00}
+	a64InstrTable["FCSELD"] = a64Enc{format: a64FFPSel, op: 0x1e600c00}
+
+	// ---- FP ↔ integer conversion ----
+	fpcvt := map[string]uint32{
+		"FCVTZSD": 0x9e780000, "FCVTZSDW": 0x1e780000,
+		"FCVTZSS": 0x9e380000, "FCVTZSSW": 0x1e380000,
+		"FCVTZUD": 0x9e790000, "FCVTZUDW": 0x1e790000,
+		"FCVTZUS": 0x9e390000, "FCVTZUSW": 0x1e390000,
+		"SCVTFD": 0x9e620000, "SCVTFS": 0x9e220000,
+		"SCVTFWD": 0x1e620000, "SCVTFWS": 0x1e220000,
+		"UCVTFD": 0x9e630000, "UCVTFS": 0x9e230000,
+		"UCVTFWD": 0x1e630000, "UCVTFWS": 0x1e230000,
+	}
+	for m, op := range fpcvt {
+		a64InstrTable[m] = a64Enc{format: a64FFPCvt, op: op}
+	}
+
+	// ---- FMOV between GP and FP registers ----
+	a64InstrTable["FMOVGR"] = a64Enc{format: a64FFMovGR, op: 0x1e260000} // placeholder, actual encoding depends on direction
+
+	// ---- conditional select: CSEL, CSINC, CSINV, CSNEG ----
+	csel := map[string]uint32{
+		"CSEL": 0x9a800000, "CSELW": 0x1a800000,
+		"CSINC": 0x9a800400, "CSINCW": 0x1a800400,
+		"CSINV": 0xda800000, "CSINVW": 0x5a800000,
+		"CSNEG": 0xda800400, "CSNEGW": 0x5a800400,
+	}
+	for m, op := range csel {
+		a64InstrTable[m] = a64Enc{format: a64FCSEL, op: op}
+	}
+	// Aliases
+	a64InstrTable["CSET"] = a64Enc{format: a64FCSEL, op: 0x9a800400}
+	a64InstrTable["CSETW"] = a64Enc{format: a64FCSEL, op: 0x1a800400}
+	a64InstrTable["CSETM"] = a64Enc{format: a64FCSEL, op: 0xda800000}
+	a64InstrTable["CSETMW"] = a64Enc{format: a64FCSEL, op: 0x5a800000}
+	a64InstrTable["CINC"] = a64Enc{format: a64FCSEL, op: 0x9a800400}
+	a64InstrTable["CINCW"] = a64Enc{format: a64FCSEL, op: 0x1a800400}
+	a64InstrTable["CINV"] = a64Enc{format: a64FCSEL, op: 0xda800000}
+	a64InstrTable["CINVW"] = a64Enc{format: a64FCSEL, op: 0x5a800000}
+	a64InstrTable["CNEG"] = a64Enc{format: a64FCSEL, op: 0xda800400}
+	a64InstrTable["CNEGW"] = a64Enc{format: a64FCSEL, op: 0x5a800400}
+
+	// ---- CRC32 ----
+	crc32 := map[string]uint32{
+		"CRC32B": 0x1ac04000, "CRC32H": 0x1ac04400,
+		"CRC32W": 0x1ac04800, "CRC32X": 0x9ac04c00,
+		"CRC32CB": 0x1ac05000, "CRC32CH": 0x1ac05400,
+		"CRC32CW": 0x1ac05800, "CRC32CX": 0x9ac05c00,
+	}
+	for m, op := range crc32 {
+		a64InstrTable[m] = a64Enc{format: a64FCRC32, op: op}
+	}
+
+	// ---- exclusive load/store ----
+	a64InstrTable["LDXR"] = a64Enc{format: a64FExcl, op: 0xc85f7c00}
+	a64InstrTable["LDXRB"] = a64Enc{format: a64FExcl, op: 0x085f7c00}
+	a64InstrTable["LDXRH"] = a64Enc{format: a64FExcl, op: 0x485f7c00}
+	a64InstrTable["LDXRW"] = a64Enc{format: a64FExcl, op: 0x885f7c00}
+	a64InstrTable["LDAXR"] = a64Enc{format: a64FExcl, op: 0xc85ffc00}
+	a64InstrTable["LDAXRB"] = a64Enc{format: a64FExcl, op: 0x085ffc00}
+	a64InstrTable["LDAXRH"] = a64Enc{format: a64FExcl, op: 0x485ffc00}
+	a64InstrTable["LDAXRW"] = a64Enc{format: a64FExcl, op: 0x885ffc00}
+	a64InstrTable["STXR"] = a64Enc{format: a64FExcl, op: 0xc8007c00}
+	a64InstrTable["STXRB"] = a64Enc{format: a64FExcl, op: 0x08007c00}
+	a64InstrTable["STXRH"] = a64Enc{format: a64FExcl, op: 0x48007c00}
+	a64InstrTable["STXRW"] = a64Enc{format: a64FExcl, op: 0x88007c00}
+	a64InstrTable["STLXR"] = a64Enc{format: a64FExcl, op: 0xc800fc00}
+	a64InstrTable["STLXRB"] = a64Enc{format: a64FExcl, op: 0x0800fc00}
+	a64InstrTable["STLXRH"] = a64Enc{format: a64FExcl, op: 0x4800fc00}
+	a64InstrTable["STLXRW"] = a64Enc{format: a64FExcl, op: 0x8800fc00}
+
+	// ---- LSE atomics ----
+	a64InstrTable["LDADDD"] = a64Enc{format: a64FLSE, op: 3<<30 | 0x1c1<<21 | 0x00<<10}
+	a64InstrTable["LDADDW"] = a64Enc{format: a64FLSE, op: 2<<30 | 0x1c1<<21 | 0x00<<10}
+	a64InstrTable["LDADDB"] = a64Enc{format: a64FLSE, op: 0<<30 | 0x1c1<<21 | 0x00<<10}
+	a64InstrTable["LDADDH"] = a64Enc{format: a64FLSE, op: 1<<30 | 0x1c1<<21 | 0x00<<10}
+	a64InstrTable["CASD"] = a64Enc{format: a64FLSE, op: 3<<30 | 0x45<<21 | 0x1f<<10}
+	a64InstrTable["CASW"] = a64Enc{format: a64FLSE, op: 2<<30 | 0x45<<21 | 0x1f<<10}
+	a64InstrTable["SWPD"] = a64Enc{format: a64FLSE, op: 3<<30 | 0x1c1<<21 | 0x20<<10}
+	a64InstrTable["SWPW"] = a64Enc{format: a64FLSE, op: 2<<30 | 0x1c1<<21 | 0x20<<10}
+
+	// ---- SIMD basics ----
+	a64InstrTable["VADD"] = a64Enc{format: a64FSIMD3, op: 0x0e208400}
+	a64InstrTable["VSUB"] = a64Enc{format: a64FSIMD3, op: 0x2e208400}
+	a64InstrTable["VMUL"] = a64Enc{format: a64FSIMD3, op: 0x0e209c00}
+}
+
+// ---- load/store helper tables ----
+
+// a64LSType describes the load/store parameters for a MOV width mnemonic.
+type a64LSType struct {
+	size int // 0=byte, 1=half, 2=word, 3=dword
+	V    int // 0=integer, 1=FP
+	opc  int // 00=store/unsigned load, 01=store FP, 10=signed load, 11=load FP
+}
+
+// a64LoadTable maps MOV width mnemonics to their load/store encoding parameters.
+// For loads, opc selects signed vs unsigned; for stores, we flip the opc.
+var a64LoadTable = map[string]a64LSType{
+	"MOVD":  {3, 0, 1}, // LDR X (64-bit, unsigned offset)
+	"MOVWU": {2, 0, 1}, // LDR W (32-bit unsigned)
+	"MOVW":  {2, 0, 2}, // LDRSW (32-bit signed → 64-bit)
+	"MOVHU": {1, 0, 1}, // LDRH (16-bit unsigned)
+	"MOVH":  {1, 0, 2}, // LDRSH (16-bit signed)
+	"MOVBU": {0, 0, 1}, // LDRB (8-bit unsigned)
+	"MOVB":  {0, 0, 2}, // LDRSB (8-bit signed)
+	"FMOVS": {2, 1, 1}, // LDR S (32-bit FP)
+	"FMOVD": {3, 1, 1}, // LDR D (64-bit FP)
+}
+
+// a64StoreOpc returns the store opc for a given load type.
+// For integer: store opc = 00 (the load opc bits cleared).
+// For FP: store opc = 00 (same pattern).
+func a64StoreOpc(t a64LSType) int {
+	if t.V == 1 {
+		return 0 // FP store
+	}
+	return 0 // integer store
+}
+
+// arm64RegClass discriminates integer (R), floating-point (F) registers for
+// the MOV pseudo-instruction.
+type arm64RegClass int
+
+const (
+	arm64ClsNone arm64RegClass = iota
+	arm64ClsGR
+	arm64ClsFP
+)
+
+// arm64RegClassOf reports the register class of a register operand name.
+func arm64RegClassOf(name string) arm64RegClass {
+	switch {
+	case name == "":
+		return arm64ClsNone
+	case len(name) >= 1 && name[0] == 'F':
+		return arm64ClsFP
+	default:
+		return arm64ClsGR
+	}
+}
+
+// arm64Movcon returns the shift (in units of 16 bits) at which a non-zero
+// 16-bit chunk of v sits, or -1 if v cannot be represented as a single
+// MOVZ/MOVN immediate.  This is the Go toolchain's movcon function.
+func arm64Movcon(v int64) int {
+	for s := 0; s < 64; s += 16 {
+		if (uint64(v) &^ (uint64(0xFFFF) << uint(s))) == 0 {
+			return s
+		}
+	}
+	return -1
+}

asm/arm64_encode_test.go

@@ -0,0 +1,574 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/ast"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+func TestArm64LDRSTREncoding(t *testing.T) {
+	tests := []struct {
+		name string
+		got  uint32
+		want uint32
+	}{
+		{"LDR X4, [SP, #56]", a64LSU(3, 0, 1, 7, 31, 4), 0xf9401fe4},
+		{"STR X4, [SP, #64]", a64LSU(3, 0, 0, 8, 31, 4), 0xf90023e4},
+		{"STR X5, [SP, #32]", a64LSU(3, 0, 0, 4, 31, 5), 0xf90013e5},
+		{"LDR X6, [SP, #32]", a64LSU(3, 0, 1, 4, 31, 6), 0xf94013e6},
+	}
+	for _, tt := range tests {
+		if tt.got != tt.want {
+			t.Errorf("%s: got %08x, want %08x", tt.name, tt.got, tt.want)
+		}
+	}
+}
+
+func TestArm64PrologueEncoding(t *testing.T) {
+	fi := arm64FrameInfo{autosize: 48, frame: 32, leaf: false}
+	pro := arm64Prologue(fi)
+	if len(pro) != 12 {
+		t.Fatalf("prologue length: got %d, want 12", len(pro))
+	}
+	expected := []uint32{0xf81d0ffe, 0xf81f83fd, 0xd10023fd}
+	for i, w := range leWords(pro) {
+		if w != expected[i] {
+			t.Errorf("prologue word %d: got %08x, want %08x", i, w, expected[i])
+		}
+	}
+}
+
+func TestArm64EpilogueSmallEncoding(t *testing.T) {
+	fi := arm64FrameInfo{autosize: 48, frame: 32, leaf: false}
+	ret := arm64Return(fi)
+	if len(ret) != 12 {
+		t.Fatalf("epilogue length: got %d, want 12", len(ret))
+	}
+	// Non-leaf small frame: LDR FP, [SP, #-8]; LDR.P LR, [SP], #48; RET
+	expected := []uint32{0xf85f83fd, 0xf84307fe, 0xd65f03c0}
+	for i, w := range leWords(ret) {
+		if w != expected[i] {
+			t.Errorf("epilogue word %d: got %08x, want %08x", i, w, expected[i])
+		}
+	}
+}
+
+func TestArm64LargeFrameEncoding(t *testing.T) {
+	fi := arm64FrameInfo{autosize: 272, frame: 256, leaf: false}
+	pro := arm64Prologue(fi)
+	if len(pro) != 16 {
+		t.Fatalf("prologue length: got %d, want 16", len(pro))
+	}
+	expected := []uint32{0xd10443f4, 0xa93ffa9d, 0x9100029f, 0xd10023fd}
+	for i, w := range leWords(pro) {
+		if w != expected[i] {
+			t.Errorf("prologue word %d: got %08x, want %08x", i, w, expected[i])
+		}
+	}
+
+	epi := arm64Return(fi)
+	if len(epi) != 12 {
+		t.Fatalf("epilogue length: got %d, want 12", len(epi))
+	}
+	eexpected := []uint32{0xa97ffbfd, 0x910443ff, 0xd65f03c0}
+	for i, w := range leWords(epi) {
+		if w != eexpected[i] {
+			t.Errorf("epilogue word %d: got %08x, want %08x", i, w, eexpected[i])
+		}
+	}
+}
+
+func TestArm64NoFrame(t *testing.T) {
+	fi := arm64FrameInfo{autosize: 0, frame: 0, leaf: true}
+	pro := arm64Prologue(fi)
+	if len(pro) != 0 {
+		t.Errorf("no-frame prologue: got %d bytes, want 0", len(pro))
+	}
+	ret := arm64Return(fi)
+	if len(ret) != 4 {
+		t.Fatalf("no-frame return: got %d bytes, want 4", len(ret))
+	}
+	if leWord(ret) != 0xd65f03c0 {
+		t.Errorf("no-frame RET: got %08x, want d65f03c0", leWord(ret))
+	}
+}
+
+func TestArm64RegNum(t *testing.T) {
+	tests := []struct {
+		name string
+		want int
+	}{
+		{"R0", 0}, {"R4", 4}, {"R29", 29}, {"R30", 30}, {"R31", 31},
+		{"FP", 29}, {"LR", 30}, {"LINK", 30}, {"SP", 31}, {"ZR", 31},
+		{"F0", 0}, {"F4", 4}, {"F31", 31},
+		{"INVALID", -1}, {"X0", -1}, {"", -1},
+	}
+	for _, tt := range tests {
+		got := arm64RegNum(tt.name)
+		if got != tt.want {
+			t.Errorf("arm64RegNum(%q) = %d, want %d", tt.name, got, tt.want)
+		}
+	}
+}
+
+func TestArm64ComputeFrame(t *testing.T) {
+	src := "TEXT ·f(SB), NOSPLIT, $32-0\n\tADD\tR4, R5\n\tRET\n"
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	fi := arm64ComputeFrame(f.Decls[0].(*ast.Text))
+	if fi.frame != 32 {
+		t.Errorf("frame: got %d, want 32", fi.frame)
+	}
+	if fi.autosize != 48 { // 32+8=40, aligned to48
+		t.Errorf("autosize: got %d, want 48", fi.autosize)
+	}
+	// ADD + RET with no CALL/BL → leaf
+	if !fi.leaf {
+		t.Error("expected leaf")
+	}
+}
+
+func TestArm64IsLeaf(t *testing.T) {
+	src := "TEXT ·f(SB), NOSPLIT, $0-0\n\tADD\tR4, R5\n\tRET\n"
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	if !arm64IsLeaf(f.Decls[0].(*ast.Text)) {
+		t.Error("expected leaf")
+	}
+
+	src2 := "TEXT ·f(SB), NOSPLIT, $0-0\n\tBL\tother(SB)\n\tRET\n"
+	f2, errs := parser.Parse("test_arm64.s", src2)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	if arm64IsLeaf(f2.Decls[0].(*ast.Text)) {
+		t.Error("expected non-leaf")
+	}
+}
+
+func TestArm64Bitmask(t *testing.T) {
+	tests := []struct {
+		v             uint64
+		sf            int
+		N, immr, imms uint32
+		ok            bool
+	}{
+		{1, 1, 1, 0, 0, true},                     // single bit at pos 0
+		{2, 1, 1, 63, 0, true},                    // single bit at pos 1 (immr = esize-1)
+		{0, 1, 0, 0, 0, false},                    // zero is not a bitmask
+		{0xFFFFFFFFFFFFFFFF, 1, 0, 0, 0, false},   // all ones is not a bitmask
+		{0x5555555555555555, 1, 0, 0, 0x3E, true}, // alternating bits (esize=2, ones=1)
+		{0xFFFFFFFF00000000, 1, 1, 32, 31, true},  // upper 32 bits set (esize=64, ones=32)
+	}
+	for _, tt := range tests {
+		N, immr, imms, ok := arm64Bitmask(tt.v, tt.sf)
+		if ok != tt.ok {
+			t.Errorf("arm64Bitmask(%#x, %d): ok=%v, want %v", tt.v, tt.sf, ok, tt.ok)
+			continue
+		}
+		if ok && (N != tt.N || immr != tt.immr || imms != tt.imms) {
+			t.Errorf("arm64Bitmask(%#x, %d): N=%d immr=%d imms=%d, want N=%d immr=%d imms=%d",
+				tt.v, tt.sf, N, immr, imms, tt.N, tt.immr, tt.imms)
+		}
+	}
+}
+
+func TestArm64AssembleFile(t *testing.T) {
+	src := `#include "textflag.h"
+
+TEXT ·simple(SB), NOSPLIT, $0-0
+	MOV	R4, R5
+	ADD	R4, R5, R6
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	if len(img.Funcs) != 1 {
+		t.Fatalf("got %d funcs, want 1", len(img.Funcs))
+	}
+	fn := img.Funcs[0]
+	if fn.Name != "simple" {
+		t.Errorf("func name: got %q, want %q", fn.Name, "simple")
+	}
+	//3 instructions ×4 bytes =12
+	if fn.Size != 12 {
+		t.Errorf("func size: got %d, want 12", fn.Size)
+	}
+}
+
+func TestArm64AssembleFileWithFrame(t *testing.T) {
+	src := `#include "textflag.h"
+
+TEXT ·framed(SB), NOSPLIT, $16-8
+	MOVD	arg+0(FP), R4
+	ADD	$1, R4, R4
+	MOVD	R4, ret+0(FP)
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	if len(img.Funcs) != 1 {
+		t.Fatalf("got %d funcs, want 1", len(img.Funcs))
+	}
+	fn := img.Funcs[0]
+	if fn.Frame != 16 {
+		t.Errorf("frame: got %d, want 16", fn.Frame)
+	}
+	// Prologue (3×4=12) + body (3×4=12) + RET epilogue (3×4=12) = 36
+	if fn.Size != 36 {
+		t.Errorf("func size: got %d, want 36", fn.Size)
+	}
+}
+
+func TestArm64AssembleFileWithBranches(t *testing.T) {
+	src := `#include "textflag.h"
+
+TEXT ·branch(SB), NOSPLIT, $0-0
+	BEQ	done
+	BNE	skip
+skip:
+	ADD	R4, R5
+done:
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	fn := img.Funcs[0]
+	if fn.Size != 16 {
+		t.Errorf("func size: got %d, want 16", fn.Size)
+	}
+}
+
+func TestArm64AssembleFileWithJumpChain(t *testing.T) {
+	src := `#include "textflag.h"
+
+TEXT ·chain(SB), NOSPLIT, $0-0
+	BNE	skip
+	ADD	R4, R5
+	RET
+skip:
+	B	target
+target:
+	ADD	R6, R7
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	// BNE should be redirected past skip→target to target directly.
+	if img.Funcs[0].Size != 24 {
+		t.Errorf("func size: got %d, want 24", img.Funcs[0].Size)
+	}
+}
+
+func TestArm64AssembleErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		src  string
+	}{
+		{"unsupported", "TEXT ·f(SB), NOSPLIT, $0-0\n\tINVALID\tR4, R5\n\tRET\n"},
+		{"undefined label", "TEXT ·f(SB), NOSPLIT, $0-0\n\tB\tnosuch\n\tRET\n"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, errs := parser.Parse("test_arm64.s", tt.src)
+			if len(errs) > 0 {
+				return // parse error, that's fine
+			}
+			_, err := AssembleFileARM64(f)
+			if err == nil {
+				t.Error("expected error, got nil")
+			}
+		})
+	}
+}
+
+func TestArm64Movcon(t *testing.T) {
+	tests := []struct {
+		v    int64
+		want int
+	}{
+		{0, 0},            // 0 fits at shift 0
+		{1, 0},            // single bit at shift 0
+		{0x10000, 16},     // single bit at shift 16
+		{0x100000000, 32}, // single bit at shift 32
+		{0xFF, 0},         // 0xFF fits at shift 0
+		{0x12345, -1},     // multiple chunks, not movcon
+	}
+	for _, tt := range tests {
+		got := arm64Movcon(tt.v)
+		if got != tt.want {
+			t.Errorf("arm64Movcon(%#x) = %d, want %d", tt.v, got, tt.want)
+		}
+	}
+}
+
+func TestArm64RegClassOf(t *testing.T) {
+	if arm64RegClassOf("R4") != arm64ClsGR {
+		t.Error("R4 should be GR")
+	}
+	if arm64RegClassOf("F4") != arm64ClsFP {
+		t.Error("F4 should be FP")
+	}
+	if arm64RegClassOf("") != arm64ClsNone {
+		t.Error("empty should be None")
+	}
+}
+
+func TestArm64ResolvePseudo(t *testing.T) {
+	fi := arm64FrameInfo{autosize: 48, frame: 32}
+	// FP: offset = sym.Offset + autosize +8
+	base, off := arm64ResolvePseudo(&ast.Symbol{Pseudo: "FP", Offset: 0}, fi)
+	if base != 31 || off != 56 {
+		t.Errorf("FP: base=%d off=%d, want 31, 56", base, off)
+	}
+	// SP: offset = sym.Offset + frame +8
+	base, off = arm64ResolvePseudo(&ast.Symbol{Pseudo: "SP", Offset: -8}, fi)
+	if base != 31 || off != 32 {
+		t.Errorf("SP: base=%d off=%d, want 31, 32", base, off)
+	}
+	// SB: unresolved
+	base, _ = arm64ResolvePseudo(&ast.Symbol{Pseudo: "SB"}, fi)
+	if base != -1 {
+		t.Errorf("SB: base=%d, want -1", base)
+	}
+}
+
+// TestArm64FPSel tests FP conditional select encoding.
+func TestArm64FPSel(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	FCSELD	GE, F10, F11, F12
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	// FCSELD should be 4 bytes + RET 4 bytes = 8
+	if img.Funcs[0].Size != 8 {
+		t.Errorf("size: got %d, want 8", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64FPCvt tests FP conversion encoding.
+func TestArm64FPCvt(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	FCVTZSD	F4, R0
+	SCVTFD	R4, F8
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	if img.Funcs[0].Size != 12 {
+		t.Errorf("size: got %d, want 12", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64CSEL tests conditional select encoding.
+func TestArm64CSEL(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	CSEL	EQ, R0, R1, R2
+	CSET	NE, R3
+	CINC	GE, R4, R5
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	if img.Funcs[0].Size != 16 {
+		t.Errorf("size: got %d, want 16", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64CRC32 tests CRC32 encoding.
+func TestArm64CRC32(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	CRC32B	R0, R2
+	CRC32W	R6, R8
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	if img.Funcs[0].Size != 12 {
+		t.Errorf("size: got %d, want 12", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64Bitfield tests bitfield/shift encoding.
+func TestArm64Bitfield(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	ASR	$4, R0, R1
+	LSL	$12, R4, R5
+	EXTR	$8, R0, R1, R2
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	if img.Funcs[0].Size != 16 {
+		t.Errorf("size: got %d, want 16", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64SIMD tests SIMD encoding (via the instruction table).
+func TestArm64SIMD(t *testing.T) {
+	// Verify SIMD instructions are in the table.
+	for _, mnem := range []string{"VADD", "VSUB", "VMUL"} {
+		if _, ok := a64InstrTable[mnem]; !ok {
+			t.Errorf("%s not in instruction table", mnem)
+		}
+	}
+}
+
+// TestArm64LoadImm64 tests 64-bit immediate loading.
+func TestArm64LoadImm64(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	MOVD	$0x123456789ABCDEF0, R0
+	MOVD	$0, R1
+	MOVD	$1, R2
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	// $0x123456789ABCDEF0 needs 4 MOVZ/MOVK instructions (16 bytes)
+	// $0 is 1 instruction (4 bytes)
+	// $1 is 1 bitmask instruction (4 bytes)
+	// RET is 1 instruction (4 bytes)
+	if img.Funcs[0].Size != 28 {
+		t.Errorf("size: got %d, want 28", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64BranchCond tests conditional branch encoding.
+func TestArm64BranchCond(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·f(SB), NOSPLIT, $0-0
+	BEQ	done
+	BNE	done
+	BGE	done
+	BLT	done
+	ADD	R4, R5
+done:
+	RET
+`
+	f, errs := parser.Parse("test_arm64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	// 4 branches + 1 ADD + 1 RET = 24 bytes
+	if img.Funcs[0].Size != 24 {
+		t.Errorf("size: got %d, want 24", img.Funcs[0].Size)
+	}
+}
+
+// TestArm64Errors tests error paths.
+func TestArm64Errors(t *testing.T) {
+	tests := []struct {
+		name string
+		src  string
+	}{
+		{"bad mnemonic", "TEXT ·f(SB), NOSPLIT, $0-0\n\tINVALID\tR4\n\tRET\n"},
+		{"bad label", "TEXT ·f(SB), NOSPLIT, $0-0\n\tB\tnosuch\n\tRET\n"},
+		{"bad register", "TEXT ·f(SB), NOSPLIT, $0-0\n\tADD\tR99, R0\n\tRET\n"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, errs := parser.Parse("test_arm64.s", tt.src)
+			if len(errs) > 0 {
+				return
+			}
+			_, err := AssembleFileARM64(f)
+			if err == nil {
+				t.Error("expected error, got nil")
+			}
+		})
+	}
+}
+
+// leWord reads a little-endian uint32 from b.
+func leWord(b []byte) uint32 {
+	return uint32(b[0]) | uint32(b[1])<<8 | uint32(b[2])<<16 | uint32(b[3])<<24
+}
+
+// leWords reads all little-endian uint32s from b.
+func leWords(b []byte) []uint32 {
+	n := len(b) / 4
+	w := make([]uint32, n)
+	for i := range w {
+		w[i] = leWord(b[i*4:])
+	}
+	return w
+}

asm/arm64_frame.go

@@ -0,0 +1,237 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+// arm64 frame mapping, matching the Go toolchain's arm64 backend.
+//
+// Go's arm64 functions use R29 as the frame pointer (FP) and R30 as the link
+// register (LR).  R31 is the stack pointer (SP).  FP and SP in the source
+// are synthetic pseudo-registers resolved against the hardware SP and the
+// frame size.
+//
+// The autosize is the real stack adjustment: the declared local frame plus
+// 8 bytes for the saved link register, rounded up to a 16-byte multiple.
+// The toolchain adds an "extrasize" to align: if autosize%16 == 8, add 8;
+// if autosize%16 == 0, add 16.
+//
+// Prologue (autosize > 0, small frame ≤ 0xf0):
+//
+//	MOVD.W  LR, -autosize(SP)    // pre-index: SP -= autosize, store LR at SP
+//	MOVD    FP, -8(SP)            // store FP at SP-8
+//	SUB     $8, SP, FP            // FP = SP - 8
+//
+// Prologue (autosize > 0, large frame > 0xf0):
+//
+//	SUB     $autosize, SP, R20    // R20 = SP - autosize
+//	STP     (FP, LR), -8(R20)    // store FP,LR at R20-8
+//	MOVD    R20, SP               // SP = R20
+//	SUB     $8, SP, FP            // FP = SP - 8
+//
+// Epilogue (non-leaf, small frame):
+//
+//	ADD     $autosize-8, SP, FP   // restore FP
+//	ADD     $autosize, SP, SP     // deallocate frame
+//	MOVD    -8(SP), FP            // (actually the reverse of prologue)
+// Actually:
+//	MOVD    -8(SP), FP            // load FP from SP-8
+//	MOVD.P  autosize(SP), LR     // post-index: load LR, SP += autosize
+//
+// Epilogue (non-leaf, large frame):
+//	ADD     $autosize-8, SP, FP
+//	ADD     $autosize, SP, SP
+// Actually:
+//	LDP     -8(SP), (FP, LR)     // load FP,LR
+//	ADD     $autosize, SP, SP    // deallocate frame
+//
+// Epilogue (leaf with frame):
+//	ADD     $autosize-8, SP, FP
+//	ADD     $autosize, SP, SP
+//
+// RET always emits as BR LR (0xd65f03c0).
+
+import (
+	"strings"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/ast"
+)
+
+// arm64FrameInfo holds the frame layout derived from a TEXT directive.
+type arm64FrameInfo struct {
+	autosize int  // the real SP adjustment (locals + saved LR + alignment)
+	frame    int  // the declared $framesize
+	args     int  // the declared -argsize
+	noSplit  bool // the NOSPLIT flag
+	leaf     bool // no call instructions in the body
+}
+
+// arm64ComputeFrame derives the frame layout for a TEXT function.
+func arm64ComputeFrame(t *ast.Text) arm64FrameInfo {
+	fi := arm64FrameInfo{
+		frame: frameSize(t),
+		args:  argsSize(t),
+	}
+	for _, f := range t.Flags {
+		if f == "NOSPLIT" {
+			fi.noSplit = true
+		}
+	}
+	fi.leaf = arm64IsLeaf(t)
+
+	if fi.frame != 0 || !fi.leaf {
+		fi.autosize = fi.frame + 8 // space for the saved LR
+		if fi.autosize%16 != 0 {
+			// The toolchain aligns to 16: if autosize%16 == 8, add 8;
+			// otherwise add whatever is needed.
+			fi.autosize += 16 - (fi.autosize % 16)
+		}
+	}
+	return fi
+}
+
+// arm64IsLeaf reports whether a function contains no call instructions
+// (BL/CALL), matching the toolchain's LEAF mark.
+func arm64IsLeaf(t *ast.Text) bool {
+	for _, stmt := range t.Body {
+		in, ok := stmt.(*ast.Instr)
+		if !ok {
+			continue
+		}
+		switch strings.ToUpper(in.Mnemonic.Text) {
+		case "BL", "CALL":
+			return false
+		}
+	}
+	return true
+}
+
+// arm64Prologue returns the prologue bytes for an arm64 function.
+func arm64Prologue(fi arm64FrameInfo) []byte {
+	if fi.autosize == 0 {
+		return nil
+	}
+	if fi.autosize <= 0xf0 {
+		// Small frame: MOVD.W LR, -autosize(SP); MOVD FP, -8(SP); SUB $8, SP, FP
+		return a64WordsLE(
+			arm64PreStoreImm(3, 0, int32(-fi.autosize), 31, 30), // STR.W LR, -autosize(SP) (pre-index store)
+			arm64UnscaledStore(3, 0, -8, 31, 29),                // STUR FP, [SP, #-8]
+			a64AddSub(1, 1, 0, 0, 8, 31, 29),                    // SUB $8, SP, FP (op=1 for SUB)
+		)
+	}
+	// Large frame: SUB $autosize, SP, R20; STP (FP,LR), -8(R20); ADD $0, R20, SP; SUB $8, SP, FP
+	return a64WordsLE(
+		a64AddSub(1, 1, 0, 0, uint32(fi.autosize), 31, 20), // SUB $autosize, SP, R20
+		a64LSP(2, 0, 0, -1, 30, 20, 29),                    // STP FP, LR, [R20, #-8] (opc=2 for 64-bit pair)
+		a64AddSub(1, 0, 0, 0, 0, 20, 31),                   // ADD $0, R20, SP (= MOV R20, SP)
+		a64AddSub(1, 1, 0, 0, 8, 31, 29),                   // SUB $8, SP, FP (op=1 for SUB)
+	)
+}
+
+// arm64Return returns the bytes for a RET: the epilogue (restore FP/LR and
+// deallocate the frame when present) followed by RET (BR LR).
+func arm64Return(fi arm64FrameInfo) []byte {
+	var ws []uint32
+	if fi.autosize != 0 {
+		if fi.leaf {
+			// Leaf with frame: ADD $autosize-8, SP, FP; ADD $autosize, SP, SP
+			ws = append(ws,
+				a64AddSub(1, 0, 0, 0, uint32(fi.autosize-8), 31, 29), // ADD $autosize-8, SP, FP
+				a64AddSub(1, 0, 0, 0, uint32(fi.autosize), 31, 31),   // ADD $autosize, SP, SP
+			)
+		} else if fi.autosize <= 0xf0 {
+			// Non-leaf small frame: LDR FP, [SP, #-8]; LDR.P LR, [SP], #autosize
+			ws = append(ws,
+				arm64UnscaledLoad(3, 0, -8, 31, 29),             // LDR FP, [SP, #-8]
+				arm64PostLoad(3, 0, int32(fi.autosize), 31, 30), // LDR.P LR, [SP], #autosize
+			)
+		} else {
+			// Large frame: LDP -8(SP), (FP, LR); ADD $autosize, SP, SP
+			ws = append(ws,
+				a64LSP(2, 0, 1, -1, 30, 31, 29),                    // LDP FP, LR, [SP, #-8] (opc=2 for 64-bit pair)
+				a64AddSub(1, 0, 0, 0, uint32(fi.autosize), 31, 31), // ADD $autosize, SP, SP
+			)
+		}
+	}
+	// RET: BR LR (0xd65f03c0)
+	ws = append(ws, a64UncondBranch(2, 30, 0)) // opc=2(RET), Rn=LR(30), Rd=0
+	return a64WordsLE(ws...)
+}
+
+// arm64PrologueSpadjPC returns the function-relative byte offset where the
+// prologue has finished decrementing SP (the delta becomes autosize).
+func arm64PrologueSpadjPC(fi arm64FrameInfo) int {
+	if fi.autosize == 0 {
+		return 0
+	}
+	if fi.autosize <= 0xf0 {
+		return 4 // MOVD.W instruction decrements SP
+	}
+	return 8 // SUB + STP + MOVD (3 instructions, SP updated at the MOVD)
+}
+
+// arm64ReturnEpilogueLen returns the byte length of the RET's epilogue up to
+// (but not including) the final RET instruction.
+func arm64ReturnEpilogueLen(fi arm64FrameInfo) int {
+	if fi.autosize == 0 {
+		return 0
+	}
+	if fi.leaf {
+		return 8 // ADD + ADD
+	}
+	if fi.autosize <= 0xf0 {
+		return 8 // LDR + LDR.P
+	}
+	return 8 // LDP + ADD
+}
+
+// arm64ResolvePseudo translates a pseudo-register memory reference into a
+// hardware base register and offset.  x+N(FP) → (N + autosize + 8)(SP);
+// x+N(SP) → (N + frame + 8)(SP).  Returns base = -1 for an unresolvable
+// reference (SB: static data, handled by the relocation path).
+//
+// The Go toolchain resolves all pseudo-register references against the
+// hardware stack pointer (R31/SP): FP references add autosize+8 (the
+// distance from SP after the prologue to the caller's argument area),
+// SP references add frame+8 (the distance to the local area).
+func arm64ResolvePseudo(sym *ast.Symbol, fi arm64FrameInfo) (base int, off int32) {
+	if sym == nil {
+		return -1, 0
+	}
+	switch sym.Pseudo {
+	case "FP":
+		return 31, int32(sym.Offset) + int32(fi.autosize) + 8
+	case "SP":
+		return 31, int32(sym.Offset) + int32(fi.frame) + 8
+	case "SB":
+		return -1, int32(sym.Offset)
+	}
+	return -1, 0
+}
+
+// arm64PreStoreImm encodes a pre-index store (STR with writeback):
+// size<<30 | 7<<27 | V<<26 | opc<<22 | 1<<11 | 1<<10 | imm9<<12 | Rn<<5 | Rt.
+func arm64PreStoreImm(size, V int, imm9 int32, rn, rt int) uint32 {
+	return uint32(size)<<30 | 7<<27 | uint32(V)<<26 | 0<<22 |
+		3<<10 | (uint32(imm9)&0x1FF)<<12 | uint32(rn&31)<<5 | uint32(rt&31)
+}
+
+// arm64UnscaledStore encodes an unscaled store (STUR):
+// size<<30 | 7<<27 | V<<26 | opc<<22 | 0<<11 | 0<<10 | imm9<<12 | Rn<<5 | Rt.
+func arm64UnscaledStore(size, V int, imm9 int32, rn, rt int) uint32 {
+	return uint32(size)<<30 | 7<<27 | uint32(V)<<26 | 0<<22 |
+		(uint32(imm9)&0x1FF)<<12 | uint32(rn&31)<<5 | uint32(rt&31)
+}
+
+// arm64UnscaledLoad encodes an unscaled load (LDUR):
+// size<<30 | 7<<27 | V<<26 | opc<<22 | 0<<11 | 0<<10 | imm9<<12 | Rn<<5 | Rt.
+func arm64UnscaledLoad(size, V int, imm9 int32, rn, rt int) uint32 {
+	return uint32(size)<<30 | 7<<27 | uint32(V)<<26 | 1<<22 |
+		(uint32(imm9)&0x1FF)<<12 | uint32(rn&31)<<5 | uint32(rt&31)
+}
+
+// arm64PostLoad encodes a post-index load (LDR with post-increment):
+// size<<30 | 7<<27 | V<<26 | opc<<22 | 0<<11 | 1<<10 | imm9<<12 | Rn<<5 | Rt.
+func arm64PostLoad(size, V int, imm9 int32, rn, rt int) uint32 {
+	return uint32(size)<<30 | 7<<27 | uint32(V)<<26 | 1<<22 |
+		1<<10 | (uint32(imm9)&0x1FF)<<12 | uint32(rn&31)<<5 | uint32(rt&31)
+}

asm/assemble.go

@@ -261,6 +261,11 @@ func subSP(size int) []byte { // SUBQ $size, SP
 	if size >= -128 && size <= 127 {
 		return []byte{0x48, 0x83, 0xEC, byte(int8(size))}
 	}
+	// 128..255 do not fit SUB's unsigned imm8, but the Go assembler
+	// switches to ADDQ $-size, SP whose sign-extended imm8 does.
+	if size >= -255 && size <= 255 {
+		return []byte{0x48, 0x83, 0xC4, byte(int8(-size))}
+	}
 	return append([]byte{0x48, 0x81, 0xEC}, le32(int64(size))...)
 }
 

asm/assemble_test.go

@@ -62,7 +62,7 @@ TEXT ·f(SB), NOSPLIT, $0
 	XORQ AX, AX
 loop:
 	ADDQ $1, AX
-	CMPQ $10, AX
+	CMPQ AX, $10
 	JLT loop
 	RET
 `)
@@ -317,3 +317,37 @@ end:
 		t.Errorf("jump-folding mismatch:\n got:  %s\n want: %s", hexBytes(code), hexBytes(want))
 	}
 }
+
+func TestAssemblePrefetch(t *testing.T) {
+	fn := firstText(t, `
+#include "textflag.h"
+TEXT ·pf(SB), NOSPLIT, $0
+	PREFETCHNTA (AX)
+	PREFETCHT0 (BX)
+	PREFETCHT1 8(CX)
+	PREFETCHT2 -1(AX)(R12*1)
+	RET
+`)
+	code, _, err := Assemble(fn)
+	if err != nil {
+		t.Fatalf("Assemble: %v", err)
+	}
+	got := strings.Join(disasm(t, code), "\n")
+	want := strings.Join([]string{
+		"prefetchnta zmmword ptr [rax]",
+		"prefetcht0 zmmword ptr [rbx]",
+		"prefetcht1 zmmword ptr [rcx+0x8]",
+		"prefetcht2 zmmword ptr [rax+r12-0x1]",
+		"ret",
+	}, "\n")
+	if got != want {
+		t.Errorf("prefetch disassembly mismatch:\n got:\n%s\n want:\n%s", got, want)
+	}
+	// Byte-level expectations: 0F 18 with the variant in the reg field.
+	if hex := hexBytes(code[:3]); hex != "0f 18 00" {
+		t.Errorf("PREFETCHNTA bytes: got %s, want 0f 18 00", hex)
+	}
+	if hex := hexBytes(code[3:6]); hex != "0f 18 0b" {
+		t.Errorf("PREFETCHT0 bytes: got %s, want 0f 18 0b", hex)
+	}
+}

asm/elf.go

@@ -17,7 +17,6 @@ import (
 // and external ones against undefined globals.  The output links with the
 // system toolchain (cc/ld) the way a hand-assembled .o would.
 
-// ELF constants (ELF64, little-endian, System V).
 const (
 	elfClass64 = 2
 	elfDataLSB = 1
@@ -36,17 +35,13 @@ const (
 	shfAlloc     = 2
 	shfExecInstr = 4
 
-	stbLocal  = 0
 	stbGlobal = 1
 
-	sttNotype   = 0
 	sttObject   = 1
 	sttFunc     = 2
 	sttSection  = 3
 	stInfoShift = 4
 
-	shnUndef = 0
-
 	rX8664PC32 = 2
 )
 
@@ -160,6 +155,9 @@ func (img *Image) ELFObject() ([]byte, error) {
 	for _, n := range []string{".text", ".data", ".symtab", ".strtab", ".rela.text", ".shstrtab"} {
 		stSections.add(n)
 	}
+	for _, n := range dwarfSectionNames {
+		stSections.add(n)
+	}
 
 	// Section presence: .rela.text only when there are relocations.
 	hasRela := len(relas) > 0
@@ -220,6 +218,17 @@ func (img *Image) ELFObject() ([]byte, error) {
 	shstrOff := len(out)
 	out = append(out, stSections.bytes()...)
 
+	// DWARF debug sections (no relocations — the linker resolves DWARF fixups).
+	dwAlign := func(n int) {
+		for len(out)%n != 0 {
+			out = append(out, 0)
+		}
+	}
+	dw := appendDWARFSections(&out, img, "gasm.s", symIdx, dwAlign)
+	if dw != nil {
+		nSections += 4 // .debug_abbrev, .debug_info, .debug_line, .debug_line_str
+	}
+
 	align(8)
 	shoff := len(out)
 
@@ -248,6 +257,17 @@ func (img *Image) ELFObject() ([]byte, error) {
 	}
 	putSh(".shstrtab", shtStrtab, 0, shstrOff, len(stSections.bytes()), 0, 0, 1, 0)
 
+	// DWARF section headers.
+	if dw != nil {
+		putSh(".debug_abbrev", shtProgbits, 0, dw.abbrevOff, dw.abbrevSize, 0, 0, 1, 0)
+		putSh(".debug_info", shtProgbits, 0, dw.infoOff, dw.infoSize, 0, 0, 1, 0)
+		putSh(".debug_line", shtProgbits, 0, dw.lineOff, dw.lineSize, 0, 0, 1, 0)
+		putSh(".debug_line_str", shtProgbits, 0, dw.lineStrOff, dw.lineStrSize, 0, 0, 1, 0)
+		if dw.frameSize > 0 {
+			putSh(".debug_frame", shtProgbits, 0, dw.frameOff, dw.frameSize, 0, 0, 8, 0)
+		}
+	}
+
 	// The ELF header.
 	hdr := out[:64]
 	copy(hdr[0:], []byte{0x7f, 'E', 'L', 'F', elfClass64, elfDataLSB, elfVersion, 0})

asm/elf_dwarf.go

@@ -0,0 +1,319 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"encoding/binary"
+)
+
+// DWARF5 section generation for ELF output.  Unlike the GOOBJ path (where
+// the linker assembles the final DWARF), the ELF path must emit complete,
+// self-contained sections because the system linker only performs fixup
+// relocations, not assembly.
+
+// dwarfAbbrevTable returns the .debug_abbrev content: a single compilation
+// unit with DW_TAG_compile_unit and DW_TAG_subprogram entries.
+func dwarfAbbrevTable() []byte {
+	var b []byte
+	// Abbrev 1: DW_TAG_compile_unit
+	b = append(b, 1)        // abbreviation code
+	b = append(b, 0x11)     // DW_TAG_compile_unit
+	b = append(b, 1)        // DW_CHILDREN_yes
+	b = appendUleb(b, 0x1b) // DW_AT_low_pc
+	b = appendUleb(b, 0x01) // DW_FORM_addr
+	b = appendUleb(b, 0x29) // DW_AT_high_pc
+	b = appendUleb(b, 0x07) // DW_FORM_data8
+	b = appendUleb(b, 0x10) // DW_AT_stmt_list
+	b = appendUleb(b, 0x25) // DW_FORM_sec_offset
+	b = appendUleb(b, 0x01) // DW_AT_name
+	b = appendUleb(b, 0x08) // DW_FORM_string
+	b = appendUleb(b, 0)    // end of attributes
+
+	// Abbrev 2: DW_TAG_subprogram
+	b = append(b, 2)        // abbreviation code
+	b = append(b, 0x2e)     // DW_TAG_subprogram
+	b = append(b, 0)        // DW_CHILDREN_no
+	b = appendUleb(b, 0x03) // DW_AT_name
+	b = appendUleb(b, 0x08) // DW_FORM_string
+	b = appendUleb(b, 0x11) // DW_AT_low_pc
+	b = appendUleb(b, 0x01) // DW_FORM_addr
+	b = appendUleb(b, 0x29) // DW_AT_high_pc
+	b = appendUleb(b, 0x07) // DW_FORM_data8
+	b = appendUleb(b, 0x3f) // DW_AT_frame_base
+	b = appendUleb(b, 0x18) // DW_FORM_exprloc
+	b = appendUleb(b, 0x3b) // DW_AT_decl_file
+	b = appendUleb(b, 0x0b) // DW_FORM_data1
+	b = appendUleb(b, 0x37) // DW_AT_decl_line
+	b = appendUleb(b, 0x0b) // DW_FORM_data1
+	b = appendUleb(b, 0x63) // DW_AT_external
+	b = appendUleb(b, 0x0b) // DW_FORM_flag
+	b = appendUleb(b, 0)    // end of attributes
+
+	// End of table.
+	b = append(b, 0)
+	return b
+}
+
+// dwarfSections holds the generated DWARF section payloads and their
+// relocations (byte offsets within .debug_info and .debug_line that need
+// fixup against .text symbols).
+type dwarfSections struct {
+	debugAbbrev  []byte
+	debugInfo    []byte
+	debugLine    []byte
+	debugLineStr []byte
+	debugFrame   []byte
+	// Relocations for .debug_info: (offset, symbol name, addend).
+	infoRelocs []dwarfReloc
+	// Relocations for .debug_line: (offset, symbol name, addend).
+	lineRelocs []dwarfReloc
+}
+
+type dwarfReloc struct {
+	off    uint64
+	name   string
+	addend int64
+}
+
+// emitDWARF generates complete DWARF5 sections for the image.
+func emitDWARF(img *Image, srcFile string) *dwarfSections {
+	ds := &dwarfSections{}
+	ds.debugAbbrev = dwarfAbbrevTable()
+
+	// Build the string table for .debug_line_str.
+	lineStr := newElfStrtab()
+	lineStr.add(srcFile)
+	ds.debugLineStr = lineStr.bytes()
+
+	// Build .debug_line.
+	ds.debugLine = dwarfBuildLineSection(img, ds)
+
+	// Build .debug_info.
+	ds.debugInfo = dwarfBuildInfoSection(img, srcFile, ds)
+
+	// Build .debug_frame.
+	ds.debugFrame = dwarfBuildFrameSection(img)
+	return ds
+}
+
+// dwarfBuildLineSection builds a complete .debug_line section.
+func dwarfBuildLineSection(img *Image, ds *dwarfSections) []byte {
+	var b []byte
+	le := binary.LittleEndian
+
+	// We'll build the header first, then the programs, then patch the length.
+	headerStart := len(b)
+	b = append(b, 0, 0, 0, 0) // unit_length (placeholder)
+	b = le.AppendUint16(b, 5) // version (DWARF5)
+	b = append(b, 8)          // address_size
+	b = append(b, 0)          // segment_selector_size
+	b = append(b, 0, 0, 0, 0) // header_length (placeholder)
+
+	// Line program parameters.
+	b = append(b, 1)                     // minimum_instruction_length
+	b = append(b, 1)                     // maximum_ops_per_instruction
+	b = append(b, 1)                     // default_is_stmt
+	b = append(b, byte(dwLineBase&0xFF)) // line_base (-4 as unsigned)
+	b = append(b, uint8(dwLineRange))    // line_range
+	b = append(b, uint8(dwOpcodeBase))   // opcode_base
+	// Standard opcode lengths (opcode 1..opcode_base-1).
+	b = append(b, 0, 1, 1, 1, 1, 0, 0, 0, 1, 0)
+
+	// Directory table (DWARF5 format).
+	b = append(b, 0) // one directory entry (index 0 = empty)
+	// File table.
+	b = appendUleb(b, 1) // file count
+	// File 1: name index into .debug_line_str, dir index, time, size.
+	b = appendUleb(b, 0) // name (index 0 in line_str)
+	b = appendUleb(b, 0) // directory index
+	b = appendUleb(b, 0) // last modification time
+	b = appendUleb(b, 0) // file size
+
+	headerEnd := len(b)
+
+	// Per-function line programs.
+	for _, fn := range img.Funcs {
+		// LNE_set_address with the function's offset in .text.
+		b = append(b, 0, 9, 2) // extended opcode, length 9, DW_LNE_set_address
+		addrOff := len(b)
+		b = le.AppendUint64(b, 0) // placeholder for address
+		ds.lineRelocs = append(ds.lineRelocs, dwarfReloc{
+			off:    uint64(addrOff),
+			name:   fn.Name,
+			addend: 0,
+		})
+
+		// Build the line entries.
+		pts := make([]LineEntry, 0, len(fn.Lines)+1)
+		if len(fn.Lines) == 0 || fn.Lines[0].Offset > 0 {
+			pts = append(pts, LineEntry{Offset: 0, Line: fn.Line})
+		}
+		pts = append(pts, fn.Lines...)
+
+		line := int64(1)
+		pc := uint64(0)
+		for _, p := range pts {
+			if p.Line == 0 || uint64(p.Offset) < pc {
+				continue
+			}
+			if int64(p.Line) == line {
+				continue
+			}
+			deltaPC := uint64(p.Offset) - pc
+			deltaLC := int64(p.Line) - line
+			b = dwPutPCLCDelta(b, deltaPC, deltaLC)
+			line, pc = int64(p.Line), uint64(p.Offset)
+		}
+
+		// Advance to end of function.
+		if end := uint64(fn.Size) - pc; end > 0 {
+			b = append(b, 2) // DW_LNS_advance_pc
+			b = appendUleb(b, end)
+		}
+		b = append(b, 0, 1, 1) // LNE_end_sequence
+	}
+
+	// Patch unit_length.
+	le.PutUint32(b[headerStart:], uint32(len(b)-headerStart-4))
+	// Patch header_length.
+	le.PutUint32(b[headerStart+6:], uint32(headerEnd-headerStart-10))
+	return b
+}
+
+// dwarfBuildInfoSection builds a complete .debug_info section.
+func dwarfBuildInfoSection(img *Image, srcFile string, ds *dwarfSections) []byte {
+	var b []byte
+	le := binary.LittleEndian
+
+	cuStart := len(b)
+	b = append(b, 0, 0, 0, 0) // unit_length (placeholder)
+	b = le.AppendUint16(b, 5) // version (DWARF5)
+	b = append(b, 0x01)       // unit_type (DW_UT_compile)
+	b = append(b, 8)          // address_size
+	b = le.AppendUint32(b, 0) // debug_abbrev_offset (0 since single CU)
+
+	// DW_TAG_compile_unit (abbrev 1).
+	b = append(b, 1) // abbreviation code
+	// DW_AT_low_pc: address of .text start.
+	infoRelocBase := len(b)
+	b = le.AppendUint64(b, 0) // placeholder
+	ds.infoRelocs = append(ds.infoRelocs, dwarfReloc{
+		off:    uint64(infoRelocBase),
+		name:   img.Funcs[0].Name,
+		addend: 0,
+	})
+	// DW_AT_high_pc: size of .text.
+	b = le.AppendUint64(b, uint64(len(img.Code)))
+	// DW_AT_stmt_list: offset into .debug_line (0).
+	b = le.AppendUint32(b, 0)
+	// DW_AT_name: source file name.
+	b = append(b, srcFile...)
+	b = append(b, 0)
+
+	// DW_TAG_subprogram entries (abbrev 2).
+	for _, fn := range img.Funcs {
+		b = append(b, 2) // abbreviation code
+		// DW_AT_name.
+		b = append(b, fn.Name...)
+		b = append(b, 0)
+		// DW_AT_low_pc.
+		addrOff := len(b)
+		b = le.AppendUint64(b, 0) // placeholder
+		ds.infoRelocs = append(ds.infoRelocs, dwarfReloc{
+			off:    uint64(addrOff),
+			name:   fn.Name,
+			addend: 0,
+		})
+		// DW_AT_high_pc: function size.
+		b = le.AppendUint64(b, uint64(fn.Size))
+		// DW_AT_frame_base: DW_OP_call_frame_cfa.
+		b = append(b, 1, 0x9c)
+		// DW_AT_decl_file: file index 1.
+		b = append(b, 1)
+		// DW_AT_decl_line.
+		b = append(b, uint8(fn.Line))
+		// DW_AT_external.
+		if fn.Static {
+			b = append(b, 0)
+		} else {
+			b = append(b, 1)
+		}
+	}
+
+	// End of compile unit children.
+	b = append(b, 0)
+
+	// Patch unit_length.
+	le.PutUint32(b[cuStart:], uint32(len(b)-cuStart-4))
+	return b
+}
+
+func appendUleb(b []byte, v uint64) []byte {
+	return binary.AppendUvarint(b, v)
+}
+
+func appendSleb(b []byte, v int64) []byte {
+	return binary.AppendVarint(b, v)
+}
+
+// dwarfBuildFrameSection builds a .debug_frame section with CFI for stack
+// unwinding.  It emits one CIE and one FDE per function, encoding the
+// CFA (Canonical Frame Address) rule changes at each stack-adjustment
+// boundary recorded in FuncLayout.Spadj.
+func dwarfBuildFrameSection(img *Image) []byte {
+	var b []byte
+	le := binary.LittleEndian
+
+	// CIE (Common Information Entry).
+	cieStart := len(b)
+	b = append(b, 0, 0, 0, 0)          // length (placeholder)
+	b = le.AppendUint32(b, 0xFFFFFFFF) // CIE marker
+	b = append(b, 3)                   // version (DWARF3, widely supported)
+	b = append(b, 0)                   // augmentation (empty)
+	b = appendUleb(b, 1)               // code alignment
+	b = appendSleb(b, -8)              // data alignment (-8 for 64-bit)
+	b = appendUleb(b, 16)              // return address register (LR on arm64, RIP on amd64)
+	// Initial CFA rule: DW_CFA_def_cfa (SP, 0)
+	b = append(b, 0x0c)   // DW_CFA_def_cfa
+	b = appendUleb(b, 31) // register: SP (RSP=7 on amd64, SP=31 on arm64)
+	b = appendUleb(b, 0)  // offset: 0
+	b = append(b, 0)      // DW_CFA_nop (padding)
+	// Patch CIE length.
+	le.PutUint32(b[cieStart:], uint32(len(b)-cieStart-4))
+
+	// FDEs (Frame Description Entries) — one per function.
+	for _, fn := range img.Funcs {
+		fdeStart := len(b)
+		b = append(b, 0, 0, 0, 0)                // length (placeholder)
+		b = le.AppendUint32(b, uint32(cieStart)) // CIE pointer (offset from start)
+		// Initial location: function offset in .text (relocated by linker).
+		b = le.AppendUint64(b, uint64(fn.Offset))
+		// Address range: function size.
+		b = le.AppendUint64(b, uint64(fn.Size))
+
+		// Emit CFA rule changes at each Spadj boundary.
+		for _, step := range fn.Spadj {
+			if step.Value == 0 {
+				continue
+			}
+			// DW_CFA_def_cfa_offset: set CFA = SP + |delta|.
+			// The delta is negative (stack grows down), so CFA offset = -delta.
+			offset := -step.Value
+			if offset > 0 {
+				b = append(b, 0x0e) // DW_CFA_def_cfa_offset
+				b = appendUleb(b, uint64(offset))
+			}
+		}
+
+		// Pad to alignment.
+		for len(b)%4 != 0 {
+			b = append(b, 0) // DW_CFA_nop
+		}
+
+		// Patch FDE length.
+		le.PutUint32(b[fdeStart:], uint32(len(b)-fdeStart-4))
+	}
+
+	return b
+}

asm/elf_dwarf_sections.go

@@ -0,0 +1,119 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+// dwarfELFSections holds the laid-out DWARF sections ready for inclusion
+// in an ELF file.
+type dwarfELFSections struct {
+	abbrevOff, abbrevSize   int
+	infoOff, infoSize       int
+	lineOff, lineSize       int
+	lineStrOff, lineStrSize int
+	frameOff, frameSize     int
+	// Relocations for .debug_info address references.
+	infoRelocs []elfDwarfReloc
+	// Relocations for .debug_line address references.
+	lineRelocs []elfDwarfReloc
+}
+
+type elfDwarfReloc struct {
+	off    uint64
+	sym    int // symbol index in .symtab
+	addend int64
+}
+
+// appendDWARFSections generates and appends DWARF5 debug sections to the ELF
+// output.  It returns the section offsets/sizes and relocations for the caller
+// to emit section headers and relocation records.
+//
+// symIdx maps function names to their .symtab indices (needed for relocations
+// against .text symbols).  The map uses objectName format (pkg.name); the
+// DWARF code uses bare function names, so we build a reverse lookup.
+func appendDWARFSections(out *[]byte, img *Image, srcFile string, symIdx map[string]int, align func(int)) *dwarfELFSections {
+	// Build a lookup from bare function name to symbol index.
+	nameToIdx := make(map[string]int, len(symIdx))
+	for name, idx := range symIdx {
+		// Strip package prefix: "pkg.name" → "name".
+		if i := len(name) - 1; i >= 0 {
+			for j := len(name) - 1; j >= 0; j-- {
+				if name[j] == '.' {
+					nameToIdx[name[j+1:]] = idx
+					break
+				}
+			}
+		}
+		nameToIdx[name] = idx
+	}
+	ds := emitDWARF(img, srcFile)
+	if ds == nil || len(ds.debugAbbrev) == 0 {
+		return nil
+	}
+
+	result := &dwarfELFSections{}
+
+	// .debug_abbrev
+	align(1)
+	result.abbrevOff = len(*out)
+	result.abbrevSize = len(ds.debugAbbrev)
+	*out = append(*out, ds.debugAbbrev...)
+
+	// .debug_line_str
+	align(1)
+	result.lineStrOff = len(*out)
+	result.lineStrSize = len(ds.debugLineStr)
+	*out = append(*out, ds.debugLineStr...)
+
+	// .debug_line
+	align(1)
+	result.lineOff = len(*out)
+	result.lineSize = len(ds.debugLine)
+	lineBase := len(*out)
+	*out = append(*out, ds.debugLine...)
+
+	// Patch .debug_line relocations: replace placeholder addresses with
+	// actual .text offsets via symbol lookup.
+	for _, dr := range ds.lineRelocs {
+		if idx, ok := nameToIdx[dr.name]; ok {
+			result.lineRelocs = append(result.lineRelocs, elfDwarfReloc{
+				off:    uint64(lineBase) + dr.off,
+				sym:    idx,
+				addend: dr.addend,
+			})
+		}
+	}
+
+	// .debug_info
+	align(1)
+	result.infoOff = len(*out)
+	result.infoSize = len(ds.debugInfo)
+	infoBase := len(*out)
+	*out = append(*out, ds.debugInfo...)
+
+	// .debug_frame
+	if len(ds.debugFrame) > 0 {
+		align(1)
+		result.frameOff = len(*out)
+		result.frameSize = len(ds.debugFrame)
+		*out = append(*out, ds.debugFrame...)
+	}
+
+	// Patch .debug_info relocations.
+	for _, dr := range ds.infoRelocs {
+		if idx, ok := nameToIdx[dr.name]; ok {
+			result.infoRelocs = append(result.infoRelocs, elfDwarfReloc{
+				off:    uint64(infoBase) + dr.off,
+				sym:    idx,
+				addend: dr.addend,
+			})
+		}
+	}
+
+	return result
+}
+
+// dwarfSectionNames returns the DWARF section names for the string table.
+var dwarfSectionNames = []string{
+	".debug_abbrev", ".debug_info", ".debug_line", ".debug_line_str",
+	".debug_frame", ".rela.debug_info", ".rela.debug_line",
+}

asm/elf_dwarf_test.go

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+func TestEmitDWARF(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOVQ a+0(FP), AX
+	MOVQ b+8(FP), BX
+	ADDQ BX, AX
+	MOVQ AX, ret+16(FP)
+	RET
+`
+	f, errs := parser.Parse("test_amd64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFile(f)
+	if err != nil {
+		t.Fatalf("assemble: %v", err)
+	}
+
+	ds := emitDWARF(img, "test_amd64.s")
+
+	// .debug_abbrev must not be empty and must start with abbrev code 1.
+	if len(ds.debugAbbrev) == 0 {
+		t.Fatal("empty .debug_abbrev")
+	}
+	if ds.debugAbbrev[0] != 1 {
+		t.Fatalf(".debug_abbrev first byte = %d, want 1", ds.debugAbbrev[0])
+	}
+
+	// .debug_info must have a compile unit header (DWARF5 version 5).
+	if len(ds.debugInfo) < 12 {
+		t.Fatalf(".debug_info too short: %d bytes", len(ds.debugInfo))
+	}
+	// Version field at offset 4 (after unit_length).
+	if ds.debugInfo[4] != 5 || ds.debugInfo[5] != 0 {
+		t.Fatalf(".debug_info version = %d, want 5", uint16(ds.debugInfo[4])|uint16(ds.debugInfo[5])<<8)
+	}
+
+	// .debug_line must have a header.
+	if len(ds.debugLine) < 20 {
+		t.Fatalf(".debug_line too short: %d bytes", len(ds.debugLine))
+	}
+	// Version at offset 4.
+	if ds.debugLine[4] != 5 || ds.debugLine[5] != 0 {
+		t.Fatalf(".debug_line version = %d, want 5", uint16(ds.debugLine[4])|uint16(ds.debugLine[5])<<8)
+	}
+
+	// .debug_line_str must contain the source file name.
+	if len(ds.debugLineStr) == 0 {
+		t.Fatal("empty .debug_line_str")
+	}
+
+	// Relocations must reference the function.
+	if len(ds.lineRelocs) == 0 {
+		t.Fatal("no .debug_line relocations")
+	}
+	if len(ds.infoRelocs) == 0 {
+		t.Fatal("no .debug_info relocations")
+	}
+}
+
+func TestDwarfAbbrevTable(t *testing.T) {
+	abbrev := dwarfAbbrevTable()
+	if len(abbrev) == 0 {
+		t.Fatal("empty abbrev table")
+	}
+	// Must end with a zero byte (end of table).
+	if abbrev[len(abbrev)-1] != 0 {
+		t.Fatalf("abbrev table last byte = %d, want 0", abbrev[len(abbrev)-1])
+	}
+}

asm/elf_test.go

@@ -187,7 +187,7 @@ func TestELFObject(t *testing.T) {
 		end := bytes.IndexByte(strtabRaw[stName:], 0)
 		return string(strtabRaw[stName : int(stName)+end])
 	}
-	for i := 0; i < 2; i++ {
+	for i := range 2 {
 		e := raw[i*24 : (i+1)*24]
 		off := binary.LittleEndian.Uint64(e[0:])
 		info := binary.LittleEndian.Uint64(e[8:])

asm/elfarm64.go

@@ -0,0 +1,252 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"encoding/binary"
+	"fmt"
+)
+
+// AArch64 ELF64 relocatable object emission.
+
+const (
+	emAARCH64 = 183 // EM_AARCH64
+
+	// AArch64 relocation types (the ELF psABI).
+	rArm64PrelPgHi21   = 275 // R_AARCH64_ADR_PREL_PG_HI21 (ADRP page)
+	rArm64AddAbsLo12NC = 277 // R_AARCH64_ADD_ABS_LO12_NC (ADD/STR/LDR page offset)
+	rArm64Call26       = 283 // R_AARCH64_CALL26 (BL instruction)
+)
+
+// ELFAARCH64Object returns the image as an ELF64 relocatable object file for
+// AArch64 (EM_AARCH64, 64-bit, little-endian).  The structure mirrors the
+// amd64 and RISC-V ELF emitters: .text, .data, .symtab, .strtab and an
+// optional .rela.text.
+func (img *Image) ELFAARCH64Object() ([]byte, error) {
+	le := binary.LittleEndian
+
+	const (
+		secText = 1
+		secData = 2
+	)
+
+	// Build symbol table.
+	var locals, globals []elfSym
+	for _, fn := range img.Funcs {
+		s := elfSym{
+			name:  objectName(fn.Pkg, fn.Name),
+			info:  sttFunc,
+			shndx: secText,
+			value: uint64(fn.Offset),
+			size:  uint64(fn.Size),
+		}
+		if fn.Static {
+			locals = append(locals, s)
+		} else {
+			s.info |= stbGlobal << stInfoShift
+			globals = append(globals, s)
+		}
+	}
+	for _, d := range img.DataSyms {
+		s := elfSym{
+			name:  objectName(d.Pkg, d.Name),
+			info:  sttObject,
+			shndx: secData,
+			value: uint64(d.Offset),
+			size:  uint64(d.Size),
+		}
+		if d.Static {
+			locals = append(locals, s)
+		} else {
+			s.info |= stbGlobal << stInfoShift
+			globals = append(globals, s)
+		}
+	}
+	for _, name := range img.Externals {
+		globals = append(globals, elfSym{name: name, info: stbGlobal << stInfoShift})
+	}
+	syms := []elfSym{
+		{},
+		{name: ".text", info: sttSection, shndx: secText},
+		{name: ".data", info: sttSection, shndx: secData},
+	}
+	syms = append(syms, locals...)
+	shInfo := len(syms)
+	syms = append(syms, globals...)
+	symIdx := map[string]int{}
+	for i, s := range syms {
+		symIdx[s.name] = i
+	}
+
+	// Build relocations.  Each SB reference is an ADRP pair:
+	//   ADRP Rd, 0  → R_AARCH64_ADR_PREL_PG_HI21
+	//   ADD/LDR/STR  → R_AARCH64_ADD_ABS_LO12_NC
+	type elfRela struct {
+		off    uint64
+		typ    uint32
+		sym    int
+		addend int64
+	}
+	var relas []elfRela
+	for _, fn := range img.Funcs {
+		for _, r := range fn.Relocs {
+			idx, ok := symIdx[r.Name]
+			if !ok {
+				return nil, fmt.Errorf("relocation references unknown symbol %q", r.Name)
+			}
+			var typ uint32
+			switch {
+			case r.Kind == RelArm64Branch:
+				typ = rArm64Call26
+			case r.Kind == RelArm64Addr && r.Off%4 == 4:
+				typ = rArm64AddAbsLo12NC
+			default:
+				typ = rArm64PrelPgHi21
+			}
+			relas = append(relas, elfRela{
+				off:    uint64(fn.Offset + r.Off),
+				typ:    typ,
+				sym:    idx,
+				addend: r.Addend - int64(r.After-r.Off),
+			})
+		}
+	}
+
+	// String tables.
+	stNames := newElfStrtab()
+	for _, s := range syms {
+		stNames.add(s.name)
+	}
+	stSections := newElfStrtab()
+	for _, n := range []string{".text", ".data", ".symtab", ".strtab", ".rela.text", ".shstrtab"} {
+		stSections.add(n)
+	}
+	for _, n := range dwarfSectionNames {
+		stSections.add(n)
+	}
+
+	hasRela := len(relas) > 0
+	nSections := 6
+	if hasRela {
+		nSections = 7
+	}
+	secSymtab, secStrtab := 3, 4
+	secShstr := nSections - 1
+
+	// Layout.
+	var out []byte
+	out = append(out, make([]byte, 64)...)
+
+	align := func(n int) {
+		for len(out)%n != 0 {
+			out = append(out, 0)
+		}
+	}
+
+	align(16)
+	textOff := len(out)
+	out = append(out, img.Code...)
+
+	align(16)
+	dataOff := len(out)
+	out = append(out, img.Data...)
+
+	align(8)
+	symtabOff := len(out)
+	for _, s := range syms {
+		var b [24]byte
+		le.PutUint32(b[0:], uint32(stNames.at(s.name)))
+		b[4] = s.info
+		b[5] = 0
+		le.PutUint16(b[6:], s.shndx)
+		le.PutUint64(b[8:], s.value)
+		le.PutUint64(b[16:], s.size)
+		out = append(out, b[:]...)
+	}
+
+	strtabOff := len(out)
+	out = append(out, stNames.bytes()...)
+
+	var relaOff int
+	if hasRela {
+		align(8)
+		relaOff = len(out)
+		for _, r := range relas {
+			var b [24]byte
+			le.PutUint64(b[0:], r.off)
+			le.PutUint64(b[8:], uint64(r.sym)<<32|uint64(r.typ))
+			le.PutUint64(b[16:], uint64(r.addend))
+			out = append(out, b[:]...)
+		}
+	}
+
+	shstrOff := len(out)
+	out = append(out, stSections.bytes()...)
+
+	// DWARF debug sections.
+	dwAlign := func(n int) {
+		for len(out)%n != 0 {
+			out = append(out, 0)
+		}
+	}
+	dw := appendDWARFSections(&out, img, "gasm.s", symIdx, dwAlign)
+	if dw != nil {
+		nSections += 4
+	}
+
+	align(8)
+	shoff := len(out)
+
+	putSh := func(name string, typ int, flags uint64, off, size int, link, info int, alignV, entsize uint64) {
+		var b [64]byte
+		le.PutUint32(b[0:], uint32(stSections.at(name)))
+		le.PutUint32(b[4:], uint32(typ))
+		le.PutUint64(b[8:], flags)
+		le.PutUint64(b[16:], 0)
+		le.PutUint64(b[24:], uint64(off))
+		le.PutUint64(b[32:], uint64(size))
+		le.PutUint32(b[40:], uint32(link))
+		le.PutUint32(b[44:], uint32(info))
+		le.PutUint64(b[48:], alignV)
+		le.PutUint64(b[56:], entsize)
+		out = append(out, b[:]...)
+	}
+	putSh("", shtNull, 0, 0, 0, 0, 0, 0, 0)
+	putSh(".text", shtProgbits, shfAlloc|shfExecInstr, textOff, len(img.Code), 0, 0, 16, 0)
+	putSh(".data", shtProgbits, shfAlloc|shfWrite, dataOff, len(img.Data), 0, 0, 16, 0)
+	putSh(".symtab", shtSymtab, 0, symtabOff, 24*len(syms), secStrtab, shInfo, 8, 24)
+	putSh(".strtab", shtStrtab, 0, strtabOff, len(stNames.bytes()), 0, 0, 1, 0)
+	if hasRela {
+		putSh(".rela.text", shtRela, 0, relaOff, 24*len(relas), secSymtab, secText, 8, 24)
+	}
+	putSh(".shstrtab", shtStrtab, 0, shstrOff, len(stSections.bytes()), 0, 0, 1, 0)
+	if dw != nil {
+		putSh(".debug_abbrev", shtProgbits, 0, dw.abbrevOff, dw.abbrevSize, 0, 0, 1, 0)
+		putSh(".debug_info", shtProgbits, 0, dw.infoOff, dw.infoSize, 0, 0, 1, 0)
+		putSh(".debug_line", shtProgbits, 0, dw.lineOff, dw.lineSize, 0, 0, 1, 0)
+		putSh(".debug_line_str", shtProgbits, 0, dw.lineStrOff, dw.lineStrSize, 0, 0, 1, 0)
+		if dw.frameSize > 0 {
+			putSh(".debug_frame", shtProgbits, 0, dw.frameOff, dw.frameSize, 0, 0, 8, 0)
+		}
+	}
+
+	// ELF header.
+	hdr := out[:64]
+	copy(hdr[0:], []byte{0x7f, 'E', 'L', 'F', elfClass64, elfDataLSB, elfVersion, 0})
+	le.PutUint16(hdr[16:], etREL)
+	le.PutUint16(hdr[18:], emAARCH64)
+	le.PutUint32(hdr[20:], elfVersion)
+	le.PutUint64(hdr[24:], 0)
+	le.PutUint64(hdr[32:], 0)
+	le.PutUint64(hdr[40:], uint64(shoff))
+	le.PutUint32(hdr[48:], 0)
+	le.PutUint16(hdr[52:], 64)
+	le.PutUint16(hdr[54:], 0)
+	le.PutUint16(hdr[56:], 0)
+	le.PutUint16(hdr[58:], 64)
+	le.PutUint16(hdr[60:], uint16(nSections))
+	le.PutUint16(hdr[62:], uint16(secShstr))
+
+	return out, nil
+}

asm/elfarm64_test.go

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"bytes"
+	"debug/elf"
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// TestELFAARCH64Object checks the structure of the emitted AArch64 ELF64
+// relocatable object: sections, the symbol table (bindings, types, values,
+// sizes) and the .rela.text relocation pair for the static-symbol load,
+// parsed back with debug/elf.
+func TestELFAARCH64Object(t *testing.T) {
+	f, errs := parser.Parse("k_arm64.s", `
+#include "textflag.h"
+
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOVD a+0(FP), R4
+	MOVD b+8(FP), R5
+	ADD R5, R4, R4
+	MOVD R4, ret+16(FP)
+	RET
+
+TEXT ·getanswer(SB), NOSPLIT, $0-8
+	MOVD answer<>(SB), R4
+	MOVD R4, ret+0(FP)
+	RET
+
+GLOBL answer<>(SB), RODATA, $8
+DATA answer<>+0(SB)/8, $42
+`)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	obj, err := img.ELFAARCH64Object()
+	if err != nil {
+		t.Fatalf("ELFAARCH64Object: %v", err)
+	}
+	ef, err := elf.NewFile(bytes.NewReader(obj))
+	if err != nil {
+		t.Fatalf("parse emitted object: %v", err)
+	}
+	defer ef.Close()
+
+	if ef.Type != elf.ET_REL || ef.Machine != elf.EM_AARCH64 {
+		t.Errorf("type/machine = %v/%v, want ET_REL/EM_AARCH64", ef.Type, ef.Machine)
+	}
+
+	text := ef.Section(".text")
+	data := ef.Section(".data")
+	if text == nil || data == nil {
+		t.Fatal("missing .text or .data section")
+	}
+	if text.Size == 0 {
+		t.Error(".text section is empty")
+	}
+
+	syms, err := ef.Symbols()
+	if err != nil {
+		t.Fatalf("symbols: %v", err)
+	}
+
+	foundAdd, foundGetanswer, foundAnswer := false, false, false
+	for _, s := range syms {
+		switch s.Name {
+		case "add":
+			foundAdd = true
+			if elf.SymType(s.Info&0xf) != elf.STT_FUNC || elf.SymBind(s.Info>>4) != elf.STB_GLOBAL {
+				t.Errorf("add: info=0x%02x, want STT_FUNC|STB_GLOBAL", s.Info)
+			}
+		case "getanswer":
+			foundGetanswer = true
+			if elf.SymType(s.Info&0xf) != elf.STT_FUNC || elf.SymBind(s.Info>>4) != elf.STB_GLOBAL {
+				t.Errorf("getanswer: info=0x%02x, want STT_FUNC|STB_GLOBAL", s.Info)
+			}
+		case "answer":
+			foundAnswer = true
+			if elf.SymType(s.Info&0xf) != elf.STT_OBJECT || elf.SymBind(s.Info>>4) != elf.STB_LOCAL {
+				t.Errorf("answer: info=0x%02x, want STT_OBJECT|STB_LOCAL", s.Info)
+			}
+		}
+	}
+	if !foundAdd {
+		t.Error("symbol 'add' not found")
+	}
+	if !foundGetanswer {
+		t.Error("symbol 'getanswer' not found")
+	}
+	if !foundAnswer {
+		t.Error("symbol 'answer' not found")
+	}
+
+	// Check that .rela.text exists (getanswer has SB reference).
+	relaText := ef.Section(".rela.text")
+	if relaText == nil {
+		t.Error("missing .rela.text section")
+	}
+}
+
+// TestELFAARCH64ObjectNoRelocations checks the ELF output when there are no
+// static-symbol references (no .rela.text section).
+func TestELFAARCH64ObjectNoRelocations(t *testing.T) {
+	f, errs := parser.Parse("k_arm64.s", `
+#include "textflag.h"
+
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOVD a+0(FP), R4
+	MOVD b+8(FP), R5
+	ADD R5, R4, R4
+	MOVD R4, ret+16(FP)
+	RET
+`)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileARM64(f)
+	if err != nil {
+		t.Fatalf("AssembleFileARM64: %v", err)
+	}
+	obj, err := img.ELFAARCH64Object()
+	if err != nil {
+		t.Fatalf("ELFAARCH64Object: %v", err)
+	}
+	ef, err := elf.NewFile(bytes.NewReader(obj))
+	if err != nil {
+		t.Fatalf("parse emitted object: %v", err)
+	}
+	defer ef.Close()
+
+	if ef.Section(".rela.text") != nil {
+		t.Error("unexpected .rela.text section when there are no relocations")
+	}
+}

asm/elfloong64.go

@@ -116,6 +116,9 @@ func (img *Image) ELFLOONG64Object() ([]byte, error) {
 	for _, n := range []string{".text", ".data", ".symtab", ".strtab", ".rela.text", ".shstrtab"} {
 		stSections.add(n)
 	}
+	for _, n := range dwarfSectionNames {
+		stSections.add(n)
+	}
 
 	hasRela := len(relas) > 0
 	nSections := 6
@@ -175,6 +178,16 @@ func (img *Image) ELFLOONG64Object() ([]byte, error) {
 	shstrOff := len(out)
 	out = append(out, stSections.bytes()...)
 
+	dwAlign := func(n int) {
+		for len(out)%n != 0 {
+			out = append(out, 0)
+		}
+	}
+	dw := appendDWARFSections(&out, img, "gasm.s", symIdx, dwAlign)
+	if dw != nil {
+		nSections += 4
+	}
+
 	align(8)
 	shoff := len(out)
 
@@ -201,6 +214,15 @@ func (img *Image) ELFLOONG64Object() ([]byte, error) {
 		putSh(".rela.text", shtRela, 0, relaOff, 24*len(relas), secSymtab, secText, 8, 24)
 	}
 	putSh(".shstrtab", shtStrtab, 0, shstrOff, len(stSections.bytes()), 0, 0, 1, 0)
+	if dw != nil {
+		putSh(".debug_abbrev", shtProgbits, 0, dw.abbrevOff, dw.abbrevSize, 0, 0, 1, 0)
+		putSh(".debug_info", shtProgbits, 0, dw.infoOff, dw.infoSize, 0, 0, 1, 0)
+		putSh(".debug_line", shtProgbits, 0, dw.lineOff, dw.lineSize, 0, 0, 1, 0)
+		putSh(".debug_line_str", shtProgbits, 0, dw.lineStrOff, dw.lineStrSize, 0, 0, 1, 0)
+		if dw.frameSize > 0 {
+			putSh(".debug_frame", shtProgbits, 0, dw.frameOff, dw.frameSize, 0, 0, 8, 0)
+		}
+	}
 
 	// ELF header.
 	hdr := out[:64]

asm/elfloong64_test.go

@@ -139,7 +139,7 @@ DATA answer<>+0(SB)/8, $42
 		t.Fatalf(".rela.text has %d bytes, want two 24-byte entries", len(raw))
 	}
 	le := binary.LittleEndian
-	for i := 0; i < 2; i++ {
+	for i := range 2 {
 		e := raw[i*24 : (i+1)*24]
 		off := le.Uint64(e[0:])
 		info := le.Uint64(e[8:])

asm/elfriscv.go

@@ -129,6 +129,9 @@ func (img *Image) ELFRISCVObject() ([]byte, error) {
 	for _, n := range []string{".text", ".data", ".symtab", ".strtab", ".rela.text", ".shstrtab"} {
 		stSections.add(n)
 	}
+	for _, n := range dwarfSectionNames {
+		stSections.add(n)
+	}
 
 	hasRela := len(relas) > 0
 	nSections := 6
@@ -188,6 +191,16 @@ func (img *Image) ELFRISCVObject() ([]byte, error) {
 	shstrOff := len(out)
 	out = append(out, stSections.bytes()...)
 
+	dwAlign := func(n int) {
+		for len(out)%n != 0 {
+			out = append(out, 0)
+		}
+	}
+	dw := appendDWARFSections(&out, img, "gasm.s", symIdx, dwAlign)
+	if dw != nil {
+		nSections += 4
+	}
+
 	align(8)
 	shoff := len(out)
 
@@ -214,6 +227,15 @@ func (img *Image) ELFRISCVObject() ([]byte, error) {
 		putSh(".rela.text", shtRela, 0, relaOff, 24*len(relas), secSymtab, secText, 8, 24)
 	}
 	putSh(".shstrtab", shtStrtab, 0, shstrOff, len(stSections.bytes()), 0, 0, 1, 0)
+	if dw != nil {
+		putSh(".debug_abbrev", shtProgbits, 0, dw.abbrevOff, dw.abbrevSize, 0, 0, 1, 0)
+		putSh(".debug_info", shtProgbits, 0, dw.infoOff, dw.infoSize, 0, 0, 1, 0)
+		putSh(".debug_line", shtProgbits, 0, dw.lineOff, dw.lineSize, 0, 0, 1, 0)
+		putSh(".debug_line_str", shtProgbits, 0, dw.lineStrOff, dw.lineStrSize, 0, 0, 1, 0)
+		if dw.frameSize > 0 {
+			putSh(".debug_frame", shtProgbits, 0, dw.frameOff, dw.frameSize, 0, 0, 8, 0)
+		}
+	}
 
 	// ELF header.
 	hdr := out[:64]

asm/encodable.go

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import "strings"
+
+// Encodable reports whether the amd64 encoder knows how to encode the
+// mnemonic.  It mirrors the dispatch in (*enc).encode: the fixed-name
+// instructions, conditional jumps, the CMOV/SET condition families, the
+// VEX/EVEX/opmask/gather/scatter vector paths, the legacy SSE tables and the
+// explicit scalar cases.  A mnemonic that parses (is in the architecture
+// table) but is not encodable would otherwise surface only at assembly time,
+// deep inside a build; the linter uses this predicate to flag it at edit
+// time.
+func Encodable(mnemonic string) bool {
+	upper := strings.ToUpper(mnemonic)
+
+	// Fixed-name instructions (no size suffix).
+	switch upper {
+	case "RET", "NOP", "CALL", "JMP":
+		return true
+	}
+	if _, ok := condCode(upper); ok {
+		return true
+	}
+
+	// VEX/EVEX and friends: the trailing B/W/L/Q/D is part of the mnemonic.
+	base, _, err := parseEvexSuffix(upper)
+	if err != nil {
+		return false
+	}
+	if isVex(base) || isEvex(base) || isKOp(base) || isGather(base) || isScatter(base) ||
+		base == "KMOVW" || base == "KMOVQ" {
+		return true
+	}
+
+	// CMOV carries size then condition (CMOVLGT); SET carries the condition
+	// alone (SETNE).
+	if rest, ok := strings.CutPrefix(upper, "CMOV"); ok && len(rest) >= 2 {
+		if _, ok := jccMap[rest[1:]]; ok {
+			return true
+		}
+	}
+	if rest, ok := strings.CutPrefix(upper, "SET"); ok {
+		if _, ok := jccMap[rest]; ok {
+			return true
+		}
+	}
+
+	// Legacy SSE shuffles and packed binaries dispatch on the full name.
+	if _, ok := sseShufTable[upper]; ok {
+		return true
+	}
+	if _, ok := sseBinTable[upper]; ok {
+		return true
+	}
+
+	// The size-suffix split: retry the tables and the scalar switch on the
+	// base.
+	base2, size := splitSize(upper)
+	if size == 0 {
+		size = 8
+	}
+	_ = size
+	if base2 != upper {
+		if _, ok := sseBinTable[base2]; ok {
+			return true
+		}
+	}
+	switch base2 {
+	case "MOV",
+		"ADD", "SUB", "AND", "OR", "XOR", "CMP",
+		"TEST",
+		"LEA",
+		"INC", "DEC", "NEG", "NOT",
+		"SHL", "SHR", "SAR",
+		"IMUL", "IMUL3",
+		"PUSH", "POP",
+		"BSF", "BSR", "LZCNT", "TZCNT", "POPCNT",
+		"BSWAP",
+		"PREFETCHNTA", "PREFETCHT0", "PREFETCHT1", "PREFETCHT2",
+		"MOVBLZX", "MOVBQZX", "MOVWLZX", "MOVWQZX", "MOVWLSX", "MOVLQSX",
+		"CVTSL2SD", "CVTSQ2SD",
+		"MOVOU", "MOVO", "MOVUPS", "MOVAPS", "MOVUPD", "MOVAPD", "MOVSD", "MOVSS":
+		return true
+	}
+	return false
+}

asm/encode.go

@@ -76,6 +76,21 @@ func (e *enc) encode(mnem string, ops []Operand) error {
 	if size == 0 {
 		size = 8 // default operand size in 64-bit mode (e.g. PUSHQ)
 	}
+	// Legacy SSE imm8 shuffles whose names end in W/H (PSHUFLW,
+	// PSHUFHW) must dispatch BEFORE the size-suffix split, and the
+	// others ride along.
+	if m, ok := sseShufTable[upper]; ok {
+		return e.encodeSSEShuf(m, ops)
+	}
+	// Legacy SSE packed binaries dispatch on the full name: the packed
+	// integer mnemonics carry real width suffixes (PADDB/PCMPGTW/...),
+	// which the size split must not eat.
+	if m, ok := sseBinTable[upper]; ok {
+		return e.encodeSSEBin(m, ops)
+	}
+	if m, ok := sseBinTable[base]; ok {
+		return e.encodeSSEBin(m, ops)
+	}
 	switch base {
 	case "MOV":
 		return e.encodeMov(ops, size)
@@ -95,8 +110,12 @@ func (e *enc) encode(mnem string, ops []Operand) error {
 		return e.encodePushPop(ops, true)
 	case "POP":
 		return e.encodePushPop(ops, false)
-	case "LZCNT", "TZCNT":
+	case "BSF", "BSR", "LZCNT", "TZCNT", "POPCNT":
 		return e.encodeCount(base, ops, size)
+	case "BSWAP":
+		return e.encodeBswap(ops, size)
+	case "PREFETCHNTA", "PREFETCHT0", "PREFETCHT1", "PREFETCHT2":
+		return e.encodePrefetch(base, ops)
 	case "MOVBLZX", "MOVBQZX", "MOVWLZX", "MOVWQZX", "MOVWLSX", "MOVLQSX":
 		return e.encodeMovExtend(base, ops)
 	case "CVTSL2SD", "CVTSQ2SD":
@@ -107,6 +126,30 @@ func (e *enc) encode(mnem string, ops []Operand) error {
 	return fmt.Errorf("unsupported instruction %q", mnem)
 }
 
+// encodePrefetch emits the 0F 18 /r prefetch hints: the reg field selects
+// the locality (NTA=0, T0=1, T1=2, T2=3) and the single operand is memory.
+func (e *enc) encodePrefetch(base string, ops []Operand) error {
+	if len(ops) != 1 {
+		return fmt.Errorf("%s expects one memory operand", base)
+	}
+	m, ok := ops[0].(Mem)
+	if !ok {
+		return fmt.Errorf("%s requires a memory operand", base)
+	}
+	i := newInstr(0, []byte{0x0F, 0x18})
+	if err := setMem(i, prefetchVariant[base], m); err != nil {
+		return err
+	}
+	return e.emit(i)
+}
+
+var prefetchVariant = map[string]int{
+	"PREFETCHNTA": 0,
+	"PREFETCHT0":  1,
+	"PREFETCHT1":  2,
+	"PREFETCHT2":  3,
+}
+
 // splitSize separates a trailing B/W/L/Q size suffix from the mnemonic.
 func splitSize(upper string) (base string, size int) {
 	if upper == "" {
@@ -297,6 +340,13 @@ func memComponents(regField int, m Mem) (modrm, sib int, disp []byte, xBit, bBit
 		return regField<<3 | 0x05, -1, le32(m.Disp), 0, 0, nil // mod=00, rm=101
 	}
 
+	// The SIB scale field only encodes 1/2/4/8; the Go assembler rejects
+	// anything else ("bad scale: 16"), so a silent fallback to scale 1 here
+	// would mis-assemble the operand instead of reporting it.
+	if m.HasIndex && m.Scale != 1 && m.Scale != 2 && m.Scale != 4 && m.Scale != 8 {
+		return 0, -1, nil, 0, 0, fmt.Errorf("bad scale: %d", m.Scale)
+	}
+
 	needSIB := m.HasIndex || (m.HasBase && m.Base.idx&7 == 4)
 
 	var mod int
@@ -369,7 +419,7 @@ func le16(v int64) []byte {
 func le64(v int64) []byte {
 	u := uint64(v)
 	b := make([]byte, 8)
-	for i := 0; i < 8; i++ {
+	for i := range 8 {
 		b[i] = byte(u >> (8 * i))
 	}
 	return b

asm/encode_test.go

@@ -4,6 +4,7 @@
 package asm
 
 import (
+	"fmt"
 	"strings"
 	"testing"
 
@@ -57,8 +58,11 @@ func TestMov(t *testing.T) {
 	checkSyntax(t, "mov qword ptr [rbx], rax", "MOVQ", AX, Ptr(BX, 0, 8))
 	checkSyntax(t, "mov rbx, qword ptr [rax+0x10]", "MOVQ", Ptr(AX, 0x10, 8), BX)
 	checkSyntax(t, "mov rbx, qword ptr [rsi+4*rbx]", "MOVQ", Idx(SI, BX, 4, 0, 8), BX)
-	checkSyntax(t, "mov rax, 0x5", "MOVQ", Imm(5), AX)
-	checkSyntax(t, "mov r8, 0x5", "MOVQ", Imm(5), Reg{idx: 8, size: 8})
+	// A small positive immediate compresses to the 32-bit zero-extending
+	// form (matching go tool asm), so the disassembler renders the 32-bit
+	// register name even for MOVQ.
+	checkSyntax(t, "mov eax, 0x5", "MOVQ", Imm(5), AX)
+	checkSyntax(t, "mov r8d, 0x5", "MOVQ", Imm(5), Reg{idx: 8, size: 8})
 	checkSyntax(t, "mov qword ptr [rax], 0x5", "MOVQ", Imm(5), Ptr(AX, 0, 8))
 	checkSyntax(t, "mov r12, r13", "MOVQ", Reg{idx: 13, size: 8}, Reg{idx: 12, size: 8})
 }
@@ -74,13 +78,63 @@ func TestALU(t *testing.T) {
 	checkSyntax(t, "cmp rsi, r10", "CMPQ", SI, Reg{idx: 10, size: 8})
 	checkSyntax(t, "add rbx, qword ptr [rax]", "ADDQ", Ptr(AX, 0, 8), BX)
 	checkSyntax(t, "add qword ptr [rax], rbx", "ADDQ", BX, Ptr(AX, 0, 8))
-	checkSyntax(t, "cmp rbx, -0x20", "CMPQ", Imm(-32), BX)
+	// The Go assembler rejects the immediate-first CMP spelling outright,
+	// so Encode errors instead of silently emitting the swapped form.
+	if _, err := Encode("CMPQ", Imm(-32), BX); err == nil {
+		t.Errorf("Encode(CMPQ imm-first) should error, got success")
+	}
 	// The Go assembler's own spelling: immediate second.
 	checkSyntax(t, "cmp ecx, 0x1f", "CMPL", CX, Imm(31))
 	checkSyntax(t, "cmp ecx, -0x80000000", "CMPL", CX, Imm(-2147483648))
 	checkSyntax(t, "cmp r9, -0x80000000", "CMPQ", Reg{idx: 9, size: 8}, Imm(-2147483648))
 }
 
+// TestScalarXmmRegMoves pins the Go-assembler byte forms of scalar
+// MOVQ/MOVL between GPRs and XMM registers (66 REX.W 0F 6E/0F 7E) and the
+// memory forms (F3 0F 7E load, 66 0F D6 store), all byte-for-byte.
+func TestScalarXmmRegMoves(t *testing.T) {
+	cases := []struct {
+		name string
+		mnem string
+		ops  []Operand
+		want string
+	}{
+		{"MOVQ AX,X1", "MOVQ", []Operand{AX, vreg(t, "X1")}, "66480f6ec8"},
+		{"MOVQ DX,X2", "MOVQ", []Operand{DX, vreg(t, "X2")}, "66480f6ed2"},
+		{"MOVQ X1,AX", "MOVQ", []Operand{vreg(t, "X1"), AX}, "66480f7ec8"},
+		{"MOVQ X0,DX", "MOVQ", []Operand{vreg(t, "X0"), DX}, "66480f7ec2"},
+		{"MOVL AX,X1", "MOVL", []Operand{AX, vreg(t, "X1")}, "660f6ec8"},
+		{"MOVL X1,AX", "MOVL", []Operand{vreg(t, "X1"), AX}, "660f7ec8"},
+		{"MOVQ (SI),X1", "MOVQ", []Operand{Ptr(SI, 0, 8), vreg(t, "X1")}, "f30f7e0e"},
+		{"MOVQ X3,(DI)", "MOVQ", []Operand{vreg(t, "X3"), Ptr(DI, 0, 8)}, "660fd61f"},
+	}
+	for _, c := range cases {
+		code, err := Encode(c.mnem, c.ops...)
+		if err != nil {
+			t.Errorf("%s: %v", c.name, err)
+			continue
+		}
+		if got := fmt.Sprintf("%x", code); got != c.want {
+			t.Errorf("%s: got %s, want %s", c.name, got, c.want)
+		}
+	}
+}
+
+// TestBadScale pins the go-tool-asm parity of rejecting SIB scales the
+// hardware cannot encode.
+func TestBadScale(t *testing.T) {
+	for _, sc := range []int{3, 5, 16, 32} {
+		if _, err := Encode("LEAQ", Idx(SI, BX, sc, 0, 8), AX); err == nil {
+			t.Errorf("LEAQ scale %d: expected error, got success", sc)
+		}
+	}
+	for _, sc := range []int{1, 2, 4, 8} {
+		if _, err := Encode("LEAQ", Idx(SI, BX, sc, 0, 8), AX); err != nil {
+			t.Errorf("LEAQ scale %d: %v", sc, err)
+		}
+	}
+}
+
 func TestLea(t *testing.T) {
 	checkSyntax(t, "lea r9, ptr [rsi+4*rbx]", "LEAQ", Idx(SI, BX, 4, 0, 8), Reg{idx: 9, size: 8})
 	checkSyntax(t, "lea rax, ptr [rbx+0x8]", "LEAQ", Ptr(BX, 0x8, 8), AX)
@@ -203,6 +257,21 @@ func TestScalarGroundTruth(t *testing.T) {
 		{"LZCNTQ R8,R9", "LZCNTQ", []Operand{r8, r9}, "f34d0fbdc8", "LZCNT"},
 		{"LZCNTW AX,CX", "LZCNTW", []Operand{AX, CX}, "66f30fbdc8", "LZCNT"},
 		{"TZCNTL AX,CX", "TZCNTL", []Operand{AX, CX}, "f30fbcc8", "TZCNT"},
+		// Bit scan: BSF/BSR are the unprefixed forms of TZCNT/LZCNT's map.
+		{"BSFL AX,CX", "BSFL", []Operand{AX, CX}, "0fbcc8", "BSF"},
+		{"BSFQ R8,R9", "BSFQ", []Operand{r8, r9}, "4d0fbcc8", "BSF"},
+		{"BSFW AX,CX", "BSFW", []Operand{AX, CX}, "660fbcc8", "BSF"},
+		{"BSRL AX,CX", "BSRL", []Operand{AX, CX}, "0fbdc8", "BSR"},
+		{"BSRQ AX,CX", "BSRQ", []Operand{AX, CX}, "480fbdc8", "BSR"},
+		{"POPCNTL AX,CX", "POPCNTL", []Operand{AX, CX}, "f30fb8c8", "POPCNT"},
+		{"POPCNTQ R8,R9", "POPCNTQ", []Operand{r8, r9}, "f34d0fb8c8", "POPCNT"},
+		// A 64-bit immediate that fits a signed int32 is compressed exactly
+		// as the Go assembler does: positive via B8+rd without REX.W
+		// (zero-extended), negative via REX.W C7 /0 (sign-extended).
+		{"MOVQ $4,BX", "MOVQ", []Operand{Imm(4), BX}, "bb04000000", "MOV"},
+		{"MOVQ $4,R8", "MOVQ", []Operand{Imm(4), r8}, "41b804000000", "MOV"},
+		{"MOVQ $-1,BX", "MOVQ", []Operand{Imm(-1), BX}, "48c7c3ffffffff", "MOV"},
+		{"MOVQ big,BX", "MOVQ", []Operand{Imm(0x1122334455667788), BX}, "48bb8877665544332211", "MOV"},
 		{"CMOVLGT CX,AX", "CMOVLGT", []Operand{CX, AX}, "0f4fc1", "CMOVG"},
 		{"CMOVLEQ CX,AX", "CMOVLEQ", []Operand{CX, AX}, "0f44c1", "CMOVE"},
 		{"CMOVQGT R9,R8", "CMOVQGT", []Operand{r9, r8}, "4d0f4fc1", "CMOVG"},
@@ -294,3 +363,85 @@ func TestScalarErrors(t *testing.T) {
 		}
 	}
 }
+
+// TestSSEBinGroundTruth checks the legacy packed/scalar binary family
+// byte for byte (no prefix / 66 / F2 / F3 variants).
+func TestSSEBinGroundTruth(t *testing.T) {
+	cases := []struct {
+		name string
+		mnem string
+		ops  []Operand
+		want string
+	}{
+		{"MULPS X0,X1", "MULPS", []Operand{vreg(t, "X0"), vreg(t, "X1")}, "0f59c8"},
+		{"MULPS (DI),X1", "MULPS", []Operand{Ptr(DI, 0, 16), vreg(t, "X1")}, "0f590f"},
+		{"ADDPD X1,X2", "ADDPD", []Operand{vreg(t, "X1"), vreg(t, "X2")}, "660f58d1"},
+		{"XORPS X0,X0", "XORPS", []Operand{vreg(t, "X0"), vreg(t, "X0")}, "0f57c0"},
+		{"UNPCKLPS X0,X0", "UNPCKLPS", []Operand{vreg(t, "X0"), vreg(t, "X0")}, "0f14c0"},
+		{"MULSD X1,X2", "MULSD", []Operand{vreg(t, "X1"), vreg(t, "X2")}, "f20f59d1"},
+		{"ADDSS (DI),X0", "ADDSS", []Operand{Ptr(DI, 0, 4), vreg(t, "X0")}, "f30f5807"},
+	}
+	for _, c := range cases {
+		code, err := Encode(c.mnem, c.ops...)
+		if err != nil {
+			t.Errorf("%s: %v", c.name, err)
+			continue
+		}
+		if got := fmt.Sprintf("%x", code); got != c.want {
+			t.Errorf("%s = %s, want %s", c.name, got, c.want)
+		}
+	}
+}
+
+// TestSSEShuffleGroundTruth checks the imm8 shuffle family: immediate
+// first in Plan 9 order, encoded last on the wire.
+func TestSSEShuffleGroundTruth(t *testing.T) {
+	cases := []struct {
+		name string
+		mnem string
+		ops  []Operand
+		want string
+	}{
+		{"SHUFPS $0,X0,X0", "SHUFPS", []Operand{Imm(0), vreg(t, "X0"), vreg(t, "X0")}, "0fc6c000"},
+		{"SHUFPS $27,X1,X2", "SHUFPS", []Operand{Imm(27), vreg(t, "X1"), vreg(t, "X2")}, "0fc6d11b"},
+		{"PSHUFD $0,X0,X0", "PSHUFD", []Operand{Imm(0), vreg(t, "X0"), vreg(t, "X0")}, "660f70c000"},
+		{"PSHUFLW $3,(DI),X1", "PSHUFLW", []Operand{Imm(3), Ptr(DI, 0, 8), vreg(t, "X1")}, "f20f700f03"},
+		{"PSHUFHW $2,X1,X2", "PSHUFHW", []Operand{Imm(2), vreg(t, "X1"), vreg(t, "X2")}, "f30f70d102"},
+	}
+	for _, c := range cases {
+		code, err := Encode(c.mnem, c.ops...)
+		if err != nil {
+			t.Errorf("%s: %v", c.name, err)
+			continue
+		}
+		if got := fmt.Sprintf("%x", code); got != c.want {
+			t.Errorf("%s = %s, want %s", c.name, got, c.want)
+		}
+	}
+}
+
+// TestMOVQXMMGroundTruth pins the SSE2 packed-quadword move encodings:
+// loads and register moves on F3 0F 7E, stores on 66 0F D6 — the forms
+// the GPR-move fallback silently corrupted.
+func TestMOVQXMMGroundTruth(t *testing.T) {
+	cases := []struct {
+		name string
+		mnem string
+		ops  []Operand
+		want string
+	}{
+		{"MOVQ (DI),X0", "MOVQ", []Operand{Ptr(DI, 0, 8), vreg(t, "X0")}, "f30f7e07"},
+		{"MOVQ X1,X2", "MOVQ", []Operand{vreg(t, "X1"), vreg(t, "X2")}, "f30f7ed1"},
+		{"MOVQ X0,(DI)", "MOVQ", []Operand{vreg(t, "X0"), Ptr(DI, 0, 8)}, "660fd607"},
+	}
+	for _, c := range cases {
+		code, err := Encode(c.mnem, c.ops...)
+		if err != nil {
+			t.Errorf("%s: %v", c.name, err)
+			continue
+		}
+		if got := fmt.Sprintf("%x", code); got != c.want {
+			t.Errorf("%s = %s, want %s", c.name, got, c.want)
+		}
+	}
+}

asm/evex.go

@@ -166,6 +166,19 @@ var evexTable = map[string]evexSpec{
 	"VCMPSD": {1, 0xC2, 1, 3, -1, vexNDS3Imm, [3]int{8, 8, 8}},
 	"VCMPSS": {1, 0xC2, 0, 2, -1, vexNDS3Imm, [3]int{4, 4, 4}},
 
+	// EVEX.66.0F3A — integer compares with an opmask destination, the same
+	// NDS3Imm-with-k-reg shape as the floating-point compares; W selects the
+	// operand width (byte/word vs dword/qword), the opcode the signedness.
+	// The memory form takes a full vector, so disp8×N is 16/32/64.
+	"VPCMPB":  {3, 0x3F, 0, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPUB": {3, 0x3E, 0, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPW":  {3, 0x3F, 1, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPUW": {3, 0x3E, 1, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPD":  {3, 0x1F, 0, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPUD": {3, 0x1E, 0, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPQ":  {3, 0x1F, 1, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+	"VPCMPUQ": {3, 0x1E, 1, 1, -1, vexNDS3Imm, [3]int{16, 32, 64}},
+
 	// EVEX.66.0F38 — permutes (NDS form).
 	"VPERMB":    {2, 0x8D, 0, 1, -1, vexNDS3, [3]int{16, 32, 64}},
 	"VPERMW":    {2, 0x8D, 1, 1, -1, vexNDS3, [3]int{16, 32, 64}},
@@ -590,12 +603,12 @@ func (s evexSuffix) evexOnly() bool {
 // broadcast together with rounding/SAE.
 func parseEvexSuffix(mnem string) (string, evexSuffix, error) {
 	sfx := evexSuffix{rounding: -1}
-	i := strings.IndexByte(mnem, '.')
-	if i < 0 {
+	before, after, ok := strings.Cut(mnem, ".")
+	if !ok {
 		return mnem, sfx, nil
 	}
-	base := mnem[:i]
-	parts := strings.Split(mnem[i+1:], ".")
+	base := before
+	parts := strings.Split(after, ".")
 	seen := map[string]bool{}
 	for j, p := range parts {
 		if seen[p] {
@@ -605,7 +618,7 @@ func parseEvexSuffix(mnem string) (string, evexSuffix, error) {
 		switch p {
 		case "Z":
 			if j != len(parts)-1 {
-				return "", sfx, fmt.Errorf("the .Z suffix must come last in %q", mnem[i+1:])
+				return "", sfx, fmt.Errorf("the .Z suffix must come last in %q", after)
 			}
 			sfx.zeroing = true
 		case "SAE":
@@ -625,7 +638,7 @@ func parseEvexSuffix(mnem string) (string, evexSuffix, error) {
 		}
 	}
 	if sfx.bcst && (sfx.sae || sfx.rounding >= 0) {
-		return "", sfx, fmt.Errorf("cannot combine .BCST with rounding or SAE in %q", mnem[i+1:])
+		return "", sfx, fmt.Errorf("cannot combine .BCST with rounding or SAE in %q", after)
 	}
 	return base, sfx, nil
 }
@@ -688,7 +701,7 @@ func splitMask(ops []Operand) ([]Operand, int, error) {
 				return nil, 0, fmt.Errorf("at most one mask register operand")
 			}
 			if r.idx == 0 {
-				return nil, 0, fmt.Errorf("K0 is not a usable mask register")
+				return nil, 0, fmt.Errorf("k0 is not a usable mask register")
 			}
 			mask = r.idx
 			continue
@@ -1190,7 +1203,7 @@ func (e *enc) emitEvexFields(spec evexSpec, ll, regIdx, vvvvIdx int, rm Operand,
 	// The b bit and the L'L field carry the rounding/SAE/broadcast mode:
 	// a rounding mode replaces L'L with the rc value, plain SAE and
 	// broadcast keep the vector length.
-	b, ll := 0, ll
+	b := 0
 	switch {
 	case sfx.rounding >= 0:
 		b, ll = 1, sfx.rounding
@@ -1471,24 +1484,60 @@ type kOpSpec struct {
 
 var kOpsTable = map[string]kOpSpec{
 	// k ← k OP k: reg = dst, vvvv = src1, rm = src2 (three opmask
-	// registers).
+	// registers).  Byte/word widths share W0 and differ by the 66 prefix;
+	// dword/qword share the W bit selection the Go assembler emits.
 	"KANDB":    {1, 0x41, 0, 1, 1, vexNDS3},
 	"KANDW":    {1, 0x41, 0, 0, 1, vexNDS3},
+	"KANDD":    {1, 0x41, 1, 1, 1, vexNDS3},
 	"KANDQ":    {1, 0x41, 1, 0, 1, vexNDS3},
+	"KANDNB":   {1, 0x42, 0, 1, 1, vexNDS3},
+	"KANDNW":   {1, 0x42, 0, 0, 1, vexNDS3},
+	"KANDND":   {1, 0x42, 1, 1, 1, vexNDS3},
+	"KANDNQ":   {1, 0x42, 1, 0, 1, vexNDS3},
 	"KORB":     {1, 0x45, 0, 1, 1, vexNDS3},
+	"KORW":     {1, 0x45, 0, 0, 1, vexNDS3},
 	"KORD":     {1, 0x45, 1, 1, 1, vexNDS3},
+	"KORQ":     {1, 0x45, 1, 0, 1, vexNDS3},
+	"KXNORB":   {1, 0x46, 0, 1, 1, vexNDS3},
 	"KXNORW":   {1, 0x46, 0, 0, 1, vexNDS3},
+	"KXNORD":   {1, 0x46, 1, 1, 1, vexNDS3},
 	"KXNORQ":   {1, 0x46, 1, 0, 1, vexNDS3},
+	"KXORB":    {1, 0x47, 0, 1, 1, vexNDS3},
+	"KXORW":    {1, 0x47, 0, 0, 1, vexNDS3},
+	"KXORD":    {1, 0x47, 1, 1, 1, vexNDS3},
+	"KXORQ":    {1, 0x47, 1, 0, 1, vexNDS3},
 	"KUNPCKBW": {1, 0x4B, 0, 1, 1, vexNDS3},
 	"KUNPCKDQ": {1, 0x4B, 1, 0, 1, vexNDS3},
 	"KADDB":    {1, 0x4A, 0, 1, 1, vexNDS3},
 	"KADDW":    {1, 0x4A, 0, 0, 1, vexNDS3},
+	"KADDD":    {1, 0x4A, 1, 1, 1, vexNDS3},
 	"KADDQ":    {1, 0x4A, 1, 0, 1, vexNDS3},
-	// k ← OP k (KNOT) and flags ← k OP k (KORTEST): reg = dst, rm = src.
+	// k ← OP k (KNOT), k ← k AND~ k (KTEST-style RM) and flags ← k OP k
+	// (KORTEST): reg = dst, rm = src.
 	"KNOTB":    {1, 0x44, 0, 1, 0, vexRM},
+	"KNOTW":    {1, 0x44, 0, 0, 0, vexRM},
+	"KNOTD":    {1, 0x44, 1, 1, 0, vexRM},
+	"KNOTQ":    {1, 0x44, 1, 0, 0, vexRM},
+	"KORTESTB": {1, 0x98, 0, 1, 0, vexRM},
+	"KORTESTW": {1, 0x98, 0, 0, 0, vexRM},
 	"KORTESTD": {1, 0x98, 1, 1, 0, vexRM},
-	// OP $imm, src, dst: reg = dst, rm = src, imm8.
+	"KORTESTQ": {1, 0x98, 1, 0, 0, vexRM},
+	"KTESTB":   {1, 0x99, 0, 1, 0, vexRM},
+	"KTESTW":   {1, 0x99, 0, 0, 0, vexRM},
+	"KTESTD":   {1, 0x99, 1, 1, 0, vexRM},
+	"KTESTQ":   {1, 0x99, 1, 0, 0, vexRM},
+	// OP $imm, src, dst: reg = dst, rm = src, imm8.  The opcodes split by
+	// direction (0x32/0x33 left, 0x30/0x31 right) and within each by
+	// element half (0x32 byte/word, 0x33 dword/qword); W picks byte/dword
+	// (W0) against word/qword (W1).
+	"KSHIFTLB": {3, 0x32, 0, 1, 0, vexImmRM},
 	"KSHIFTLW": {3, 0x32, 1, 1, 0, vexImmRM},
+	"KSHIFTLD": {3, 0x33, 0, 1, 0, vexImmRM},
+	"KSHIFTLQ": {3, 0x33, 1, 1, 0, vexImmRM},
+	"KSHIFTRB": {3, 0x30, 0, 1, 0, vexImmRM},
+	"KSHIFTRW": {3, 0x30, 1, 1, 0, vexImmRM},
+	"KSHIFTRD": {3, 0x31, 0, 1, 0, vexImmRM},
+	"KSHIFTRQ": {3, 0x31, 1, 1, 0, vexImmRM},
 }
 
 // isKOp reports whether the mnemonic is an opmask-register instruction.

asm/evex_test.go

@@ -319,6 +319,43 @@ func TestEvexExtendedGroundTruth(t *testing.T) {
 		{"KORTESTD", "KORTESTD", []Operand{vreg(t, "K1"), vreg(t, "K2")}, "c4e1f998d1"},
 		{"KMOVQ k,k", "KMOVQ", []Operand{vreg(t, "K1"), vreg(t, "K2")}, "c4e1f890d1"},
 		{"KMOVQ gpr,k", "KMOVQ", []Operand{BX, vreg(t, "K1")}, "c4e1fb92cb"},
+		// Completed opmask families (ANDN, NOT, OR/XOR word+qword, TEST,
+		// word-width shifts; byte-exact against go tool asm).
+		{"KANDNW", "KANDNW", []Operand{vreg(t, "K1"), vreg(t, "K2"), vreg(t, "K3")}, "c5ec42d9"},
+		{"KANDNB", "KANDNB", []Operand{vreg(t, "K4"), vreg(t, "K5"), vreg(t, "K6")}, "c5d542f4"},
+		{"KANDND", "KANDND", []Operand{vreg(t, "K1"), vreg(t, "K2"), vreg(t, "K3")}, "c4e1ed42d9"},
+		{"KANDNQ", "KANDNQ", []Operand{vreg(t, "K4"), vreg(t, "K5"), vreg(t, "K6")}, "c4e1d442f4"},
+		{"KANDD", "KANDD", []Operand{vreg(t, "K1"), vreg(t, "K2"), vreg(t, "K3")}, "c4e1ed41d9"},
+		{"KADDD", "KADDD", []Operand{vreg(t, "K4"), vreg(t, "K5"), vreg(t, "K6")}, "c4e1d54af4"},
+		{"KNOTW", "KNOTW", []Operand{vreg(t, "K1"), vreg(t, "K2")}, "c5f844d1"},
+		{"KNOTD", "KNOTD", []Operand{vreg(t, "K3"), vreg(t, "K4")}, "c4e1f944e3"},
+		{"KNOTQ", "KNOTQ", []Operand{vreg(t, "K5"), vreg(t, "K6")}, "c4e1f844f5"},
+		{"KORW", "KORW", []Operand{vreg(t, "K1"), vreg(t, "K2"), vreg(t, "K3")}, "c5ec45d9"},
+		{"KORQ", "KORQ", []Operand{vreg(t, "K4"), vreg(t, "K5"), vreg(t, "K6")}, "c4e1d445f4"},
+		{"KXNORB", "KXNORB", []Operand{vreg(t, "K1"), vreg(t, "K2"), vreg(t, "K3")}, "c5ed46d9"},
+		{"KXORW", "KXORW", []Operand{vreg(t, "K1"), vreg(t, "K2"), vreg(t, "K3")}, "c5ec47d9"},
+		{"KXORQ", "KXORQ", []Operand{vreg(t, "K4"), vreg(t, "K5"), vreg(t, "K6")}, "c4e1d447f4"},
+		{"KORTESTW", "KORTESTW", []Operand{vreg(t, "K1"), vreg(t, "K2")}, "c5f898d1"},
+		{"KORTESTB", "KORTESTB", []Operand{vreg(t, "K3"), vreg(t, "K4")}, "c5f998e3"},
+		{"KORTESTQ", "KORTESTQ", []Operand{vreg(t, "K5"), vreg(t, "K6")}, "c4e1f898f5"},
+		{"KTESTW", "KTESTW", []Operand{vreg(t, "K1"), vreg(t, "K2")}, "c5f899d1"},
+		{"KTESTD", "KTESTD", []Operand{vreg(t, "K3"), vreg(t, "K4")}, "c4e1f999e3"},
+		{"KSHIFTLB", "KSHIFTLB", []Operand{Imm(1), vreg(t, "K1"), vreg(t, "K2")}, "c4e37932d101"},
+		{"KSHIFTLD", "KSHIFTLD", []Operand{Imm(2), vreg(t, "K3"), vreg(t, "K4")}, "c4e37933e302"},
+		{"KSHIFTLQ", "KSHIFTLQ", []Operand{Imm(3), vreg(t, "K5"), vreg(t, "K6")}, "c4e3f933f503"},
+		{"KSHIFTRB", "KSHIFTRB", []Operand{Imm(4), vreg(t, "K1"), vreg(t, "K2")}, "c4e37930d104"},
+		{"KSHIFTRW", "KSHIFTRW", []Operand{Imm(5), vreg(t, "K3"), vreg(t, "K4")}, "c4e3f930e305"},
+		{"KSHIFTRQ", "KSHIFTRQ", []Operand{Imm(6), vreg(t, "K5"), vreg(t, "K6")}, "c4e3f931f506"},
+		// Integer compares with an opmask destination (0F3A map, the
+		// go-bzip2 partition kernel's classify instructions).
+		{"VPCMPUB", "VPCMPUB", []Operand{Imm(1), vreg(t, "X1"), vreg(t, "X0"), vreg(t, "K1")}, "62f37d083ec901"},
+		{"VPCMPB", "VPCMPB", []Operand{Imm(2), vreg(t, "Y2"), vreg(t, "Y3"), vreg(t, "K2")}, "62f365283fd202"},
+		{"VPCMPUW", "VPCMPUW", []Operand{Imm(5), vreg(t, "Z1"), vreg(t, "Z2"), vreg(t, "K3")}, "62f3ed483ed905"},
+		{"VPCMPW", "VPCMPW", []Operand{Imm(6), vreg(t, "X3"), vreg(t, "X4"), vreg(t, "K4")}, "62f3dd083fe306"},
+		{"VPCMPD", "VPCMPD", []Operand{Imm(0), vreg(t, "Y1"), vreg(t, "Y2"), vreg(t, "K1")}, "62f36d281fc900"},
+		{"VPCMPUD", "VPCMPUD", []Operand{Imm(1), vreg(t, "Z2"), vreg(t, "Z3"), vreg(t, "K2")}, "62f365481ed201"},
+		{"VPCMPQ", "VPCMPQ", []Operand{Imm(2), vreg(t, "X1"), vreg(t, "X2"), vreg(t, "K3")}, "62f3ed081fd902"},
+		{"VPCMPUQ", "VPCMPUQ", []Operand{Imm(3), vreg(t, "Y3"), vreg(t, "Y4"), vreg(t, "K4")}, "62f3dd281ee303"},
 		// Lane extract / insert.
 		{"VEXTRACTF32X4", "VEXTRACTF32X4", []Operand{Imm(1), vreg(t, "Y1"), vreg(t, "X2")}, "62f37d2819ca01"},
 		{"VEXTRACTI64X2", "VEXTRACTI64X2", []Operand{Imm(1), vreg(t, "Y1"), vreg(t, "X2")}, "62f3fd2839ca01"},

asm/goobj.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"sync"
 )
 
@@ -32,7 +33,10 @@ import (
 // methods supply the toolchain preamble, the MinLC (pc-value delta unit)
 // and the relocation-type mapping for code relocations.
 
-// GOOBJ block indices (cmd/internal/goobj).
+// GOOBJ block indices (cmd/internal/goobj).  These MUST match the real
+// archive layout: the emitter writes the header offsets per index and the
+// reader (groundtruth, goobj_resolve) parses real Go archives with them.
+// blkAutolib is unused by the emitter but still defines index 0.
 const (
 	blkAutolib = iota
 	blkPkgIdx
@@ -90,12 +94,50 @@ const (
 )
 
 // Relocation types (cmd/internal/objabi).
+// R_PCREL and R_ADDR are stable across Go versions.
 const (
-	relocPCRel       = 14  // R_PCREL
-	relocAddr        = 1   // R_ADDR
-	relocDWTXTADDRU4 = 106 // R_DWTXTADDR_U4
+	relocPCRel = 14 // R_PCREL
+	relocAddr  = 1  // R_ADDR
 )
 
+// relocDWTXTADDRU4 returns the R_DWTXTADDR_U4 relocation type for the
+// installed Go toolchain.  The value shifted between Go 1.26 (103) and
+// Go 1.27 (106) because new LoongArch relocations were inserted before it.
+func relocDWTXTADDRU4() uint16 {
+	if isGo127OrLater() {
+		return 106
+	}
+	return 103
+}
+
+var (
+	goVersionOnce sync.Once
+	goVersionGT26 bool
+)
+
+// isGo127OrLater reports whether the installed Go toolchain is 1.27 or later.
+func isGo127OrLater() bool {
+	goVersionOnce.Do(func() {
+		goBin, err := exec.LookPath("go")
+		if err != nil {
+			return
+		}
+		out, err := exec.Command(goBin, "version").Output()
+		if err != nil {
+			return
+		}
+		// "go version go1.27rc1 linux/amd64"
+		s := string(out)
+		for _, prefix := range []string{"go version go1.27", "go version go1.28", "go version go1.29", "go version go2."} {
+			if strings.Contains(s, prefix) {
+				goVersionGT26 = true
+				return
+			}
+		}
+	})
+	return goVersionGT26
+}
+
 // Special package indices for symbol references.
 const (
 	pkgIdxNone = 0x7fffffff
@@ -378,7 +420,7 @@ func (img *Image) emitGOObject(pkgPath, srcPath string, pre []byte, minLC int, r
 	// The string table.  Absolute offsets: it starts right after the
 	// 96-byte header (magic, fingerprint, flags, the 19 block offsets).
 	const headerSize = 8 + 8 + 4 + 4*(blkEnd+1)
-	strTab := []byte{}
+	var strTab []byte
 	strOff := map[string]uint32{}
 	addStr := func(s string) {
 		if _, ok := strOff[s]; ok {
@@ -425,7 +467,7 @@ func (img *Image) emitGOObject(pkgPath, srcPath string, pre []byte, minLC int, r
 	auxIdxBlk := make([]byte, 0, 4*(nsyms+1))
 	dataIdxBlk := make([]byte, 0, 4*(nsyms+1))
 	var nr, na, nd uint32
-	for si := 0; si < nsyms; si++ {
+	for si := range nsyms {
 		relocIdxBlk = binary.LittleEndian.AppendUint32(relocIdxBlk, nr)
 		auxIdxBlk = binary.LittleEndian.AppendUint32(auxIdxBlk, na)
 		dataIdxBlk = binary.LittleEndian.AppendUint32(dataIdxBlk, nd)
@@ -466,7 +508,7 @@ func (img *Image) emitGOObject(pkgPath, srcPath string, pre []byte, minLC int, r
 	// The fingerprint stays zero, as cmd/asm leaves it.
 	binary.LittleEndian.PutUint32(payload[16:], 4) // ObjFlagFromAssembly
 	off := uint32(headerSize + len(strTab))
-	for i := 0; i < blkEnd; i++ {
+	for i := range blkEnd {
 		binary.LittleEndian.PutUint32(payload[20+4*i:], off)
 		off += uint32(len(blocks[i]))
 	}

asm/goobj_dwarf.go

@@ -139,10 +139,7 @@ func dwSelectOpcode(deltaPC uint64, deltaLC int64) int64 {
 		return int64(dwOpcodeBase) + (deltaLC - dwLineBase) + dwLineRange*int64(deltaPC)
 	default:
 		if deltaPC <= uint64(dwPCRange) {
-			op := int64(dwOpcodeBase) + (dwLineRange - 1) + dwLineRange*int64(deltaPC)
-			if op > 255 {
-				op = 255
-			}
+			op := min(int64(dwOpcodeBase)+(dwLineRange-1)+dwLineRange*int64(deltaPC), 255)
 			return op
 		}
 		switch deltaPC - uint64(dwPCRange) {
@@ -181,7 +178,7 @@ func goobjDwarfInfo(fn FuncLayout, name string, fnNpIdx int) ([]byte, []goobjRel
 	out = append(out, 0) // end of children
 
 	relocs := []goobjReloc{{
-		off: int32(addrx), siz: 4, typ: relocDWTXTADDRU4,
+		off: int32(addrx), siz: 4, typ: relocDWTXTADDRU4(),
 		pkg: pkgIdxNone, sym: uint32(fnNpIdx),
 	}}
 	return out, relocs

asm/goobj_dwarf_test.go

@@ -169,7 +169,7 @@ func TestGoobjDwarfInfo(t *testing.T) {
 	if !bytes.Equal(die, want) {
 		t.Errorf("DIE = %x, want %x", die, want)
 	}
-	if len(relocs) != 1 || relocs[0].off != 7 || relocs[0].siz != 4 || relocs[0].typ != relocDWTXTADDRU4 || relocs[0].sym != 3 {
+	if len(relocs) != 1 || relocs[0].off != 7 || relocs[0].siz != 4 || relocs[0].typ != relocDWTXTADDRU4() || relocs[0].sym != 3 {
 		t.Errorf("relocs = %+v", relocs)
 	}
 

asm/goobj_resolve.go

@@ -12,24 +12,6 @@ import (
 	"strings"
 )
 
-// readGOOBJSymbols reads the GOOBJ symbol definitions from a compiled Go
-// package's export file.  The file is an ar archive containing a __.PKGDEF
-// member whose payload is the "go object ...\n!\n" preamble followed by the
-// GOOBJ data.  The function returns the symbol names in definition order
-// (the order they appear in blkSymdef), which matches the SymIdx the linker
-// expects for cross-package references.
-func readGOOBJSymbols(exportPath string) ([]string, error) {
-	data, err := os.ReadFile(exportPath)
-	if err != nil {
-		return nil, err
-	}
-	goobj, err := extractGOOBJ(data)
-	if err != nil {
-		return nil, fmt.Errorf("%s: %w", exportPath, err)
-	}
-	return goobj.symbols(), nil
-}
-
 // exportPath returns the export file path for a given import path by running
 // "go list -export".  The result is cached so repeated calls for the same
 // package are fast.
@@ -221,7 +203,7 @@ func (f *goobjFile) readSymNames(block []byte) []string {
 	}
 	n := len(block) / recSize
 	names := make([]string, 0, n)
-	for i := 0; i < n; i++ {
+	for i := range n {
 		rec := block[i*recSize : (i+1)*recSize]
 		nameLen := binary.LittleEndian.Uint32(rec[0:4])
 		nameOff := binary.LittleEndian.Uint32(rec[4:8])
@@ -341,8 +323,8 @@ func splitQualified(full string) (pkg, name string) {
 	if idx := strings.IndexByte(full, '\u00b7'); idx >= 0 {
 		return full[:idx], full[idx+len("\u00b7"):]
 	}
-	if idx := strings.IndexByte(full, '.'); idx >= 0 {
-		return full[:idx], full[idx+1:]
+	if before, after, ok := strings.Cut(full, "."); ok {
+		return before, after
 	}
 	return "", full
 }

asm/goobj_test.go

@@ -186,7 +186,7 @@ DATA mask<>+8(SB)/8, $0x800f0e0d0c0b0a09
 		t.Errorf("addq lines reloc = %x", lr)
 	}
 	dr := relocs[23:46]
-	if dr[4] != 4 || le.Uint16(dr[5:]) != relocDWTXTADDRU4 ||
+	if dr[4] != 4 || le.Uint16(dr[5:]) != relocDWTXTADDRU4() ||
 		le.Uint32(dr[15:]) != pkgIdxNone || le.Uint32(dr[19:]) != 4 {
 		t.Errorf("addq DIE reloc = %x", dr)
 	}
@@ -379,7 +379,7 @@ func main() {
 	if err := os.WriteFile(filepath.Join(dir, "main.go"), []byte(mainSrc), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(dir, "go.mod"), []byte("module goobjtest\n\ngo 1.26\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(dir, "go.mod"), []byte("module goobjtest\n\ngo 1.27\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 
@@ -393,7 +393,7 @@ func main() {
 	}
 	var work string
 	var asmObj, pkgArch, linkLine string
-	for _, line := range strings.Split(string(buildLog), "\n") {
+	for line := range strings.SplitSeq(string(buildLog), "\n") {
 		switch {
 		case strings.HasPrefix(line, "WORK="):
 			work = strings.TrimPrefix(line, "WORK=")
@@ -461,7 +461,7 @@ func main() {
 	newArch := filepath.Join(dir, "pkg.a")
 	args := []string{"tool", "pack", "c", newArch}
 	seen := map[string]bool{}
-	for _, m := range strings.Fields(string(listOut)) {
+	for m := range strings.FieldsSeq(string(listOut)) {
 		if seen[m] {
 			continue
 		}

asm/goobjarm64.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sync"
+)
+
+// GOObjectAARCH64 emits a GOOBJ object file for AArch64.  The layout is
+// the shared one in goobj.go — the toolchain preamble, the go120ld header
+// with its block offsets, the string table, the symbol definitions and the
+// reloc/aux/data index arrays — with the arm64 preamble, the MinLC of 4
+// for the pc-value deltas, and R_ADDRARM64 relocation types for the
+// ADRP+ADD/LDR/STR address pairs.
+func (img *Image) GOObjectAARCH64(pkgPath, srcPath string) ([]byte, error) {
+	pre, err := toolchainObjectPreambleAARCH64()
+	if err != nil {
+		return nil, err
+	}
+	return img.emitGOObject(pkgPath, srcPath, pre, 4, func(r Reloc) (uint16, uint8) {
+		if r.Kind == RelArm64Branch {
+			return relocArm64Branch, 4
+		}
+		return relocArm64Addr, 4
+	})
+}
+
+// arm64 relocation types (cmd/internal/objabi).
+const (
+	relocArm64Addr   = 3 // R_ADDRARM64 — ADRP+ADD/LDR/STR pair
+	relocArm64Branch = 9 // R_CALLARM64 — BL instruction
+)
+
+// toolchainObjectPreambleAARCH64 returns the "go object ...\n!\n" header
+// the installed go tool asm writes for arm64, captured by assembling a
+// one-instruction probe.
+var (
+	preambleAARCH64Once sync.Once
+	preambleAARCH64     []byte
+	preambleAARCH64Err  error
+)
+
+func toolchainObjectPreambleAARCH64() ([]byte, error) {
+	preambleAARCH64Once.Do(func() {
+		goBin, err := exec.LookPath("go")
+		if err != nil {
+			preambleAARCH64Err = fmt.Errorf("GOOBJ emission needs the Go toolchain: %w", err)
+			return
+		}
+		dir, err := os.MkdirTemp("", "gasm-preamble-arm64")
+		if err != nil {
+			preambleAARCH64Err = err
+			return
+		}
+		defer os.RemoveAll(dir)
+		src := filepath.Join(dir, "probe_arm64.s")
+		if err := os.WriteFile(src, []byte("TEXT \u00b7x(SB), $0-0\n\tRET\n"), 0o644); err != nil {
+			preambleAARCH64Err = err
+			return
+		}
+		obj := filepath.Join(dir, "probe.o")
+		cmd := exec.Command(goBin, "tool", "asm", "-p", "probe", "-o", obj, src)
+		cmd.Env = append(os.Environ(), "GOARCH=arm64")
+		if out, err := cmd.CombinedOutput(); err != nil {
+			preambleAARCH64Err = fmt.Errorf("probing the assembler for the object header: %v\n%s", err, out)
+			return
+		}
+		data, err := os.ReadFile(obj)
+		if err != nil {
+			preambleAARCH64Err = err
+			return
+		}
+		i := bytes.Index(data, []byte("\n!\n"))
+		if i < 0 || !bytes.HasPrefix(data[i+3:], []byte(goobjMagic)) {
+			preambleAARCH64Err = fmt.Errorf("unrecognised assembler object layout")
+			return
+		}
+		preambleAARCH64 = data[:i+3]
+	})
+	return preambleAARCH64, preambleAARCH64Err
+}

asm/instrs.go

@@ -48,6 +48,57 @@ func (e *enc) encodeMov(ops []Operand, size int) error {
 	}
 	src, dst := ops[0], ops[1]
 
+	// Integer scalar XMM moves: MOVQ with an XMM operand is the SSE2
+	// packed-quadword move, NOT a GPR move: mem→xmm encodes as F3 0F 7E
+	// (reg = dst, no REX.W — the Go assembler's form), xmm→mem as
+	// 66 0F D6 (rm = xmm).  Register forms against a GPR use the MOVD
+	// opcodes with REX.W instead: 66 REX.W 0F 6E (gpr→xmm) and
+	// 66 REX.W 0F 7E (xmm→gpr); the memory opcodes with a register r/m
+	// would be undefined forms.  MOVL is the packed-dword move:
+	// 66 0F 6E load, 66 0F 7E store, no REX.W.  A GPR-move fallback would
+	// silently emit REX.W 8B with the wrong operand meaning.
+	_, srcVec := vecReg(src)
+	dstReg, dstVec := vecReg(dst)
+	if srcVec || dstVec {
+		if dstVec {
+			if g, ok := src.(Reg); ok && !g.isVec() {
+				i := &instr{prefix: 0x66, opcode: []byte{0x0F, 0x6E}, modrm: -1, sib: -1, rexW: size == 8}
+				if err := setRM(i, dstReg, src, 8); err != nil {
+					return err
+				}
+				return e.emit(i)
+			}
+			i := &instr{prefix: 0xF3, opcode: []byte{0x0F, 0x7E}, modrm: -1, sib: -1}
+			if size == 4 {
+				i.prefix = 0x66
+				i.opcode = []byte{0x0F, 0x6E}
+			}
+			if err := setRM(i, dstReg, src, 8); err != nil {
+				return err
+			}
+			return e.emit(i)
+		}
+		srcXMM, srcIsXMM := src.(Reg)
+		if !srcIsXMM || !srcXMM.isVec() {
+			return fmt.Errorf("MOV: store needs an XMM source")
+		}
+		if g, ok := dst.(Reg); ok && !g.isVec() {
+			i := &instr{prefix: 0x66, opcode: []byte{0x0F, 0x7E}, modrm: -1, sib: -1, rexW: size == 8}
+			if err := setRM(i, srcXMM, dst, 8); err != nil {
+				return err
+			}
+			return e.emit(i)
+		}
+		i := &instr{prefix: 0x66, opcode: []byte{0x0F, 0xD6}, modrm: -1, sib: -1}
+		if size == 4 {
+			i.opcode = []byte{0x0F, 0x7E}
+		}
+		if err := setRM(i, srcXMM, dst, 8); err != nil {
+			return err
+		}
+		return e.emit(i)
+	}
+
 	dstReg, dstIsReg := dst.(Reg)
 	switch src := src.(type) {
 	case Reg:
@@ -91,7 +142,28 @@ func (e *enc) encodeMov(ops []Operand, size int) error {
 
 	case Imm:
 		if dstIsReg {
-			// MOV r, imm: 0xB0+reg (8-bit) / 0xB8+reg (16/32/64, imm64 for Q).
+			v := int64(src)
+			// The Go assembler compresses 64-bit moves whose immediate fits
+			// a signed int32, choosing per sign:
+			//   v >= 0: B8+rd imm32 without REX.W (zero-extended by the
+			//           hardware, REX.B still emitted for R8-R15);
+			//   v <  0: REX.W C7 /0 imm32 (sign-extended — the plain B8+rd
+			//           form would zero-extend and corrupt the value).
+			// Out-of-range immediates keep the B8+rd imm64 form.
+			if size == 8 && v >= 0 && v <= (1<<31)-1 {
+				i := newInstr(4, []byte{0xB8 + byte(dstReg.idx&7)})
+				i.rexB = dstReg.idx >= 8
+				i.imm = le32(v)
+				return e.emit(i)
+			}
+			if size == 8 && v < 0 && v >= -(1<<31) {
+				i := newInstr(8, []byte{0xC7})
+				if err := setRMDigit(i, 0, dstReg, 8); err != nil {
+					return err
+				}
+				i.imm = le32(v)
+				return e.emit(i)
+			}
 			opBase := byte(0xB8)
 			if size == 1 {
 				opBase = 0xB0
@@ -101,7 +173,7 @@ func (e *enc) encodeMov(ops []Operand, size int) error {
 			if dstReg.needsREX(size) {
 				i.rexForced = true
 			}
-			i.imm = immediate(int64(src), size, true)
+			i.imm = immediate(v, size, true)
 			return e.emit(i)
 		}
 		// MOV r/m, imm: 0xC6 (8-bit) / 0xC7 /0.
@@ -144,7 +216,13 @@ func (e *enc) encodeALU(op struct {
 	}
 	src, dst := ops[0], ops[1]
 
+	// CMP never takes its immediate first: the Go assembler rejects
+	// CMPL $0, AX outright (only CMPL AX, $0 is legal, unlike TEST and the
+	// writing ALU ops whose immediate is naturally the source).
 	if imm, ok := src.(Imm); ok {
+		if op.digit == 7 {
+			return fmt.Errorf("CMP immediate must be the second operand (reg, $imm)")
+		}
 		return e.encodeALUImm(op.digit, dst, int64(imm), size)
 	}
 
@@ -235,6 +313,15 @@ func (e *enc) encodeALUImm(digit int, dst Operand, imm int64, size int) error {
 		i.imm = []byte{byte(int8(imm))}
 		return e.emit(i)
 	}
+	// 0x81 /digit, imm16/imm32 — or the Go assembler's accumulator short
+	// form (opcode+5, no ModR/M) when the destination is AX/AL, which it
+	// prefers over the generic form exactly here.
+	if r, ok := dst.(Reg); ok && r.idx == 0 {
+		accOp := map[int]byte{0: 0x05, 1: 0x0D, 2: 0x15, 3: 0x1D, 4: 0x25, 5: 0x2D, 6: 0x35, 7: 0x3D}[digit]
+		i := newInstr(size, []byte{accOp})
+		i.imm = immediate(imm, size, false)
+		return e.emit(i)
+	}
 	// 0x81 /digit, imm16/imm32.
 	i := newInstr(size, []byte{0x81})
 	if err := setRMDigit(i, digit, dst, size); err != nil {
@@ -252,7 +339,18 @@ func (e *enc) encodeTest(ops []Operand, size int) error {
 	}
 	src, dst := ops[0], ops[1]
 	if imm, ok := src.(Imm); ok {
-		// TEST r/m, imm: 0xF6 (8-bit) / 0xF7 /0.
+		// TEST r/m, imm: 0xF6 (8-bit) / 0xF7 /0 — but the Go assembler
+		// always uses the accumulator forms (A8/A9, no ModR/M) when the
+		// register operand is AL/AX, whatever the immediate's width.
+		if r, ok := dst.(Reg); ok && r.idx == 0 {
+			op := byte(0xA9)
+			if size == 1 {
+				op = 0xA8
+			}
+			i := newInstr(size, []byte{op})
+			i.imm = immediate(int64(imm), size, false)
+			return e.emit(i)
+		}
 		op := byte(0xF7)
 		if size == 1 {
 			op = 0xF6
@@ -597,31 +695,60 @@ func (e *enc) encodeSet(upper string, ops []Operand) error {
 	return e.emit(i)
 }
 
-// --- LZCNT / TZCNT ----------------------------------------------------------
+// --- bit scan / bit count ----------------------------------------------------
 
-// encodeCount encodes LZCNT/TZCNT (leading / trailing zero count): F3 0F BD
-// or F3 0F BC, with reg = dst and rm = src.  The size suffix selects the
-// operand width (LZCNTW/LZCNTL/LZCNTQ).
+// countOp maps the bit-scan and bit-count mnemonics to their opcode byte and
+// mandatory prefix.  TZCNT/LZCNT/POPCNT are the F3-prefixed forms of the
+// same map as BSF/BSR's 0F BC/BD; POPCNT is F3 0F B8.
+var countOp = map[string]struct {
+	op     byte
+	prefix byte
+}{
+	"BSF":    {0xBC, 0},
+	"BSR":    {0xBD, 0},
+	"TZCNT":  {0xBC, 0xF3},
+	"LZCNT":  {0xBD, 0xF3},
+	"POPCNT": {0xB8, 0xF3},
+}
+
+// encodeCount encodes the bit-scan and bit-count family — BSF (0F BC),
+// BSR (0F BD), TZCNT (F3 0F BC), LZCNT (F3 0F BD) and POPCNT (F3 0F B8) —
+// with reg = dst and rm = src.  The size suffix selects the operand width
+// (BSFQ, TZCNTL, …).  Note BSF/BSR leave the destination undefined when the
+// source is zero (unlike their F3-prefixed counterparts); callers must
+// guard non-zero inputs themselves.
 func (e *enc) encodeCount(base string, ops []Operand, size int) error {
 	if len(ops) != 2 {
 		return fmt.Errorf("%s expects 2 operands, got %d", base, len(ops))
 	}
-	op := byte(0xBD)
-	if base == "TZCNT" {
-		op = 0xBC
-	}
+	spec := countOp[base]
 	dstReg, ok := ops[1].(Reg)
 	if !ok {
 		return fmt.Errorf("%s destination must be a register", base)
 	}
-	i := newInstr(size, []byte{0x0F, op})
-	i.prefix = 0xF3
+	i := newInstr(size, []byte{0x0F, spec.op})
+	i.prefix = spec.prefix
 	if err := setRM(i, dstReg, ops[0], size); err != nil {
 		return err
 	}
 	return e.emit(i)
 }
 
+// encodeBswap encodes BSWAP: the single register operand is encoded in the
+// opcode byte (0F C8+r), with REX.B for R8-R15 and REX.W for the quad form.
+func (e *enc) encodeBswap(ops []Operand, size int) error {
+	if len(ops) != 1 {
+		return fmt.Errorf("BSWAP expects 1 operand, got %d", len(ops))
+	}
+	reg, ok := ops[0].(Reg)
+	if !ok {
+		return fmt.Errorf("BSWAP operand must be a register")
+	}
+	i := newInstr(size, []byte{0x0F, 0xC8 + byte(reg.idx&7)})
+	i.rexB = reg.idx >= 8
+	return e.emit(i)
+}
+
 // --- mixed-width sign/zero-extending moves -----------------------------------
 
 // movExtendOp maps Go's mixed-width move names to their opcode and destination
@@ -721,6 +848,112 @@ func (e *enc) encodeSSEMove(m sseMove, ops []Operand) error {
 	return e.emit(i)
 }
 
+// --- legacy SSE packed binary and shuffles -----------------------------------
+
+// sseBin describes a legacy (non-VEX) SSE packed/scalar binary op: an
+// optional mandatory prefix plus the 0F-prefixed opcode (0F38 for the
+// SSSE3 integer shuffles).  Plan 9 asm lists the source operand first, so
+// MULPS X0, X1 computes X1 = X1 * X0.
+type sseBin struct {
+	prefix byte // 0, 0x66, 0xF2 or 0xF3
+	op     byte
+	map38  bool // opcode lives under 0F38 instead of 0F
+}
+
+var sseBinTable = map[string]sseBin{
+	"ADDPS": {0, 0x58, false}, "ADDPD": {0x66, 0x58, false},
+	"MULPS": {0, 0x59, false}, "MULPD": {0x66, 0x59, false},
+	"SUBPS": {0, 0x5C, false}, "SUBPD": {0x66, 0x5C, false},
+	"DIVPS": {0, 0x5E, false}, "DIVPD": {0x66, 0x5E, false},
+	"ANDPS": {0, 0x54, false}, "ANDPD": {0x66, 0x54, false},
+	"ORPS": {0, 0x56, false}, "ORPD": {0x66, 0x56, false},
+	"XORPS": {0, 0x57, false}, "XORPD": {0x66, 0x57, false},
+	"MINPS": {0, 0x5D, false}, "MINPD": {0x66, 0x5D, false},
+	"MAXPS": {0, 0x5F, false}, "MAXPD": {0x66, 0x5F, false},
+	"ADDSS": {0xF3, 0x58, false}, "ADDSD": {0xF2, 0x58, false},
+	"MULSS": {0xF3, 0x59, false}, "MULSD": {0xF2, 0x59, false},
+	"SUBSS": {0xF3, 0x5C, false}, "SUBSD": {0xF2, 0x5C, false},
+	"DIVSS": {0xF3, 0x5E, false}, "DIVSD": {0xF2, 0x5E, false},
+	"MINSS": {0xF3, 0x5D, false}, "MINSD": {0xF2, 0x5D, false},
+	"MAXSS": {0xF3, 0x5F, false}, "MAXSD": {0xF2, 0x5F, false},
+	"UNPCKLPS": {0, 0x14, false}, "UNPCKHPS": {0, 0x15, false},
+	"UNPCKLPD": {0x66, 0x14, false}, "UNPCKHPD": {0x66, 0x15, false},
+	"CVTSS2SD": {0xF3, 0x5A, false}, "CVTSD2SS": {0xF2, 0x5A, false},
+	"CVTPS2PD": {0, 0x5A, false}, "CVTPD2PS": {0x66, 0x5A, false},
+	// SSE2 packed integers (reg = reg op rm) and the SSSE3 byte shuffle.
+	"PXOR":  {0x66, 0xEF, false},
+	"POR":   {0x66, 0xEB, false},
+	"PAND":  {0x66, 0xDB, false},
+	"PANDN": {0x66, 0xDF, false},
+	"PADDB": {0x66, 0xFC, false}, "PADDW": {0x66, 0xFD, false},
+	"PADDD": {0x66, 0xFE, false}, "PADDQ": {0x66, 0xD4, false},
+	"PSUBB": {0x66, 0xF8, false}, "PSUBW": {0x66, 0xF9, false},
+	"PSUBD": {0x66, 0xFA, false}, "PSUBQ": {0x66, 0xFB, false},
+	"PCMPEQB": {0x66, 0x74, false}, "PCMPEQW": {0x66, 0x75, false},
+	"PCMPEQD": {0x66, 0x76, false},
+	"PCMPGTB": {0x66, 0x64, false}, "PCMPGTW": {0x66, 0x65, false},
+	"PCMPGTD": {0x66, 0x66, false},
+	"PSHUFB":  {0x66, 0x00, true},
+}
+
+// sseShuf describes a legacy SSE shuffle taking a trailing imm8
+// (PSHUFD/PSHUFHW/PSHUFLW also carry the packed-int 0x66/F3/F2 prefixes).
+type sseShuf struct {
+	prefix byte
+	op     byte
+}
+
+var sseShufTable = map[string]sseShuf{
+	"SHUFPS": {0, 0xC6}, "SHUFPD": {0x66, 0xC6},
+	"PSHUFD": {0x66, 0x70}, "PSHUFHW": {0xF3, 0x70}, "PSHUFLW": {0xF2, 0x70},
+}
+
+// encodeSSEBin encodes reg = reg op rm (memory allowed for rm).
+func (e *enc) encodeSSEBin(m sseBin, ops []Operand) error {
+	if len(ops) != 2 {
+		return fmt.Errorf("SSE binary expects 2 operands, got %d", len(ops))
+	}
+	src, dst := ops[0], ops[1]
+	dstReg, ok := dst.(Reg)
+	if !ok || !dstReg.isVec() {
+		return fmt.Errorf("SSE binary destination must be a vector register")
+	}
+	opcode := []byte{0x0F, m.op}
+	if m.map38 {
+		opcode = []byte{0x0F, 0x38, m.op}
+	}
+	i := &instr{prefix: m.prefix, opcode: opcode, modrm: -1, sib: -1}
+	if err := setRM(i, dstReg, src, 8); err != nil {
+		return err
+	}
+	return e.emit(i)
+}
+
+// encodeSSEShuf encodes an imm8 shuffle: SHUFPS $imm, src, dst.
+func (e *enc) encodeSSEShuf(m sseShuf, ops []Operand) error {
+	if len(ops) != 3 {
+		return fmt.Errorf("SSE shuffle expects 3 operands, got %d", len(ops))
+	}
+	imm, ok := ops[0].(Imm)
+	if !ok {
+		return fmt.Errorf("SSE shuffle needs an imm8 first operand")
+	}
+	if imm < -128 || imm > 255 {
+		return fmt.Errorf("SSE shuffle imm8 %d out of range", imm)
+	}
+	src, dst := ops[1], ops[2]
+	dstReg, ok2 := dst.(Reg)
+	if !ok2 || !dstReg.isVec() {
+		return fmt.Errorf("SSE shuffle destination must be a vector register")
+	}
+	i := &instr{prefix: m.prefix, opcode: []byte{0x0F, m.op}, modrm: -1, sib: -1}
+	if err := setRM(i, dstReg, src, 8); err != nil {
+		return err
+	}
+	i.imm = []byte{byte(int8(imm))}
+	return e.emit(i)
+}
+
 // --- CVTSL2SD / CVTSQ2SD -----------------------------------------------------
 
 // encodeCvtsi2sd encodes a signed integer to scalar double conversion

asm/l64_goobj_test.go

@@ -153,7 +153,7 @@ DATA ·table<>+0(SB)/8, $0x1122334455667788
 		t.Errorf("lines reloc = %x", lr)
 	}
 	dr := relocs[23:46]
-	if int32(le.Uint32(dr[0:])) != 13 || dr[4] != 4 || le.Uint16(dr[5:]) != relocDWTXTADDRU4 ||
+	if int32(le.Uint32(dr[0:])) != 13 || dr[4] != 4 || le.Uint16(dr[5:]) != relocDWTXTADDRU4() ||
 		le.Uint32(dr[15:]) != pkgIdxNone || le.Uint32(dr[19:]) != 4 {
 		t.Errorf("die reloc = %x", dr)
 	}
@@ -214,7 +214,7 @@ func main() {
 		t.Fatalf("baseline build: %v\n%s", err, buildLog)
 	}
 	var pkgArch, work, linkLine, asmObj string
-	for _, line := range strings.Split(string(buildLog), "\n") {
+	for line := range strings.SplitSeq(string(buildLog), "\n") {
 		switch {
 		case strings.HasPrefix(line, "WORK="):
 			work = strings.TrimPrefix(line, "WORK=")
@@ -278,7 +278,7 @@ func main() {
 	newArch := filepath.Join(dir, "pkg.a")
 	args := []string{"tool", "pack", "c", newArch}
 	seen := map[string]bool{}
-	for _, m := range strings.Fields(string(listOut)) {
+	for m := range strings.FieldsSeq(string(listOut)) {
 		if seen[m] {
 			continue
 		}

asm/link.go

@@ -80,7 +80,7 @@ func (fl *FuncLayout) LineAt(offset int) int {
 	return 0
 }
 
-// Reloc is one static-symbol reference within a function body: the disp32
+// RelocKind Reloc is one static-symbol reference within a function body: the disp32
 // field at Off (function-relative) must reach the symbol plus Addend,
 // measured from After, the address just past the instruction.  An External
 // relocation names a symbol no GLOBL in the file defines; the object-file
@@ -96,6 +96,8 @@ const (
 	RelPCRelAbs                         // 32-bit absolute (R_RISCV_32)
 	RelLoong64AddrHi                    // R_LOONG64_ADDR_HI (pcalau12i)
 	RelLoong64AddrLo                    // R_LOONG64_ADDR_LO (addi.d/ld/st)
+	RelArm64Addr                        // R_ADDRARM64 (ADRP + ADD/LDR/STR pair)
+	RelArm64Branch                      // R_CALLARM64 (BL instruction)
 )
 
 type Reloc struct {
@@ -301,6 +303,7 @@ func AssembleFileRISCV(f *ast.File) (*Image, error) {
 		})
 	}
 
+	markExternals(img, dataSyms)
 	return img, nil
 }
 
@@ -372,9 +375,38 @@ func AssembleFileLOONG64(f *ast.File) (*Image, error) {
 		})
 	}
 
+	markExternals(img, dataSyms)
 	return img, nil
 }
 
+// markExternals identifies relocations that reference symbols not defined in
+// the file (neither a GLOBL/DATA symbol nor a TEXT function) and records them
+// as external.  The non-amd64 architectures emit relocations for every SB
+// reference; this post-processing step distinguishes file-local from external.
+func markExternals(img *Image, dataSyms []dataSym) {
+	known := make(map[string]bool, len(dataSyms)+len(img.Funcs))
+	for _, d := range dataSyms {
+		known[d.name] = true
+	}
+	for _, fn := range img.Funcs {
+		known[fn.Name] = true
+	}
+	externals := map[string]bool{}
+	for i := range img.Funcs {
+		for j := range img.Funcs[i].Relocs {
+			r := &img.Funcs[i].Relocs[j]
+			if !known[r.Name] {
+				r.External = true
+				externals[r.Name] = true
+			}
+		}
+	}
+	for name := range externals {
+		img.Externals = append(img.Externals, name)
+	}
+	sort.Strings(img.Externals)
+}
+
 // dataSym is one GLOBL symbol and its DATA initialiser.
 type dataSym struct {
 	name   string
@@ -456,7 +488,7 @@ func collectData(f *ast.File) ([]dataSym, error) {
 			if dd.Value.Imm.Neg {
 				v = -v
 			}
-			for j := 0; j < w; j++ {
+			for j := range w {
 				buf[off+int64(j)] = byte(v >> (8 * j))
 			}
 		}

asm/loong64_assemble.go

@@ -672,8 +672,6 @@ func encodeLOONG64ImmArith(mnem string, de l64DualEnc, ops []*ast.Operand) ([]by
 	const (
 		lu12iw = 0x0a << 25
 		ori    = 0x00e << 22
-		lu32id = 0x0b << 25
-		lu52id = 0x00c << 22
 	)
 	if v == int64(int32(v)) {
 		if v&0xfff == 0 && (v < 0x800 || v > 0xfff) {
@@ -771,7 +769,7 @@ func encodeLOONG64Mov(instr *ast.Instr, mnem string, fi loong64FrameInfo, relocs
 			if rd < 0 {
 				return nil, fmt.Errorf("%s $sym(SB): invalid destination register", mnem)
 			}
-			return encodeLOONG64SBAddr(src.Imm.Sym, rd, mnem, relocs), nil
+			return encodeLOONG64SBAddr(src.Imm.Sym, rd, relocs), nil
 		}
 		rd := l64Reg(dst)
 		if rd < 0 {
@@ -832,14 +830,14 @@ func encodeLOONG64Mov(instr *ast.Instr, mnem string, fi loong64FrameInfo, relocs
 		if rd < 0 {
 			return nil, fmt.Errorf("%s: invalid destination register", mnem)
 		}
-		return encodeLOONG64MemOp(mnem, ops[0], rd, true, fi, relocs)
+		return encodeLOONG64MemOp(mnem, ops[0], rd, true, fi)
 	}
 	if !isMemOperand(src) && isMemOperand(dst) {
 		rs := l64Reg(src)
 		if rs < 0 {
 			return nil, fmt.Errorf("%s: invalid source register", mnem)
 		}
-		return encodeLOONG64MemOp(mnem, ops[1], rs, false, fi, relocs)
+		return encodeLOONG64MemOp(mnem, ops[1], rs, false, fi)
 	}
 
 	// Register → register.
@@ -933,20 +931,20 @@ const (
 	l64St1
 	l64St0
 
-	l64Dcon12_0
-	l64Dcon12_20S
-	l64Dcon20S_20
-	l64Dcon12_12S
-	l64Dcon20S_12S
-	l64Dcon20S_0
-	l64Dcon12_12U
-	l64Dcon20S_12U
-	l64Dcon32_12S
-	l64Dcon32_0
-	l64Dcon32_20
-	l64Dcon12_32S
-	l64Dcon20S_32
-	l64Dcon32_12U
+	l64dcon120
+	l64dcon1220s
+	l64dcon20s20
+	l64dcon1212s
+	l64dcon20s12s
+	l64dcon20s0
+	l64dcon1212u
+	l64dcon20s12u
+	l64dcon3212s
+	l64dcon320
+	l64dcon3220
+	l64dcon1232s
+	l64dcon20s32
+	l64dcon3212u
 	l64Dcon
 )
 
@@ -987,91 +985,91 @@ func l64DconClass(v int64) int {
 	lo20 := l64BitField(v, 12, 20)
 	lo12 := l64BitField(v, 0, 12)
 	if tzb >= 52 {
-		return l64Dcon12_0
+		return l64dcon120
 	}
 	if tzb >= 32 {
 		if ((hi20 == l64All1 || hi20 == l64St1) && hi12 == l64All1) || ((hi20 == l64All0 || hi20 == l64St0) && hi12 == l64All0) {
-			return l64Dcon20S_0
+			return l64dcon20s0
 		}
-		return l64Dcon32_0
+		return l64dcon320
 	}
 	if tzb >= 12 {
 		if lo20 == l64St1 || lo20 == l64All1 {
 			if hi20 == l64All1 {
-				return l64Dcon12_20S
+				return l64dcon1220s
 			}
 			if (hi20 == l64St1 && hi12 == l64All1) || ((hi20 == l64St0 || hi20 == l64All0) && hi12 == l64All0) {
-				return l64Dcon20S_20
+				return l64dcon20s20
 			}
-			return l64Dcon32_20
+			return l64dcon3220
 		}
 		if hi20 == l64All0 {
-			return l64Dcon12_20S
+			return l64dcon1220s
 		}
 		if (hi20 == l64St0 && hi12 == l64All0) || ((hi20 == l64St1 || hi20 == l64All1) && hi12 == l64All1) {
-			return l64Dcon20S_20
+			return l64dcon20s20
 		}
-		return l64Dcon32_20
+		return l64dcon3220
 	}
 	if lo12 == l64St1 || lo12 == l64All1 {
 		if lo20 == l64All1 {
 			if hi20 == l64All1 {
-				return l64Dcon12_12S
+				return l64dcon1212s
 			}
 			if (hi20 == l64St1 && hi12 == l64All1) || ((hi20 == l64St0 || hi20 == l64All0) && hi12 == l64All0) {
-				return l64Dcon20S_12S
+				return l64dcon20s12s
 			}
-			return l64Dcon32_12S
+			return l64dcon3212s
 		}
 		if lo20 == l64St1 {
 			if hi20 == l64All1 {
-				return l64Dcon12_32S
+				return l64dcon1232s
 			}
 			if (hi20 == l64St1 && hi12 == l64All1) || ((hi20 == l64St0 || hi20 == l64All0) && hi12 == l64All0) {
-				return l64Dcon20S_32
+				return l64dcon20s32
 			}
 			return l64Dcon
 		}
 		if lo20 == l64All0 {
 			if hi20 == l64All0 {
-				return l64Dcon12_12U
+				return l64dcon1212u
 			}
 			if ((hi20 == l64St1 || hi20 == l64All1) && hi12 == l64All1) || (hi20 == l64St0 && hi12 == l64All0) {
-				return l64Dcon20S_12U
+				return l64dcon20s12u
 			}
-			return l64Dcon32_12U
+			return l64dcon3212u
 		}
 		if hi20 == l64All0 {
-			return l64Dcon12_32S
+			return l64dcon1232s
 		}
 		if ((hi20 == l64St1 || hi20 == l64All1) && hi12 == l64All1) || (hi20 == l64St0 && hi12 == l64All0) {
-			return l64Dcon20S_32
+			return l64dcon20s32
 		}
 		return l64Dcon
 	}
 	if lo20 == l64All0 {
 		if hi20 == l64All0 {
-			return l64Dcon12_12U
+			return l64dcon1212u
 		}
 		if ((hi20 == l64St1 || hi20 == l64All1) && hi12 == l64All1) || (hi20 == l64St0 && hi12 == l64All0) {
-			return l64Dcon20S_12U
+			return l64dcon20s12u
 		}
-		return l64Dcon32_12U
+		return l64dcon3212u
 	}
 	if lo20 == l64St1 || lo20 == l64All1 {
 		if hi20 == l64All1 {
-			return l64Dcon12_32S
+			return l64dcon1232s
 		}
 		if (hi20 == l64St1 && hi12 == l64All1) || ((hi20 == l64St0 || hi20 == l64All0) && hi12 == l64All0) {
-			return l64Dcon20S_32
+			return l64dcon20s32
 		}
 		return l64Dcon
 	}
 	if hi20 == l64All0 {
-		return l64Dcon12_32S
+		return l64dcon1232s
 	}
 	if ((hi20 == l64St1 || hi20 == l64All1) && hi12 == l64All1) || (hi20 == l64St0 && hi12 == l64All0) {
-		return l64Dcon20S_32
+		return l64dcon20s32
 	}
 	return l64Dcon
 }
@@ -1088,29 +1086,29 @@ func l64DconMovWords(rd int, v int64) []uint32 {
 		ori    = 0x00e << 22
 	)
 	switch l64DconClass(v) {
-	case l64Dcon12_0:
+	case l64dcon120:
 		return []uint32{l64irr(lu52id, int(v>>52), 0, rd)}
-	case l64Dcon12_20S:
+	case l64dcon1220s:
 		return []uint32{l64ir(lu12iw, int(v>>12), rd), l64irr(lu52id, int(v>>52), rd, rd)}
-	case l64Dcon20S_20:
+	case l64dcon20s20:
 		return []uint32{l64ir(lu12iw, int(v>>12), rd), l64ir(lu32id, int(v>>32), rd)}
-	case l64Dcon12_12S:
+	case l64dcon1212s:
 		return []uint32{l64irr(addid, int(v), 0, rd), l64irr(lu52id, int(v>>52), rd, rd)}
-	case l64Dcon20S_12S, l64Dcon20S_0:
+	case l64dcon20s12s, l64dcon20s0:
 		return []uint32{l64irr(addiw, int(v), 0, rd), l64ir(lu32id, int(v>>32), rd)}
-	case l64Dcon12_12U:
+	case l64dcon1212u:
 		return []uint32{l64irr(ori, int(v), 0, rd), l64irr(lu52id, int(v>>52), rd, rd)}
-	case l64Dcon20S_12U:
+	case l64dcon20s12u:
 		return []uint32{l64irr(ori, int(v), 0, rd), l64ir(lu32id, int(v>>32), rd)}
-	case l64Dcon32_12S, l64Dcon32_0:
+	case l64dcon3212s, l64dcon320:
 		return []uint32{l64irr(addiw, int(v), 0, rd), l64ir(lu32id, int(v>>32), rd), l64irr(lu52id, int(v>>52), rd, rd)}
-	case l64Dcon32_20:
+	case l64dcon3220:
 		return []uint32{l64ir(lu12iw, int(v>>12), rd), l64ir(lu32id, int(v>>32), rd), l64irr(lu52id, int(v>>52), rd, rd)}
-	case l64Dcon12_32S:
+	case l64dcon1232s:
 		return []uint32{l64ir(lu12iw, int(v>>12), rd), l64irr(ori, int(v), rd, rd), l64irr(lu52id, int(v>>52), rd, rd)}
-	case l64Dcon20S_32:
+	case l64dcon20s32:
 		return []uint32{l64ir(lu12iw, int(v>>12), rd), l64irr(ori, int(v), rd, rd), l64ir(lu32id, int(v>>32), rd)}
-	case l64Dcon32_12U:
+	case l64dcon3212u:
 		return []uint32{l64irr(ori, int(v), 0, rd), l64ir(lu32id, int(v>>32), rd), l64irr(lu52id, int(v>>52), rd, rd)}
 	default:
 		return []uint32{l64ir(lu12iw, int(v>>12), rd), l64irr(ori, int(v), rd, rd), l64ir(lu32id, int(v>>32), rd), l64irr(lu52id, int(v>>52), rd, rd)}
@@ -1161,7 +1159,7 @@ func encodeLOONG64LoadImm(rd int, v int64, mnem string) []byte {
 // encodeLOONG64MemOp encodes a memory load (load = true) or store with a
 // 12-bit offset, or the 3-instruction expansion for larger offsets:
 // lu12i.w r30, (off+0x800)>>12; add.d r30, rj, r30; ld/st rd, off(r30).
-func encodeLOONG64MemOp(mnem string, mem *ast.Operand, reg int, load bool, fi loong64FrameInfo, relocs *[]Reloc) ([]byte, error) {
+func encodeLOONG64MemOp(mnem string, mem *ast.Operand, reg int, load bool, fi loong64FrameInfo) ([]byte, error) {
 	rj, off := l64MemWithFrame(mem, fi)
 	if rj < 0 {
 		return nil, fmt.Errorf("invalid memory operand")
@@ -1266,7 +1264,7 @@ func l64FpMoveKey(mnem string, sc, dc l64RegClass) (string, bool) {
 
 // encodeLOONG64SBAddr emits pcalau12i rd, 0; addi.d rd, rd, 0 with the
 // R_LOONG64_ADDR_HI/LO relocation pair, loading a symbol's address.
-func encodeLOONG64SBAddr(sym *ast.Symbol, rd int, mnem string, relocs *[]Reloc) []byte {
+func encodeLOONG64SBAddr(sym *ast.Symbol, rd int, relocs *[]Reloc) []byte {
 	if relocs != nil {
 		*relocs = append(*relocs,
 			Reloc{Off: 0, After: 0, Name: sym.Name, Kind: RelLoong64AddrHi, Addend: sym.Offset},
@@ -1342,11 +1340,6 @@ func l64Reg(op *ast.Operand) int {
 	return loong64RegNum(operandRegName(op))
 }
 
-// l64Imm returns the immediate value of an operand.
-func l64Imm(op *ast.Operand) int32 {
-	return immFromOperand(op)
-}
-
 // l64Imm64 returns the full 64-bit immediate value of an operand.
 func l64Imm64(op *ast.Operand) int64 {
 	if op.Imm.HasVal {

asm/loong64_encode.go

@@ -30,6 +30,8 @@ package asm
 // of the immediate and register fields), mirroring the toolchain's OP_*
 // helpers, so each l64* function only ORs its fields in.
 
+import "maps"
+
 // loong64RegNum returns the 5-bit register number for a LoongArch register
 // name: R0–R31 (integer), F0–F31 (floating point), FCC0–FCC7 (condition
 // flags), FCSR0–FCSR31 (control/status) and the ABI aliases the runtime's
@@ -103,10 +105,10 @@ func loong64RegNum(name string) int {
 	}
 	// F0–F31, FCC0–FCC7, FCSR0–FCSR31.
 	if len(name) >= 4 && name[:4] == "FCSR" {
-		return loong64RegSpecial(name[4:], "FCSR", 31)
+		return loong64RegSpecial(name[4:], 31)
 	}
 	if len(name) >= 3 && name[:3] == "FCC" {
-		return loong64RegSpecial(name[3:], "FCC", 7)
+		return loong64RegSpecial(name[3:], 7)
 	}
 	if len(name) < 2 {
 		return -1
@@ -129,7 +131,7 @@ func loong64RegNum(name string) int {
 }
 
 // loong64RegSpecial parses a numbered FCC/FCSR register.
-func loong64RegSpecial(digits, prefix string, max int) int {
+func loong64RegSpecial(digits string, max int) int {
 	if digits == "" {
 		return -1
 	}
@@ -368,7 +370,7 @@ func init() {
 	// The dual-form arithmetic mnemonics (register 3R + immediate 2RI12),
 	// selected by the operand kind; the shift mnemonics pair the 3R form
 	// with a 5/6-bit shift immediate.
-	for m, e := range map[string]l64DualEnc{
+	maps.Copy(l64DualTable, map[string]l64DualEnc{
 		"ADD":   {rrr: 0x20 << 15, imm: 0x00a << 22},
 		"ADDW":  {rrr: 0x20 << 15, imm: 0x00a << 22},
 		"ADDV":  {rrr: 0x21 << 15, imm: 0x00b << 22},
@@ -386,9 +388,7 @@ func init() {
 		"SRLV":  {rrr: 0x32 << 15, imm: 0x0045 << 16, shift: true},
 		"SRAV":  {rrr: 0x33 << 15, imm: 0x0049 << 16, shift: true},
 		"ROTRV": {rrr: 0x37 << 15, imm: 0x004d << 16, shift: true},
-	} {
-		l64DualTable[m] = e
-	}
+	})
 
 	// 2RI12 — pure immediate arithmetic (LU52ID has no register form).
 	l64InstrTable["LU52ID"] = l64Enc{format: l64Firr, op: 0x00c << 22}

asm/operand.go

@@ -37,11 +37,6 @@ func Idx(base, index Reg, scale int, disp int64, size int) Mem {
 	return Mem{Base: base, Index: index, Scale: scale, Disp: disp, Size: size, HasBase: true, HasIndex: true}
 }
 
-// Rip builds a RIP-relative memory operand (RIP)+disp.
-func Rip(disp int64, size int) Mem {
-	return Mem{Disp: disp, Size: size}
-}
-
 // sbMem is a memory operand that references a static (SB) symbol.  It encodes
 // as a RIP-relative reference with a placeholder displacement; the encoder
 // records a patch site so the file-level layout can fill in the true rel32

asm/reg.go

@@ -7,6 +7,8 @@
 // by round-tripping through golang.org/x/arch's decoder in the tests.
 package asm
 
+import "maps"
+
 import "strings"
 
 // Reg is an x86-64 register.  In Plan 9 assembly the classic names (AX, BX, …)
@@ -63,28 +65,28 @@ var (
 	CX = Reg{idx: 1, size: 2}
 	DX = Reg{idx: 2, size: 2}
 	BX = Reg{idx: 3, size: 2}
-	SP = Reg{idx: 4, size: 2}
-	BP = Reg{idx: 5, size: 2}
+	_  = Reg{idx: 4, size: 2}
+	_  = Reg{idx: 5, size: 2}
 	SI = Reg{idx: 6, size: 2}
 	DI = Reg{idx: 7, size: 2}
 
-	EAX = Reg{idx: 0, size: 4}
-	ECX = Reg{idx: 1, size: 4}
-	EDX = Reg{idx: 2, size: 4}
-	EBX = Reg{idx: 3, size: 4}
-	ESP = Reg{idx: 4, size: 4}
-	EBP = Reg{idx: 5, size: 4}
-	ESI = Reg{idx: 6, size: 4}
-	EDI = Reg{idx: 7, size: 4}
+	_ = Reg{idx: 0, size: 4}
+	_ = Reg{idx: 1, size: 4}
+	_ = Reg{idx: 2, size: 4}
+	_ = Reg{idx: 3, size: 4}
+	_ = Reg{idx: 4, size: 4}
+	_ = Reg{idx: 5, size: 4}
+	_ = Reg{idx: 6, size: 4}
+	_ = Reg{idx: 7, size: 4}
 
-	RAX = Reg{idx: 0, size: 8}
-	RCX = Reg{idx: 1, size: 8}
-	RDX = Reg{idx: 2, size: 8}
-	RBX = Reg{idx: 3, size: 8}
-	RSP = Reg{idx: 4, size: 8}
-	RBP = Reg{idx: 5, size: 8}
-	RSI = Reg{idx: 6, size: 8}
-	RDI = Reg{idx: 7, size: 8}
+	_ = Reg{idx: 0, size: 8}
+	_ = Reg{idx: 1, size: 8}
+	_ = Reg{idx: 2, size: 8}
+	_ = Reg{idx: 3, size: 8}
+	_ = Reg{idx: 4, size: 8}
+	_ = Reg{idx: 5, size: 8}
+	_ = Reg{idx: 6, size: 8}
+	_ = Reg{idx: 7, size: 8}
 )
 
 // regByName maps an assembly register name (case-insensitive) to a Reg.
@@ -121,13 +123,11 @@ func buildRegByName() map[string]Reg {
 	}
 
 	// 8-bit: AL..BH, SPL..DIL, R8B..R15B.
-	for n, r := range map[string]Reg{
+	maps.Copy(m, map[string]Reg{
 		"AL": AL, "CL": CL, "DL": DL, "BL": BL,
 		"AH": AH, "CH": CH, "DH": DH, "BH": BH,
 		"SPL": SPL, "BPL": BPL, "SIL": SIL, "DIL": DIL,
-	} {
-		m[n] = r
-	}
+	})
 	for i := 8; i <= 15; i++ {
 		m["R"+itoa(i)+"B"] = Reg{idx: i, size: 1}
 	}

asm/riscv_assemble.go

@@ -228,7 +228,7 @@ func encodeRISCVInstr(instr *ast.Instr, pc int, offsets map[string]int, fi riscv
 	// MOV is a pseudo-instruction that the Go assembler uses for loads,
 	// stores, register moves and immediate loads.
 	case "MOV":
-		return encodeRISCVMov(instr, offsets, fi, relocs)
+		return encodeRISCVMov(instr, fi, relocs)
 
 	// JALR: indirect jump/call.  Plan 9: JALR rs1, rd or JALR offset(rs1).
 	case "JALR":
@@ -527,7 +527,7 @@ func isImmOperand(op *ast.Operand) bool {
 //   - MOV Rs, (Rd)          register-relative store
 //   - MOV Rs, Rd            register-to-register move (ADDI $0)
 //   - MOV $imm, Rd          load immediate (ADDI or LUI+ADDIW)
-func encodeRISCVMov(instr *ast.Instr, offsets map[string]int, fi riscvFrameInfo, relocs *[]Reloc) ([]byte, error) {
+func encodeRISCVMov(instr *ast.Instr, fi riscvFrameInfo, relocs *[]Reloc) ([]byte, error) {
 	ops := instr.Operands
 	if len(ops) != 2 {
 		return nil, fmt.Errorf("MOV expects 2 operands, got %d", len(ops))
@@ -911,7 +911,7 @@ func tryCompressRVC(instr *ast.Instr, fi riscvFrameInfo) (uint16, bool) {
 		}
 
 	case "ADDI":
-		rd, rs1, imm := extractITypeParams(instr, fi)
+		rd, rs1, imm := extractITypeParams(instr)
 		if rd == -1 || rs1 == -1 {
 			return 0, false
 		}
@@ -1060,13 +1060,13 @@ func tryCompressRVC(instr *ast.Instr, fi riscvFrameInfo) (uint16, bool) {
 		}
 
 	case "ADDIW":
-		rd, rs1, imm := extractITypeParams(instr, fi)
+		rd, rs1, imm := extractITypeParams(instr)
 		if rd == rs1 && rd != 0 && imm >= -32 && imm <= 31 {
 			return rvcCI(0x1, uint32(rd), uint32(imm)&0x3F), true
 		}
 
 	case "SLLI", "SRLI", "SRAI":
-		rd, rs1, imm := extractITypeParams(instr, fi)
+		rd, rs1, imm := extractITypeParams(instr)
 		if rd == rs1 && rd != 0 && imm != 0 && imm >= 1 && imm <= 63 {
 			if mnem == "SLLI" {
 				// C.SLLI: funct3=0, op=10 quadrant, shamt in bits [12|6:2].
@@ -1083,7 +1083,7 @@ func tryCompressRVC(instr *ast.Instr, fi riscvFrameInfo) (uint16, bool) {
 		}
 
 	case "ANDI":
-		rd, rs1, imm := extractITypeParams(instr, fi)
+		rd, rs1, imm := extractITypeParams(instr)
 		if isRVCIntReg(rd) && rd == rs1 && imm >= -32 && imm <= 31 {
 			// C.ANDI: CB-type, funct3=0x4, funct2=0x2.
 			return rvcCBShift(0x2, rvcReg3(rd), uint32(imm)&0x3F), true
@@ -1131,7 +1131,7 @@ func extractSDParams(instr *ast.Instr, fi riscvFrameInfo) (rs2, rs1 int, imm int
 // extractITypeParams extracts rd, rs1, and immediate for an I-type
 // instruction.  The Plan 9 order is INSTR $imm, rs1, rd (3 operands) or
 // INSTR $imm, rd (2 operands, rd is also the source).
-func extractITypeParams(instr *ast.Instr, fi riscvFrameInfo) (rd, rs1 int, imm int32) {
+func extractITypeParams(instr *ast.Instr) (rd, rs1 int, imm int32) {
 	ops := instr.Operands
 	switch len(ops) {
 	case 3:
@@ -1250,11 +1250,6 @@ func isFPCmpInstr(m string) bool {
 	return false
 }
 
-func isFPCvtInstr(m string) bool {
-	_, ok := riscvCvtTable[m]
-	return ok
-}
-
 // Operand helpers.
 func regFromOperand(op *ast.Operand) int {
 	// Register is in Addr.Base (from (base) syntax) or Addr.Sym.Name (bare ident).

asm/riscv_goobj_test.go

@@ -141,7 +141,7 @@ DATA answer<>+0(SB)/8, $42
 	first := int(le.Uint32(relocIdx[4*(4+4):]))
 	wantType := []uint16{relocRISCVPcrelItype, relocRISCVPcrelItype, relocRISCVPcrelStype}
 	wantOffAbs := []int{0, 8, 16}
-	for i := 0; i < 3; i++ {
+	for i := range 3 {
 		e := relocs[(first+i)*23:]
 		if int32(le.Uint32(e[0:])) != int32(wantOffAbs[i]) || e[4] != 8 || le.Uint16(e[5:]) != wantType[i] ||
 			le.Uint32(e[15:]) != pkgIdxSelf || le.Uint32(e[19:]) != 0 {
@@ -221,7 +221,7 @@ func main() {
 		t.Fatalf("baseline build: %v\n%s", err, buildLog)
 	}
 	var pkgArch, work, linkLine, asmObj string
-	for _, line := range strings.Split(string(buildLog), "\n") {
+	for line := range strings.SplitSeq(string(buildLog), "\n") {
 		switch {
 		case strings.HasPrefix(line, "WORK="):
 			work = strings.TrimPrefix(line, "WORK=")
@@ -279,7 +279,7 @@ func main() {
 	newArch := filepath.Join(dir, "pkg.a")
 	args := []string{"tool", "pack", "c", newArch}
 	seen := map[string]bool{}
-	for _, m := range strings.Fields(string(listOut)) {
+	for m := range strings.FieldsSeq(string(listOut)) {
 		if seen[m] {
 			continue
 		}

asm/vex.go

@@ -141,6 +141,8 @@ var vexTable = map[string]vexSpec{
 	"VPMOVZXWQ":    {2, 0x34, 0, 1, -1, vexRM},
 	"VPBROADCASTD": {2, 0x58, 0, 1, -1, vexRM},
 	"VPBROADCASTQ": {2, 0x59, 0, 1, -1, vexRM},
+	"VPBROADCASTB": {2, 0x78, 0, 1, -1, vexRM},
+	"VPBROADCASTW": {2, 0x79, 0, 1, -1, vexRM},
 	// VEX.128/256.F3.0F.WIG — signed dword to packed double conversion
 	// (reg=dst, rm=src, no vvvv; the length follows the destination).
 	"VCVTDQ2PD": {1, 0xE6, 0, 2, -1, vexRM},

ast/ast.go

@@ -123,10 +123,8 @@ type Symbol struct {
 // OpKind classifies an operand syntactically.
 type OpKind int
 
-// Operand kinds.
 const (
-	OpInvalid   OpKind = iota
-	OpImmediate        // $value
+	OpImmediate = iota // $value
 	OpAddr             // register, memory reference, symbol or label
 )
 

ast/ast_test.go

@@ -54,11 +54,11 @@ func TestStmtPositions(t *testing.T) {
 // TestInterfaces confirms the node types satisfy their interfaces, so callers
 // can range over Decls and Stmts.
 func TestInterfaces(t *testing.T) {
-	var decls []Decl = []Decl{&Include{}, &Preproc{}, &Text{}, &Globl{}, &Data{}}
+	var decls = []Decl{&Include{}, &Preproc{}, &Text{}, &Globl{}, &Data{}}
 	if len(decls) != 5 {
 		t.Fatal("decl interface set")
 	}
-	var stmts []Stmt = []Stmt{&Label{}, &Instr{}}
+	var stmts = []Stmt{&Label{}, &Instr{}}
 	if len(stmts) != 2 {
 		t.Fatal("stmt interface set")
 	}

cmd/gasm/audit.go

@@ -0,0 +1,307 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"slices"
+	"strconv"
+	"strings"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
+	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// cmdAuditInstructions cross-checks a gasm encoder against the Go toolchain's
+// own assembler, probed black-box: every mnemonic in the gasm table is offered
+// to go tool asm in its bare form, and a mnemonic counts as known to Go when
+// the error is anything but "unrecognized instruction" (a wrong-shape error
+// still proves the mnemonic exists in Go's tables).  The audit answers three
+// questions at a glance:
+//
+//   - which mnemonics gasm can encode that go tool asm does not know
+//     (superset encodings, usable only through the gasm goobj path);
+//   - which mnemonics the architecture table knows but the encoder cannot
+//     emit yet (the implementation backlog);
+//   - which mnemonics go tool asm knows that gasm cannot encode (feature
+//     gaps).
+//
+// The amd64 derived families (Jcc, CMOVcc, SETcc) exist on both sides by
+// construction and are excluded from the diff; the other architectures list
+// their conditional branches outright.
+func cmdAuditInstructions(args []string) error {
+	fs := newCommand("audit-instructions", "gasm audit-instructions [amd64|arm64|riscv64|loong64]", `
+Compare the gasm encoder for the given architecture (default amd64) against
+go tool asm and print the diff: superset encodings (gasm-only, shippable via
+gasm asm --format goobj), known-but-unencodable names (the backlog) and go-
+only names (feature gaps).  The Go side is probed black-box with a battery
+of bare mnemonics, so the audit tracks whatever toolchain `+"`go env GOROOT`"+`
+provides.
+`)
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	archName := "amd64"
+	switch n := len(fs.Args()); {
+	case n > 1:
+		return fmt.Errorf("audit-instructions takes at most one architecture argument")
+	case n == 1:
+		archName = strings.ToLower(fs.Arg(0))
+	}
+	a, err := auditArch(archName)
+	if err != nil {
+		return err
+	}
+
+	tab := arch.ForArch(a)
+	var names []string
+	seen := map[string]bool{}
+	for _, in := range tab.Instructions() {
+		name := strings.ToUpper(in.Name)
+		if a == arch.AMD64 && derivedFamily(name) || seen[name] {
+			continue
+		}
+		seen[name] = true
+		names = append(names, name)
+	}
+
+	goKnown, err := probeGoAsm(goarchName(a), names)
+	if err != nil {
+		return err
+	}
+
+	var superset, backlog, shared []string
+	for _, name := range names {
+		switch {
+		case !gasmEncodable(a, name):
+			backlog = append(backlog, name)
+		case !goKnown[name]:
+			superset = append(superset, name)
+		default:
+			shared = append(shared, name)
+		}
+	}
+	// GO-ONLY is not enumerable by probing: Go's table is only visible
+	// through names we already know, so nothing can be reported there.
+
+	slices.Sort(superset)
+	slices.Sort(backlog)
+	slices.Sort(shared)
+
+	w := os.Stdout
+	fmt.Fprintf(w, "gasm table (%s, families excluded): %d mnemonics\n", archName, len(names))
+	fmt.Fprintf(w, "gasm encodable: %d   go tool asm recognized: %d\n", len(shared)+len(superset), countTrue(goKnown))
+	fmt.Fprintf(w, "shared: %d\n", len(shared))
+	fmt.Fprintf(w, "\nSuperset encodings (gasm-only; ship via gasm asm --format goobj):\n")
+	for _, n := range superset {
+		fmt.Fprintf(w, "  %s\n", n)
+	}
+	fmt.Fprintf(w, "\nKnown but not encodable (backlog):\n")
+	for _, n := range backlog {
+		fmt.Fprintf(w, "  %s\n", n)
+	}
+	fmt.Fprintf(w, "\nGo-only names cannot be enumerated by probing; extend the gasm\n")
+	fmt.Fprintf(w, "table from the Go release notes when a new instruction family ships.\n")
+	return nil
+}
+
+// auditArch resolves the audit's architecture argument.
+func auditArch(name string) (arch.Arch, error) {
+	switch strings.ToLower(name) {
+	case "amd64":
+		return arch.AMD64, nil
+	case "arm64":
+		return arch.ARM64, nil
+	case "riscv64", "riscv":
+		return arch.RISCV, nil
+	case "loong64", "loong":
+		return arch.LOONG64, nil
+	}
+	return arch.Unknown, fmt.Errorf("unknown architecture %q: want amd64, arm64, riscv64 or loong64", name)
+}
+
+// goarchName maps an arch identifier onto its GOARCH spelling.
+func goarchName(a arch.Arch) string {
+	switch a {
+	case arch.ARM64:
+		return "arm64"
+	case arch.RISCV:
+		return "riscv64"
+	case arch.LOONG64:
+		return "loong64"
+	}
+	return "amd64"
+}
+
+func countTrue(m map[string]bool) int {
+	n := 0
+	for _, v := range m {
+		if v {
+			n++
+		}
+	}
+	return n
+}
+
+// derivedFamily reports whether a mnemonic belongs to a family both
+// assemblers construct from condition codes rather than list exhaustively
+// (JEQ/CMOVLGT/SETNE and friends).  Such names never probe cleanly, so
+// including them in the diff would be noise.  amd64 only: the other
+// architectures list their conditional branches outright.
+func derivedFamily(name string) bool {
+	if strings.HasPrefix(name, "J") && name != "JMP" && name != "JMPQ" {
+		return true
+	}
+	if strings.HasPrefix(name, "CMOV") || strings.HasPrefix(name, "SET") {
+		return true
+	}
+	return false
+}
+
+var unrecognizedRe = regexp.MustCompile(`unrecognized instruction`)
+
+// probeGoAsm feeds every mnemonic to go tool asm in one generated file and
+// classifies the diagnostics.  "Unrecognized instruction" is a parse-stage
+// verdict on the mnemonic alone, so a single bare-instruction probe per
+// mnemonic decides recognition; the combined file still reports every line's
+// error even when others fail.
+func probeGoAsm(goarch string, names []string) (map[string]bool, error) {
+	dir, err := os.MkdirTemp("", "gasm-audit")
+	if err != nil {
+		return nil, err
+	}
+	defer os.RemoveAll(dir)
+
+	var sb strings.Builder
+	sb.WriteString("TEXT ·probe(SB), 4, $0\n\tRET\n")
+	lineMnemonic := map[int]string{}
+	line := 3
+	for _, name := range names {
+		fmt.Fprintf(&sb, "TEXT ·p%s%d(SB), 4, $0\n", sanitize(name), line)
+		sb.WriteString("\t" + name + "\n\tRET\n")
+		lineMnemonic[line+1] = name // the instruction line, after TEXT
+		line += 3
+	}
+	probePath := filepath.Join(dir, "probe.s")
+	if err := os.WriteFile(probePath, []byte(sb.String()), 0o644); err != nil {
+		return nil, err
+	}
+
+	toolDir, err := exec.Command("go", "env", "GOTOOLDIR").Output()
+	if err != nil {
+		return nil, fmt.Errorf("go env GOTOOLDIR: %w", err)
+	}
+	asmBin := filepath.Join(strings.TrimSpace(string(toolDir)), "asm")
+	if _, err := os.Stat(asmBin); err != nil {
+		return nil, fmt.Errorf("go tool asm not found at %s", asmBin)
+	}
+	cmd := exec.Command(asmBin, "-p", "probe", "-o", filepath.Join(dir, "probe.o"), probePath)
+	cmd.Env = append(os.Environ(), "GOARCH="+goarch, "GOOS="+runtime.GOOS)
+	out, _ := cmd.CombinedOutput()
+
+	result := map[string]bool{}
+	for _, name := range names {
+		result[name] = true // no news = the name parsed fine
+	}
+	reParse := regexp.MustCompile(`probe\.s:(\d+):`)
+	for l := range strings.SplitSeq(string(out), "\n") {
+		m := reParse.FindStringSubmatch(l)
+		if m == nil {
+			continue
+		}
+		lineNo, err := strconv.Atoi(m[1])
+		if err != nil {
+			continue
+		}
+		if name, ok := lineMnemonic[lineNo]; ok && unrecognizedRe.MatchString(l) {
+			result[name] = false
+		}
+	}
+	return result, nil
+}
+
+// probeShapes lists representative operand shapes for the encodability
+// probe.  The assemblers report an unknown mnemonic and a known mnemonic
+// with no supported form alike ("unsupported <arch> instruction"), so only
+// a shape that assembles cleanly counts, and the backlog over-approximates:
+// a name whose real forms the battery misses lands there.  amd64 keeps its
+// exact table-driven check.
+func probeShapes(a arch.Arch) []string {
+	switch a {
+	case arch.ARM64:
+		return []string{
+			"X0, X1, X2", "X0, X1", "X0", "$1, X0", "X0, (X1)", "(X0), X1",
+			"X0, (X1, 8)", "(SP), X0", "F0, F1, F2", "F0, F1", "F0",
+			"V0.B16, V1.B16, V2.B16", "p2", "X0, p2", "X0, X1, p2",
+			// The conditional select family spells the condition first
+			// and takes R register spellings.
+			"EQ, R0, R1, R2", "EQ, R0, R1", "EQ, R0",
+			"GE, F0, F1, F2", "NE, F0, F1, $0",
+		}
+	case arch.RISCV:
+		return []string{
+			"X5, X6, X7", "X5, X6", "X5", "$1, X5", "X5, (X6)", "$1, X5, X6",
+			"(X5), X6", "F0, F1, F2", "F0, F1", "p2", "X1, p2", "X0, p2",
+			"X5, X6, p2", "p2(SB)",
+		}
+	case arch.LOONG64:
+		return []string{
+			"R4, R5, R6", "R4, R5", "R4", "$1, R4", "R4, (R5)", "(R4), R5",
+			"F0, F1, F2", "F0, F1", "p2", "R1, p2", "R4, p2",
+			"$1, R4, R5, R6", "$65536, R4", "R4, R5, p2", "p2(SB)",
+		}
+	}
+	return nil
+}
+
+// gasmEncodable reports whether the gasm encoder for a can emit the
+// mnemonic, decided by trial assembly over the shape battery.
+func gasmEncodable(a arch.Arch, name string) bool {
+	switch a {
+	case arch.ARM64, arch.RISCV, arch.LOONG64:
+	default:
+		return asm.Encodable(name)
+	}
+	for _, shape := range probeShapes(a) {
+		if gasmAssembles(a, name, shape) {
+			return true
+		}
+	}
+	return false
+}
+
+// gasmAssembles reports whether a one-instruction probe file containing name
+// with the given operand shape assembles without error.
+func gasmAssembles(a arch.Arch, name, shape string) bool {
+	src := "TEXT ·p(SB), NOSPLIT, $0\n\t" + name
+	if shape != "" {
+		src += " " + shape
+	}
+	src += "\n\tRET\np2:\n\tRET\n"
+	f, errs := parser.Parse("probe.s", src)
+	if len(errs) > 0 {
+		return false
+	}
+	var err error
+	switch a {
+	case arch.ARM64:
+		_, err = asm.AssembleFileARM64(f)
+	case arch.RISCV:
+		_, err = asm.AssembleFileRISCV(f)
+	case arch.LOONG64:
+		_, err = asm.AssembleFileLOONG64(f)
+	}
+	return err == nil
+}
+
+// sanitize makes a mnemonic safe for use in a Go symbol name.
+func sanitize(name string) string {
+	return strings.NewReplacer(".", "_", "$", "_").Replace(name)
+}

cmd/gasm/audit_test.go

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package main
+
+import (
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
+)
+
+func TestDerivedFamily(t *testing.T) {
+	for _, n := range []string{"JEQ", "JLT", "JCC", "CMOVLGT", "SETNE", "SETA"} {
+		if !derivedFamily(n) {
+			t.Errorf("derivedFamily(%q) = false, want true", n)
+		}
+	}
+	for _, n := range []string{"JMP", "ADDQ", "VPGATHERDD", "MOVBE", "PSHUFB"} {
+		if derivedFamily(n) {
+			t.Errorf("derivedFamily(%q) = true, want false", n)
+		}
+	}
+}
+
+func TestSanitize(t *testing.T) {
+	if got := sanitize("VPCMP.UB"); got != "VPCMP_UB" {
+		t.Errorf("sanitize: got %q", got)
+	}
+}
+
+func TestAuditArch(t *testing.T) {
+	for in, want := range map[string]arch.Arch{
+		"amd64": arch.AMD64, "arm64": arch.ARM64,
+		"riscv64": arch.RISCV, "riscv": arch.RISCV,
+		"loong64": arch.LOONG64, "LOONG": arch.LOONG64,
+	} {
+		got, err := auditArch(in)
+		if err != nil || got != want {
+			t.Errorf("auditArch(%q) = %v, %v; want %v", in, got, err, want)
+		}
+	}
+	if _, err := auditArch("mips"); err == nil {
+		t.Error("auditArch(mips) must fail")
+	}
+}
+
+func TestGasmEncodable(t *testing.T) {
+	cases := []struct {
+		a   arch.Arch
+		yes string
+		no  string
+	}{
+		{arch.AMD64, "ADDQ", "NOSUCHMNEMONIC"},
+		{arch.ARM64, "ADD", "NOSUCHMNEMONIC"},
+		{arch.RISCV, "ADD", "NOSUCHMNEMONIC"},
+		{arch.LOONG64, "ADDV", "NOSUCHMNEMONIC"},
+	}
+	for _, c := range cases {
+		if !gasmEncodable(c.a, c.yes) {
+			t.Errorf("%s: %s should be encodable", c.a, c.yes)
+		}
+		if gasmEncodable(c.a, c.no) {
+			t.Errorf("%s: %s should not be encodable", c.a, c.no)
+		}
+	}
+}

cmd/gasm/debug_linux.go

@@ -0,0 +1,331 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux
+
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"sort"
+	"strings"
+	"time"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/debug"
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+func cmdDebug(args []string) int {
+	fs := newCommand("debug", "gasm debug <file.s> --func <name>", `
+Interactive debugger for JIT-assembled functions.  Launches the
+function in a traced subprocess (ptrace), then provides a REPL for
+single-stepping, breakpoints, register and memory inspection.
+
+REPL commands:
+  break <label|addr> [if <reg> <op> <val>]
+                       set a breakpoint, optionally conditional on a
+                       register comparison (reg-reg or reg-immediate)
+  delete <label|addr>  remove a breakpoint
+  info break           list all breakpoints
+  step [n], s          single-step n instructions (default 1)
+  next, n              step over a CALL
+  finish, fin          run until the function returns
+  continue, c          run until a breakpoint, watchpoint or exit
+  disas [n], u         disassemble n instructions at PC
+  regs                 print general-purpose and 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 (default: current PC, 64 bytes)
+  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 watchpoint, or all without an argument
+  labels, l            list function labels and offsets
+  help, h, ?           show command help
+  quit, q              kill the debuggee and exit
+`)
+	funcName := fs.String("func", "", "function to debug")
+	argsFile := fs.String("args", "", "file containing the ABI0 argument block")
+	bufSpec := fs.String("buf", "", "buffer specification: name:size:pattern[,name:size:pattern...] where pattern is zero, ones, seq, or hex")
+	script := fs.String("script", "", "run REPL commands from a file (one per line) and exit; '-' reads stdin")
+	cover := fs.Bool("cover", false, "run to completion with a breakpoint on every instruction and report which executed and how often")
+	timeout := fs.Duration("timeout", 0, "kill the debuggee after this duration (e.g. 30s); for headless --script runs")
+	fs.Parse(args)
+
+	// --- Debuggee mode (internal, spawned by the debugger) ---
+	if os.Getenv("GASM_DEBUG_TARGET") != "" {
+		tmpDir := os.Getenv("GASM_DEBUG_TMP")
+		if tmpDir == "" || fs.NArg() < 1 || *funcName == "" || *argsFile == "" {
+			fmt.Fprintln(os.Stderr, "gasm debug: internal debuggee mode")
+			return 2
+		}
+		if err := debug.RunTarget(fs.Arg(0), *funcName, *argsFile, tmpDir); err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+		return 0
+	}
+
+	// --- Debugger mode (interactive REPL) ---
+	if fs.NArg() < 1 || *funcName == "" {
+		fmt.Fprintln(os.Stderr, "usage: gasm debug <file.s> --func <name>")
+		return 2
+	}
+	path := fs.Arg(0)
+
+	// The watchdog is armed before anything can block: ptrace attach and a
+	// continued kernel loop both hang the run when the environment forbids
+	// tracing or the kernel loops forever, and neither is interruptible from
+	// the inside.
+	if *timeout > 0 {
+		go func() {
+			time.Sleep(*timeout)
+			fmt.Fprintf(os.Stderr, "gasm debug: timeout (%s) — killing the debuggee\n", *timeout)
+			os.Exit(3)
+		}()
+	}
+
+	// Load the kernel to extract function metadata and labels.
+	k, err := verify.Load(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+		return 1
+	}
+	defer k.Close()
+
+	fl, err := k.Func(*funcName)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+		return 1
+	}
+
+	// Build the label list for the REPL.
+	var labels []debug.Label
+	for name, off := range fl.Labels {
+		labels = append(labels, debug.Label{Name: name, Offset: off})
+	}
+	sort.Slice(labels, func(i, j int) bool { return labels[i].Offset < labels[j].Offset })
+
+	// Launch the debuggee with the argument block.
+	var argBlock []byte
+	var bufAddrs []uint64
+	var sess *debug.Session
+	if *bufSpec != "" {
+		// Parse the function signature to determine argument layout.
+		src, err := readSource(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+		sig, ok := verify.ExtractFuncSig(src, *funcName)
+		if !ok {
+			fmt.Fprintf(os.Stderr, "gasm debug: no // func signature found for %s\n", *funcName)
+			return 1
+		}
+		layout := verify.ArgLayout(sig)
+
+		// Parse the buffer spec to get buffer names.
+		bufNames := parseBufNames(*bufSpec)
+
+		// Allocate buffers in the debuggee.
+		argBlock = make([]byte, fl.Args)
+		sess, bufAddrs, err = debug.LaunchWithBuffers("", path, *funcName, argBlock, *bufSpec)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+
+		// Construct the argument block with buffer pointers at the correct positions.
+		bufIdx := 0
+		for _, arg := range layout {
+			if !arg.IsPtr {
+				continue
+			}
+			// Find the buffer that matches this argument.
+			for i, name := range bufNames {
+				if i < len(bufAddrs) && (name == arg.Name || strings.HasPrefix(arg.Name, name)) {
+					addr := bufAddrs[i]
+					off := arg.Offset
+					if off+8 <= len(argBlock) {
+						argBlock[off] = byte(addr)
+						argBlock[off+1] = byte(addr >> 8)
+						argBlock[off+2] = byte(addr >> 16)
+						argBlock[off+3] = byte(addr >> 24)
+						argBlock[off+4] = byte(addr >> 32)
+						argBlock[off+5] = byte(addr >> 40)
+						argBlock[off+6] = byte(addr >> 48)
+						argBlock[off+7] = byte(addr >> 56)
+					}
+					// For slices, also set the length and capacity.
+					if strings.HasPrefix(arg.Typ, "[]") && off+24 <= len(argBlock) {
+						// Find the buffer size from the spec.
+						size := parseBufSize(*bufSpec, name)
+						// Length at offset+8, capacity at offset+16.
+						for j := range 8 {
+							argBlock[off+8+j] = byte(size >> (j * 8))
+							argBlock[off+16+j] = byte(size >> (j * 8))
+						}
+					}
+					bufIdx++
+					break
+				}
+			}
+		}
+		_ = bufIdx
+	} else {
+		argBlock = make([]byte, fl.Args)
+		sess, err = debug.Launch("", path, *funcName, argBlock)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+	}
+	defer sess.Kill()
+
+	bm := debug.NewBreakpoints(sess)
+	fmt.Printf("gasm debug: %s in %s (pid %d)\n", *funcName, path, sess.Pid())
+
+	// Convert the line table for the command loop.
+	var srcLines []debug.SourceLine
+	for _, le := range fl.Lines {
+		srcLines = append(srcLines, debug.SourceLine{Offset: le.Offset, Line: le.Line})
+	}
+
+	// Coverage mode: pre-register a breakpoint on every instruction (walked
+	// by length through the function body while the debuggee is stopped) and
+	// let the kernel run to completion.  Each trap counts a hit for that
+	// instruction, so the final report shows exactly which instructions
+	// executed and how often, with the label-level view derived from it.
+	// Expect the run to slow to ptrace speed: one trap per executed
+	// instruction.
+	if *cover {
+		base := sess.CodeBase() + uint64(fl.Offset)
+		type coverInstr struct {
+			off  uint64
+			text string
+		}
+		var instrs []coverInstr
+		for off := uint64(0); off < uint64(fl.Size); {
+			text, ln, err := sess.Disassemble(base + off)
+			if err != nil || ln == 0 {
+				break
+			}
+			instrs = append(instrs, coverInstr{off: off, text: text})
+			off += uint64(ln)
+		}
+		for _, in := range instrs {
+			if _, err := bm.SetWithCond(base+in.off, fmt.Sprintf("func+%#x", in.off), nil); err != nil {
+				fmt.Fprintf(os.Stderr, "gasm debug: cover: %v\n", err)
+				return 1
+			}
+		}
+		fmt.Printf("gasm debug: coverage run over %d instructions\n", len(instrs))
+		for {
+			for _, bp := range bm.All() {
+				bm.Reinsert(bp.Addr)
+			}
+			if err := sess.Continue(); err != nil {
+				break // debuggee finished or died
+			}
+			if sess.Exited() {
+				break
+			}
+			regs, rerr := sess.GetRegs()
+			if rerr != nil {
+				break
+			}
+			// HandleTrap restores the original byte, rewinds PC and counts
+			// the hit on the breakpoint itself.  Single-step over the
+			// restored instruction so the reinsertion at the top of the
+			// loop cannot re-trap on the same breakpoint.
+			if bp := bm.HandleTrap(&regs); bp != nil {
+				if err := sess.Step(); err != nil {
+					break
+				}
+			}
+		}
+		hits := map[uint64]int{}
+		traps := 0
+		for _, bp := range bm.All() {
+			if n := bp.Hits(); n > 0 {
+				hits[bp.Addr-base] = n
+				traps += n
+			}
+		}
+		var hit []string
+		var missed []string
+		for _, l := range labels {
+			if hits[uint64(l.Offset)] > 0 {
+				hit = append(hit, l.Name)
+			} else {
+				missed = append(missed, l.Name)
+			}
+		}
+		sort.Strings(hit)
+		sort.Strings(missed)
+		fmt.Printf("coverage: %d/%d instructions executed (%d traps)\n", len(hits), len(instrs), traps)
+		fmt.Printf("coverage: %d/%d labels reached\n", len(hit), len(labels))
+		for _, l := range hit {
+			fmt.Printf("  covered   %s\n", l)
+		}
+		for _, l := range missed {
+			fmt.Printf("  MISSED    %s\n", l)
+		}
+		fmt.Println("executed instructions:")
+		for _, in := range instrs {
+			if n := hits[in.off]; n > 0 {
+				fmt.Printf("  func+%#04x  %4dx  %s\n", in.off, n, in.text)
+			}
+		}
+		return 0
+	}
+
+	// Headless mode: run the script through the normal command loop and
+	// exit.  The watchdog armed above covers launch, continue and step.
+	var in io.Reader = os.Stdin
+	if *script != "" {
+		if *script == "-" {
+			in = os.Stdin
+		} else {
+			f, err := os.Open(*script)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+				return 1
+			}
+			defer f.Close()
+			in = f
+		}
+	}
+	debug.REPL(sess, bm, sess.CodeBase(), fl.Offset, fl.Size, fl.Args, labels, srcLines, in)
+	return 0
+}
+
+// parseBufNames extracts buffer names from a buffer specification.
+// Format: name:size:pattern[,name:size:pattern...]
+func parseBufNames(spec string) []string {
+	var names []string
+	for part := range strings.SplitSeq(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) >= 1 && fields[0] != "" {
+			names = append(names, fields[0])
+		}
+	}
+	return names
+}
+
+// parseBufSize extracts the size of a named buffer from a buffer specification.
+func parseBufSize(spec, name string) int {
+	for part := range strings.SplitSeq(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) >= 2 && fields[0] == name {
+			var size int
+			fmt.Sscanf(fields[1], "%d", &size)
+			return size
+		}
+	}
+	return 0
+}

cmd/gasm/debug_linux_amd64.go

@@ -1,193 +0,0 @@
-// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
-// SPDX-License-Identifier: BSD-3-Clause
-
-//go:build linux && amd64
-
-package main
-
-import (
-	"fmt"
-	"os"
-	"sort"
-	"strings"
-
-	"sourcedock.dev/petrbalvin/gasm-devkit/debug"
-	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
-)
-
-func cmdDebug(args []string) int {
-	fs := newCommand("debug", "gasm debug <file.s> --func <name>", `
-Interactive debugger for JIT-assembled amd64 functions.  Launches the
-function in a traced subprocess (ptrace), then provides a REPL for
-single-stepping, breakpoints, register and memory inspection.
-
-REPL commands:
-  break <label|addr>   set a breakpoint at a label or absolute address
-  step [n]             single-step n instructions (default 1)
-  continue             run until next breakpoint or exit
-  regs                 print general-purpose registers
-  x [addr] [len]       hex-dump memory (default: current PC, 64 bytes)
-  labels               list function labels and offsets
-  quit                 kill the debuggee and exit
-`)
-	target := fs.Bool("target", false, "") // hidden: debuggee subprocess mode
-	funcName := fs.String("func", "", "function to debug")
-	argsFile := fs.String("args", "", "file containing the ABI0 argument block")
-	bufSpec := fs.String("buf", "", "buffer specification: name:size:pattern[,name:size:pattern...] where pattern is zero, ones, seq, or hex")
-	fs.Parse(args)
-
-	// --- Debuggee mode (internal, spawned by the debugger) ---
-	if *target {
-		tmpDir := os.Getenv("GASM_DEBUG_TMP")
-		if tmpDir == "" || fs.NArg() < 1 || *funcName == "" || *argsFile == "" {
-			fmt.Fprintln(os.Stderr, "gasm debug --target: internal mode")
-			return 2
-		}
-		if err := debug.RunTarget(fs.Arg(0), *funcName, *argsFile, tmpDir); err != nil {
-			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
-			return 1
-		}
-		return 0
-	}
-
-	// --- Debugger mode (interactive REPL) ---
-	if fs.NArg() < 1 || *funcName == "" {
-		fmt.Fprintln(os.Stderr, "usage: gasm debug <file.s> --func <name>")
-		return 2
-	}
-	path := fs.Arg(0)
-
-	// Load the kernel to extract function metadata and labels.
-	k, err := verify.Load(path)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
-		return 1
-	}
-	defer k.Close()
-
-	fl, err := k.Func(*funcName)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
-		return 1
-	}
-
-	// Build the label list for the REPL.
-	var labels []debug.Label
-	for name, off := range fl.Labels {
-		labels = append(labels, debug.Label{Name: name, Offset: off})
-	}
-	sort.Slice(labels, func(i, j int) bool { return labels[i].Offset < labels[j].Offset })
-
-	// Launch the debuggee with the argument block.
-	var argBlock []byte
-	var bufAddrs []uint64
-	var sess *debug.Session
-	if *bufSpec != "" {
-		// Parse the function signature to determine argument layout.
-		src, err := readSource(path)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
-			return 1
-		}
-		sig, ok := verify.ExtractFuncSig(src, *funcName)
-		if !ok {
-			fmt.Fprintf(os.Stderr, "gasm debug: no // func signature found for %s\n", *funcName)
-			return 1
-		}
-		layout := verify.ArgLayout(sig)
-
-		// Parse the buffer spec to get buffer names.
-		bufNames := parseBufNames(*bufSpec)
-
-		// Allocate buffers in the debuggee.
-		argBlock = make([]byte, fl.Args)
-		sess, bufAddrs, err = debug.LaunchWithBuffers("", path, *funcName, argBlock, *bufSpec)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
-			return 1
-		}
-
-		// Construct the argument block with buffer pointers at the correct positions.
-		bufIdx := 0
-		for _, arg := range layout {
-			if !arg.IsPtr {
-				continue
-			}
-			// Find the buffer that matches this argument.
-			for i, name := range bufNames {
-				if i < len(bufAddrs) && (name == arg.Name || strings.HasPrefix(arg.Name, name)) {
-					addr := bufAddrs[i]
-					off := arg.Offset
-					if off+8 <= len(argBlock) {
-						argBlock[off] = byte(addr)
-						argBlock[off+1] = byte(addr >> 8)
-						argBlock[off+2] = byte(addr >> 16)
-						argBlock[off+3] = byte(addr >> 24)
-						argBlock[off+4] = byte(addr >> 32)
-						argBlock[off+5] = byte(addr >> 40)
-						argBlock[off+6] = byte(addr >> 48)
-						argBlock[off+7] = byte(addr >> 56)
-					}
-					// For slices, also set the length and capacity.
-					if strings.HasPrefix(arg.Typ, "[]") && off+24 <= len(argBlock) {
-						// Find the buffer size from the spec.
-						size := parseBufSize(*bufSpec, name)
-						// Length at offset+8, capacity at offset+16.
-						for j := 0; j < 8; j++ {
-							argBlock[off+8+j] = byte(size >> (j * 8))
-							argBlock[off+16+j] = byte(size >> (j * 8))
-						}
-					}
-					bufIdx++
-					break
-				}
-			}
-		}
-		_ = bufIdx
-	} else {
-		argBlock = make([]byte, fl.Args)
-		sess, err = debug.Launch("", path, *funcName, argBlock)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
-			return 1
-		}
-	}
-	defer sess.Kill()
-
-	bm := debug.NewBreakpoints(sess)
-	fmt.Printf("gasm debug: %s in %s (pid %d)\n", *funcName, path, sess.Pid())
-
-	// Convert the line table for the REPL.
-	var srcLines []debug.SourceLine
-	for _, le := range fl.Lines {
-		srcLines = append(srcLines, debug.SourceLine{Offset: le.Offset, Line: le.Line})
-	}
-	debug.REPL(sess, bm, sess.CodeBase(), fl.Offset, fl.Size, fl.Args, labels, srcLines)
-	return 0
-}
-
-// parseBufNames extracts buffer names from a buffer specification.
-// Format: name:size:pattern[,name:size:pattern...]
-func parseBufNames(spec string) []string {
-	var names []string
-	for _, part := range strings.Split(spec, ",") {
-		fields := strings.SplitN(part, ":", 3)
-		if len(fields) >= 1 && fields[0] != "" {
-			names = append(names, fields[0])
-		}
-	}
-	return names
-}
-
-// parseBufSize extracts the size of a named buffer from a buffer specification.
-func parseBufSize(spec, name string) int {
-	for _, part := range strings.Split(spec, ",") {
-		fields := strings.SplitN(part, ":", 3)
-		if len(fields) >= 2 && fields[0] == name {
-			var size int
-			fmt.Sscanf(fields[1], "%d", &size)
-			return size
-		}
-	}
-	return 0
-}

cmd/gasm/debug_other.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
 // SPDX-License-Identifier: BSD-3-Clause
 
-//go:build !(linux && amd64)
+//go:build !linux
 
 package main
 
@@ -11,6 +11,6 @@ import (
 )
 
 func cmdDebug(args []string) int {
-	fmt.Fprintln(os.Stderr, "gasm debug: the interactive debugger requires linux/amd64 (ptrace)")
+	fmt.Fprintln(os.Stderr, "gasm debug: the interactive debugger requires Linux (ptrace)")
 	return 1
 }

cmd/gasm/main.go

@@ -9,6 +9,7 @@ package main
 
 import (
 	"bytes"
+	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
@@ -16,9 +17,12 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 
 	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
@@ -34,7 +38,7 @@ import (
 
 // version is the release version, stamped at build time via
 // -ldflags "-X main.version=…" (defaulting to the current release).
-var version = "0.30.0"
+var version = "0.32.0"
 
 func main() {
 	if len(os.Args) < 2 {
@@ -60,6 +64,16 @@ func main() {
 		os.Exit(cmdDiff(os.Args[2:]))
 	case "profile":
 		os.Exit(cmdProfile(os.Args[2:]))
+	case "audit-instructions":
+		if err := cmdAuditInstructions(os.Args[2:]); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+	case "scaffold":
+		if err := cmdScaffold(os.Args[2:]); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
 	case "lsp":
 		os.Exit(cmdLSP(os.Args[2:]))
 	case "version", "--version", "-V":
@@ -117,11 +131,13 @@ func usage(w io.Writer) {
 		{"parse", "parse and report syntax errors"},
 		{"fmt", "canonicalise formatting (gofmt for assembly)"},
 		{"lint", "run static checks"},
-		{"asm", "assemble .s files to machine code (amd64, riscv64)"},
-		{"verify", "JIT-assemble and run dynamic checks (amd64, riscv64)"},
-		{"debug", "interactive source-level debugger (amd64)"},
+		{"asm", "assemble .s files to machine code (amd64, arm64, riscv64, loong64)"},
+		{"verify", "JIT-assemble and run dynamic checks (amd64, arm64, riscv64, loong64)"},
+		{"debug", "interactive source-level debugger (amd64, arm64, riscv64, loong64)"},
 		{"diff", "compare machine code of two .s files"},
 		{"profile", "show basic-block structure of functions"},
+		{"audit-instructions", "diff the encoder against the Go toolchain's name table"},
+		{"scaffold", "generate a differential test skeleton for a kernel file"},
 		{"lsp", "run the language server over stdio"},
 		{"version", "print the version (same as --version)"},
 	}
@@ -171,6 +187,22 @@ func newCommand(name, usageLine, long string) *flag.FlagSet {
 }
 
 // readSource returns the contents of path, or stdin when path is "-".
+// hostArch maps the running GOARCH onto the arch package's identifiers.
+// It returns arch.Unknown on hosts the toolkit cannot JIT for.
+func hostArch() arch.Arch {
+	switch runtime.GOARCH {
+	case "amd64":
+		return arch.AMD64
+	case "arm64":
+		return arch.ARM64
+	case "riscv64":
+		return arch.RISCV
+	case "loong64":
+		return arch.LOONG64
+	}
+	return arch.Unknown
+}
+
 func readSource(path string) (string, error) {
 	if path == "-" {
 		b, err := io.ReadAll(os.Stdin)
@@ -285,7 +317,7 @@ given.
 			rc = 1
 			continue
 		}
-		out := format.Source(path, src)
+		out := format.Source(src)
 		if dirMode || *write {
 			if out != src {
 				if err := os.WriteFile(path, []byte(out), 0o644); err != nil {
@@ -345,7 +377,7 @@ unreachable-code, register-clobber and funcdata-pcdata.
 		return 2
 	}
 	disabled := map[string]bool{}
-	for _, code := range strings.Split(*disable, ",") {
+	for code := range strings.SplitSeq(*disable, ",") {
 		if code = strings.TrimSpace(code); code != "" {
 			disabled[code] = true
 		}
@@ -398,8 +430,9 @@ func cmdAsm(args []string) int {
 	fs := newCommand("asm", "gasm asm [--format raw|elf|goobj] [-p pkg] [-o out] <file>", `
 	Assemble FILE without the Go toolchain: every TEXT function is encoded to
 	machine code and printed as a hex dump.  Supported architectures: amd64
-	(including VEX/AVX2 and EVEX/AVX-512), riscv64 (RV64IMAFDC + RVC) and
-	loong64 (LoongArch base ISA); arm64 encoding is not yet implemented.
+	(including VEX/AVX2 and EVEX/AVX-512), arm64 (AArch64 integer, FP,
+	conditional select, CRC32, and MOV pseudo), riscv64 (RV64IMAFDC + RVC)
+	and loong64 (LoongArch base ISA).
 
 With -o the output is written to a file instead.  The --format flag selects
 what is written: raw (the default) concatenates the functions and the data
@@ -432,7 +465,7 @@ requires -p, the package path, and the installed Go toolchain).
 		return 1
 	}
 
-	img, err := assembleFile(path, targetArch, f)
+	img, err := assembleFile(targetArch, f)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "%s: %v\n", path, err)
 		return 1
@@ -445,10 +478,7 @@ requires -p, the package path, and the installed Go toolchain).
 		code := img.Code[fn.Offset : fn.Offset+fn.Size]
 		fmt.Printf("%s: %d bytes\n", fn.Name, fn.Size)
 		for i := 0; i < len(code); i += 16 {
-			end := i + 16
-			if end > len(code) {
-				end = len(code)
-			}
+			end := min(i+16, len(code))
 			fmt.Printf("  %04x:", i)
 			for _, b := range code[i:end] {
 				fmt.Printf(" %02x", b)
@@ -470,10 +500,7 @@ requires -p, the package path, and the installed Go toolchain).
 			fmt.Printf("  %s: %d bytes at 0x%x\n", g.Name.Name, size, img.Symbols[g.Name.Name])
 		}
 		for i := 0; i < len(img.Data); i += 16 {
-			end := i + 16
-			if end > len(img.Data) {
-				end = len(img.Data)
-			}
+			end := min(i+16, len(img.Data))
 			fmt.Printf("  %04x:", len(img.Code)+i)
 			for _, b := range img.Data[i:end] {
 				fmt.Printf(" %02x", b)
@@ -498,6 +525,8 @@ requires -p, the package path, and the installed Go toolchain).
 				obj, err = img.ELFRISCVObject()
 			case arch.LOONG64:
 				obj, err = img.ELFLOONG64Object()
+			case arch.ARM64:
+				obj, err = img.ELFAARCH64Object()
 			default:
 				obj, err = img.ELFObject()
 			}
@@ -508,6 +537,8 @@ requires -p, the package path, and the installed Go toolchain).
 				obj, err = img.GOObjectRISCV(*pkg, path)
 			case arch.LOONG64:
 				obj, err = img.GOObjectLOONG64(*pkg, path)
+			case arch.ARM64:
+				obj, err = img.GOObjectAARCH64(*pkg, path)
 			default:
 				obj, err = img.GOObject(*pkg, path)
 			}
@@ -531,7 +562,7 @@ requires -p, the package path, and the installed Go toolchain).
 
 // cmdDiff compares the machine code of two assembly files.
 func cmdDiff(args []string) int {
-	fs := newCommand("diff", "gasm diff <file1.s> <file2.s>", `
+	set := newCommand("diff", "gasm diff <file1.s> <file2.s>", `
 Compare the machine code produced by assembling two files.
 Shows which functions differ and the byte-level differences.
 Useful for verifying that two implementations produce identical code,
@@ -540,18 +571,18 @@ or for tracking encoding changes between Go assembler versions.
 Use --map to compare functions whose names differ between the files,
 e.g. --map wideCopyAVX2=wideCopyAVX512 pairs the two regardless of suffix.
 `)
-	mapSpec := fs.String("map", "", "comma-separated old=new pairs to match functions with different names")
-	fs.Parse(args)
-	if fs.NArg() != 2 {
+	mapSpec := set.String("map", "", "comma-separated old=new pairs to match functions with different names")
+	set.Parse(args)
+	if set.NArg() != 2 {
 		fmt.Fprintln(os.Stderr, "usage: gasm diff <file1.s> <file2.s>")
 		return 2
 	}
-	path1, path2 := fs.Arg(0), fs.Arg(1)
+	path1, path2 := set.Arg(0), set.Arg(1)
 
 	// Parse the name mapping (file1 name → file2 name).
 	nameMap := make(map[string]string)
 	if *mapSpec != "" {
-		for _, pair := range strings.Split(*mapSpec, ",") {
+		for pair := range strings.SplitSeq(*mapSpec, ",") {
 			old, new, ok := strings.Cut(pair, "=")
 			if !ok || old == "" || new == "" {
 				fmt.Fprintf(os.Stderr, "gasm diff: invalid --map pair %q (expected old=new)\n", pair)
@@ -627,7 +658,7 @@ e.g. --map wideCopyAVX2=wideCopyAVX512 pairs the two regardless of suffix.
 }
 
 // assembleFile assembles a parsed file for the given architecture and returns the image.
-func assembleFile(path string, targetArch arch.Arch, f *ast.File) (*asm.Image, error) {
+func assembleFile(targetArch arch.Arch, f *ast.File) (*asm.Image, error) {
 	switch targetArch {
 	case arch.AMD64:
 		return asm.AssembleFile(f)
@@ -655,15 +686,12 @@ func assemblePath(path string) (*asm.Image, error) {
 	if len(errs) > 0 {
 		return nil, fmt.Errorf("parse errors")
 	}
-	return assembleFile(path, arch.FromFilename(path), f)
+	return assembleFile(arch.FromFilename(path), f)
 }
 
 // printByteDiff shows the first few byte differences between two code blocks.
 func printByteDiff(a, b []byte) {
-	maxLen := len(a)
-	if len(b) < maxLen {
-		maxLen = len(b)
-	}
+	maxLen := min(len(b), len(a))
 	shown := 0
 	for i := 0; i < maxLen && shown < 8; i++ {
 		if a[i] != b[i] {
@@ -678,18 +706,18 @@ func printByteDiff(a, b []byte) {
 
 // cmdProfile shows the basic-block structure of functions in an assembly file.
 func cmdProfile(args []string) int {
-	fs := newCommand("profile", "gasm profile <file.s>", `
+	flagSet := newCommand("profile", "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.
 `)
-	fs.Parse(args)
-	if fs.NArg() != 1 {
+	flagSet.Parse(args)
+	if flagSet.NArg() != 1 {
 		fmt.Fprintln(os.Stderr, "usage: gasm profile <file.s>")
 		return 2
 	}
-	path := fs.Arg(0)
+	path := flagSet.Arg(0)
 
 	// Load the file to get function metadata.
 	k, err := verify.Load(path)
@@ -921,8 +949,97 @@ func cmdVerifyLOONG64(path string, groundTruth, profile bool) int {
 	return 0
 }
 
+func cmdVerifyARM64(path string, groundTruth, profile bool) int {
+	src, err := readSource(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	f, errs := parser.Parse(path, src)
+	for _, e := range errs {
+		fmt.Fprintf(os.Stderr, "%s: %v\n", path, e)
+	}
+	if len(errs) > 0 {
+		return 1
+	}
+	img, err := asm.AssembleFileARM64(f)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+
+	if groundTruth {
+		gt, err := verify.GroundTruthARM64(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: ground truth: %v\n", err)
+			return 1
+		}
+		matched, total := 0, 0
+		for _, fn := range img.Funcs {
+			gasmCode := img.Code[fn.Offset : fn.Offset+fn.Size]
+			goCode, ok := gt[fn.Name]
+			if !ok {
+				fmt.Printf("  %s: SKIP (not in go tool asm output)\n", fn.Name)
+				continue
+			}
+			total++
+			gasmCmp := make([]byte, len(gasmCode))
+			goCmp := make([]byte, len(goCode))
+			copy(gasmCmp, gasmCode)
+			copy(goCmp, goCode)
+			for _, r := range fn.Relocs {
+				for j := r.Off; j < r.Off+4 && j < len(gasmCmp); j++ {
+					gasmCmp[j] = 0
+				}
+				for j := r.Off; j < r.Off+4 && j < len(goCmp); j++ {
+					goCmp[j] = 0
+				}
+			}
+			if bytes.Equal(gasmCmp, goCmp) {
+				matched++
+				if len(fn.Relocs) > 0 {
+					fmt.Printf("  %s: MATCH (%d bytes, %d relocs masked)\n", fn.Name, fn.Size, len(fn.Relocs))
+				} else {
+					fmt.Printf("  %s: MATCH (%d bytes)\n", fn.Name, fn.Size)
+				}
+			} else {
+				fmt.Printf("  %s: MISMATCH (%d vs %d bytes)\n", fn.Name, fn.Size, len(goCode))
+				for i := 0; i < len(gasmCode) || i < len(goCode); i += 16 {
+					var gb, gs string
+					for j := i; j < i+16 && j < len(gasmCode); j++ {
+						gb += fmt.Sprintf(" %02x", gasmCode[j])
+					}
+					for j := i; j < i+16 && j < len(goCode); j++ {
+						gs += fmt.Sprintf(" %02x", goCode[j])
+					}
+					fmt.Printf("    %04x: gasm:%s\n", i, gb)
+					fmt.Printf("    %04x: gt:  %s\n", i, gs)
+				}
+			}
+		}
+		fmt.Printf("%s: %d/%d matched\n", path, matched, total)
+		if matched < total {
+			return 1
+		}
+		return 0
+	}
+
+	if profile {
+		for _, fn := range img.Funcs {
+			fmt.Printf("%s: %d bytes, labels: %v\n", fn.Name, fn.Size, fn.Labels)
+		}
+		return 0
+	}
+
+	fmt.Printf("%s: %d functions assembled\n", path, len(img.Funcs))
+	for _, fn := range img.Funcs {
+		fmt.Printf("  %s: %d bytes\n", fn.Name, fn.Size)
+	}
+	return 0
+}
+
 func cmdVerify(args []string) int {
-	fs := newCommand("verify", "gasm verify [-smoke] [-abi] [-fuzz] [-ground-truth] [-profile] [-call] <file.s>", `
+	set := newCommand("verify", "gasm verify [-smoke] [-abi] [-fuzz] [-ground-truth] [-profile] [-call] <file.s>", `
 Assemble FILE (amd64), map it into executable memory and report the available
 functions.  This confirms the assembled image is self-consistent (no
 unresolved external symbols) and executable — the prerequisite for dynamic
@@ -932,8 +1049,11 @@ With -smoke, each NOSPLIT function is called with a zeroed argument block to
 confirm the JIT trampoline works end-to-end.  This is safe only for functions
 that tolerate nil pointers and zero lengths in their arguments.
 
-With -abi, each function is called with sentinel values in the callee-saved
-registers (BP, R14) and a red-zone canary below SP; violations are reported.
+With -abi, each function is called with sentinel values in the registers
+the Go ABI fixes across calls (the frame pointer and the goroutine
+pointer) plus a canary below SP; violations are reported.  JIT-based
+checks run when the host matches the file's architecture (all but
+loong64, which is ground-truth only for now).
 
 With -fuzz, each function with a // func signature is differentially fuzzed
 against the go-tool-asm version in a subprocess (so a crash on a partial
@@ -947,37 +1067,57 @@ With -profile, the static basic-block structure is listed for each function.
 With -call, a single function is invoked with user-supplied buffers (-buf)
 instead of the smoke/abi/fuzz sweeps.  Useful for partial functions (e.g.
 decoders) that crash on random input but should succeed on valid data.
+
+With -save-corpus (and -fuzz), every input that crashes or mismatches is
+written to the directory as replayable JSON.  -replay re-runs saved
+entries against the kernel, one child process per entry, so an input that
+crashed the original run crashes only the child: the report says whether
+each entry reproduces.
 `)
-	smoke := fs.Bool("smoke", false, "call each NOSPLIT function with zeroed args")
-	abi := fs.Bool("abi", false, "run ABI-checking calls (sentinel registers + red zone)")
-	abiN := fs.Int("abi-n", 100, "number of ABI check iterations with varied inputs")
-	profile := fs.Bool("profile", false, "list basic-block structure per function")
-	groundTruth := fs.Bool("ground-truth", false, "compare machine code byte-for-byte against go tool asm")
-	fuzz := fs.Bool("fuzz", false, "differential fuzz: JIT both gasm and go-tool-asm versions, compare outputs")
-	fuzzN := fs.Int("n", 1000, "number of fuzz iterations per function")
-	fuzzOne := fs.String("fuzz-one", "", "") // hidden: fuzz a single function (subprocess mode)
-	call := fs.String("call", "", "call a single function with -buf instead of the sweeps")
-	bufSpec := fs.String("buf", "", "buffer spec for -call: name:size:pattern[,name:size:pattern] (zero, ones, seq, or hex)")
-	repeat := fs.Int("repeat", 1, "number of times to repeat a -call invocation")
-	fs.Parse(args)
-	if fs.NArg() != 1 {
+	smoke := set.Bool("smoke", false, "call each NOSPLIT function with zeroed args")
+	abi := set.Bool("abi", false, "run ABI-checking calls (sentinel registers + red zone)")
+	abiN := set.Int("abi-n", 100, "number of ABI check iterations with varied inputs")
+	profile := set.Bool("profile", false, "list basic-block structure per function")
+	groundTruth := set.Bool("ground-truth", false, "compare machine code byte-for-byte against go tool asm")
+	fuzz := set.Bool("fuzz", false, "differential fuzz: JIT both gasm and go-tool-asm versions, compare outputs")
+	fuzzN := set.Int("n", 1000, "number of fuzz iterations per function")
+	call := set.String("call", "", "call a single function with -buf instead of the sweeps")
+	bufSpec := set.String("buf", "", "buffer spec for -call: name:size:pattern[,name:size:pattern] (zero, ones, seq, or hex)")
+	scalarSpec := set.String("args", "", "scalar args for -call: name=value[,name=value] (decimal or 0x hex)")
+	repeat := set.Int("repeat", 1, "number of times to repeat a -call invocation")
+	saveCorpus := set.String("save-corpus", "", "with -fuzz: write each failing input to this directory as replayable JSON")
+	replay := set.String("replay", "", "replay saved corpus entries (JSON files in this directory) against the kernel")
+	set.Parse(args)
+	if set.NArg() != 1 {
 		fmt.Fprintln(os.Stderr, "usage: gasm verify [-smoke] [-abi] [-fuzz] [-ground-truth] [-profile] [-call] <file.s>")
 		return 2
 	}
-	path := fs.Arg(0)
+	path := set.Arg(0)
 	targetArch := arch.FromFilename(path)
-	switch targetArch {
-	case arch.AMD64:
-		// JIT-based verification below.
-	case arch.RISCV:
-		// RISC-V: ground-truth only (no JIT on non-RISC-V hosts).
-		return cmdVerifyRISCV(path, *groundTruth, *profile)
-	case arch.LOONG64:
-		// LoongArch: ground-truth only (no JIT on non-LoongArch hosts).
-		return cmdVerifyLOONG64(path, *groundTruth, *profile)
-	default:
-		fmt.Fprintln(os.Stderr, "gasm verify: only amd64, riscv64 and loong64 are supported")
-		return 1
+	// JIT execution runs when the host CPU matches the kernel's
+	// architecture, except loong64: its trampoline is implemented but not
+	// yet validated against real hardware (the Go runtime cannot start
+	// under the available loong64 emulators), so those kernels take the
+	// toolchain-comparison path.
+	if targetArch != hostArch() || targetArch == arch.LOONG64 {
+		switch targetArch {
+		case arch.RISCV:
+			// RISC-V: ground-truth only (no JIT on non-RISC-V hosts).
+			return cmdVerifyRISCV(path, *groundTruth, *profile)
+		case arch.LOONG64:
+			// LoongArch: ground-truth only (trampoline not yet
+			// hardware-validated).
+			return cmdVerifyLOONG64(path, *groundTruth, *profile)
+		case arch.ARM64:
+			// AArch64: ground-truth only (no JIT on non-ARM64 hosts).
+			return cmdVerifyARM64(path, *groundTruth, *profile)
+		case arch.AMD64:
+			fmt.Fprintln(os.Stderr, "gasm verify: JIT-based checks need an amd64 host; use --ground-truth here")
+			return 1
+		default:
+			fmt.Fprintln(os.Stderr, "gasm verify: unsupported architecture")
+			return 1
+		}
 	}
 
 	k, err := verify.Load(path)
@@ -993,11 +1133,23 @@ decoders) that crash on random input but should succeed on valid data.
 
 	// Single-function call mode: invoke one function with user-supplied buffers.
 	if *call != "" {
-		return cmdVerifyCall(k, path, *call, *bufSpec, *repeat)
+		return cmdVerifyCall(k, path, *call, *bufSpec, *scalarSpec, *repeat)
 	}
 
-	// Subprocess mode: fuzz a single function and exit.
-	if *fuzzOne != "" {
+	// Corpus replay: re-run every saved entry in its own child process, so
+	// an input that crashed the original run crashes only the child.
+	if rp := os.Getenv("GASM_VERIFY_REPLAY_ONE"); rp != "" {
+		return cmdReplayOne(k, rp)
+	}
+	if *replay != "" {
+		return cmdVerifyReplay(path, *replay)
+	}
+
+	// Subprocess mode: fuzz a single function and exit.  The parent selects
+	// the function through the environment, so no internal flag leaks into
+	// the -h output.
+	fuzzOne := os.Getenv("GASM_VERIFY_FUZZ_ONE")
+	if fuzzOne != "" {
 		gt, err := verify.GroundTruth(path)
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
@@ -1009,17 +1161,34 @@ decoders) that crash on random input but should succeed on valid data.
 			return 1
 		}
 		sigs := verify.ExtractSignatures(src)
-		sig, ok := sigs[*fuzzOne]
+		sig, ok := sigs[fuzzOne]
 		if !ok {
-			fmt.Printf("%s: no signature\n", *fuzzOne)
+			fmt.Printf("%s: no signature\n", fuzzOne)
 			return 0
 		}
-		goCode, ok := gt[*fuzzOne]
+		goCode, ok := gt[fuzzOne]
 		if !ok {
-			fmt.Printf("%s: not in go tool asm\n", *fuzzOne)
+			fmt.Printf("%s: not in go tool asm\n", fuzzOne)
 			return 0
 		}
-		res := k.FuzzFunc(*fuzzOne, sig, goCode, *fuzzN, 42)
+		var onSave func(verify.CorpusEntry)
+		if *saveCorpus != "" {
+			if err := os.MkdirAll(*saveCorpus, 0o755); err != nil {
+				fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+				return 1
+			}
+			saved := 0
+			onSave = func(e verify.CorpusEntry) {
+				file := filepath.Join(*saveCorpus, fmt.Sprintf("%s@%d.json", sanitize(e.Func), saved))
+				saved++
+				data, err := json.MarshalIndent(e, "", "  ")
+				if err != nil {
+					return
+				}
+				_ = os.WriteFile(file, data, 0o644)
+			}
+		}
+		res := k.FuzzFuncHook(fuzzOne, sig, goCode, *fuzzN, 42, onSave)
 		fmt.Printf("%s\n", res)
 		if !res.OK() {
 			return 1
@@ -1027,6 +1196,27 @@ decoders) that crash on random input but should succeed on valid data.
 		return 0
 	}
 
+	// Subprocess mode: run the smoke/abi checks for a single function and
+	// exit with the accumulated status.  The parent interprets a clean exit
+	// as success, a non-zero exit as failure and death-by-signal as a crash.
+	// Like the fuzz mode, the parent selects the function through the
+	// environment instead of an internal flag.
+	if sweepOne := os.Getenv("GASM_VERIFY_SWEEP_ONE"); sweepOne != "" {
+		fl, err := k.Func(sweepOne)
+		if err != nil || !fl.NoSplit {
+			fmt.Fprintf(os.Stderr, "gasm verify: %s: %v\n", sweepOne, err)
+			return 1
+		}
+		msgs, failed := runSweepChecks(k, path, sweepOne, fl, *smoke, *abi, *abiN)
+		for _, m := range msgs {
+			fmt.Println(m)
+		}
+		if failed {
+			return 1
+		}
+		return 0
+	}
+
 	// Ground-truth comparison: assemble with go tool asm and compare bytes.
 	if *groundTruth {
 		gt, err := verify.GroundTruth(path)
@@ -1111,7 +1301,11 @@ decoders) that crash on random input but should succeed on valid data.
 			}
 			// Run in a subprocess: if the function crashes on random
 			// input (partial function), we report it and move on.
-			res := fuzzInSubprocess(path, name, *fuzzN)
+			var extra []string
+			if *saveCorpus != "" {
+				extra = append(extra, "-save-corpus", *saveCorpus)
+			}
+			res := fuzzInSubprocess(path, name, *fuzzN, extra...)
 			if res != "" {
 				fmt.Printf("  %s\n", res)
 				if strings.Contains(res, "MISMATCH") {
@@ -1124,6 +1318,7 @@ decoders) that crash on random input but should succeed on valid data.
 		}
 		fmt.Printf("fuzz: %d functions tested, %d iterations each\n", fuzzed, *fuzzN)
 	}
+	// Print function info and profile.
 	for _, name := range names {
 		fl, _ := k.Func(name)
 		flags := ""
@@ -1131,7 +1326,6 @@ decoders) that crash on random input but should succeed on valid data.
 			flags = " NOSPLIT"
 		}
 		fmt.Printf("  %s: %d bytes, args=%d, frame=%d%s\n", name, fl.Size, fl.Args, fl.Frame, flags)
-
 		if *profile {
 			blocks, err := k.Blocks(name)
 			if err != nil {
@@ -1140,40 +1334,52 @@ decoders) that crash on random input but should succeed on valid data.
 				fmt.Printf("    blocks: %d\n", len(blocks))
 			}
 		}
+	}
 
-		if *smoke && fl.NoSplit {
-			args := make([]byte, fl.Args)
-			_, err := k.CallFunc(name, args)
-			if err != nil {
-				fmt.Printf("    smoke: FAIL — %v\n", err)
-				rc = 1
-			} else {
-				fmt.Printf("    smoke: OK\n")
-			}
+	// Run smoke and ABI checks in parallel, each function in its own child
+	// process: the JIT'd code runs with zeroed or fuzzed arguments, and a
+	// function that dereferences them faults — the crash is reported as a
+	// CRASH line instead of killing this process (mirrors fuzzInSubprocess).
+	if *smoke || *abi {
+		type checkResult struct {
+			name string
+			msg  string
+			fail bool
 		}
+		var mu sync.Mutex
+		var results []checkResult
+		sem := make(chan struct{}, runtime.NumCPU())
+		var wg sync.WaitGroup
 
-		if *abi && fl.NoSplit {
-			// Try varied-input ABI fuzzing first.
-			if src, err := readSource(path); err == nil {
-				result := k.FuzzFuncCheckedByName(name, src, *abiN, int64(*abiN))
-				if result.Mismatches > 0 {
-					fmt.Printf("    abi: %s\n", result)
+		for _, name := range names {
+			fl, _ := k.Func(name)
+			if !fl.NoSplit {
+				continue
+			}
+			wg.Add(1)
+			go func(name string) {
+				defer wg.Done()
+				sem <- struct{}{}
+				defer func() { <-sem }()
+
+				msg, fail := sweepInSubprocess(path, name, *smoke, *abi, *abiN)
+				mu.Lock()
+				results = append(results, checkResult{name: name, msg: msg, fail: fail})
+				mu.Unlock()
+			}(name)
+		}
+		wg.Wait()
+
+		// Print results in source order.
+		resultMap := make(map[string]checkResult, len(results))
+		for _, r := range results {
+			resultMap[r.name] = r
+		}
+		for _, name := range names {
+			if r, ok := resultMap[name]; ok {
+				fmt.Println(r.msg)
+				if r.fail {
 					rc = 1
-				} else {
-					fmt.Printf("    abi: clean (%d varied inputs)\n", result.Matches)
-				}
-			} else {
-				// Fallback: single zeroed-arg call.
-				args := make([]byte, fl.Args)
-				_, report, err := k.CallFuncChecked(name, args)
-				if err != nil {
-					fmt.Printf("    abi: FAIL — %v\n", err)
-					rc = 1
-				} else if !report.OK() {
-					fmt.Printf("    abi: %s\n", report)
-					rc = 1
-				} else {
-					fmt.Printf("    abi: clean\n")
 				}
 			}
 		}
@@ -1182,14 +1388,91 @@ decoders) that crash on random input but should succeed on valid data.
 }
 
 // fuzzInSubprocess runs the fuzz for a single function in a child process.
+// cmdVerifyReplay replays every saved corpus entry against the kernel, one
+// child process per entry so an input that crashed the original run crashes
+// only the child.  Exits non-zero when any entry crashes or fails.
+func cmdVerifyReplay(path, dir string) int {
+	self, err := os.Executable()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: cannot find self: %v\n", err)
+		return 1
+	}
+	files, err := filepath.Glob(filepath.Join(dir, "*.json"))
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	if len(files) == 0 {
+		fmt.Fprintf(os.Stderr, "gasm verify: no corpus entries in %s\n", dir)
+		return 1
+	}
+	slices.Sort(files)
+	rc := 0
+	for _, f := range files {
+		cmd := exec.Command(self, "verify", path)
+		cmd.Env = append(os.Environ(), "GASM_VERIFY_REPLAY_ONE="+f)
+		out, err := cmd.CombinedOutput()
+		name := filepath.Base(f)
+		switch {
+		case err == nil:
+			fmt.Printf("  %s: OK\n", name)
+		case replayCrashed(err):
+			rc = 1
+			fmt.Printf("  %s: CRASH (reproduced)\n", name)
+		default:
+			rc = 1
+			detail := strings.TrimSpace(string(out))
+			if detail == "" {
+				detail = err.Error()
+			}
+			fmt.Printf("  %s: FAIL (%s)\n", name, detail)
+		}
+	}
+	return rc
+}
+
+// replayCrashed reports whether a replay child died from a signal, which
+// means the saved input reproduced its original crash.
+func replayCrashed(err error) bool {
+	exitErr, ok := err.(*exec.ExitError)
+	if !ok {
+		return false
+	}
+	ws, ok := exitErr.Sys().(syscall.WaitStatus)
+	return ok && ws.Signaled()
+}
+
+// cmdReplayOne is the child half of corpus replay: rebuild one entry and
+// call it, reporting the outcome on stdout.
+func cmdReplayOne(k *verify.Kernel, file string) int {
+	data, err := os.ReadFile(file)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	var e verify.CorpusEntry
+	if err := json.Unmarshal(data, &e); err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %s: %v\n", file, err)
+		return 1
+	}
+	if _, err := k.ReplayEntry(e.Func, e); err != nil {
+		fmt.Printf("%s: %v\n", e.Func, err)
+		return 1
+	}
+	return 0
+}
+
 // If the child is killed by a signal (e.g. SIGSEGV from a partial function
 // faulting on random input), it returns a CRASH report instead of dying.
-func fuzzInSubprocess(path, funcName string, n int) string {
+func fuzzInSubprocess(path, funcName string, n int, extra ...string) string {
 	self, err := os.Executable()
 	if err != nil {
 		return fmt.Sprintf("%s: cannot find self: %v", funcName, err)
 	}
-	cmd := exec.Command(self, "verify", "--fuzz-one="+funcName, "-n", strconv.Itoa(n), path)
+	fuzzChildArgs := append([]string{"verify", "-n", strconv.Itoa(n)}, extra...)
+	fuzzChildArgs = append(fuzzChildArgs, path)
+	cmd := exec.Command(self, fuzzChildArgs...)
+	cmd.Env = append(os.Environ(), "GASM_VERIFY_FUZZ_ONE="+funcName)
 	out, err := cmd.CombinedOutput()
 	if err != nil {
 		// Check if the child was killed by a signal.
@@ -1200,8 +1483,8 @@ func fuzzInSubprocess(path, funcName string, n int) string {
 			}
 		}
 		// Non-zero exit without a signal: the fuzz reported mismatches.
-		lines := strings.Split(strings.TrimSpace(string(out)), "\n")
-		for _, l := range lines {
+		lines := strings.SplitSeq(strings.TrimSpace(string(out)), "\n")
+		for l := range lines {
 			if strings.Contains(l, funcName) {
 				return strings.TrimSpace(l)
 			}
@@ -1209,8 +1492,8 @@ func fuzzInSubprocess(path, funcName string, n int) string {
 		return fmt.Sprintf("%s: FAIL (exit %v)", funcName, err)
 	}
 	// Success: extract the result line.
-	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
-	for _, l := range lines {
+	lines := strings.SplitSeq(strings.TrimSpace(string(out)), "\n")
+	for l := range lines {
 		if strings.Contains(l, funcName) {
 			return strings.TrimSpace(l)
 		}
@@ -1218,11 +1501,102 @@ func fuzzInSubprocess(path, funcName string, n int) string {
 	return strings.TrimSpace(string(out))
 }
 
-// cmdVerifyCall implements `gasm verify --call <func> [--buf spec] [--repeat n]`.
-// It invokes a single function with user-supplied buffers and prints the arg
-// block before and after the call, so the user can inspect return values and
-// any output written to the buffers.
-func cmdVerifyCall(k *verify.Kernel, path, funcName, bufSpec string, repeat int) int {
+// sweepInSubprocess runs the smoke/abi checks for a single function in a
+// child process.  If the child is killed by a signal (e.g. SIGSEGV from a
+// function that dereferences its zeroed or fuzzed arguments), it returns a
+// CRASH report instead of dying — the same isolation fuzzInSubprocess
+// provides for the fuzz sweep.
+func sweepInSubprocess(path, funcName string, smoke, abi bool, abiN int) (string, bool) {
+	self, err := os.Executable()
+	if err != nil {
+		return fmt.Sprintf("    smoke/abi: FAIL — cannot find self: %v", err), true
+	}
+	args := []string{"verify"}
+	if smoke {
+		args = append(args, "-smoke")
+	}
+	if abi {
+		args = append(args, "-abi", "-abi-n", strconv.Itoa(abiN))
+	}
+	args = append(args, path)
+	cmd := exec.Command(self, args...)
+	cmd.Env = append(os.Environ(), "GASM_VERIFY_SWEEP_ONE="+funcName)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			ws, ok := exitErr.Sys().(syscall.WaitStatus)
+			if ok && ws.Signaled() {
+				return fmt.Sprintf("    smoke/abi: CRASH (%v — the function faults on zeroed or fuzzed\n    arguments; verify it with -call and valid buffers)", ws.Signal()), true
+			}
+		}
+		// Non-zero exit without a signal: the checks themselves failed and
+		// the child already printed the diagnostic lines.
+		return sweepCheckLines(out), true
+	}
+	return sweepCheckLines(out), false
+}
+
+// sweepCheckLines extracts the check-result lines from child output,
+// dropping the child's own file/function banners (the parent prints those).
+func sweepCheckLines(out []byte) string {
+	var lines []string
+	for l := range strings.SplitSeq(string(out), "\n") {
+		t := strings.TrimSpace(l)
+		if strings.HasPrefix(t, "smoke:") || strings.HasPrefix(t, "abi:") {
+			lines = append(lines, "    "+t)
+		}
+	}
+	return strings.Join(lines, "\n")
+}
+
+// runSweepChecks performs the in-process smoke and ABI checks for one
+// function — the child half of sweepInSubprocess.
+func runSweepChecks(k *verify.Kernel, path, name string, fl asm.FuncLayout, smoke, abi bool, abiN int) ([]string, bool) {
+	var msgs []string
+	failed := false
+
+	if smoke {
+		args := make([]byte, fl.Args)
+		_, err := k.CallFunc(name, args)
+		if err != nil {
+			msgs = append(msgs, fmt.Sprintf("    smoke: FAIL — %v", err))
+			failed = true
+		} else {
+			msgs = append(msgs, "    smoke: OK")
+		}
+	}
+
+	if abi {
+		if src, err := readSource(path); err == nil {
+			result := k.FuzzFuncCheckedByName(name, src, abiN, int64(abiN))
+			if result.Mismatches > 0 {
+				msgs = append(msgs, fmt.Sprintf("    abi: %s", result))
+				failed = true
+			} else {
+				msgs = append(msgs, fmt.Sprintf("    abi: clean (%d varied inputs)", result.Matches))
+			}
+		} else {
+			args := make([]byte, fl.Args)
+			_, report, err := k.CallFuncChecked(name, args)
+			if err != nil {
+				msgs = append(msgs, fmt.Sprintf("    abi: FAIL — %v", err))
+				failed = true
+			} else if !report.OK() {
+				msgs = append(msgs, fmt.Sprintf("    abi: %s", report))
+				failed = true
+			} else {
+				msgs = append(msgs, "    abi: clean")
+			}
+		}
+	}
+	return msgs, failed
+}
+
+// cmdVerifyCall implements `gasm verify --call <func> [--buf spec] [--args spec] [--repeat n]`.
+// It invokes a single function with user-supplied buffers and scalar
+// arguments and prints the arg block before and after the call, so the user
+// can inspect return values and any output written to the buffers.
+func cmdVerifyCall(k *verify.Kernel, path, funcName, bufSpec, scalarSpec string, repeat int) int {
 	fl, err := k.Func(funcName)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
@@ -1260,6 +1634,16 @@ func cmdVerifyCall(k *verify.Kernel, path, funcName, bufSpec string, repeat int)
 	defer pool.Close()
 	args := pool.BuildArgs(layout, fl.Args)
 
+	scalars, err := verify.ParseScalarArgs(scalarSpec)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	if err := verify.ApplyScalarArgs(args, layout, scalars); err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+
 	fmt.Printf("%s: %d bytes, args=%d\n", funcName, fl.Size, fl.Args)
 	fmt.Printf("  signature: func %s(%s) %s\n", sig.Name, formatParams(sig.Params), formatResults(sig.Results))
 	if len(specs) > 0 {
@@ -1268,10 +1652,21 @@ func cmdVerifyCall(k *verify.Kernel, path, funcName, bufSpec string, repeat int)
 			fmt.Printf("    %s: %d bytes, pattern=%s\n", s.Name, s.Size, s.Pattern)
 		}
 	}
+	if len(scalars) > 0 {
+		names := make([]string, 0, len(scalars))
+		for n := range scalars {
+			names = append(names, n)
+		}
+		sort.Strings(names)
+		fmt.Printf("  scalars:\n")
+		for _, n := range names {
+			fmt.Printf("    %s = %d\n", n, scalars[n])
+		}
+	}
 	fmt.Printf("  args before: %s\n", hexDump(args))
 
 	rc := 0
-	for i := 0; i < repeat; i++ {
+	for i := range repeat {
 		out, err := k.CallFunc(funcName, args)
 		if err != nil {
 			fmt.Printf("  call %d: FAIL — %v\n", i+1, err)
@@ -1315,12 +1710,9 @@ func formatResults(rs []verify.Param) string {
 // hexDump returns a one-line hex dump of buf, truncated to 64 bytes.
 func hexDump(buf []byte) string {
 	const max = 64
-	n := len(buf)
-	if n > max {
-		n = max
-	}
+	n := min(len(buf), max)
 	var sb strings.Builder
-	for i := 0; i < n; i++ {
+	for i := range n {
 		if i > 0 {
 			sb.WriteByte(' ')
 		}

cmd/gasm/main_test.go

@@ -7,8 +7,11 @@ import (
 	"bytes"
 	"io"
 	"os"
+	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
+	"syscall"
 	"testing"
 )
 
@@ -237,3 +240,55 @@ func TestCmdArgErrors(t *testing.T) {
 		t.Errorf("cmdParse() code = %d, want 2", code)
 	}
 }
+
+// TestVerifySmokeCrashIsolation checks that a function faulting on its
+// zeroed smoke arguments is reported as CRASH by a child process instead of
+// killing `gasm verify` itself.
+func TestVerifySmokeCrashIsolation(t *testing.T) {
+	if testing.Short() {
+		t.Skip("builds the gasm binary")
+	}
+	if runtime.GOARCH != "amd64" {
+		t.Skip("amd64 JIT only")
+	}
+	bin := filepath.Join(t.TempDir(), "gasm")
+	if out, err := exec.Command("go", "build", "-o", bin, ".").CombinedOutput(); err != nil {
+		t.Fatalf("build gasm: %v\n%s", err, out)
+	}
+	src := filepath.Join(t.TempDir(), "crash_amd64.s")
+	kernel := "#include \"textflag.h\"\n" +
+		"\n" +
+		"// func Fault(x []byte) int\n" +
+		"TEXT ·Fault(SB), NOSPLIT, $0-32\n" +
+		"\tMOVQ\tx+0(FP), AX\n" +
+		"\tMOVQ\t(AX), AX // faults on the zeroed nil pointer\n" +
+		"\tMOVQ\tAX, ret+24(FP)\n" +
+		"\tRET\n"
+	if err := os.WriteFile(src, []byte(kernel), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command(bin, "verify", "-smoke", src)
+	out, err := cmd.CombinedOutput()
+	if err == nil {
+		t.Fatalf("expected a failure report, got success:\n%s", out)
+	}
+	if exitErr, ok := err.(*exec.ExitError); ok {
+		if ws, ok := exitErr.Sys().(syscall.WaitStatus); ok && ws.Signaled() {
+			t.Fatalf("verify died from %v — the crash was not isolated:\n%s", ws.Signal(), out)
+		}
+	}
+	if !strings.Contains(string(out), "CRASH") {
+		t.Errorf("output does not report CRASH:\n%s", out)
+	}
+}
+
+func TestSweepCheckLines(t *testing.T) {
+	out := []byte("crash_amd64.s: 1 functions JIT-loaded\n" +
+		"  Fault: 21 bytes, args=32, frame=0 NOSPLIT\n" +
+		"    smoke: OK\n" +
+		"    abi: clean (10 varied inputs)\n")
+	want := "    smoke: OK\n    abi: clean (10 varied inputs)"
+	if got := sweepCheckLines(out); got != want {
+		t.Errorf("sweepCheckLines = %q, want %q", got, want)
+	}
+}

cmd/gasm/scaffold.go

@@ -0,0 +1,345 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package main
+
+import (
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"strings"
+
+	gasmast "sourcedock.dev/petrbalvin/gasm-devkit/ast"
+	gasmparser "sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// cmdScaffold generates a differential test skeleton for every kernel in a
+// file: a Go test that seeds random states, drives both the assembly kernel
+// and a caller-provided portable reference, and compares the outputs
+// byte-for-byte.  The lesson this encodes: a pipeline-level fuzz cannot see
+// an unwired kernel — only a direct-call differential against the portable
+// specification can, so every kernel ships with one.
+//
+// The generated file follows two conventions the caller fills in:
+//   - the assembly symbols resolve because the test lives in the kernel's
+//     own package (the //go:noescape declarations reference them);
+//   - each kernel gets a <name>Portable Go function the author implements as
+//     the specification, and the test fails on the first divergent byte.
+func cmdScaffold(args []string) error {
+	fs := newCommand("scaffold", "gasm scaffold differential <file.s>", `
+Print a differential test skeleton for every // func signature in FILE.
+The 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.
+`)
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	rest := fs.Args()
+	// The first positional word is the scaffold style; "differential" is the
+	// only one today.
+	if len(rest) > 0 && rest[0] == "differential" {
+		rest = rest[1:]
+	}
+	if len(rest) != 1 {
+		return fmt.Errorf("usage: gasm scaffold differential <file.s>")
+	}
+	path := rest[0]
+	src, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+	f, errs := gasmparser.Parse(path, string(src))
+	if len(errs) > 0 {
+		return fmt.Errorf("parse: %v", errs[0])
+	}
+
+	var out strings.Builder
+	out.WriteString(headerComment)
+	out.WriteString("package " + packageName + "\n\n")
+	out.WriteString("import (\n\t\"bytes\"\n\t\"math/rand\"\n\t\"testing\"\n)\n\n")
+	out.WriteString(generatedHelpers)
+
+	kernels := 0
+	for _, d := range f.Decls {
+		txt, ok := d.(*gasmast.Text)
+		if !ok {
+			continue
+		}
+		params, results, ok := parseSig(txt.Doc)
+		if !ok || len(params) == 0 {
+			continue
+		}
+		kernels++
+		name := txt.Name.Name
+		fmt.Fprintf(&out, "// %sPortable is the specification %s is pinned against:\n", name, name)
+		fmt.Fprintf(&out, "// fill in a straightforward implementation of the same contract.\n")
+		fmt.Fprintf(&out, "func %sPortable(%s) (%s) {\n\tpanic(\"implement the portable specification\")\n}\n\n", name, paramDecl(params), resultDecl(results))
+
+		fmt.Fprintf(&out, "func Test%sDifferential(t *testing.T) {\n", strings.ToUpper(name[:1])+name[1:])
+		fmt.Fprintf(&out, "\trng := rand.New(rand.NewSource(1))\n")
+		fmt.Fprintf(&out, "\tfor range 1000 {\n")
+		// Seed two independent argument sets per iteration: the kernel runs
+		// on set A, the portable reference on set B, so in-place writes
+		// through pointer/slice arguments cannot contaminate the other side.
+		var sliceNames []string
+		seen := map[string]bool{}
+		aArgs := make([]string, 0, len(params))
+		bArgs := make([]string, 0, len(params))
+		for _, p := range params {
+			a, b, slices := genParamSeed(&out, p, seen)
+			aArgs = append(aArgs, a)
+			bArgs = append(bArgs, b)
+			sliceNames = append(sliceNames, slices...)
+		}
+		fmt.Fprintf(&out, "\t\tgot := %s(%s)\n", name, strings.Join(aArgs, ", "))
+		fmt.Fprintf(&out, "\t\twant := %sPortable(%s)\n", name, strings.Join(bArgs, ", "))
+		fmt.Fprintf(&out, "\t\tif !bytes.Equal(outputBytes(got), outputBytes(want)) {\n")
+		fmt.Fprintf(&out, "\t\t\tt.Fatalf(\"kernel diverges from the portable spec (seed 1, deterministic)\")\n")
+		fmt.Fprintf(&out, "\t\t}\n")
+		for _, s := range sliceNames {
+			fmt.Fprintf(&out, "\t\tif !bytes.Equal(outputBytes(%sA), outputBytes(%sB)) {\n", s, s)
+			fmt.Fprintf(&out, "\t\t\tt.Fatalf(\"kernel mutated %%q differently (seed 1, deterministic)\", %q)\n", s)
+			fmt.Fprintf(&out, "\t\t}\n")
+		}
+		fmt.Fprintf(&out, "\t}\n}\n\n")
+	}
+	if kernels == 0 {
+		return fmt.Errorf("%s: no // func signatures found; add one doc comment per kernel", path)
+	}
+	os.Stdout.WriteString(out.String())
+	return nil
+}
+
+const packageName = "yourpkg"
+
+const headerComment = `// Code generated by gasm scaffold differential; EDIT THE PANICS.
+// Each Test*Differential drives the assembly kernel and its portable
+// reference over the same random states and compares the outputs.
+// Place this file in the kernel's own package so the symbols resolve.
+
+`
+
+// sigParam is one parsed // func parameter.
+type sigParam struct {
+	Names []string
+	Type  string
+}
+
+type sigResult struct {
+	Names []string
+	Type  string
+}
+
+// parseSig parses the // func signature of a doc comment.
+func parseSig(doc string) ([]sigParam, []sigResult, bool) {
+	var line string
+	for l := range strings.SplitSeq(doc, "\n") {
+		if t := strings.TrimSpace(l); strings.HasPrefix(t, "func ") {
+			line = t
+			break
+		}
+	}
+	if line == "" {
+		return nil, nil, false
+	}
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "sig.go", "package p\n"+line+" {}\n", 0)
+	if err != nil {
+		return nil, nil, false
+	}
+	fd, ok := f.Decls[0].(*ast.FuncDecl)
+	if !ok || fd.Type == nil {
+		return nil, nil, false
+	}
+	var params []sigParam
+	for _, field := range fd.Type.Params.List {
+		typ := exprString(field.Type)
+		if len(field.Names) == 0 {
+			params = append(params, sigParam{Names: []string{""}, Type: typ})
+			continue
+		}
+		// Shared names (`L, result *byte`) expand to one entry per name:
+		// every name is a separate argument at the call site.
+		for _, n := range field.Names {
+			params = append(params, sigParam{Names: []string{n.Name}, Type: typ})
+		}
+	}
+	var results []sigResult
+	if fd.Type.Results != nil {
+		for _, field := range fd.Type.Results.List {
+			results = append(results, sigResult{Names: identNames(field.Names), Type: exprString(field.Type)})
+		}
+	}
+	return params, results, true
+}
+
+func identNames(idents []*ast.Ident) []string {
+	var out []string
+	for _, id := range idents {
+		out = append(out, id.Name)
+	}
+	return out
+}
+
+func exprString(e ast.Expr) string {
+	switch t := e.(type) {
+	case *ast.Ident:
+		return t.Name
+	case *ast.StarExpr:
+		return "*" + exprString(t.X)
+	case *ast.SelectorExpr:
+		return exprString(t.X) + "." + t.Sel.Name
+	case *ast.ArrayType:
+		if t.Len == nil {
+			return "[]" + exprString(t.Elt)
+		}
+		return "[N]" + exprString(t.Elt)
+	}
+	return "interface{}"
+}
+
+// paramDecl renders a parameter list for the portable reference signature.
+func paramDecl(params []sigParam) string {
+	var parts []string
+	for _, p := range params {
+		if len(p.Names) == 0 {
+			parts = append(parts, p.Type)
+			continue
+		}
+		for _, n := range p.Names {
+			parts = append(parts, n+" "+p.Type)
+		}
+	}
+	return strings.Join(parts, ", ")
+}
+
+// resultDecl renders a result list; unnamed results keep bare types.
+func resultDecl(results []sigResult) string {
+	if len(results) == 0 {
+		return ""
+	}
+	var parts []string
+	for _, r := range results {
+		parts = append(parts, r.Type)
+	}
+	return strings.Join(parts, ", ")
+}
+
+// genParamSeed emits the seeding statements for one parameter and returns
+// the kernel-side (A) and reference-side (B) argument expressions, plus the
+// names of any slice variables written in place (compared after the calls).
+func genParamSeed(out *strings.Builder, p sigParam, seen map[string]bool) (aArg, bArg string, slices []string) {
+	name := p.Names[0]
+	elem := strings.TrimPrefix(p.Type, "*")
+	isSlice := strings.HasPrefix(p.Type, "[]")
+	if isSlice {
+		elem = strings.TrimPrefix(p.Type, "[]")
+	}
+	switch {
+	case isSlice:
+		v := uniqueName(seen, name)
+		fmt.Fprintf(out, "\t\t%sA := make([]%s, 1+rng.Intn(512))\n", v, elem)
+		fmt.Fprintf(out, "\t\t%sB := make([]%s, len(%sA))\n", v, elem, v)
+		fmt.Fprintf(out, "\t\tfor i := range %sA {\n", v)
+		fmt.Fprintf(out, "\t\t\tw%s := %s(rng.Intn(256))\n", v, goCast(elem))
+		fmt.Fprintf(out, "\t\t\t%sA[i] = w%s\n", v, v)
+		fmt.Fprintf(out, "\t\t\t%sB[i] = w%s\n", v, v)
+		fmt.Fprintf(out, "\t\t}\n")
+		return v, v, []string{v}
+	case strings.HasPrefix(p.Type, "*"):
+		v := uniqueName(seen, name)
+		fmt.Fprintf(out, "\t\tvar %sA, %sB %s\n", v, v, elem)
+		fmt.Fprintf(out, "\t\tw%s := %s(rng.Intn(256))\n", v, goCast(elem))
+		fmt.Fprintf(out, "\t\t%sA = w%s\n", v, v)
+		fmt.Fprintf(out, "\t\t%sB = w%s\n", v, v)
+		return "&" + v + "A", "&" + v + "B", nil
+	default:
+		v := uniqueName(seen, name)
+		fmt.Fprintf(out, "\t\tw%s := %s(rng.Intn(512))\n", v, goCast(""))
+		fmt.Fprintf(out, "\t\tvar %sA, %sB %s = w%s, w%s\n", v, v, p.Type, v, v)
+		return v + "A", v + "B", nil
+	}
+}
+
+// uniqueName de-duplicates seeded variable names when one kernel takes two
+// parameters of the same name (impossible in Go) or a name repeats across
+// kernels in one file.
+func uniqueName(seen map[string]bool, base string) string {
+	if base == "" {
+		base = "arg"
+	}
+	if !seen[base] {
+		seen[base] = true
+		return base
+	}
+	for i := 2; ; i++ {
+		cand := fmt.Sprintf("%s%d", base, i)
+		if !seen[cand] {
+			seen[cand] = true
+			return cand
+		}
+	}
+}
+
+// goCast returns the conversion turning rng.Intn into the element type.
+func goCast(elem string) string {
+	switch elem {
+	case "byte", "uint8":
+		return "byte"
+	case "int8":
+		return "int8"
+	case "uint16":
+		return "uint16"
+	case "int16":
+		return "int16"
+	case "uint32":
+		return "uint32"
+	case "int32":
+		return "int32"
+	case "uint64":
+		return "uint64"
+	default:
+		return "int"
+	}
+}
+
+// generatedHelpers is emitted into every generated test file: outputBytes
+// narrows returned slices and scalars to a byte form for the comparison.
+// It lives in the template, not in this binary, because only the generated
+// file ever calls it.
+const generatedHelpers = `// outputBytes narrows a returned slice or scalar to bytes for the
+// comparison; extend the switch when a kernel returns a wider type.
+func outputBytes(v any) []byte {
+	switch t := v.(type) {
+	case []byte:
+		return t
+	case []int32:
+		b := make([]byte, 4*len(t))
+		for i, x := range t {
+			b[i*4] = byte(x)
+			b[i*4+1] = byte(x >> 8)
+			b[i*4+2] = byte(x >> 16)
+			b[i*4+3] = byte(x >> 24)
+		}
+		return b
+	case []uint16:
+		b := make([]byte, 2*len(t))
+		for i, x := range t {
+			b[i*2] = byte(x)
+			b[i*2+1] = byte(x >> 8)
+		}
+		return b
+	case int:
+		b := make([]byte, 8)
+		for i := range 8 {
+			b[i] = byte(uint64(t) >> (8 * i))
+		}
+		return b
+	default:
+		return nil
+	}
+}
+`

debug/breakpoint.go

@@ -1,8 +1,12 @@
 // Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
 // SPDX-License-Identifier: BSD-3-Clause
 
+//go:build linux
+
 package debug
 
+import "strings"
+
 import "fmt"
 
 // Breakpoint is one INT3 breakpoint in the debuggee.
@@ -15,68 +19,54 @@ type Breakpoint struct {
 	hits    int
 }
 
-// Condition is a simple register-comparison condition evaluated when a
-// breakpoint is hit.  Format: <reg> <op> <value>.
+// Condition is a register-comparison condition evaluated when a breakpoint
+// is hit.  Supports three forms:
+//   - register vs constant:  <reg> <op> <value>
+//   - register vs register:  <reg> <op> <reg2>
+//   - register vs memory:    <reg> <op> *<addr>
 type Condition struct {
-	Reg   string // register name (rax, rbx, rip, rsp, ...)
-	Op    string // comparison operator: ==, !=, <, >, <=, >=
-	Value uint64
+	Reg     string // register name (rax, rbx, rip, rsp, ...)
+	Op      string // comparison operator: ==, !=, <, >, <=, >=
+	Value   uint64 // constant value (when Reg2 == "" and MemAddr == 0)
+	Reg2    string // second register name (for register-register comparison)
+	MemAddr uint64 // memory address (for register-memory comparison, prefixed with *)
 }
 
 // Eval checks the condition against the current registers.
 func (c *Condition) Eval(regs *Regs) bool {
-	var actual uint64
-	switch c.Reg {
-	case "rax", "eax", "ax", "al":
-		actual = regs.RAX
-	case "rbx", "ebx", "bx", "bl":
-		actual = regs.RBX
-	case "rcx", "ecx", "cx", "cl":
-		actual = regs.RCX
-	case "rdx", "edx", "dx", "dl":
-		actual = regs.RDX
-	case "rsi", "esi", "si":
-		actual = regs.RSI
-	case "rdi", "edi", "di":
-		actual = regs.RDI
-	case "rbp", "ebp", "bp":
-		actual = regs.RBP
-	case "rsp", "esp", "sp":
-		actual = regs.RSP
-	case "r8":
-		actual = regs.R8
-	case "r9":
-		actual = regs.R9
-	case "r10":
-		actual = regs.R10
-	case "r11":
-		actual = regs.R11
-	case "r12":
-		actual = regs.R12
-	case "r13":
-		actual = regs.R13
-	case "r14":
-		actual = regs.R14
-	case "r15":
-		actual = regs.R15
-	case "rip", "eip":
-		actual = regs.RIP
-	default:
+	actual, ok := regs.RegValue(c.Reg)
+	if !ok {
 		return true // unknown register — don't block
 	}
+	var expected uint64
+	switch {
+	case c.Reg2 != "":
+		// Register-register comparison.
+		v, ok := regs.RegValue(c.Reg2)
+		if !ok {
+			return true
+		}
+		expected = v
+	case c.MemAddr != 0:
+		// Register-memory comparison — requires a Session, not available here.
+		// Fall back to treating as constant (the caller should resolve).
+		expected = c.Value
+	default:
+		expected = c.Value
+	}
 	switch c.Op {
 	case "==", "=":
-		return actual == c.Value
+		return actual == expected
 	case "!=":
-		return actual != c.Value
+		return actual != expected
 	case "<":
-		return actual < c.Value
+		return actual < expected
 	case ">":
-		return actual > c.Value
+		return actual > expected
 	case "<=":
-		return actual <= c.Value
+		return actual <= expected
 	case ">=":
-		return actual >= c.Value
+		return actual >= expected
 	default:
 		return true
 	}
@@ -106,14 +96,18 @@ func (bm *Breakpoints) SetWithCond(addr uint64, label string, cond *Condition) (
 		bp.Cond = cond
 		return bp, nil
 	}
-	// Read the original byte.
+	// Read the original bytes.
 	word, err := bm.t.Peek(addr)
 	if err != nil {
 		return nil, err
 	}
 	orig := byte(word)
-	// Patch with INT3 (0xCC), preserving the rest of the word.
-	patched := (word &^ 0xFF) | 0xCC
+	// Patch with the breakpoint instruction, preserving the rest of the word.
+	mask := uint64(0)
+	for range breakpointInsn {
+		mask = (mask << 8) | 0xFF
+	}
+	patched := (word &^ mask) | breakpointWord(breakpointInsn)
 	if err := bm.t.Poke(addr, patched); err != nil {
 		return nil, err
 	}
@@ -122,17 +116,12 @@ func (bm *Breakpoints) SetWithCond(addr uint64, label string, cond *Condition) (
 	return bp, nil
 }
 
-// Hits returns the number of times the breakpoint has been hit.
-func (bp *Breakpoint) Hits() int {
-	return bp.hits
-}
-
 // Info returns a formatted list of all breakpoints.
 func (bm *Breakpoints) Info() string {
 	if len(bm.bps) == 0 {
 		return "no breakpoints set\n"
 	}
-	result := ""
+	var result strings.Builder
 	i := 0
 	for _, bp := range bm.bps {
 		i++
@@ -148,9 +137,9 @@ func (bm *Breakpoints) Info() string {
 		if bp.Cond != nil {
 			cond = fmt.Sprintf(" if %s %s %#x", bp.Cond.Reg, bp.Cond.Op, bp.Cond.Value)
 		}
-		result += fmt.Sprintf("  %d: %s at %#x [%s, %d hits]%s\n", i, label, bp.Addr, status, bp.hits, cond)
+		result.WriteString(fmt.Sprintf("  %d: %s at %#x [%s, %d hits]%s\n", i, label, bp.Addr, status, bp.hits, cond))
 	}
-	return result
+	return result.String()
 }
 
 // Clear removes the breakpoint at addr, restoring the original byte.
@@ -196,12 +185,15 @@ func (bm *Breakpoints) All() []*Breakpoint {
 }
 
 // HandleTrap is called after the debuggee stops on SIGTRAP.  It checks
-// whether the trap was caused by one of our breakpoints (RIP-1 matches
-// a breakpoint address), restores the original byte, rewinds RIP, and
+// whether the trap was caused by one of our breakpoints (PC-adjust matches
+// a breakpoint address), restores the original byte, rewinds PC, and
 // returns the breakpoint that was hit (or nil if it was a single-step).
+// Hits returns how many times the breakpoint has been hit.
+func (bp *Breakpoint) Hits() int { return bp.hits }
+
 func (bm *Breakpoints) HandleTrap(regs *Regs) *Breakpoint {
-	// After INT3, RIP points to the byte AFTER the 0xCC.
-	trapAddr := regs.RIP - 1
+	// After a breakpoint trap, PC points past the breakpoint instruction.
+	trapAddr := regs.GetPC() - uint64(breakpointPCAdjust)
 	bp, ok := bm.bps[trapAddr]
 	if !ok || !bp.Enabled {
 		return nil // single-step trap or unknown
@@ -225,8 +217,8 @@ func (bm *Breakpoints) HandleTrap(regs *Regs) *Breakpoint {
 		restored := (word &^ 0xFF) | uint64(bp.Orig)
 		bm.t.Poke(trapAddr, restored)
 	}
-	// Rewind RIP to re-execute the original instruction.
-	regs.RIP = trapAddr
+	// Rewind PC to re-execute the original instruction.
+	regs.SetPC(trapAddr)
 	bm.t.SetRegs(regs)
 	return bp
 }
@@ -243,6 +235,19 @@ func (bm *Breakpoints) Reinsert(addr uint64) error {
 	if err != nil {
 		return err
 	}
-	patched := (word &^ 0xFF) | 0xCC
+	mask := uint64(0)
+	for range breakpointInsn {
+		mask = (mask << 8) | 0xFF
+	}
+	patched := (word &^ mask) | breakpointWord(breakpointInsn)
 	return bm.t.Poke(addr, patched)
 }
+
+// breakpointWord converts the breakpoint instruction bytes to a uint64.
+func breakpointWord(insn []byte) uint64 {
+	var w uint64
+	for i, b := range insn {
+		w |= uint64(b) << (i * 8)
+	}
+	return w
+}

debug/debug_test.go

@@ -1,6 +1,8 @@
 // Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
 // SPDX-License-Identifier: BSD-3-Clause
 
+//go:build linux && amd64
+
 package debug
 
 import (
@@ -273,10 +275,11 @@ func TestBreakpointInfo(t *testing.T) {
 }
 
 func TestWatchpointSlotTracking(t *testing.T) {
+	wpSlots = [4]bool{} // reset
 	s := &Session{}
 
 	// All four slots are free initially.
-	for i := 0; i < 4; i++ {
+	for i := range 4 {
 		if s.IsWatchpointSlotUsed(i) {
 			t.Errorf("slot %d should be free initially", i)
 		}
@@ -286,8 +289,8 @@ func TestWatchpointSlotTracking(t *testing.T) {
 	}
 
 	// Manually mark slots 0 and 2 as used (simulating successful SetWatchpoint).
-	s.wpSlots[0] = true
-	s.wpSlots[2] = true
+	wpSlots[0] = true
+	wpSlots[2] = true
 
 	if !s.IsWatchpointSlotUsed(0) {
 		t.Error("slot 0 should be in use")
@@ -314,8 +317,8 @@ func TestWatchpointSlotTracking(t *testing.T) {
 	}
 
 	// Mark all slots used: FindFreeWatchpointSlot returns -1.
-	for i := 0; i < 4; i++ {
-		s.wpSlots[i] = true
+	for i := range 4 {
+		wpSlots[i] = true
 	}
 	if got := s.FindFreeWatchpointSlot(); got != -1 {
 		t.Errorf("FindFreeWatchpointSlot() with all slots used = %d, want -1", got)

debug/disasm_linux_amd64.go

@@ -7,6 +7,7 @@ package debug
 
 import (
 	"fmt"
+	"strings"
 
 	"golang.org/x/arch/x86/x86asm"
 )
@@ -34,19 +35,19 @@ func (s *Session) Disassemble(addr uint64) (string, int, error) {
 // DisassembleN decodes up to n instructions starting at addr and returns
 // them as a formatted string with addresses and byte offsets.
 func (s *Session) DisassembleN(addr uint64, n int) string {
-	var result string
+	var result strings.Builder
 	pc := addr
-	for i := 0; i < n; i++ {
+	for range n {
 		text, length, err := s.Disassemble(pc)
 		if err != nil {
-			result += fmt.Sprintf("  %#08x: <error: %v>\n", pc, err)
+			result.WriteString(fmt.Sprintf("  %#08x: <error: %v>\n", pc, err))
 			break
 		}
-		result += fmt.Sprintf("  %#08x: %s\n", pc, text)
+		result.WriteString(fmt.Sprintf("  %#08x: %s\n", pc, text))
 		if length == 0 {
 			length = 1
 		}
 		pc += uint64(length)
 	}
-	return result
+	return result.String()
 }

debug/disasm_linux_arm64.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+import (
+	"fmt"
+
+	"golang.org/x/arch/arm64/arm64asm"
+)
+
+// Disassemble decodes the instruction at the given address in the debuggee's
+// memory and returns its text representation and length in bytes.
+func (s *Session) Disassemble(addr uint64) (string, int, error) {
+	mem, err := s.ReadMemory(addr, 4)
+	if err != nil {
+		return "", 0, err
+	}
+	inst, err := arm64asm.Decode(mem)
+	if err != nil {
+		return "???", 4, nil
+	}
+	text := arm64asm.GoSyntax(inst, addr, nil, nil)
+	return text, 4, nil
+}
+
+// DisassembleN decodes up to n instructions starting at addr.
+func (s *Session) DisassembleN(addr uint64, n int) string {
+	var result string
+	pc := addr
+	for range n {
+		text, length, err := s.Disassemble(pc)
+		if err != nil {
+			result += fmt.Sprintf("  %#08x: <error: %v>\n", pc, err)
+			break
+		}
+		result += fmt.Sprintf("  %#08x: %s\n", pc, text)
+		if length == 0 {
+			length = 4
+		}
+		pc += uint64(length)
+	}
+	return result
+}

debug/disasm_linux_loong64.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+import (
+	"fmt"
+
+	"golang.org/x/arch/loong64/loong64asm"
+)
+
+// Disassemble decodes the instruction at the given address in the debuggee's
+// memory and returns its text representation and length in bytes.
+func (s *Session) Disassemble(addr uint64) (string, int, error) {
+	mem, err := s.ReadMemory(addr, 4)
+	if err != nil {
+		return "", 0, err
+	}
+	inst, err := loong64asm.Decode(mem)
+	if err != nil {
+		return "???", 4, nil
+	}
+	text := loong64asm.GoSyntax(inst, addr, nil)
+	return text, 4, nil
+}
+
+// DisassembleN decodes up to n instructions starting at addr.
+func (s *Session) DisassembleN(addr uint64, n int) string {
+	var result string
+	pc := addr
+	for range n {
+		text, length, err := s.Disassemble(pc)
+		if err != nil {
+			result += fmt.Sprintf("  %#08x: <error: %v>\n", pc, err)
+			break
+		}
+		result += fmt.Sprintf("  %#08x: %s\n", pc, text)
+		if length == 0 {
+			length = 4
+		}
+		pc += uint64(length)
+	}
+	return result
+}

debug/disasm_linux_riscv64.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+import (
+	"fmt"
+
+	"golang.org/x/arch/riscv64/riscv64asm"
+)
+
+// Disassemble decodes the instruction at the given address in the debuggee's
+// memory and returns its text representation and length in bytes.
+func (s *Session) Disassemble(addr uint64) (string, int, error) {
+	mem, err := s.ReadMemory(addr, 4)
+	if err != nil {
+		return "", 0, err
+	}
+	inst, err := riscv64asm.Decode(mem)
+	if err != nil {
+		return "???", 4, nil
+	}
+	text := riscv64asm.GoSyntax(inst, addr, nil, nil)
+	return text, inst.Len, nil
+}
+
+// DisassembleN decodes up to n instructions starting at addr.
+func (s *Session) DisassembleN(addr uint64, n int) string {
+	var result string
+	pc := addr
+	for range n {
+		text, length, err := s.Disassemble(pc)
+		if err != nil {
+			result += fmt.Sprintf("  %#08x: <error: %v>\n", pc, err)
+			break
+		}
+		result += fmt.Sprintf("  %#08x: %s\n", pc, text)
+		if length == 0 {
+			length = 4
+		}
+		pc += uint64(length)
+	}
+	return result
+}

debug/display_linux_amd64.go

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import "fmt"
+
+func printRegs(regs *Regs, codeBase, funcOff uint64) {
+	fmt.Printf("  RIP = %#016x  (func+%#x)\n", regs.RIP, regs.RIP-codeBase-funcOff)
+	fmt.Printf("  RSP = %#016x  RBP = %#016x\n", regs.RSP, regs.RBP)
+	fmt.Printf("  RAX = %#016x  RBX = %#016x\n", regs.RAX, regs.RBX)
+	fmt.Printf("  RCX = %#016x  RDX = %#016x\n", regs.RCX, regs.RDX)
+	fmt.Printf("  RSI = %#016x  RDI = %#016x\n", regs.RSI, regs.RDI)
+	fmt.Printf("  R8  = %#016x  R9  = %#016x\n", regs.R8, regs.R9)
+	fmt.Printf("  R10 = %#016x  R11 = %#016x\n", regs.R10, regs.R11)
+	fmt.Printf("  R12 = %#016x  R13 = %#016x\n", regs.R12, regs.R13)
+	fmt.Printf("  R14 = %#016x  R15 = %#016x\n", regs.R14, regs.R15)
+	fmt.Printf("  RFLAGS = %#x  [%s]\n", regs.RFLAGS, decodeRflags(regs.RFLAGS))
+}
+
+func printVectorRegs(v *VectorRegs) {
+	fmt.Println("\n  Vector registers (YMM):")
+	for i := 0; i < 16; i += 2 {
+		fmt.Printf("  YMM%-2d = ", i)
+		printYMM(v.YMM[i][:])
+		fmt.Printf("  YMM%-2d = ", i+1)
+		printYMM(v.YMM[i+1][:])
+		fmt.Println()
+	}
+}
+
+func printYMM(b []byte) {
+	for j := 0; j < 32; j += 4 {
+		v := uint32(b[j]) | uint32(b[j+1])<<8 | uint32(b[j+2])<<16 | uint32(b[j+3])<<24
+		fmt.Printf("%08x ", v)
+	}
+}
+
+func decodeRflags(f uint64) string {
+	var flags string
+	if f&1 != 0 {
+		flags += "CF "
+	}
+	if f&(1<<2) != 0 {
+		flags += "PF "
+	}
+	if f&(1<<4) != 0 {
+		flags += "AF "
+	}
+	if f&(1<<6) != 0 {
+		flags += "ZF "
+	}
+	if f&(1<<7) != 0 {
+		flags += "SF "
+	}
+	if f&(1<<8) != 0 {
+		flags += "TF "
+	}
+	if f&(1<<9) != 0 {
+		flags += "IF "
+	}
+	if f&(1<<10) != 0 {
+		flags += "DF "
+	}
+	if f&(1<<11) != 0 {
+		flags += "OF "
+	}
+	if flags == "" {
+		return "none"
+	}
+	return flags[:len(flags)-1]
+}
+
+// archReturnAddr reads the return address from the stack (amd64 ABI0 convention).
+func archReturnAddr(s *Session, regs *Regs) (uint64, error) {
+	return s.Peek(regs.GetSP())
+}
+
+// archSPLabel returns the SP register name for display.
+func archSPLabel() string { return "RSP" }

debug/display_linux_arm64.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+import "fmt"
+
+func printRegs(regs *Regs, codeBase, funcOff uint64) {
+	fmt.Printf("  PC  = %#016x  (func+%#x)\n", regs.PC, regs.PC-codeBase-funcOff)
+	fmt.Printf("  SP  = %#016x  FP  = %#016x\n", regs.SP, regs.X29)
+	fmt.Printf("  LR  = %#016x\n", regs.X30)
+	fmt.Printf("  X0  = %#016x  X1  = %#016x\n", regs.X0, regs.X1)
+	fmt.Printf("  X2  = %#016x  X3  = %#016x\n", regs.X2, regs.X3)
+	fmt.Printf("  X4  = %#016x  X5  = %#016x\n", regs.X4, regs.X5)
+	fmt.Printf("  X6  = %#016x  X7  = %#016x\n", regs.X6, regs.X7)
+	fmt.Printf("  X8  = %#016x  X9  = %#016x\n", regs.X8, regs.X9)
+	fmt.Printf("  X10 = %#016x  X11 = %#016x\n", regs.X10, regs.X11)
+	fmt.Printf("  X12 = %#016x  X13 = %#016x\n", regs.X12, regs.X13)
+	fmt.Printf("  X14 = %#016x  X15 = %#016x\n", regs.X14, regs.X15)
+	fmt.Printf("  X16 = %#016x  X17 = %#016x\n", regs.X16, regs.X17)
+	fmt.Printf("  X18 = %#016x  X19 = %#016x\n", regs.X18, regs.X19)
+	fmt.Printf("  X20 = %#016x  X21 = %#016x\n", regs.X20, regs.X21)
+	fmt.Printf("  X22 = %#016x  X23 = %#016x\n", regs.X22, regs.X23)
+	fmt.Printf("  X24 = %#016x  X25 = %#016x\n", regs.X24, regs.X25)
+	fmt.Printf("  X26 = %#016x  X27 = %#016x\n", regs.X26, regs.X27)
+	fmt.Printf("  X28 = %#016x  PSTATE = %#x\n", regs.X28, regs.PSTATE)
+}
+
+func printVectorRegs(v *VectorRegs) {
+	fmt.Println("\n  Vector registers (V0-V31):")
+	for i := 0; i < 32; i += 2 {
+		fmt.Printf("  V%-2d  = %016x%016x\n", i, v.V[i][8], v.V[i][0])
+		fmt.Printf("  V%-2d  = %016x%016x\n", i+1, v.V[i+1][8], v.V[i+1][0])
+	}
+}
+
+// archReturnAddr reads the return address from LR (arm64 convention).
+func archReturnAddr(s *Session, regs *Regs) (uint64, error) {
+	return regs.X30, nil
+}
+
+// archSPLabel returns the SP register name for display.
+func archSPLabel() string { return "SP" }

debug/display_linux_loong64.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+import "fmt"
+
+func printRegs(regs *Regs, codeBase, funcOff uint64) {
+	fmt.Printf("  PC  = %#016x  (func+%#x)\n", regs.R31, regs.R31-codeBase-funcOff)
+	fmt.Printf("  SP  = %#016x  FP  = %#016x\n", regs.R3, regs.R21)
+	fmt.Printf("  RA  = %#016x\n", regs.R1)
+	fmt.Printf("  A0  = %#016x  A1  = %#016x\n", regs.R4, regs.R5)
+	fmt.Printf("  A2  = %#016x  A3  = %#016x\n", regs.R6, regs.R7)
+	fmt.Printf("  A4  = %#016x  A5  = %#016x\n", regs.R8, regs.R9)
+	fmt.Printf("  A6  = %#016x  A7  = %#016x\n", regs.R10, regs.R11)
+	fmt.Printf("  T0  = %#016x  T1  = %#016x\n", regs.R12, regs.R13)
+	fmt.Printf("  T2  = %#016x  T3  = %#016x\n", regs.R14, regs.R15)
+	fmt.Printf("  T4  = %#016x  T5  = %#016x\n", regs.R16, regs.R17)
+	fmt.Printf("  T6  = %#016x  T7  = %#016x\n", regs.R18, regs.R19)
+	fmt.Printf("  T8  = %#016x\n", regs.R20)
+	fmt.Printf("  S0  = %#016x  S1  = %#016x\n", regs.R22, regs.R23)
+	fmt.Printf("  S2  = %#016x  S3  = %#016x\n", regs.R24, regs.R25)
+	fmt.Printf("  S4  = %#016x  S5  = %#016x\n", regs.R26, regs.R27)
+	fmt.Printf("  S6  = %#016x  S7  = %#016x\n", regs.R28, regs.R29)
+	fmt.Printf("  S8  = %#016x\n", regs.R30)
+}
+
+func printVectorRegs(v *VectorRegs) {
+	fmt.Println("\n  FP registers (F0-F31):")
+	for i := 0; i < 32; i += 2 {
+		fmt.Printf("  F%-2d  = %#018x  F%-2d  = %#018x\n", i, v.F[i], i+1, v.F[i+1])
+	}
+	fmt.Printf("  FCC  = %#016x  FCSR = %#x\n", v.FCC, v.FCSR)
+}
+
+// archReturnAddr reads the return address from RA (loong64 convention).
+func archReturnAddr(s *Session, regs *Regs) (uint64, error) {
+	return regs.R1, nil
+}
+
+// archSPLabel returns the SP register name for display.
+func archSPLabel() string { return "SP" }

debug/display_linux_riscv64.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+import "fmt"
+
+func printRegs(regs *Regs, codeBase, funcOff uint64) {
+	fmt.Printf("  PC  = %#016x  (func+%#x)\n", regs.PC, regs.PC-codeBase-funcOff)
+	fmt.Printf("  SP  = %#016x  FP  = %#016x\n", regs.Sp, regs.S0)
+	fmt.Printf("  RA  = %#016x\n", regs.Ra)
+	fmt.Printf("  A0  = %#016x  A1  = %#016x\n", regs.A0, regs.A1)
+	fmt.Printf("  A2  = %#016x  A3  = %#016x\n", regs.A2, regs.A3)
+	fmt.Printf("  A4  = %#016x  A5  = %#016x\n", regs.A4, regs.A5)
+	fmt.Printf("  A6  = %#016x  A7  = %#016x\n", regs.A6, regs.A7)
+	fmt.Printf("  T0  = %#016x  T1  = %#016x\n", regs.T0, regs.T1)
+	fmt.Printf("  T2  = %#016x  T3  = %#016x\n", regs.T2, regs.T3)
+	fmt.Printf("  T4  = %#016x  T5  = %#016x\n", regs.T4, regs.T5)
+	fmt.Printf("  T6  = %#016x\n", regs.T6)
+	fmt.Printf("  S1  = %#016x  S2  = %#016x\n", regs.S1, regs.S2)
+	fmt.Printf("  S3  = %#016x  S4  = %#016x\n", regs.S3, regs.S4)
+	fmt.Printf("  S5  = %#016x  S6  = %#016x\n", regs.S5, regs.S6)
+	fmt.Printf("  S7  = %#016x  S8  = %#016x\n", regs.S7, regs.S8)
+	fmt.Printf("  S9  = %#016x  S10 = %#016x\n", regs.S9, regs.S10)
+	fmt.Printf("  S11 = %#016x\n", regs.S11)
+}
+
+func printVectorRegs(v *VectorRegs) {
+	fmt.Println("\n  FP registers (F0-F31):")
+	for i := 0; i < 32; i += 2 {
+		fmt.Printf("  F%-2d  = %#018x  F%-2d  = %#018x\n", i, v.F[i], i+1, v.F[i+1])
+	}
+	fmt.Printf("  FCSR = %#x\n", v.FCSR)
+}
+
+// archReturnAddr reads the return address from RA (riscv64 convention).
+func archReturnAddr(s *Session, regs *Regs) (uint64, error) {
+	return regs.Ra, nil
+}
+
+// archSPLabel returns the SP register name for display.
+func archSPLabel() string { return "SP" }

debug/ptrace_integration_test.go

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+// buildGasm produces the gasm binary the debugger spawns as its debuggee.
+func buildGasm(t *testing.T) string {
+	t.Helper()
+	if p := os.Getenv("GASM_TEST_BIN"); p != "" {
+		return p
+	}
+	bin := filepath.Join(t.TempDir(), "gasm")
+	cmd := exec.Command("go", "build", "-o", bin, "sourcedock.dev/petrbalvin/gasm-devkit/cmd/gasm")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("build gasm: %v: %s", err, out)
+	}
+	return bin
+}
+
+// TestLaunchAndBreakpoint drives a real ptrace session end to end: launch the
+// debuggee, break on the first instruction of the function and expect a
+// breakpoint trap instead of a clean exit.
+func TestLaunchAndBreakpoint(t *testing.T) {
+	if runtime.GOARCH != "amd64" {
+		t.Skip("runs only on amd64 hosts")
+	}
+	// The tracer is the OS thread that forked the debuggee (PTRACE_TRACEME
+	// binds the relation to that thread); every ptrace request must come
+	// from the same thread, so pin the test goroutine to one thread.
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+	bin := buildGasm(t)
+
+	const kernelPath = "../testdata/verify/basic_amd64.s"
+	k, err := verify.Load(kernelPath)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	t.Cleanup(k.Close)
+	fl, err := k.Func("wideCopy")
+	if err != nil {
+		t.Fatalf("Func: %v", err)
+	}
+
+	sess, err := Launch(bin, kernelPath, "wideCopy", make([]byte, fl.Args))
+	if err != nil {
+		t.Fatalf("Launch: %v", err)
+	}
+	t.Cleanup(sess.Kill)
+
+	bm := NewBreakpoints(sess)
+	entry := sess.CodeBase() + uint64(fl.Offset)
+	if _, err := bm.Set(entry, "entry"); err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+
+	// The INT3 must be visible in the debuggee's memory.
+	word, err := sess.Peek(entry)
+	if err != nil {
+		t.Fatalf("Peek: %v", err)
+	}
+	if b := word & 0xFF; b != 0xCC {
+		t.Fatalf("int3 not patched: first byte %#02x at %#x", b, entry)
+	}
+
+	// The debuggee raises a second SIGSTOP after the launch barrier (the
+	// child's RunTarget marks its entry), so like the REPL and the cover
+	// mode the test keeps resuming until the breakpoint trap arrives.
+	for range 10 {
+		if err := sess.Continue(); err != nil {
+			st, _ := os.ReadFile(fmt.Sprintf("/proc/%d/stat", sess.Pid()))
+			status, _ := os.ReadFile(fmt.Sprintf("/proc/%d/status", sess.Pid()))
+			t.Fatalf("Continue: %v\nstate: %s\n%s", err, fieldName(st), statusDump(status))
+		}
+		if sess.Exited() {
+			t.Fatal("debuggee exited instead of trapping on the breakpoint")
+		}
+		regs, err := sess.GetRegs()
+		if err != nil {
+			t.Fatalf("GetRegs: %v", err)
+		}
+		if bp := bm.HandleTrap(&regs); bp != nil {
+			if bp.Addr != entry {
+				t.Fatalf("trap at %#x, want %#x", bp.Addr, entry)
+			}
+			return // trap on the entry breakpoint: the whole flow works
+		}
+	}
+	t.Fatal("no breakpoint trap after 10 resumes")
+}
+
+func fieldName(stat []byte) string {
+	f := strings.Split(string(stat), " ")
+	if len(f) > 2 {
+		return "state=" + f[2]
+	}
+	return "no stat"
+}
+
+func statusDump(b []byte) string {
+	var out []string
+	for l := range strings.SplitSeq(string(b), "\n") {
+		if strings.HasPrefix(l, "State") || strings.HasPrefix(l, "Pid") ||
+			strings.HasPrefix(l, "PPid") || strings.HasPrefix(l, "TracerPid") ||
+			strings.HasPrefix(l, "Threads") || strings.HasPrefix(l, "SigPnd") ||
+			strings.HasPrefix(l, "SigBlk") || strings.HasPrefix(l, "SigIgn") {
+			out = append(out, l)
+		}
+	}
+	return strings.Join(out, "\n")
+}

debug/ptrace_linux.go

@@ -0,0 +1,328 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux
+
+package debug
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Session is a ptrace debugging session controlling one debuggee process.
+type Session struct {
+	pid      int
+	cmd      *exec.Cmd
+	stopped  bool
+	exited   bool
+	codeBase uint64 // base address of the JIT code in the debuggee
+}
+
+// Launch starts the debuggee subprocess (gasm debug --target ...) and
+// attaches to it via ptrace.
+func Launch(gasmBin, asmPath, funcName string, args []byte) (*Session, error) {
+	sess, _, err := LaunchWithBuffers(gasmBin, asmPath, funcName, args, "")
+	return sess, err
+}
+
+// LaunchWithBuffers is like Launch but also allocates buffers in the debuggee.
+//
+// It pins the calling goroutine to its OS thread and leaves it pinned: the
+// debuggee's PTRACE_TRACEME binds the tracer relation to the forking thread,
+// and every ptrace request on the session must come from that same thread.
+// All Session methods must therefore be called from the goroutine that
+// launched the session (the REPL and coverage loops do exactly that).
+func LaunchWithBuffers(gasmBin, asmPath, funcName string, args []byte, bufSpec string) (*Session, []uint64, error) {
+	runtime.LockOSThread() // ptrace requests must stay on the forking thread
+	self, err := os.Executable()
+	if err != nil {
+		return nil, nil, fmt.Errorf("debug: cannot find gasm binary: %w", err)
+	}
+	if gasmBin != "" {
+		self = gasmBin
+	}
+
+	tmpDir, err := os.MkdirTemp("", "gasm-debug-*")
+	if err != nil {
+		return nil, nil, fmt.Errorf("debug: tempdir: %w", err)
+	}
+	argsFile := filepath.Join(tmpDir, "args.bin")
+	if err := os.WriteFile(argsFile, args, 0o644); err != nil {
+		os.RemoveAll(tmpDir)
+		return nil, nil, fmt.Errorf("debug: write args: %w", err)
+	}
+
+	if bufSpec != "" {
+		if err := os.WriteFile(filepath.Join(tmpDir, "bufspec"), []byte(bufSpec), 0o644); err != nil {
+			os.RemoveAll(tmpDir)
+			return nil, nil, fmt.Errorf("debug: write bufspec: %w", err)
+		}
+	}
+
+	cmd := exec.Command(self, "debug", "--func", funcName, "--args", argsFile, asmPath)
+	cmd.Env = append(os.Environ(), "GASM_DEBUG_TARGET=1", "GASM_DEBUG_TMP="+tmpDir)
+	cmd.Stdout = nil
+	cmd.Stderr = os.Stderr
+	cmd.SysProcAttr = &syscall.SysProcAttr{}
+
+	if err := cmd.Start(); err != nil {
+		os.RemoveAll(tmpDir)
+		return nil, nil, fmt.Errorf("debug: start debuggee: %w", err)
+	}
+
+	s := &Session{pid: cmd.Process.Pid, cmd: cmd}
+
+	readyFile := filepath.Join(tmpDir, "ready")
+	for range 500 {
+		if _, err := os.Stat(readyFile); err == nil {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	// The debuggee parks itself with SIGSTOP once the JIT code is mapped.
+	// A Go tracee also reports SIGURG preemption as signal-delivery-stops,
+	// so the wait loops until a stop the debugger cares about instead of
+	// assuming the first event is the SIGSTOP.
+	if _, err := s.waitStopped(); err != nil {
+		cmd.Process.Kill()
+		os.RemoveAll(tmpDir)
+		return nil, nil, fmt.Errorf("debug: wait for debuggee: %w", err)
+	}
+	s.stopped = true
+
+	// The debuggee reports its JIT mapping in the codebase file; that is the
+	// exact region the kernel was written to.  Scanning /proc/pid/maps for
+	// any RWX region is only the fallback.
+	if data, err := os.ReadFile(filepath.Join(tmpDir, "codebase")); err == nil {
+		fmt.Sscanf(string(data), "%d", &s.codeBase)
+	}
+	if s.codeBase == 0 {
+		s.codeBase = findRWXMapping(s.pid)
+	}
+
+	var bufAddrs []uint64
+	if bufSpec != "" {
+		addrFile := filepath.Join(tmpDir, "bufaddrs")
+		if data, err := os.ReadFile(addrFile); err == nil {
+			for line := range strings.SplitSeq(strings.TrimSpace(string(data)), "\n") {
+				var addr uint64
+				if _, err := fmt.Sscanf(line, "%d", &addr); err == nil {
+					bufAddrs = append(bufAddrs, addr)
+				}
+			}
+		}
+	}
+
+	return s, bufAddrs, nil
+}
+
+// wait waits for the debuggee to stop and returns the wait status.
+func (s *Session) wait() error {
+	var ws syscall.WaitStatus
+	_, err := syscall.Wait4(s.pid, &ws, 0, nil)
+	if err != nil {
+		return err
+	}
+	if ws.Exited() {
+		s.exited = true
+		return fmt.Errorf("debuggee exited with status %d", ws.ExitStatus())
+	}
+	s.stopped = true
+	return nil
+}
+
+// waitStopped consumes ptrace-stop events until one the debugger cares
+// about arrives: SIGTRAP (a breakpoint or a completed single-step) or the
+// debuggee's own SIGSTOP.  A Go tracee's runtime raises SIGURG for
+// asynchronous preemption, and every signal on a traced thread surfaces as
+// a signal-delivery-stop, so those are suppressed and the tracee resumed
+// without them.  Runtime noise is why a single wait can return in the
+// middle of runtime code and a resume can then fail: the event stream must
+// be drained by the tracer.
+func (s *Session) waitStopped() (syscall.Signal, error) {
+	for {
+		var ws syscall.WaitStatus
+		if _, err := syscall.Wait4(s.pid, &ws, syscall.WUNTRACED, nil); err != nil {
+			return 0, err
+		}
+		if ws.Exited() {
+			s.exited = true
+			return 0, fmt.Errorf("debuggee exited with status %d", ws.ExitStatus())
+		}
+		if ws.Signaled() {
+			s.exited = true
+			return 0, fmt.Errorf("debuggee killed by signal %v", ws.Signal())
+		}
+		switch sig := ws.StopSignal(); sig {
+		case syscall.SIGTRAP, syscall.SIGSTOP:
+			s.stopped = true
+			return sig, nil
+		default:
+			// Runtime noise (SIGURG preemption and friends): resume the
+			// tracee without delivering the signal.
+			if _, _, errno := syscall.Syscall6(
+				syscall.SYS_PTRACE,
+				uintptr(syscall.PTRACE_CONT),
+				uintptr(s.pid),
+				0, 0, 0, 0,
+			); errno != 0 {
+				return 0, fmt.Errorf("debug: PTRACE_CONT: %w", errno)
+			}
+		}
+	}
+}
+
+// Peek reads a word (8 bytes) from the debuggee's memory at addr.
+func (s *Session) Peek(addr uint64) (uint64, error) {
+	mem, err := os.OpenFile(fmt.Sprintf("/proc/%d/mem", s.pid), os.O_RDONLY, 0)
+	if err != nil {
+		return 0, fmt.Errorf("debug: open /proc/%d/mem: %w", s.pid, err)
+	}
+	defer mem.Close()
+	buf := make([]byte, 8)
+	if _, err := mem.ReadAt(buf, int64(addr)); err != nil {
+		return 0, fmt.Errorf("debug: read mem %#x: %w", addr, err)
+	}
+	return uint64(buf[0]) | uint64(buf[1])<<8 | uint64(buf[2])<<16 | uint64(buf[3])<<24 |
+		uint64(buf[4])<<32 | uint64(buf[5])<<40 | uint64(buf[6])<<48 | uint64(buf[7])<<56, nil
+}
+
+// Poke writes a word (8 bytes) to the debuggee's memory at addr.
+func (s *Session) Poke(addr, val uint64) error {
+	mem, err := os.OpenFile(fmt.Sprintf("/proc/%d/mem", s.pid), os.O_WRONLY, 0)
+	if err != nil {
+		return fmt.Errorf("debug: open /proc/%d/mem: %w", s.pid, err)
+	}
+	defer mem.Close()
+	buf := []byte{byte(val), byte(val >> 8), byte(val >> 16), byte(val >> 24),
+		byte(val >> 32), byte(val >> 40), byte(val >> 48), byte(val >> 56)}
+	if _, err := mem.WriteAt(buf, int64(addr)); err != nil {
+		return fmt.Errorf("debug: write mem %#x: %w", addr, err)
+	}
+	return nil
+}
+
+// ReadMemory reads len bytes from the debuggee's memory at addr.
+func (s *Session) ReadMemory(addr uint64, length int) ([]byte, error) {
+	out := make([]byte, length)
+	for i := 0; i < length; i += 8 {
+		word, err := s.Peek(addr + uint64(i))
+		if err != nil {
+			return out[:i], err
+		}
+		for j := 0; j < 8 && i+j < length; j++ {
+			out[i+j] = byte(word >> (8 * j))
+		}
+	}
+	return out, nil
+}
+
+// WriteMemory writes bytes to the debuggee's memory at addr.
+func (s *Session) WriteMemory(addr uint64, data []byte) error {
+	for i := 0; i < len(data); i += 8 {
+		end := min(i+8, len(data))
+		var word uint64
+		for j := 0; j < end-i; j++ {
+			word |= uint64(data[i+j]) << (8 * j)
+		}
+		if end-i < 8 {
+			existing, err := s.Peek(addr + uint64(i))
+			if err != nil {
+				return err
+			}
+			mask := ^((uint64(1) << (8 * (end - i))) - 1)
+			word = (existing & mask) | word
+		}
+		if err := s.Poke(addr+uint64(i), word); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Step executes a single instruction in the debuggee.
+func (s *Session) Step() error {
+	if s.exited {
+		return fmt.Errorf("debug: debuggee has exited")
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SINGLESTEP),
+		uintptr(s.pid),
+		0, 0, 0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_SINGLESTEP: %w", errno)
+	}
+	_, err := s.waitStopped()
+	return err
+}
+
+// Continue resumes execution until the next breakpoint or exit.
+func (s *Session) Continue() error {
+	if s.exited {
+		return fmt.Errorf("debug: debuggee has exited")
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_CONT),
+		uintptr(s.pid),
+		0, 0, 0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_CONT: %w", errno)
+	}
+	_, err := s.waitStopped()
+	return err
+}
+
+// Exited returns true if the debuggee has terminated.
+func (s *Session) Exited() bool { return s.exited }
+
+// Pid returns the debuggee's process ID.
+func (s *Session) Pid() int { return s.pid }
+
+// CodeBase returns the base address of the JIT code in the debuggee.
+func (s *Session) CodeBase() uint64 { return s.codeBase }
+
+// Kill terminates the debuggee.
+func (s *Session) Kill() {
+	if !s.exited {
+		syscall.Kill(s.pid, syscall.SIGKILL)
+		syscall.Wait4(s.pid, nil, 0, nil)
+		s.exited = true
+	}
+	if s.cmd != nil && s.cmd.Process != nil {
+		s.cmd.Wait()
+	}
+}
+
+// findRWXMapping reads /proc/pid/maps and returns the base address of the
+// first read-write-execute mapping (the JIT code region).
+func findRWXMapping(pid int) uint64 {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/maps", pid))
+	if err != nil {
+		return 0
+	}
+	for line := range strings.SplitSeq(string(data), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) < 2 {
+			continue
+		}
+		perms := fields[1]
+		if len(perms) >= 3 && perms[0] == 'r' && perms[1] == 'w' && perms[2] == 'x' {
+			var start uint64
+			fmt.Sscanf(fields[0], "%x-", &start)
+			return start
+		}
+	}
+	return 0
+}

debug/ptrace_linux_amd64.go

@@ -3,165 +3,14 @@
 
 //go:build linux && amd64
 
-// Package debug implements the interactive debugger for gasm (Phase 4):
-// single-stepping, breakpoints, register and memory inspection for
-// JIT-assembled Plan 9 amd64 functions, controlled via ptrace.
 package debug
 
 import (
 	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
 	"syscall"
-	"time"
 	"unsafe"
 )
 
-// Session is a ptrace debugging session controlling one debuggee process.
-type Session struct {
-	pid      int
-	cmd      *exec.Cmd
-	stopped  bool
-	exited   bool
-	codeBase uint64  // base address of the JIT code in the debuggee
-	wpSlots  [4]bool // watchpoint slot occupancy (DR0-DR3)
-}
-
-// Launch starts the debuggee subprocess (gasm debug --target ...) and
-// attaches to it via ptrace.  The debuggee assembles the file, maps the
-// JIT code, calls PTRACE_TRACEME and raises SIGSTOP; Launch waits for
-// that initial stop and returns a ready Session.
-func Launch(gasmBin, asmPath, funcName string, args []byte) (*Session, error) {
-	sess, _, err := LaunchWithBuffers(gasmBin, asmPath, funcName, args, "")
-	return sess, err
-}
-
-// LaunchWithBuffers is like Launch but also allocates buffers in the debuggee
-// based on the buffer specification.  Returns the Session and the buffer
-// addresses (in the order they appear in the spec).
-func LaunchWithBuffers(gasmBin, asmPath, funcName string, args []byte, bufSpec string) (*Session, []uint64, error) {
-	self, err := os.Executable()
-	if err != nil {
-		return nil, nil, fmt.Errorf("debug: cannot find gasm binary: %w", err)
-	}
-	if gasmBin != "" {
-		self = gasmBin
-	}
-
-	// Write the arg block to a temp file (the child reads it).
-	tmpDir, err := os.MkdirTemp("", "gasm-debug-*")
-	if err != nil {
-		return nil, nil, fmt.Errorf("debug: tempdir: %w", err)
-	}
-	argsFile := filepath.Join(tmpDir, "args.bin")
-	if err := os.WriteFile(argsFile, args, 0o644); err != nil {
-		os.RemoveAll(tmpDir)
-		return nil, nil, fmt.Errorf("debug: write args: %w", err)
-	}
-
-	// Write the buffer spec if present.
-	if bufSpec != "" {
-		if err := os.WriteFile(filepath.Join(tmpDir, "bufspec"), []byte(bufSpec), 0o644); err != nil {
-			os.RemoveAll(tmpDir)
-			return nil, nil, fmt.Errorf("debug: write bufspec: %w", err)
-		}
-	}
-
-	cmd := exec.Command(self, "debug", "--target", "--func", funcName, "--args", argsFile, asmPath)
-	cmd.Env = append(os.Environ(), "GASM_DEBUG_TMP="+tmpDir)
-	cmd.Stdout = nil // output goes to the debugger, not the terminal
-	cmd.Stderr = os.Stderr
-	cmd.SysProcAttr = &syscall.SysProcAttr{}
-
-	if err := cmd.Start(); err != nil {
-		os.RemoveAll(tmpDir)
-		return nil, nil, fmt.Errorf("debug: start debuggee: %w", err)
-	}
-
-	s := &Session{pid: cmd.Process.Pid, cmd: cmd}
-
-	// Wait for the child to signal readiness and stop.  The child calls
-	// PTRACE_TRACEME then SIGSTOP, so Wait4 with WUNTRACED observes the
-	// ptrace-stop directly (no PTRACE_ATTACH needed).
-	readyFile := filepath.Join(tmpDir, "ready")
-	for i := 0; i < 500; i++ {
-		if _, err := os.Stat(readyFile); err == nil {
-			break
-		}
-		time.Sleep(5 * time.Millisecond)
-	}
-	var ws syscall.WaitStatus
-	if _, err := syscall.Wait4(s.pid, &ws, syscall.WUNTRACED, nil); err != nil {
-		cmd.Process.Kill()
-		os.RemoveAll(tmpDir)
-		return nil, nil, fmt.Errorf("debug: wait for stop: %w", err)
-	}
-
-	// Wait for the debuggee to reach the function entry point.
-	entryFile := filepath.Join(tmpDir, "entry")
-	for i := 0; i < 500; i++ {
-		if _, err := os.Stat(entryFile); err == nil {
-			break
-		}
-		time.Sleep(5 * time.Millisecond)
-	}
-
-	// Continue the debuggee to the entry point.
-	if err := s.Continue(); err != nil {
-		return nil, nil, fmt.Errorf("debug: continue to entry: %w", err)
-	}
-
-	// Wait for the entry stop.
-	if _, err := syscall.Wait4(s.pid, &ws, syscall.WUNTRACED, nil); err != nil {
-		return nil, nil, fmt.Errorf("debug: wait for entry: %w", err)
-	}
-
-	s.stopped = true
-
-	// Read the code base from /proc/pid/maps (find the RWX mapping).
-	s.codeBase = findRWXMapping(s.pid)
-	if s.codeBase == 0 {
-		// Fallback: try the file the child wrote.
-		baseFile := filepath.Join(tmpDir, "codebase")
-		if data, err := os.ReadFile(baseFile); err == nil {
-			fmt.Sscanf(string(data), "%d", &s.codeBase)
-		}
-	}
-
-	// Read buffer addresses if buffers were allocated.
-	var bufAddrs []uint64
-	if bufSpec != "" {
-		addrFile := filepath.Join(tmpDir, "bufaddrs")
-		if data, err := os.ReadFile(addrFile); err == nil {
-			for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
-				var addr uint64
-				if _, err := fmt.Sscanf(line, "%d", &addr); err == nil {
-					bufAddrs = append(bufAddrs, addr)
-				}
-			}
-		}
-	}
-
-	return s, bufAddrs, nil
-}
-
-// wait waits for the debuggee to stop and returns the wait status.
-func (s *Session) wait() error {
-	var ws syscall.WaitStatus
-	_, err := syscall.Wait4(s.pid, &ws, 0, nil)
-	if err != nil {
-		return err
-	}
-	if ws.Exited() {
-		s.exited = true
-		return fmt.Errorf("debuggee exited with status %d", ws.ExitStatus())
-	}
-	s.stopped = true
-	return nil
-}
-
 // GetRegs reads the general-purpose registers of the stopped debuggee.
 func (s *Session) GetRegs() (Regs, error) {
 	var regs Regs
@@ -234,179 +83,16 @@ type VectorRegs struct {
 }
 
 // GetVectorRegs retrieves the YMM registers via PTRACE_GETREGSET + XSAVE.
-// Falls back to XMM if XSAVE is unavailable.
 func (s *Session) GetVectorRegs() (VectorRegs, error) {
 	var v VectorRegs
 	fp, err := s.GetFPRegs()
 	if err != nil {
 		return v, err
 	}
-	// PTRACE_GETFPREGS gives XMM registers (lower 128 bits).
-	// For YMM we'd need XSAVE; for now, copy XMM and zero the upper half.
-	for i := 0; i < 16; i++ {
-		for j := 0; j < 16; j++ {
+	for i := range 16 {
+		for j := range 16 {
 			v.YMM[i][j] = fp.XMM[i][j]
 		}
-		// Upper 128 bits would come from XSAVE, not available via GETFPREGS.
 	}
 	return v, nil
 }
-
-// Peek reads a word (8 bytes) from the debuggee's memory at addr.
-// Uses /proc/pid/mem which works reliably with Go's multi-threaded runtime.
-func (s *Session) Peek(addr uint64) (uint64, error) {
-	mem, err := os.OpenFile(fmt.Sprintf("/proc/%d/mem", s.pid), os.O_RDONLY, 0)
-	if err != nil {
-		return 0, fmt.Errorf("debug: open /proc/%d/mem: %w", s.pid, err)
-	}
-	defer mem.Close()
-	buf := make([]byte, 8)
-	if _, err := mem.ReadAt(buf, int64(addr)); err != nil {
-		return 0, fmt.Errorf("debug: read mem %#x: %w", addr, err)
-	}
-	return uint64(buf[0]) | uint64(buf[1])<<8 | uint64(buf[2])<<16 | uint64(buf[3])<<24 |
-		uint64(buf[4])<<32 | uint64(buf[5])<<40 | uint64(buf[6])<<48 | uint64(buf[7])<<56, nil
-}
-
-// Poke writes a word (8 bytes) to the debuggee's memory at addr.
-func (s *Session) Poke(addr, val uint64) error {
-	mem, err := os.OpenFile(fmt.Sprintf("/proc/%d/mem", s.pid), os.O_WRONLY, 0)
-	if err != nil {
-		return fmt.Errorf("debug: open /proc/%d/mem: %w", s.pid, err)
-	}
-	defer mem.Close()
-	buf := []byte{byte(val), byte(val >> 8), byte(val >> 16), byte(val >> 24),
-		byte(val >> 32), byte(val >> 40), byte(val >> 48), byte(val >> 56)}
-	if _, err := mem.WriteAt(buf, int64(addr)); err != nil {
-		return fmt.Errorf("debug: write mem %#x: %w", addr, err)
-	}
-	return nil
-}
-
-// ReadMemory reads len bytes from the debuggee's memory at addr.
-func (s *Session) ReadMemory(addr uint64, length int) ([]byte, error) {
-	out := make([]byte, length)
-	for i := 0; i < length; i += 8 {
-		word, err := s.Peek(addr + uint64(i))
-		if err != nil {
-			return out[:i], err
-		}
-		for j := 0; j < 8 && i+j < length; j++ {
-			out[i+j] = byte(word >> (8 * j))
-		}
-	}
-	return out, nil
-}
-
-// WriteMemory writes bytes to the debuggee's memory at addr.
-func (s *Session) WriteMemory(addr uint64, data []byte) error {
-	for i := 0; i < len(data); i += 8 {
-		end := i + 8
-		if end > len(data) {
-			end = len(data)
-		}
-		var word uint64
-		for j := 0; j < end-i; j++ {
-			word |= uint64(data[i+j]) << (8 * j)
-		}
-		// For partial writes, read-modify-write the existing word.
-		if end-i < 8 {
-			existing, err := s.Peek(addr + uint64(i))
-			if err != nil {
-				return err
-			}
-			// Clear the bytes we're overwriting and merge.
-			mask := ^((uint64(1) << (8 * (end - i))) - 1)
-			word = (existing & mask) | word
-		}
-		if err := s.Poke(addr+uint64(i), word); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// Step executes a single instruction in the debuggee.
-func (s *Session) Step() error {
-	if s.exited {
-		return fmt.Errorf("debug: debuggee has exited")
-	}
-	_, _, errno := syscall.Syscall6(
-		syscall.SYS_PTRACE,
-		uintptr(syscall.PTRACE_SINGLESTEP),
-		uintptr(s.pid),
-		0, 0, 0, 0,
-	)
-	if errno != 0 {
-		return fmt.Errorf("debug: PTRACE_SINGLESTEP: %w", errno)
-	}
-	return s.wait()
-}
-
-// Continue resumes execution until the next breakpoint or exit.
-func (s *Session) Continue() error {
-	if s.exited {
-		return fmt.Errorf("debug: debuggee has exited")
-	}
-	_, _, errno := syscall.Syscall6(
-		syscall.SYS_PTRACE,
-		uintptr(syscall.PTRACE_CONT),
-		uintptr(s.pid),
-		0, 0, 0, 0,
-	)
-	if errno != 0 {
-		return fmt.Errorf("debug: PTRACE_CONT: %w", errno)
-	}
-	return s.wait()
-}
-
-// Exited returns true if the debuggee has terminated.
-func (s *Session) Exited() bool {
-	return s.exited
-}
-
-// Pid returns the debuggee's process ID.
-func (s *Session) Pid() int {
-	return s.pid
-}
-
-// CodeBase returns the base address of the JIT code in the debuggee.
-func (s *Session) CodeBase() uint64 {
-	return s.codeBase
-}
-
-// Kill terminates the debuggee.
-func (s *Session) Kill() {
-	if !s.exited {
-		syscall.Kill(s.pid, syscall.SIGKILL)
-		syscall.Wait4(s.pid, nil, 0, nil)
-		s.exited = true
-	}
-	if s.cmd != nil && s.cmd.Process != nil {
-		s.cmd.Wait()
-	}
-}
-
-// findRWXMapping reads /proc/pid/maps and returns the base address of the
-// first read-write-execute mapping (the JIT code region).
-func findRWXMapping(pid int) uint64 {
-	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/maps", pid))
-	if err != nil {
-		return 0
-	}
-	for _, line := range strings.Split(string(data), "\n") {
-		// Format: addr-addr perms offset dev inode pathname
-		fields := strings.Fields(line)
-		if len(fields) < 2 {
-			continue
-		}
-		perms := fields[1]
-		if len(perms) >= 3 && perms[0] == 'r' && perms[1] == 'w' && perms[2] == 'x' {
-			// Parse the start address.
-			var start uint64
-			fmt.Sscanf(fields[0], "%x-", &start)
-			return start
-		}
-	}
-	return 0
-}

debug/ptrace_linux_arm64.go

@@ -0,0 +1,94 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// GetRegs reads the general-purpose registers of the stopped debuggee.
+func (s *Session) GetRegs() (Regs, error) {
+	var regs Regs
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return regs, fmt.Errorf("debug: PTRACE_GETREGS: %w", errno)
+	}
+	return regs, nil
+}
+
+// SetRegs writes the general-purpose registers of the stopped debuggee.
+func (s *Session) SetRegs(regs *Regs) error {
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_SETREGS: %w", errno)
+	}
+	return nil
+}
+
+// ntPrFPREG is the NT_PRFPREG note type (ELF NT ver): the FP register set.
+const ntPrFPREG = 0x2
+
+// FPRegs holds the arm64 FP/NEON register state, matching the kernel's
+// user_fpsimd_struct layout (32 128-bit V registers, then FPSR and FPCR).
+type FPRegs struct {
+	V    [32][16]byte // V0-V31 (128-bit NEON/FP registers)
+	FPSR uint32
+	FPCR uint32
+}
+
+// GetFPRegs retrieves the FP register state via PTRACE_GETREGSET with
+// NT_PRFPREG (this architecture has no PTRACE_GETFPREGS request).
+func (s *Session) GetFPRegs() (FPRegs, error) {
+	var fp FPRegs
+	iovec := syscall.Iovec{
+		Base: (*byte)(unsafe.Pointer(&fp)),
+		Len:  uint64(unsafe.Sizeof(fp)),
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGSET),
+		uintptr(s.pid),
+		uintptr(ntPrFPREG),
+		uintptr(unsafe.Pointer(&iovec)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fp, fmt.Errorf("debug: PTRACE_GETREGSET (NT_PRFPREG): %w", errno)
+	}
+	return fp, nil
+}
+
+// VectorRegs holds the full SIMD register state.
+type VectorRegs struct {
+	V [32][16]byte // V0-V31 (128-bit)
+}
+
+// GetVectorRegs retrieves the SIMD registers.
+func (s *Session) GetVectorRegs() (VectorRegs, error) {
+	var v VectorRegs
+	fp, err := s.GetFPRegs()
+	if err != nil {
+		return v, err
+	}
+	copy(v.V[:][:], fp.V[:][:])
+	return v, nil
+}

debug/ptrace_linux_loong64.go

@@ -0,0 +1,97 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// GetRegs reads the general-purpose registers of the stopped debuggee.
+func (s *Session) GetRegs() (Regs, error) {
+	var regs Regs
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return regs, fmt.Errorf("debug: PTRACE_GETREGS: %w", errno)
+	}
+	return regs, nil
+}
+
+// SetRegs writes the general-purpose registers of the stopped debuggee.
+func (s *Session) SetRegs(regs *Regs) error {
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_SETREGS: %w", errno)
+	}
+	return nil
+}
+
+// ntPrFPREG is the NT_PRFPREG note type (ELF NT ver): the FP register set.
+const ntPrFPREG = 0x2
+
+// FPRegs holds the LoongArch FP register state, matching the kernel's
+// user_fp_struct layout (32 64-bit FP registers, the fcc condition flags,
+// and fcsr).
+type FPRegs struct {
+	F    [32]uint64 // F0-F31 (64-bit FP registers)
+	FCC  uint64     // eight per-register condition flags, packed
+	FCSR uint32
+}
+
+// GetFPRegs retrieves the FP register state via PTRACE_GETREGSET with
+// NT_PRFPREG (this architecture has no PTRACE_GETFPREGS request).
+func (s *Session) GetFPRegs() (FPRegs, error) {
+	var fp FPRegs
+	iovec := syscall.Iovec{
+		Base: (*byte)(unsafe.Pointer(&fp)),
+		Len:  uint64(unsafe.Sizeof(fp)),
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGSET),
+		uintptr(s.pid),
+		uintptr(ntPrFPREG),
+		uintptr(unsafe.Pointer(&iovec)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fp, fmt.Errorf("debug: PTRACE_GETREGSET (NT_PRFPREG): %w", errno)
+	}
+	return fp, nil
+}
+
+// VectorRegs holds the FP register state shown by the regs command
+// (the scalar FP subset: 32 64-bit registers, fcc and fcsr; the LSX/LASX
+// vector files are not read yet).
+type VectorRegs struct {
+	F    [32]uint64
+	FCC  uint64
+	FCSR uint32
+}
+
+// GetVectorRegs retrieves the FP registers.
+func (s *Session) GetVectorRegs() (VectorRegs, error) {
+	fp, err := s.GetFPRegs()
+	if err != nil {
+		return VectorRegs{}, err
+	}
+	return VectorRegs{F: fp.F, FCC: fp.FCC, FCSR: fp.FCSR}, nil
+}

debug/ptrace_linux_riscv64.go

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// GetRegs reads the general-purpose registers of the stopped debuggee.
+func (s *Session) GetRegs() (Regs, error) {
+	var regs Regs
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return regs, fmt.Errorf("debug: PTRACE_GETREGS: %w", errno)
+	}
+	return regs, nil
+}
+
+// SetRegs writes the general-purpose registers of the stopped debuggee.
+func (s *Session) SetRegs(regs *Regs) error {
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_SETREGS: %w", errno)
+	}
+	return nil
+}
+
+// ntPrFPREG is the NT_PRFPREG note type (ELF NT ver): the FP register set.
+const ntPrFPREG = 0x2
+
+// FPRegs holds the RISC-V FP register state, matching the kernel's
+// user_fp_struct layout (32 64-bit FP registers plus fcsr).
+type FPRegs struct {
+	F    [32]uint64 // F0-F31 (64-bit FP registers)
+	FCSR uint32
+}
+
+// GetFPRegs retrieves the FP register state via PTRACE_GETREGSET with
+// NT_PRFPREG (this architecture has no PTRACE_GETFPREGS request).
+func (s *Session) GetFPRegs() (FPRegs, error) {
+	var fp FPRegs
+	iovec := syscall.Iovec{
+		Base: (*byte)(unsafe.Pointer(&fp)),
+		Len:  uint64(unsafe.Sizeof(fp)),
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGSET),
+		uintptr(s.pid),
+		uintptr(ntPrFPREG),
+		uintptr(unsafe.Pointer(&iovec)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fp, fmt.Errorf("debug: PTRACE_GETREGSET (NT_PRFPREG): %w", errno)
+	}
+	return fp, nil
+}
+
+// VectorRegs holds the FP register state shown by the regs command
+// (riscv64 has 32 64-bit FP registers and fcsr).
+type VectorRegs struct {
+	F    [32]uint64
+	FCSR uint32
+}
+
+// GetVectorRegs retrieves the FP registers.
+func (s *Session) GetVectorRegs() (VectorRegs, error) {
+	fp, err := s.GetFPRegs()
+	if err != nil {
+		return VectorRegs{}, err
+	}
+	return VectorRegs{F: fp.F, FCSR: fp.FCSR}, nil
+}

debug/regs_linux_amd64.go

@@ -0,0 +1,95 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+// Regs holds the full general-purpose register set of a traced process
+// (the Linux amd64 user_regs_struct layout).
+type Regs struct {
+	R15     uint64
+	R14     uint64
+	R13     uint64
+	R12     uint64
+	RBP     uint64
+	RBX     uint64
+	R11     uint64
+	R10     uint64
+	R9      uint64
+	R8      uint64
+	RAX     uint64
+	RCX     uint64
+	RDX     uint64
+	RSI     uint64
+	RDI     uint64
+	OrigRAX uint64
+	RIP     uint64
+	CS      uint64
+	RFLAGS  uint64
+	RSP     uint64
+	SS      uint64
+	FSBase  uint64
+	GSBase  uint64
+	DS      uint64
+	ES      uint64
+	FS      uint64
+	GS      uint64
+}
+
+// GetPC returns the program counter.
+func (r *Regs) GetPC() uint64 { return r.RIP }
+
+// SetPC sets the program counter.
+func (r *Regs) SetPC(pc uint64) { r.RIP = pc }
+
+// GetSP returns the stack pointer.
+func (r *Regs) GetSP() uint64 { return r.RSP }
+
+// RegValue returns the value of the named register, or false if unknown.
+func (r *Regs) RegValue(name string) (uint64, bool) {
+	switch name {
+	case "rax", "eax", "ax", "al":
+		return r.RAX, true
+	case "rbx", "ebx", "bx", "bl":
+		return r.RBX, true
+	case "rcx", "ecx", "cx", "cl":
+		return r.RCX, true
+	case "rdx", "edx", "dx", "dl":
+		return r.RDX, true
+	case "rsi", "esi", "si":
+		return r.RSI, true
+	case "rdi", "edi", "di":
+		return r.RDI, true
+	case "rbp", "ebp", "bp":
+		return r.RBP, true
+	case "rsp", "esp", "sp":
+		return r.RSP, true
+	case "r8":
+		return r.R8, true
+	case "r9":
+		return r.R9, true
+	case "r10":
+		return r.R10, true
+	case "r11":
+		return r.R11, true
+	case "r12":
+		return r.R12, true
+	case "r13":
+		return r.R13, true
+	case "r14":
+		return r.R14, true
+	case "r15":
+		return r.R15, true
+	case "rip", "eip":
+		return r.RIP, true
+	default:
+		return 0, false
+	}
+}
+
+// breakpointInsn is the software breakpoint instruction.
+var breakpointInsn = []byte{0xCC} // INT3
+
+// breakpointPCAdjust is how far PC is past the breakpoint instruction after a trap.
+const breakpointPCAdjust = 1

debug/regs_linux_arm64.go

@@ -0,0 +1,134 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+// Regs holds the full general-purpose register set of a traced process
+// (the Linux arm64 user_pt_regs layout).
+type Regs struct {
+	X0     uint64
+	X1     uint64
+	X2     uint64
+	X3     uint64
+	X4     uint64
+	X5     uint64
+	X6     uint64
+	X7     uint64
+	X8     uint64
+	X9     uint64
+	X10    uint64
+	X11    uint64
+	X12    uint64
+	X13    uint64
+	X14    uint64
+	X15    uint64
+	X16    uint64
+	X17    uint64
+	X18    uint64
+	X19    uint64
+	X20    uint64
+	X21    uint64
+	X22    uint64
+	X23    uint64
+	X24    uint64
+	X25    uint64
+	X26    uint64
+	X27    uint64
+	X28    uint64
+	X29    uint64 // FP (frame pointer)
+	X30    uint64 // LR (link register)
+	SP     uint64
+	PC     uint64
+	PSTATE uint64
+}
+
+// PC returns the program counter.
+func (r *Regs) GetPC() uint64 { return r.PC }
+
+// SetPC sets the program counter.
+func (r *Regs) SetPC(pc uint64) { r.PC = pc }
+
+// GetSP returns the stack pointer.
+func (r *Regs) GetSP() uint64 { return r.SP }
+
+// RegValue returns the value of the named register, or false if unknown.
+func (r *Regs) RegValue(name string) (uint64, bool) {
+	switch name {
+	case "x0":
+		return r.X0, true
+	case "x1":
+		return r.X1, true
+	case "x2":
+		return r.X2, true
+	case "x3":
+		return r.X3, true
+	case "x4":
+		return r.X4, true
+	case "x5":
+		return r.X5, true
+	case "x6":
+		return r.X6, true
+	case "x7":
+		return r.X7, true
+	case "x8":
+		return r.X8, true
+	case "x9":
+		return r.X9, true
+	case "x10":
+		return r.X10, true
+	case "x11":
+		return r.X11, true
+	case "x12":
+		return r.X12, true
+	case "x13":
+		return r.X13, true
+	case "x14":
+		return r.X14, true
+	case "x15":
+		return r.X15, true
+	case "x16":
+		return r.X16, true
+	case "x17":
+		return r.X17, true
+	case "x18":
+		return r.X18, true
+	case "x19":
+		return r.X19, true
+	case "x20":
+		return r.X20, true
+	case "x21":
+		return r.X21, true
+	case "x22":
+		return r.X22, true
+	case "x23":
+		return r.X23, true
+	case "x24":
+		return r.X24, true
+	case "x25":
+		return r.X25, true
+	case "x26":
+		return r.X26, true
+	case "x27":
+		return r.X27, true
+	case "x28":
+		return r.X28, true
+	case "x29", "fp":
+		return r.X29, true
+	case "x30", "lr":
+		return r.X30, true
+	case "sp":
+		return r.SP, true
+	case "pc":
+		return r.PC, true
+	default:
+		return 0, false
+	}
+}
+
+// breakpointInsn is the software breakpoint instruction (BRK #0).
+var breakpointInsn = []byte{0x00, 0x00, 0x20, 0xD4} // BRK #0
+
+// breakpointPCAdjust is how far PC is past the breakpoint instruction after a trap.
+const breakpointPCAdjust = 4

debug/regs_linux_loong64.go

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+// Regs holds the full general-purpose register set of a traced process
+// (the Linux loong64 user_pt_regs layout).
+type Regs struct {
+	R0  uint64 // zero
+	R1  uint64 // RA (return address)
+	R2  uint64 // TP (thread pointer)
+	R3  uint64 // SP (stack pointer)
+	R4  uint64 // A0
+	R5  uint64 // A1
+	R6  uint64 // A2
+	R7  uint64 // A3
+	R8  uint64 // A4
+	R9  uint64 // A5
+	R10 uint64 // A6
+	R11 uint64 // A7
+	R12 uint64 // T0
+	R13 uint64 // T1
+	R14 uint64 // T2
+	R15 uint64 // T3
+	R16 uint64 // T4
+	R17 uint64 // T5
+	R18 uint64 // T6
+	R19 uint64 // T7
+	R20 uint64 // T8
+	R21 uint64 // FP (frame pointer)
+	R22 uint64 // S0
+	R23 uint64 // S1
+	R24 uint64 // S2
+	R25 uint64 // S3
+	R26 uint64 // S4
+	R27 uint64 // S5
+	R28 uint64 // S6
+	R29 uint64 // S7
+	R30 uint64 // S8
+	R31 uint64 // PC
+}
+
+// GetPC returns the program counter.
+func (r *Regs) GetPC() uint64 { return r.R31 }
+
+// SetPC sets the program counter.
+func (r *Regs) SetPC(pc uint64) { r.R31 = pc }
+
+// GetSP returns the stack pointer.
+func (r *Regs) GetSP() uint64 { return r.R3 }
+
+// RegValue returns the value of the named register, or false if unknown.
+func (r *Regs) RegValue(name string) (uint64, bool) {
+	switch name {
+	case "r0", "zero":
+		return r.R0, true
+	case "r1", "ra":
+		return r.R1, true
+	case "r2", "tp":
+		return r.R2, true
+	case "r3", "sp":
+		return r.R3, true
+	case "r4", "a0":
+		return r.R4, true
+	case "r5", "a1":
+		return r.R5, true
+	case "r6", "a2":
+		return r.R6, true
+	case "r7", "a3":
+		return r.R7, true
+	case "r8", "a4":
+		return r.R8, true
+	case "r9", "a5":
+		return r.R9, true
+	case "r10", "a6":
+		return r.R10, true
+	case "r11", "a7":
+		return r.R11, true
+	case "r12", "t0":
+		return r.R12, true
+	case "r13", "t1":
+		return r.R13, true
+	case "r14", "t2":
+		return r.R14, true
+	case "r15", "t3":
+		return r.R15, true
+	case "r16", "t4":
+		return r.R16, true
+	case "r17", "t5":
+		return r.R17, true
+	case "r18", "t6":
+		return r.R18, true
+	case "r19", "t7":
+		return r.R19, true
+	case "r20", "t8":
+		return r.R20, true
+	case "r21", "fp":
+		return r.R21, true
+	case "r22", "s0":
+		return r.R22, true
+	case "r23", "s1":
+		return r.R23, true
+	case "r24", "s2":
+		return r.R24, true
+	case "r25", "s3":
+		return r.R25, true
+	case "r26", "s4":
+		return r.R26, true
+	case "r27", "s5":
+		return r.R27, true
+	case "r28", "s6":
+		return r.R28, true
+	case "r29", "s7":
+		return r.R29, true
+	case "r30", "s8":
+		return r.R30, true
+	case "r31", "pc":
+		return r.R31, true
+	default:
+		return 0, false
+	}
+}
+
+// breakpointInsn is the software breakpoint instruction (BRK $0).
+var breakpointInsn = []byte{0x05, 0x00, 0x2a, 0x00} // break 0
+
+// breakpointPCAdjust is how far PC is past the breakpoint instruction after a trap.
+const breakpointPCAdjust = 4

debug/regs_linux_riscv64.go

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+// Regs holds the full general-purpose register set of a traced process
+// (the Linux riscv64 user_regs_struct layout).
+type Regs struct {
+	PC  uint64
+	Ra  uint64 // x1 (return address)
+	Sp  uint64 // x2
+	Gp  uint64 // x3
+	Tp  uint64 // x4
+	T0  uint64 // x5
+	T1  uint64 // x6
+	T2  uint64 // x7
+	S0  uint64 // x8 (frame pointer)
+	S1  uint64 // x9
+	A0  uint64 // x10
+	A1  uint64 // x11
+	A2  uint64 // x12
+	A3  uint64 // x13
+	A4  uint64 // x14
+	A5  uint64 // x15
+	A6  uint64 // x16
+	A7  uint64 // x17
+	S2  uint64 // x18
+	S3  uint64 // x19
+	S4  uint64 // x20
+	S5  uint64 // x21
+	S6  uint64 // x22
+	S7  uint64 // x23
+	S8  uint64 // x24
+	S9  uint64 // x25
+	S10 uint64 // x26
+	S11 uint64 // x27
+	T3  uint64 // x28
+	T4  uint64 // x29
+	T5  uint64 // x30
+	T6  uint64 // x31
+}
+
+// GetPC returns the program counter.
+func (r *Regs) GetPC() uint64 { return r.PC }
+
+// SetPC sets the program counter.
+func (r *Regs) SetPC(pc uint64) { r.PC = pc }
+
+// GetSP returns the stack pointer.
+func (r *Regs) GetSP() uint64 { return r.Sp }
+
+// RegValue returns the value of the named register, or false if unknown.
+func (r *Regs) RegValue(name string) (uint64, bool) {
+	switch name {
+	case "pc":
+		return r.PC, true
+	case "ra", "x1":
+		return r.Ra, true
+	case "sp", "x2":
+		return r.Sp, true
+	case "gp", "x3":
+		return r.Gp, true
+	case "tp", "x4":
+		return r.Tp, true
+	case "t0", "x5":
+		return r.T0, true
+	case "t1", "x6":
+		return r.T1, true
+	case "t2", "x7":
+		return r.T2, true
+	case "s0", "fp", "x8":
+		return r.S0, true
+	case "s1", "x9":
+		return r.S1, true
+	case "a0", "x10":
+		return r.A0, true
+	case "a1", "x11":
+		return r.A1, true
+	case "a2", "x12":
+		return r.A2, true
+	case "a3", "x13":
+		return r.A3, true
+	case "a4", "x14":
+		return r.A4, true
+	case "a5", "x15":
+		return r.A5, true
+	case "a6", "x16":
+		return r.A6, true
+	case "a7", "x17":
+		return r.A7, true
+	case "s2", "x18":
+		return r.S2, true
+	case "s3", "x19":
+		return r.S3, true
+	case "s4", "x20":
+		return r.S4, true
+	case "s5", "x21":
+		return r.S5, true
+	case "s6", "x22":
+		return r.S6, true
+	case "s7", "x23":
+		return r.S7, true
+	case "s8", "x24":
+		return r.S8, true
+	case "s9", "x25":
+		return r.S9, true
+	case "s10", "x26":
+		return r.S10, true
+	case "s11", "x27":
+		return r.S11, true
+	case "t3", "x28":
+		return r.T3, true
+	case "t4", "x29":
+		return r.T4, true
+	case "t5", "x30":
+		return r.T5, true
+	case "t6", "x31":
+		return r.T6, true
+	default:
+		return 0, false
+	}
+}
+
+// breakpointInsn is the software breakpoint instruction (EBREAK).
+var breakpointInsn = []byte{0x73, 0x00, 0x10, 0x00} // ebreak
+
+// breakpointPCAdjust is how far PC is past the breakpoint instruction after a trap.
+const breakpointPCAdjust = 4

debug/repl.go

@@ -1,14 +1,14 @@
 // Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
 // SPDX-License-Identifier: BSD-3-Clause
 
-//go:build linux && amd64
+//go:build linux
 
 package debug
 
 import (
 	"bufio"
 	"fmt"
-	"os"
+	"io"
 	"sort"
 	"strconv"
 	"strings"
@@ -26,19 +26,15 @@ type SourceLine struct {
 	Line   int
 }
 
-// REPL runs the interactive debugger loop.  On entry, the debuggee is
-// stopped in the Go runtime (after PTRACE_TRACEME + SIGSTOP).  The REPL
-// sets a temporary breakpoint at the function entry, continues to it, and
-// then presents the prompt — so the user starts debugging at the first
-// instruction of the assembled function.
-func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, argsSize int, labels []Label, lines []SourceLine) {
+// REPL runs the interactive debugger loop, reading commands from in (pass
+// os.Stdin interactively, or a bytes.Reader/script file for headless runs).
+func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, argsSize int, labels []Label, lines []SourceLine, in io.Reader) {
 	entryAddr := codeBase + uint64(funcOffset)
 
-	// The debuggee is already stopped at the function entry point.
 	fmt.Printf("stopped at function entry: %#x (%d bytes)\n", entryAddr, funcSize)
 	fmt.Println("commands: break <label|addr> | step [n] | continue | disas [n] | regs | where | x <addr> [len] | w <addr> <val...> | labels | quit")
 
-	scanner := bufio.NewScanner(os.Stdin)
+	scanner := bufio.NewScanner(in)
 
 	for {
 		fmt.Print("(gasm) ")
@@ -64,7 +60,6 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				continue
 			}
 			printRegs(&regs, codeBase, uint64(funcOffset))
-			// Also show vector registers.
 			vregs, err := s.GetVectorRegs()
 			if err != nil {
 				fmt.Printf("  (vector regs unavailable: %v)\n", err)
@@ -77,7 +72,7 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 			if len(parts) > 1 {
 				n, _ = strconv.Atoi(parts[1])
 			}
-			for i := 0; i < n; i++ {
+			for range n {
 				if s.Exited() {
 					fmt.Println("debuggee exited")
 					break
@@ -89,24 +84,22 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 			}
 			if !s.Exited() {
 				regs, _ := s.GetRegs()
-				text, _, _ := s.Disassemble(regs.RIP)
-				fmt.Printf("=> %#x (func+%#x): %s\n", regs.RIP, regs.RIP-codeBase-uint64(funcOffset), text)
+				pc := regs.GetPC()
+				text, _, _ := s.Disassemble(pc)
+				fmt.Printf("=> %#x (func+%#x): %s\n", pc, pc-codeBase-uint64(funcOffset), text)
 			}
 
 		case "next", "n":
-			// Step over: if the current instruction is a CALL, set a
-			// breakpoint after it and continue; otherwise single-step.
 			regs, _ := s.GetRegs()
-			text, instLen, _ := s.Disassemble(regs.RIP)
-			if strings.HasPrefix(strings.ToLower(text), "call") {
-				// Set a temporary breakpoint after the CALL.
-				afterAddr := regs.RIP + uint64(instLen)
-				bp, err := bm.Set(afterAddr, "(next)")
+			pc := regs.GetPC()
+			text, instLen, _ := s.Disassemble(pc)
+			if strings.HasPrefix(strings.ToLower(text), "call") || strings.HasPrefix(strings.ToLower(text), "bl") {
+				afterAddr := pc + uint64(instLen)
+				_, err := bm.Set(afterAddr, "(next)")
 				if err != nil {
 					fmt.Printf("cannot set next breakpoint: %v\n", err)
 					continue
 				}
-				// Continue until the breakpoint.
 				for _, b := range bm.All() {
 					bm.Reinsert(b.Addr)
 				}
@@ -117,9 +110,7 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				}
 				bm.HandleTrap(&regs)
 				bm.Clear(afterAddr)
-				_ = bp
 			} else {
-				// Not a CALL — just single-step.
 				if err := s.Step(); err != nil {
 					fmt.Println(err)
 					continue
@@ -127,26 +118,23 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 			}
 			if !s.Exited() {
 				regs, _ := s.GetRegs()
-				text, _, _ := s.Disassemble(regs.RIP)
-				fmt.Printf("=> %#x (func+%#x): %s\n", regs.RIP, regs.RIP-codeBase-uint64(funcOffset), text)
+				pc := regs.GetPC()
+				text, _, _ := s.Disassemble(pc)
+				fmt.Printf("=> %#x (func+%#x): %s\n", pc, pc-codeBase-uint64(funcOffset), text)
 			}
 
 		case "finish", "fin":
-			// Run until the current function returns.
-			// For NOSPLIT frame=0: return address is at [RSP].
 			regs, _ := s.GetRegs()
-			retAddr, err := s.Peek(regs.RSP)
+			retAddr, err := archReturnAddr(s, &regs)
 			if err != nil {
 				fmt.Printf("cannot read return address: %v\n", err)
 				continue
 			}
-			// Set a temporary breakpoint at the return address.
-			bp, err := bm.Set(retAddr, "(finish)")
+			_, err = bm.Set(retAddr, "(finish)")
 			if err != nil {
 				fmt.Printf("cannot set finish breakpoint: %v\n", err)
 				continue
 			}
-			// Continue until the breakpoint.
 			for _, b := range bm.All() {
 				bm.Reinsert(b.Addr)
 			}
@@ -159,12 +147,11 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				bm.HandleTrap(&regs)
 			}
 			bm.Clear(retAddr)
-			_ = bp
 			if s.Exited() {
 				fmt.Println("debuggee exited")
 			} else {
 				regs, _ := s.GetRegs()
-				fmt.Printf("finished, now at %#x\n", regs.RIP)
+				fmt.Printf("finished, now at %#x\n", regs.GetPC())
 			}
 
 		case "continue", "c":
@@ -172,9 +159,7 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				fmt.Println("debuggee exited")
 				continue
 			}
-			// Loop: continue until a breakpoint fires (condition met) or exit.
 			for {
-				// Re-insert all breakpoints before continuing.
 				for _, bp := range bm.All() {
 					bm.Reinsert(bp.Addr)
 				}
@@ -186,7 +171,6 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 					fmt.Println("debuggee exited")
 					break
 				}
-				// Check for watchpoint hits.
 				reason, wpAddr := s.StopInfo()
 				if reason == StopWatchpoint {
 					fmt.Printf("watchpoint hit at %#x\n", wpAddr)
@@ -194,6 +178,13 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				}
 				regs, _ := s.GetRegs()
 				if bp := bm.HandleTrap(&regs); bp != nil {
+					// Execute the instruction under the restored breakpoint
+					// so the next continue cannot re-trap on the same
+					// breakpoint; the process parks right after it.
+					if err := s.Step(); err != nil {
+						fmt.Println(err)
+						break
+					}
 					name := bp.Label
 					if name == "" {
 						name = fmt.Sprintf("%#x", bp.Addr)
@@ -201,7 +192,6 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 					fmt.Printf("breakpoint hit: %s (func+%#x)\n", name, bp.Addr-codeBase-uint64(funcOffset))
 					break
 				}
-				// Condition not met (or single-step trap) — re-insert and continue.
 			}
 
 		case "break", "b":
@@ -209,11 +199,9 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				fmt.Println("usage: break <label|addr|line> [if <reg> <op> <val>]")
 				continue
 			}
-			// Try as a line number first.
 			var addr uint64
 			var label string
 			if lineNum, err := strconv.Atoi(parts[1]); err == nil && lineNum > 0 {
-				// Find the byte offset for this line.
 				off := offsetForLine(lines, lineNum)
 				if off < 0 {
 					fmt.Printf("no instruction at line %d\n", lineNum)
@@ -228,17 +216,18 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				fmt.Printf("unknown label, address, or line: %s\n", parts[1])
 				continue
 			}
-			// Parse optional condition: "if <reg> <op> <value>"
 			var cond *Condition
 			if len(parts) >= 6 && parts[2] == "if" {
-				val, err := strconv.ParseUint(parts[5], 0, 64)
-				if err != nil {
-					fmt.Printf("invalid condition value: %s\n", parts[5])
-					continue
+				reg := strings.ToLower(parts[3])
+				op := parts[4]
+				operand := parts[5]
+				if val, err := strconv.ParseUint(operand, 0, 64); err == nil {
+					cond = &Condition{Reg: reg, Op: op, Value: val}
+				} else {
+					cond = &Condition{Reg: reg, Op: op, Reg2: strings.ToLower(operand)}
 				}
-				cond = &Condition{Reg: strings.ToLower(parts[3]), Op: parts[4], Value: val}
 			} else if len(parts) >= 4 && parts[2] == "if" {
-				fmt.Println("usage: break <label|addr> if <reg> <op> <value>")
+				fmt.Println("usage: break <label|addr> if <reg> <op> <value|reg>")
 				continue
 			}
 			bp, err := bm.SetWithCond(addr, label, cond)
@@ -282,7 +271,7 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 
 		case "x":
 			regs, _ := s.GetRegs()
-			addr := regs.RIP // default: current PC
+			addr := regs.GetPC()
 			length := 64
 			if len(parts) > 1 {
 				addr, _ = resolveAddr(parts[1], codeBase, uint64(funcOffset), labels)
@@ -314,9 +303,8 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 					fmt.Printf("invalid value: %s\n", arg)
 					continue
 				}
-				// Write as 8-byte word if it looks like a large value, else single byte.
 				if v > 255 {
-					for j := 0; j < 8; j++ {
+					for j := range 8 {
 						bytes = append(bytes, byte(v>>(8*j)))
 					}
 				} else {
@@ -364,11 +352,11 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				}
 			}
 			regs, _ := s.GetRegs()
-			fmt.Print(s.DisassembleN(regs.RIP, n))
+			fmt.Print(s.DisassembleN(regs.GetPC(), n))
 
 		case "where":
 			regs, _ := s.GetRegs()
-			funcOff := int(regs.RIP - codeBase - uint64(funcOffset))
+			funcOff := int(regs.GetPC() - codeBase - uint64(funcOffset))
 			line := lineAt(lines, funcOff)
 			label := nearestLabel(labels, funcOff)
 			fmt.Printf("  func+%#x", funcOff)
@@ -381,32 +369,32 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 			fmt.Println()
 
 		case "help", "h", "?":
-			fmt.Println(`  break <label|addr> [if <reg> <op> <val>]  set a breakpoint
+			fmt.Printf(`  break <label|addr> [if <reg> <op> <val>]  set a breakpoint
   delete <label|addr>  remove a breakpoint
   info break           list all breakpoints
   watch <addr> [r|w] [size]  set a hardware watchpoint (write by default)
   unwatch [<slot>]     clear one or all watchpoints
   step [n], s          single-step n instructions
-  next, n              step over CALL
+  next, n              step over CALL/BL
   continue, c          run until breakpoint or exit
   disas [n], u         disassemble n instructions at PC
-  regs                 print registers and RFLAGS
+  regs                 print registers
   where                show source line and nearest label
-  stack                show stack near RSP (args + return address)
+  stack                show stack near %s (args + return address)
   x [addr] [len]       hex-dump memory
   w <addr> <val...>    write bytes to memory
   labels, l            list function labels
   help, h, ?           this help
-  quit, q              kill debuggee and exit`)
+  quit, q              kill debuggee and exit`, archSPLabel())
 
 		case "stack":
 			regs, _ := s.GetRegs()
-			// For NOSPLIT frame=0: [RSP] = return address, [RSP+8..] = args.
-			retAddr, _ := s.Peek(regs.RSP)
-			fmt.Printf("  [RSP]   return addr = %#x\n", retAddr)
+			sp := regs.GetSP()
+			retAddr, _ := archReturnAddr(s, &regs)
+			fmt.Printf("  [%s]   return addr = %#x\n", archSPLabel(), retAddr)
 			if argsSize > 0 {
-				fmt.Printf("  args (%d bytes at RSP+8):\n", argsSize)
-				argBytes, err := s.ReadMemory(regs.RSP+8, argsSize)
+				fmt.Printf("  args (%d bytes at %s+8):\n", argsSize, archSPLabel())
+				argBytes, err := s.ReadMemory(sp+8, argsSize)
 				if err == nil {
 					for i := 0; i < argsSize; i += 8 {
 						var v uint64
@@ -420,7 +408,7 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 
 		case "bt", "backtrace":
 			regs, _ := s.GetRegs()
-			funcOff := int(regs.RIP - codeBase - uint64(funcOffset))
+			funcOff := int(regs.GetPC() - codeBase - uint64(funcOffset))
 			line := lineAt(lines, funcOff)
 			label := nearestLabel(labels, funcOff)
 			fmt.Printf("  #0  func+%#x", funcOff)
@@ -431,7 +419,7 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 				fmt.Printf(" [line %d]", line)
 			}
 			fmt.Println()
-			retAddr, _ := s.Peek(regs.RSP)
+			retAddr, _ := archReturnAddr(s, &regs)
 			fmt.Printf("  #1  return to %#x\n", retAddr)
 
 		case "watch":
@@ -499,80 +487,9 @@ func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, ar
 	s.Kill()
 }
 
-func printRegs(regs *Regs, codeBase, funcOff uint64) {
-	fmt.Printf("  RIP = %#016x  (func+%#x)\n", regs.RIP, regs.RIP-codeBase-funcOff)
-	fmt.Printf("  RSP = %#016x  RBP = %#016x\n", regs.RSP, regs.RBP)
-	fmt.Printf("  RAX = %#016x  RBX = %#016x\n", regs.RAX, regs.RBX)
-	fmt.Printf("  RCX = %#016x  RDX = %#016x\n", regs.RCX, regs.RDX)
-	fmt.Printf("  RSI = %#016x  RDI = %#016x\n", regs.RSI, regs.RDI)
-	fmt.Printf("  R8  = %#016x  R9  = %#016x\n", regs.R8, regs.R9)
-	fmt.Printf("  R10 = %#016x  R11 = %#016x\n", regs.R10, regs.R11)
-	fmt.Printf("  R12 = %#016x  R13 = %#016x\n", regs.R12, regs.R13)
-	fmt.Printf("  R14 = %#016x  R15 = %#016x\n", regs.R14, regs.R15)
-	fmt.Printf("  RFLAGS = %#x  [%s]\n", regs.RFLAGS, decodeRflags(regs.RFLAGS))
-}
-
-// printVectorRegs displays the YMM registers.
-func printVectorRegs(v *VectorRegs) {
-	fmt.Println("\n  Vector registers (YMM):")
-	for i := 0; i < 16; i += 2 {
-		fmt.Printf("  YMM%-2d = ", i)
-		printYMM(v.YMM[i][:])
-		fmt.Printf("  YMM%-2d = ", i+1)
-		printYMM(v.YMM[i+1][:])
-		fmt.Println()
-	}
-}
-
-func printYMM(b []byte) {
-	// Show as 8 32-bit values.
-	for j := 0; j < 32; j += 4 {
-		v := uint32(b[j]) | uint32(b[j+1])<<8 | uint32(b[j+2])<<16 | uint32(b[j+3])<<24
-		fmt.Printf("%08x ", v)
-	}
-}
-
-func decodeRflags(f uint64) string {
-	var flags string
-	if f&1 != 0 {
-		flags += "CF "
-	}
-	if f&(1<<2) != 0 {
-		flags += "PF "
-	}
-	if f&(1<<4) != 0 {
-		flags += "AF "
-	}
-	if f&(1<<6) != 0 {
-		flags += "ZF "
-	}
-	if f&(1<<7) != 0 {
-		flags += "SF "
-	}
-	if f&(1<<8) != 0 {
-		flags += "TF "
-	}
-	if f&(1<<9) != 0 {
-		flags += "IF "
-	}
-	if f&(1<<10) != 0 {
-		flags += "DF "
-	}
-	if f&(1<<11) != 0 {
-		flags += "OF "
-	}
-	if flags == "" {
-		return "none"
-	}
-	return flags[:len(flags)-1] // trim trailing space
-}
-
 func hexDump(addr uint64, data []byte) {
 	for i := 0; i < len(data); i += 16 {
-		end := i + 16
-		if end > len(data) {
-			end = len(data)
-		}
+		end := min(i+16, len(data))
 		fmt.Printf("  %#08x:", addr+uint64(i))
 		for j := i; j < i+16; j++ {
 			if j < end {
@@ -594,21 +511,18 @@ func hexDump(addr uint64, data []byte) {
 }
 
 func resolveAddr(s string, codeBase, funcOff uint64, labels []Label) (uint64, string) {
-	// Try as a hex address.
 	if strings.HasPrefix(s, "0x") || strings.HasPrefix(s, "0X") {
 		v, err := strconv.ParseUint(s, 0, 64)
 		if err == nil {
 			return v, ""
 		}
 	}
-	// Try as func+offset.
 	if strings.HasPrefix(s, "+") {
 		off, err := strconv.ParseUint(s[1:], 0, 64)
 		if err == nil {
 			return codeBase + funcOff + off, fmt.Sprintf("func+%#x", off)
 		}
 	}
-	// Try as a label name.
 	for _, l := range labels {
 		if l.Name == s {
 			return codeBase + funcOff + uint64(l.Offset), l.Name
@@ -617,7 +531,6 @@ func resolveAddr(s string, codeBase, funcOff uint64, labels []Label) (uint64, st
 	return 0, ""
 }
 
-// lineAt returns the source line for a given function-relative offset.
 func lineAt(lines []SourceLine, offset int) int {
 	if len(lines) == 0 {
 		return 0
@@ -637,8 +550,6 @@ func lineAt(lines []SourceLine, offset int) int {
 	return 0
 }
 
-// offsetForLine returns the byte offset for a given source line number.
-// Returns -1 if no instruction is at that line.
 func offsetForLine(lines []SourceLine, line int) int {
 	for _, le := range lines {
 		if le.Line == line {
@@ -648,7 +559,6 @@ func offsetForLine(lines []SourceLine, line int) int {
 	return -1
 }
 
-// nearestLabel returns the name of the label at or just before the offset.
 func nearestLabel(labels []Label, offset int) string {
 	best := ""
 	bestOff := -1

debug/stopinfo_linux.go

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux
+
+package debug
+
+import (
+	"syscall"
+	"unsafe"
+)
+
+// StopReason describes why the debuggee stopped.
+type StopReason int
+
+const (
+	StopNone       StopReason = iota
+	StopBreakpoint            // software breakpoint hit
+	StopWatchpoint            // hardware watchpoint triggered
+	StopSingleStep            // single-step completed
+	StopSignal                // stopped by a signal
+	StopExited                // process exited
+)
+
+// siginfo_t layout (Linux): si_signo, si_errno, si_code, then union.
+// The si_addr field is at offset 16 on all supported architectures.
+type siginfoT struct {
+	SiSigno int32
+	SiErrno int32
+	SiCode  int32
+	_pad    [125]byte
+}
+
+const (
+	trapBRKPT   = 1 // software breakpoint
+	trapHWBRKPT = 4 // hardware watchpoint
+)
+
+// StopInfo returns the reason the debuggee stopped and the faulting address
+// (for watchpoints, the watched address that was accessed).
+func (s *Session) StopInfo() (StopReason, uint64) {
+	if s.exited {
+		return StopExited, 0
+	}
+	var info siginfoT
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETSIGINFO),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&info)),
+		0, 0,
+	)
+	if errno != 0 {
+		return StopNone, 0
+	}
+	if info.SiSigno != int32(syscall.SIGTRAP) {
+		return StopSignal, uint64(info.SiCode)
+	}
+	switch info.SiCode {
+	case trapBRKPT:
+		return StopBreakpoint, 0
+	case trapHWBRKPT:
+		addr := *(*uint64)(unsafe.Add(unsafe.Pointer(&info), 16))
+		return StopWatchpoint, addr
+	default:
+		return StopSingleStep, 0
+	}
+}

debug/stopinfo_linux_amd64.go

@@ -5,69 +5,7 @@
 
 package debug
 
-import (
-	"fmt"
-	"syscall"
-	"unsafe"
-)
-
-// StopReason describes why the debuggee stopped.
-type StopReason int
-
-const (
-	StopNone       StopReason = iota
-	StopBreakpoint            // INT3 breakpoint hit
-	StopWatchpoint            // hardware watchpoint triggered
-	StopSingleStep            // single-step completed
-	StopSignal                // stopped by a signal
-	StopExited                // process exited
-)
-
-// siginfo_t layout (Linux amd64): si_signo, si_errno, si_code, then union.
-type siginfoT struct {
-	SiSigno int32
-	SiErrno int32
-	SiCode  int32
-	_pad    [125]byte
-}
-
-const (
-	trapBRKPT   = 1 // INT3 breakpoint
-	trapHWBRKPT = 4 // hardware watchpoint
-)
-
-// StopInfo returns the reason the debuggee stopped and the faulting address
-// (for watchpoints, the watched address that was accessed).
-func (s *Session) StopInfo() (StopReason, uint64) {
-	if s.exited {
-		return StopExited, 0
-	}
-	var info siginfoT
-	_, _, errno := syscall.Syscall6(
-		syscall.SYS_PTRACE,
-		uintptr(syscall.PTRACE_GETSIGINFO),
-		uintptr(s.pid),
-		0,
-		uintptr(unsafe.Pointer(&info)),
-		0, 0,
-	)
-	if errno != 0 {
-		return StopNone, 0
-	}
-	if info.SiSigno != int32(syscall.SIGTRAP) {
-		return StopSignal, uint64(info.SiCode)
-	}
-	switch info.SiCode {
-	case trapBRKPT:
-		return StopBreakpoint, 0
-	case trapHWBRKPT:
-		// The faulting address is in si_addr (offset 16 in siginfo_t on amd64).
-		addr := *(*uint64)(unsafe.Pointer(uintptr(unsafe.Pointer(&info)) + 16))
-		return StopWatchpoint, addr
-	default:
-		return StopSingleStep, 0
-	}
-}
+import "fmt"
 
 // SetReg modifies a register value in the debuggee.
 func (s *Session) SetReg(name string, value uint64) error {

debug/stopinfo_linux_arm64.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+import "fmt"
+
+// SetReg modifies a register value in the debuggee.
+func (s *Session) SetReg(name string, value uint64) error {
+	regs, err := s.GetRegs()
+	if err != nil {
+		return err
+	}
+	switch name {
+	case "x0":
+		regs.X0 = value
+	case "x1":
+		regs.X1 = value
+	case "x2":
+		regs.X2 = value
+	case "x3":
+		regs.X3 = value
+	case "x4":
+		regs.X4 = value
+	case "x5":
+		regs.X5 = value
+	case "x6":
+		regs.X6 = value
+	case "x7":
+		regs.X7 = value
+	case "x8":
+		regs.X8 = value
+	case "x9":
+		regs.X9 = value
+	case "x10":
+		regs.X10 = value
+	case "x11":
+		regs.X11 = value
+	case "x12":
+		regs.X12 = value
+	case "x13":
+		regs.X13 = value
+	case "x14":
+		regs.X14 = value
+	case "x15":
+		regs.X15 = value
+	case "x16":
+		regs.X16 = value
+	case "x17":
+		regs.X17 = value
+	case "x18":
+		regs.X18 = value
+	case "x19":
+		regs.X19 = value
+	case "x20":
+		regs.X20 = value
+	case "x21":
+		regs.X21 = value
+	case "x22":
+		regs.X22 = value
+	case "x23":
+		regs.X23 = value
+	case "x24":
+		regs.X24 = value
+	case "x25":
+		regs.X25 = value
+	case "x26":
+		regs.X26 = value
+	case "x27":
+		regs.X27 = value
+	case "x28":
+		regs.X28 = value
+	case "x29", "fp":
+		regs.X29 = value
+	case "x30", "lr":
+		regs.X30 = value
+	case "sp":
+		regs.SP = value
+	case "pc":
+		regs.PC = value
+	default:
+		return fmt.Errorf("debug: unknown register %q", name)
+	}
+	return s.SetRegs(&regs)
+}

debug/stopinfo_linux_loong64.go

@@ -0,0 +1,85 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+import "fmt"
+
+// SetReg modifies a register value in the debuggee.
+func (s *Session) SetReg(name string, value uint64) error {
+	regs, err := s.GetRegs()
+	if err != nil {
+		return err
+	}
+	switch name {
+	case "r0", "zero":
+		regs.R0 = value
+	case "r1", "ra":
+		regs.R1 = value
+	case "r2", "tp":
+		regs.R2 = value
+	case "r3", "sp":
+		regs.R3 = value
+	case "r4", "a0":
+		regs.R4 = value
+	case "r5", "a1":
+		regs.R5 = value
+	case "r6", "a2":
+		regs.R6 = value
+	case "r7", "a3":
+		regs.R7 = value
+	case "r8", "a4":
+		regs.R8 = value
+	case "r9", "a5":
+		regs.R9 = value
+	case "r10", "a6":
+		regs.R10 = value
+	case "r11", "a7":
+		regs.R11 = value
+	case "r12", "t0":
+		regs.R12 = value
+	case "r13", "t1":
+		regs.R13 = value
+	case "r14", "t2":
+		regs.R14 = value
+	case "r15", "t3":
+		regs.R15 = value
+	case "r16", "t4":
+		regs.R16 = value
+	case "r17", "t5":
+		regs.R17 = value
+	case "r18", "t6":
+		regs.R18 = value
+	case "r19", "t7":
+		regs.R19 = value
+	case "r20", "t8":
+		regs.R20 = value
+	case "r21", "fp":
+		regs.R21 = value
+	case "r22", "s0":
+		regs.R22 = value
+	case "r23", "s1":
+		regs.R23 = value
+	case "r24", "s2":
+		regs.R24 = value
+	case "r25", "s3":
+		regs.R25 = value
+	case "r26", "s4":
+		regs.R26 = value
+	case "r27", "s5":
+		regs.R27 = value
+	case "r28", "s6":
+		regs.R28 = value
+	case "r29", "s7":
+		regs.R29 = value
+	case "r30", "s8":
+		regs.R30 = value
+	case "r31", "pc":
+		regs.R31 = value
+	default:
+		return fmt.Errorf("debug: unknown register %q", name)
+	}
+	return s.SetRegs(&regs)
+}

debug/stopinfo_linux_riscv64.go

@@ -0,0 +1,85 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+import "fmt"
+
+// SetReg modifies a register value in the debuggee.
+func (s *Session) SetReg(name string, value uint64) error {
+	regs, err := s.GetRegs()
+	if err != nil {
+		return err
+	}
+	switch name {
+	case "pc":
+		regs.PC = value
+	case "ra", "x1":
+		regs.Ra = value
+	case "sp", "x2":
+		regs.Sp = value
+	case "gp", "x3":
+		regs.Gp = value
+	case "tp", "x4":
+		regs.Tp = value
+	case "t0", "x5":
+		regs.T0 = value
+	case "t1", "x6":
+		regs.T1 = value
+	case "t2", "x7":
+		regs.T2 = value
+	case "s0", "fp", "x8":
+		regs.S0 = value
+	case "s1", "x9":
+		regs.S1 = value
+	case "a0", "x10":
+		regs.A0 = value
+	case "a1", "x11":
+		regs.A1 = value
+	case "a2", "x12":
+		regs.A2 = value
+	case "a3", "x13":
+		regs.A3 = value
+	case "a4", "x14":
+		regs.A4 = value
+	case "a5", "x15":
+		regs.A5 = value
+	case "a6", "x16":
+		regs.A6 = value
+	case "a7", "x17":
+		regs.A7 = value
+	case "s2", "x18":
+		regs.S2 = value
+	case "s3", "x19":
+		regs.S3 = value
+	case "s4", "x20":
+		regs.S4 = value
+	case "s5", "x21":
+		regs.S5 = value
+	case "s6", "x22":
+		regs.S6 = value
+	case "s7", "x23":
+		regs.S7 = value
+	case "s8", "x24":
+		regs.S8 = value
+	case "s9", "x25":
+		regs.S9 = value
+	case "s10", "x26":
+		regs.S10 = value
+	case "s11", "x27":
+		regs.S11 = value
+	case "t3", "x28":
+		regs.T3 = value
+	case "t4", "x29":
+		regs.T4 = value
+	case "t5", "x30":
+		regs.T5 = value
+	case "t6", "x31":
+		regs.T6 = value
+	default:
+		return fmt.Errorf("debug: unknown register %q", name)
+	}
+	return s.SetRegs(&regs)
+}

debug/target_linux.go

@@ -0,0 +1,99 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux
+
+package debug
+
+import (
+	"encoding/hex"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"syscall"
+	"unsafe"
+)
+
+// mapRWX maps code into a read-write-execute region.
+func mapRWX(code []byte) ([]byte, error) {
+	const pageSize = 4096
+	size := (len(code) + pageSize - 1) &^ (pageSize - 1)
+	mem, err := syscall.Mmap(-1, 0, size,
+		syscall.PROT_READ|syscall.PROT_WRITE|syscall.PROT_EXEC,
+		syscall.MAP_PRIVATE|syscall.MAP_ANON)
+	if err != nil {
+		return nil, err
+	}
+	copy(mem, code)
+	return mem, nil
+}
+
+// setupBuffers allocates buffers in the debuggee's memory.
+func setupBuffers(spec string, args []byte, tmpDir string) ([]byte, error) {
+	type bufSpec struct {
+		name    string
+		size    int
+		pattern string
+	}
+	var specs []bufSpec
+	for part := range strings.SplitSeq(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) != 3 {
+			continue
+		}
+		size, err := strconv.Atoi(fields[1])
+		if err != nil || size <= 0 {
+			continue
+		}
+		specs = append(specs, bufSpec{name: fields[0], size: size, pattern: fields[2]})
+	}
+
+	if len(specs) == 0 {
+		return args, nil
+	}
+
+	var bufAddrs []uint64
+	for _, s := range specs {
+		buf, err := syscall.Mmap(-1, 0, s.size,
+			syscall.PROT_READ|syscall.PROT_WRITE,
+			syscall.MAP_PRIVATE|syscall.MAP_ANON)
+		if err != nil {
+			return nil, fmt.Errorf("mmap buffer %s: %w", s.name, err)
+		}
+		fillBuffer(buf, s.pattern)
+		bufAddrs = append(bufAddrs, uint64(uintptr(unsafe.Pointer(&buf[0]))))
+	}
+
+	addrFile, err := os.Create(tmpDir + "/bufaddrs")
+	if err != nil {
+		return nil, err
+	}
+	for _, addr := range bufAddrs {
+		fmt.Fprintf(addrFile, "%d\n", addr)
+	}
+	addrFile.Close()
+
+	return args, nil
+}
+
+// fillBuffer fills a buffer with the specified pattern.
+func fillBuffer(buf []byte, pattern string) {
+	switch pattern {
+	case "zero":
+	case "ones":
+		for i := range buf {
+			buf[i] = 0xFF
+		}
+	case "seq":
+		for i := range buf {
+			buf[i] = byte(i)
+		}
+	default:
+		if data, err := hex.DecodeString(pattern); err == nil && len(data) > 0 {
+			for i := range buf {
+				buf[i] = data[i%len(data)]
+			}
+		}
+	}
+}

debug/target_linux_amd64.go

@@ -6,12 +6,9 @@
 package debug
 
 import (
-	"encoding/hex"
 	"fmt"
 	"os"
 	"runtime"
-	"strconv"
-	"strings"
 	"syscall"
 	"unsafe"
 
@@ -20,12 +17,8 @@ import (
 	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
 )
 
-// RunTarget is the debuggee entry point (gasm debug --target).  It
-// assembles the file, maps the JIT code, registers itself for ptrace,
-// stops, and then executes the named function.  The parent debugger
-// controls execution from there.
+// RunTarget is the debuggee entry point (gasm debug --target).
 func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
-	// Parse and assemble.
 	src, err := os.ReadFile(asmPath)
 	if err != nil {
 		return fmt.Errorf("debug target: %w", err)
@@ -39,7 +32,6 @@ func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
 		return fmt.Errorf("debug target: assemble: %w", err)
 	}
 
-	// Find the function.
 	var fl *asm.FuncLayout
 	for i := range img.Funcs {
 		if img.Funcs[i].Name == funcName {
@@ -51,24 +43,20 @@ func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
 		return fmt.Errorf("debug target: function %q not found", funcName)
 	}
 
-	// Map the entire image RWX (we need write access for breakpoints).
 	code := img.Bytes()
 	exec, err := mapRWX(code)
 	if err != nil {
 		return fmt.Errorf("debug target: mmap: %w", err)
 	}
 
-	// Write the code base address for the parent.
 	codeBase := uintptr(unsafe.Pointer(&exec[0]))
 	if err := os.WriteFile(tmpDir+"/codebase", []byte(fmt.Sprintf("%d", codeBase)), 0o644); err != nil {
 		return fmt.Errorf("debug target: write codebase: %w", err)
 	}
 
-	// Write function metadata (offset, size, args) for the parent.
 	meta := fmt.Sprintf("%d %d %d", fl.Offset, fl.Size, fl.Args)
 	os.WriteFile(tmpDir+"/funcmeta", []byte(meta), 0o644)
 
-	// Write label table for breakpoint resolution.
 	labelsFile, _ := os.Create(tmpDir + "/labels")
 	if labelsFile != nil {
 		for label, off := range fl.Labels {
@@ -77,7 +65,6 @@ func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
 		labelsFile.Close()
 	}
 
-	// Read the argument block.
 	args, err := os.ReadFile(argsFile)
 	if err != nil {
 		return fmt.Errorf("debug target: read args: %w", err)
@@ -88,140 +75,33 @@ func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
 		args = padded
 	}
 
-	// Read buffer specification if present.
 	bufSpecFile := tmpDir + "/bufspec"
 	if bufSpec, err := os.ReadFile(bufSpecFile); err == nil && len(bufSpec) > 0 {
-		args, err = setupBuffers(string(bufSpec), args, fl.Args, tmpDir)
+		args, err = setupBuffers(string(bufSpec), args, tmpDir)
 		if err != nil {
 			return fmt.Errorf("debug target: setup buffers: %w", err)
 		}
 	}
 
-	// Lock this goroutine to the current OS thread so the parent's
-	// ptrace (attached to this thread) controls the JIT execution.
 	runtime.LockOSThread()
 
-	// Request tracing by the parent, then stop.  PTRACE_TRACEME makes
-	// the subsequent SIGSTOP a ptrace-stop (not a group-stop), giving
-	// the parent full control from the start.
 	if _, _, errno := syscall.Syscall(syscall.SYS_PTRACE, uintptr(syscall.PTRACE_TRACEME), 0, 0); errno != 0 {
 		return fmt.Errorf("debug target: PTRACE_TRACEME: %v", errno)
 	}
 	os.WriteFile(tmpDir+"/ready", []byte("ok"), 0o644)
 	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
 
-	// --- Execution resumes here after the parent continues us ---
-
-	// Stop at the function entry point so the debugger can set breakpoints.
-	// The parent will continue us when ready.
 	os.WriteFile(tmpDir+"/entry", []byte("ok"), 0o644)
 	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
 
-	// Prepare the ABI0 stack and call the function.
 	fnAddr := codeBase + uintptr(fl.Offset)
 	stackArgs := make([]byte, fl.Args)
 	copy(stackArgs, args)
 
-	_, callErr := verify.Call(fnAddr, stackArgs)
-	if callErr != nil {
-		// The function returned an error (shouldn't happen for valid code).
+	if _, callErr := verify.Call(fnAddr, stackArgs); callErr != nil {
 		os.Exit(1)
 	}
-	os.Exit(0)
+	// Success returns to the caller, which exits with status 0; the JIT
+	// code has already run to its own trampoline by the time Call returns.
 	return nil
 }
-
-// mapRWX maps code into a read-write-execute region (needed for
-// breakpoint patching via ptrace POKETEXT, though ptrace can write
-// to any mapping regardless of permissions).
-func mapRWX(code []byte) ([]byte, error) {
-	const pageSize = 4096
-	size := (len(code) + pageSize - 1) &^ (pageSize - 1)
-	mem, err := syscall.Mmap(-1, 0, size,
-		syscall.PROT_READ|syscall.PROT_WRITE|syscall.PROT_EXEC,
-		syscall.MAP_PRIVATE|syscall.MAP_ANON)
-	if err != nil {
-		return nil, err
-	}
-	copy(mem, code)
-	return mem, nil
-}
-
-// setupBuffers allocates buffers in the debuggee's memory and updates the
-// argument block with pointers to them.
-// Format: name:size:pattern[,name:size:pattern...]
-// Patterns: zero, ones, seq, or hex (e.g. "deadbeef").
-func setupBuffers(spec string, args []byte, argSize int, tmpDir string) ([]byte, error) {
-	// Parse the buffer spec.
-	type bufSpec struct {
-		name    string
-		size    int
-		pattern string
-	}
-	var specs []bufSpec
-	for _, part := range strings.Split(spec, ",") {
-		fields := strings.SplitN(part, ":", 3)
-		if len(fields) != 3 {
-			continue
-		}
-		size, err := strconv.Atoi(fields[1])
-		if err != nil || size <= 0 {
-			continue
-		}
-		specs = append(specs, bufSpec{name: fields[0], size: size, pattern: fields[2]})
-	}
-
-	if len(specs) == 0 {
-		return args, nil
-	}
-
-	// Allocate buffers and write their addresses to a file for the parent.
-	var bufAddrs []uint64
-	for _, s := range specs {
-		buf, err := syscall.Mmap(-1, 0, s.size,
-			syscall.PROT_READ|syscall.PROT_WRITE,
-			syscall.MAP_PRIVATE|syscall.MAP_ANON)
-		if err != nil {
-			return nil, fmt.Errorf("mmap buffer %s: %w", s.name, err)
-		}
-		fillBuffer(buf, s.pattern)
-		bufAddrs = append(bufAddrs, uint64(uintptr(unsafe.Pointer(&buf[0]))))
-	}
-
-	// Write buffer addresses to a file for the parent to read.
-	addrFile, err := os.Create(tmpDir + "/bufaddrs")
-	if err != nil {
-		return nil, err
-	}
-	for _, addr := range bufAddrs {
-		fmt.Fprintf(addrFile, "%d\n", addr)
-	}
-	addrFile.Close()
-
-	// For now, return the args unchanged. The parent will read bufaddrs
-	// and construct the final argument block with the correct pointers.
-	return args, nil
-}
-
-// fillBuffer fills a buffer with the specified pattern.
-func fillBuffer(buf []byte, pattern string) {
-	switch pattern {
-	case "zero":
-		// Already zeroed by mmap.
-	case "ones":
-		for i := range buf {
-			buf[i] = 0xFF
-		}
-	case "seq":
-		for i := range buf {
-			buf[i] = byte(i)
-		}
-	default:
-		// Try to parse as hex.
-		if data, err := hex.DecodeString(pattern); err == nil && len(data) > 0 {
-			for i := range buf {
-				buf[i] = data[i%len(data)]
-			}
-		}
-	}
-}

debug/target_linux_arm64.go

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+	"syscall"
+	"unsafe"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+// RunTarget is the debuggee entry point (gasm debug --target).
+func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
+	src, err := os.ReadFile(asmPath)
+	if err != nil {
+		return fmt.Errorf("debug target: %w", err)
+	}
+	file, errs := parser.Parse(asmPath, string(src))
+	if len(errs) > 0 {
+		return fmt.Errorf("debug target: parse: %v", errs[0])
+	}
+
+	var img *asm.Image
+	switch "arm64" {
+	case "arm64":
+		img, err = asm.AssembleFileARM64(file)
+	case "riscv64":
+		img, err = asm.AssembleFileRISCV(file)
+	case "loong64":
+		img, err = asm.AssembleFileLOONG64(file)
+	}
+	if err != nil {
+		return fmt.Errorf("debug target: assemble: %w", err)
+	}
+
+	var fl *asm.FuncLayout
+	for i := range img.Funcs {
+		if img.Funcs[i].Name == funcName {
+			fl = &img.Funcs[i]
+			break
+		}
+	}
+	if fl == nil {
+		return fmt.Errorf("debug target: function %q not found", funcName)
+	}
+
+	code := img.Bytes()
+	exec, err := mapRWX(code)
+	if err != nil {
+		return fmt.Errorf("debug target: mmap: %w", err)
+	}
+
+	codeBase := uintptr(unsafe.Pointer(&exec[0]))
+	if err := os.WriteFile(tmpDir+"/codebase", []byte(fmt.Sprintf("%d", codeBase)), 0o644); err != nil {
+		return fmt.Errorf("debug target: write codebase: %w", err)
+	}
+
+	meta := fmt.Sprintf("%d %d %d", fl.Offset, fl.Size, fl.Args)
+	os.WriteFile(tmpDir+"/funcmeta", []byte(meta), 0o644)
+
+	labelsFile, _ := os.Create(tmpDir + "/labels")
+	if labelsFile != nil {
+		for label, off := range fl.Labels {
+			fmt.Fprintf(labelsFile, "%s %d\n", label, off)
+		}
+		labelsFile.Close()
+	}
+
+	args, err := os.ReadFile(argsFile)
+	if err != nil {
+		return fmt.Errorf("debug target: read args: %w", err)
+	}
+	if len(args) < fl.Args {
+		padded := make([]byte, fl.Args)
+		copy(padded, args)
+		args = padded
+	}
+
+	bufSpecFile := tmpDir + "/bufspec"
+	if bufSpec, err := os.ReadFile(bufSpecFile); err == nil && len(bufSpec) > 0 {
+		args, err = setupBuffers(string(bufSpec), args, tmpDir)
+		if err != nil {
+			return fmt.Errorf("debug target: setup buffers: %w", err)
+		}
+	}
+
+	runtime.LockOSThread()
+
+	if _, _, errno := syscall.Syscall(syscall.SYS_PTRACE, uintptr(syscall.PTRACE_TRACEME), 0, 0); errno != 0 {
+		return fmt.Errorf("debug target: PTRACE_TRACEME: %v", errno)
+	}
+	os.WriteFile(tmpDir+"/ready", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	os.WriteFile(tmpDir+"/entry", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	fnAddr := codeBase + uintptr(fl.Offset)
+	stackArgs := make([]byte, fl.Args)
+	copy(stackArgs, args)
+
+	_, callErr := verify.Call(fnAddr, stackArgs)
+	if callErr != nil {
+		os.Exit(1)
+	}
+	os.Exit(0)
+	return nil
+}

debug/target_linux_loong64.go

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+	"syscall"
+	"unsafe"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+// RunTarget is the debuggee entry point (gasm debug --target).
+func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
+	src, err := os.ReadFile(asmPath)
+	if err != nil {
+		return fmt.Errorf("debug target: %w", err)
+	}
+	file, errs := parser.Parse(asmPath, string(src))
+	if len(errs) > 0 {
+		return fmt.Errorf("debug target: parse: %v", errs[0])
+	}
+
+	var img *asm.Image
+	switch "loong64" {
+	case "arm64":
+		img, err = asm.AssembleFileARM64(file)
+	case "riscv64":
+		img, err = asm.AssembleFileRISCV(file)
+	case "loong64":
+		img, err = asm.AssembleFileLOONG64(file)
+	}
+	if err != nil {
+		return fmt.Errorf("debug target: assemble: %w", err)
+	}
+
+	var fl *asm.FuncLayout
+	for i := range img.Funcs {
+		if img.Funcs[i].Name == funcName {
+			fl = &img.Funcs[i]
+			break
+		}
+	}
+	if fl == nil {
+		return fmt.Errorf("debug target: function %q not found", funcName)
+	}
+
+	code := img.Bytes()
+	exec, err := mapRWX(code)
+	if err != nil {
+		return fmt.Errorf("debug target: mmap: %w", err)
+	}
+
+	codeBase := uintptr(unsafe.Pointer(&exec[0]))
+	if err := os.WriteFile(tmpDir+"/codebase", []byte(fmt.Sprintf("%d", codeBase)), 0o644); err != nil {
+		return fmt.Errorf("debug target: write codebase: %w", err)
+	}
+
+	meta := fmt.Sprintf("%d %d %d", fl.Offset, fl.Size, fl.Args)
+	os.WriteFile(tmpDir+"/funcmeta", []byte(meta), 0o644)
+
+	labelsFile, _ := os.Create(tmpDir + "/labels")
+	if labelsFile != nil {
+		for label, off := range fl.Labels {
+			fmt.Fprintf(labelsFile, "%s %d\n", label, off)
+		}
+		labelsFile.Close()
+	}
+
+	args, err := os.ReadFile(argsFile)
+	if err != nil {
+		return fmt.Errorf("debug target: read args: %w", err)
+	}
+	if len(args) < fl.Args {
+		padded := make([]byte, fl.Args)
+		copy(padded, args)
+		args = padded
+	}
+
+	bufSpecFile := tmpDir + "/bufspec"
+	if bufSpec, err := os.ReadFile(bufSpecFile); err == nil && len(bufSpec) > 0 {
+		args, err = setupBuffers(string(bufSpec), args, tmpDir)
+		if err != nil {
+			return fmt.Errorf("debug target: setup buffers: %w", err)
+		}
+	}
+
+	runtime.LockOSThread()
+
+	if _, _, errno := syscall.Syscall(syscall.SYS_PTRACE, uintptr(syscall.PTRACE_TRACEME), 0, 0); errno != 0 {
+		return fmt.Errorf("debug target: PTRACE_TRACEME: %v", errno)
+	}
+	os.WriteFile(tmpDir+"/ready", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	os.WriteFile(tmpDir+"/entry", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	fnAddr := codeBase + uintptr(fl.Offset)
+	stackArgs := make([]byte, fl.Args)
+	copy(stackArgs, args)
+
+	_, callErr := verify.Call(fnAddr, stackArgs)
+	if callErr != nil {
+		os.Exit(1)
+	}
+	os.Exit(0)
+	return nil
+}

debug/target_linux_riscv64.go

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+	"syscall"
+	"unsafe"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+// RunTarget is the debuggee entry point (gasm debug --target).
+func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
+	src, err := os.ReadFile(asmPath)
+	if err != nil {
+		return fmt.Errorf("debug target: %w", err)
+	}
+	file, errs := parser.Parse(asmPath, string(src))
+	if len(errs) > 0 {
+		return fmt.Errorf("debug target: parse: %v", errs[0])
+	}
+
+	img, err := asm.AssembleFileRISCV(file)
+	if err != nil {
+		return fmt.Errorf("debug target: assemble: %w", err)
+	}
+
+	var fl *asm.FuncLayout
+	for i := range img.Funcs {
+		if img.Funcs[i].Name == funcName {
+			fl = &img.Funcs[i]
+			break
+		}
+	}
+	if fl == nil {
+		return fmt.Errorf("debug target: function %q not found", funcName)
+	}
+
+	code := img.Bytes()
+	exec, err := mapRWX(code)
+	if err != nil {
+		return fmt.Errorf("debug target: mmap: %w", err)
+	}
+
+	codeBase := uintptr(unsafe.Pointer(&exec[0]))
+	if err := os.WriteFile(tmpDir+"/codebase", []byte(fmt.Sprintf("%d", codeBase)), 0o644); err != nil {
+		return fmt.Errorf("debug target: write codebase: %w", err)
+	}
+
+	meta := fmt.Sprintf("%d %d %d", fl.Offset, fl.Size, fl.Args)
+	os.WriteFile(tmpDir+"/funcmeta", []byte(meta), 0o644)
+
+	labelsFile, _ := os.Create(tmpDir + "/labels")
+	if labelsFile != nil {
+		for label, off := range fl.Labels {
+			fmt.Fprintf(labelsFile, "%s %d\n", label, off)
+		}
+		labelsFile.Close()
+	}
+
+	args, err := os.ReadFile(argsFile)
+	if err != nil {
+		return fmt.Errorf("debug target: read args: %w", err)
+	}
+	if len(args) < fl.Args {
+		padded := make([]byte, fl.Args)
+		copy(padded, args)
+		args = padded
+	}
+
+	bufSpecFile := tmpDir + "/bufspec"
+	if bufSpec, err := os.ReadFile(bufSpecFile); err == nil && len(bufSpec) > 0 {
+		args, err = setupBuffers(string(bufSpec), args, tmpDir)
+		if err != nil {
+			return fmt.Errorf("debug target: setup buffers: %w", err)
+		}
+	}
+
+	runtime.LockOSThread()
+
+	if _, _, errno := syscall.Syscall(syscall.SYS_PTRACE, uintptr(syscall.PTRACE_TRACEME), 0, 0); errno != 0 {
+		return fmt.Errorf("debug target: PTRACE_TRACEME: %v", errno)
+	}
+	os.WriteFile(tmpDir+"/ready", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	os.WriteFile(tmpDir+"/entry", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	fnAddr := codeBase + uintptr(fl.Offset)
+	stackArgs := make([]byte, fl.Args)
+	copy(stackArgs, args)
+
+	_, callErr := verify.Call(fnAddr, stackArgs)
+	if callErr != nil {
+		os.Exit(1)
+	}
+	os.Exit(0)
+	return nil
+}

debug/tracer.go

@@ -1,39 +1,9 @@
 // Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
 // SPDX-License-Identifier: BSD-3-Clause
 
-package debug
+//go:build linux
 
-// Regs holds the full general-purpose register set of a traced process
-// (the Linux amd64 user_regs_struct layout).
-type Regs struct {
-	R15     uint64
-	R14     uint64
-	R13     uint64
-	R12     uint64
-	RBP     uint64
-	RBX     uint64
-	R11     uint64
-	R10     uint64
-	R9      uint64
-	R8      uint64
-	RAX     uint64
-	RCX     uint64
-	RDX     uint64
-	RSI     uint64
-	RDI     uint64
-	OrigRAX uint64
-	RIP     uint64
-	CS      uint64
-	RFLAGS  uint64
-	RSP     uint64
-	SS      uint64
-	FSBase  uint64
-	GSBase  uint64
-	DS      uint64
-	ES      uint64
-	FS      uint64
-	GS      uint64
-}
+package debug
 
 // tracer abstracts the minimal ptrace operations needed by the breakpoint
 // manager and the stop-information helpers.  The live implementation is
@@ -66,7 +36,7 @@ func newMockTracer() *mockTracer {
 func (m *mockTracer) Peek(addr uint64) (uint64, error) {
 	m.peeks = append(m.peeks, addr)
 	var val uint64
-	for i := uint64(0); i < 8; i++ {
+	for i := range uint64(8) {
 		val |= uint64(m.mem[addr+i]) << (i * 8)
 	}
 	return val, nil
@@ -77,7 +47,7 @@ func (m *mockTracer) Poke(addr uint64, val uint64) error {
 		addr uint64
 		val  uint64
 	}{addr, val})
-	for i := uint64(0); i < 8; i++ {
+	for i := range uint64(8) {
 		m.mem[addr+i] = byte(val >> (i * 8))
 	}
 	return nil

debug/watchpoint_linux_amd64.go

@@ -11,11 +11,6 @@ import (
 )
 
 // Hardware watchpoint support via x86-64 debug registers (DR0-DR3, DR7).
-//
-// DR0-DR3 hold the watched addresses.  DR7 is the control register:
-//   bits 0,2,4,6: local enable for DR0-DR3
-//   bits 16-17,20-21,24-25,28-29: R/W type (00=exec, 01=write, 11=read/write)
-//   bits 18-19,22-23,26-27,30-31: length (00=1, 01=2, 10=8, 11=4)
 
 // WatchpointType selects what triggers the watchpoint.
 type WatchpointType int
@@ -25,11 +20,14 @@ const (
 	WatchRead  WatchpointType = 3 // trigger on read or write
 )
 
+// wpSlots tracks watchpoint slot occupancy (DR0-DR3).
+var wpSlots [4]bool
+
 // FindFreeWatchpointSlot returns the index of the first free watchpoint slot
 // (0-3), or -1 if all four hardware watchpoints are in use.
 func (s *Session) FindFreeWatchpointSlot() int {
-	for i := 0; i < 4; i++ {
-		if !s.wpSlots[i] {
+	for i := range 4 {
+		if !wpSlots[i] {
 			return i
 		}
 	}
@@ -41,20 +39,18 @@ func (s *Session) IsWatchpointSlotUsed(slot int) bool {
 	if slot < 0 || slot > 3 {
 		return false
 	}
-	return s.wpSlots[slot]
+	return wpSlots[slot]
 }
 
 // SetWatchpoint installs a hardware watchpoint on the given address.
-// slot is 0-3 (four hardware watchpoints available); the slot must be free.
 func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size int) error {
 	if slot < 0 || slot > 3 {
 		return fmt.Errorf("debug: watchpoint slot must be 0-3")
 	}
-	if s.wpSlots[slot] {
+	if wpSlots[slot] {
 		return fmt.Errorf("debug: watchpoint slot %d already in use", slot)
 	}
 
-	// Determine the length encoding.
 	var lenBits uint64
 	switch size {
 	case 1:
@@ -69,42 +65,38 @@ func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size
 		return fmt.Errorf("debug: watchpoint size must be 1, 2, 4, or 8")
 	}
 
-	// Write the watched address to DR0-DR3.
 	var drAddr uintptr
 	switch slot {
 	case 0:
-		drAddr = 0x0 // DR0 offset in user_regs_struct
+		drAddr = 0x0
 	case 1:
-		drAddr = 0x8 // DR1
+		drAddr = 0x8
 	case 2:
-		drAddr = 0x10 // DR2
+		drAddr = 0x10
 	case 3:
-		drAddr = 0x18 // DR3
+		drAddr = 0x18
 	}
 
-	// PTRACE_POKEUSER writes to the debuggee's user area (includes debug regs).
 	if err := ptracePokeUser(s.pid, drAddr, addr); err != nil {
 		return fmt.Errorf("debug: set DR%d: %w", slot, err)
 	}
 
-	// Read the current DR7, set the enable and type bits, write it back.
-	dr7, err := ptracePeekUser(s.pid, 0x38) // DR7 offset
+	dr7, err := ptracePeekUser(s.pid, 0x38)
 	if err != nil {
 		return fmt.Errorf("debug: read DR7: %w", err)
 	}
 
-	enableBit := uint64(1) << (2 * slot)   // local enable
-	rwBits := uint64(typ) << (16 + 4*slot) // R/W type
-	lenField := lenBits << (18 + 4*slot)   // length
+	enableBit := uint64(1) << (2 * slot)
+	rwBits := uint64(typ) << (16 + 4*slot)
+	lenField := lenBits << (18 + 4*slot)
 
-	// Clear the existing bits for this slot, then set the new ones.
 	mask := ^((uint64(1) << (2 * slot)) | (uint64(3) << (16 + 4*slot)) | (uint64(3) << (18 + 4*slot)))
 	dr7 = (dr7 & mask) | enableBit | rwBits | lenField
 
 	if err := ptracePokeUser(s.pid, 0x38, dr7); err != nil {
 		return fmt.Errorf("debug: set DR7: %w", err)
 	}
-	s.wpSlots[slot] = true
+	wpSlots[slot] = true
 	return nil
 }
 
@@ -113,26 +105,25 @@ func (s *Session) ClearWatchpoint(slot int) error {
 	if slot < 0 || slot > 3 {
 		return fmt.Errorf("debug: watchpoint slot must be 0-3")
 	}
-	if !s.wpSlots[slot] {
+	if !wpSlots[slot] {
 		return fmt.Errorf("debug: watchpoint slot %d is not in use", slot)
 	}
-	// Read DR7, clear the enable bit for this slot.
 	dr7, err := ptracePeekUser(s.pid, 0x38)
 	if err != nil {
 		return err
 	}
-	dr7 &^= uint64(1) << (2 * slot) // disable
+	dr7 &^= uint64(1) << (2 * slot)
 	if err := ptracePokeUser(s.pid, 0x38, dr7); err != nil {
 		return err
 	}
-	s.wpSlots[slot] = false
+	wpSlots[slot] = false
 	return nil
 }
 
 // ClearAllWatchpoints removes all hardware watchpoints.
 func (s *Session) ClearAllWatchpoints() error {
-	for slot := 0; slot < 4; slot++ {
-		if s.wpSlots[slot] {
+	for slot := range 4 {
+		if wpSlots[slot] {
 			if err := s.ClearWatchpoint(slot); err != nil {
 				return err
 			}
@@ -141,9 +132,8 @@ func (s *Session) ClearAllWatchpoints() error {
 	return nil
 }
 
-// ptracePokeUser writes a value to the debuggee's user area at the given offset.
 func ptracePokeUser(pid int, offset uintptr, val uint64) error {
-	const ptracePokeuser = 6 // PTRACE_POKEUSER
+	const ptracePokeuser = 6
 	_, _, errno := syscall.Syscall6(
 		syscall.SYS_PTRACE,
 		uintptr(ptracePokeuser),
@@ -158,9 +148,8 @@ func ptracePokeUser(pid int, offset uintptr, val uint64) error {
 	return nil
 }
 
-// ptracePeekUser reads a value from the debuggee's user area at the given offset.
 func ptracePeekUser(pid int, offset uintptr) (uint64, error) {
-	const ptracePeekuser = 3 // PTRACE_PEEKUSER
+	const ptracePeekuser = 3
 	val, _, errno := syscall.Syscall6(
 		syscall.SYS_PTRACE,
 		uintptr(ptracePeekuser),

debug/watchpoint_linux_arm64.go

@@ -0,0 +1,181 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && arm64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// Hardware watchpoint support via arm64 debug registers (DBGWVR/DBGWCR).
+// Accessed via PTRACE_SETREGSET with NT_ARM_HW_BREAK.
+
+// WatchpointType selects what triggers the watchpoint.
+type WatchpointType int
+
+const (
+	WatchWrite WatchpointType = 1
+	WatchRead  WatchpointType = 3
+)
+
+// wpSlots tracks watchpoint slot occupancy.
+var wpSlots [16]bool // arm64 supports up to 16 watchpoints
+
+const maxWatchpoints = 16
+
+// hwBreakState mirrors the kernel's struct user_hwdebug_state.
+type hwBreakState struct {
+	DbgInfo uint32
+	_pad    [4]byte
+	DbgRegs [16]hwBreakReg
+}
+
+type hwBreakReg struct {
+	Addr uint64
+	Ctrl uint64
+}
+
+const (
+	ntArmHWBreak = 0x403 // NT_ARM_HW_BREAK
+)
+
+func (s *Session) FindFreeWatchpointSlot() int {
+	for i := range maxWatchpoints {
+		if !wpSlots[i] {
+			return i
+		}
+	}
+	return -1
+}
+
+func (s *Session) IsWatchpointSlotUsed(slot int) bool {
+	if slot < 0 || slot >= maxWatchpoints {
+		return false
+	}
+	return wpSlots[slot]
+}
+
+// SetWatchpoint installs a hardware watchpoint on the given address.
+func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size int) error {
+	if slot < 0 || slot >= maxWatchpoints {
+		return fmt.Errorf("debug: watchpoint slot must be 0-%d", maxWatchpoints-1)
+	}
+	if wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d already in use", slot)
+	}
+
+	state, err := s.getHWBreakState()
+	if err != nil {
+		return fmt.Errorf("debug: read watchpoint state: %w", err)
+	}
+
+	if uint32(slot) >= state.DbgInfo {
+		return fmt.Errorf("debug: slot %d exceeds available watchpoints (%d)", slot, state.DbgInfo)
+	}
+
+	state.DbgRegs[slot].Addr = addr
+	ctrl := uint64(1) // enable
+	switch typ {
+	case WatchWrite:
+		ctrl |= 1 << 3 // store only
+	case WatchRead:
+		ctrl |= 3 << 3 // load+store
+	}
+	var bas uint64
+	switch size {
+	case 1:
+		bas = 0x01
+	case 2:
+		bas = 0x03
+	case 4:
+		bas = 0x0F
+	case 8:
+		bas = 0xFF
+	default:
+		return fmt.Errorf("debug: watchpoint size must be 1, 2, 4, or 8")
+	}
+	ctrl |= bas << 5
+	state.DbgRegs[slot].Ctrl = ctrl
+
+	if err := s.setHWBreakState(state); err != nil {
+		return fmt.Errorf("debug: set watchpoint: %w", err)
+	}
+
+	wpSlots[slot] = true
+	return nil
+}
+
+func (s *Session) ClearWatchpoint(slot int) error {
+	if slot < 0 || slot >= maxWatchpoints {
+		return fmt.Errorf("debug: watchpoint slot must be 0-%d", maxWatchpoints-1)
+	}
+	if !wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d is not in use", slot)
+	}
+
+	state, err := s.getHWBreakState()
+	if err != nil {
+		return err
+	}
+	state.DbgRegs[slot].Addr = 0
+	state.DbgRegs[slot].Ctrl = 0
+	if err := s.setHWBreakState(state); err != nil {
+		return err
+	}
+	wpSlots[slot] = false
+	return nil
+}
+
+func (s *Session) ClearAllWatchpoints() error {
+	for slot := 0; slot < maxWatchpoints; slot++ {
+		if wpSlots[slot] {
+			if err := s.ClearWatchpoint(slot); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func (s *Session) getHWBreakState() (*hwBreakState, error) {
+	var state hwBreakState
+	iovec := syscall.Iovec{
+		Base: (*byte)(unsafe.Pointer(&state)),
+		Len:  uint64(unsafe.Sizeof(state)),
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGSET),
+		uintptr(s.pid),
+		uintptr(ntArmHWBreak),
+		uintptr(unsafe.Pointer(&iovec)),
+		0, 0,
+	)
+	if errno != 0 {
+		return nil, errno
+	}
+	return &state, nil
+}
+
+func (s *Session) setHWBreakState(state *hwBreakState) error {
+	iovec := syscall.Iovec{
+		Base: (*byte)(unsafe.Pointer(state)),
+		Len:  uint64(unsafe.Sizeof(*state)),
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SETREGSET),
+		uintptr(s.pid),
+		uintptr(ntArmHWBreak),
+		uintptr(unsafe.Pointer(&iovec)),
+		0, 0,
+	)
+	if errno != 0 {
+		return errno
+	}
+	return nil
+}

debug/watchpoint_linux_loong64.go

@@ -0,0 +1,147 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && loong64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+)
+
+// Hardware watchpoint support for LoongArch via debug registers.
+// Uses PTRACE_POKEUSER/PEEKUSER to access HW watchpoint registers.
+
+// WatchpointType selects what triggers the watchpoint.
+type WatchpointType int
+
+const (
+	WatchWrite WatchpointType = 1
+	WatchRead  WatchpointType = 3
+)
+
+// wpSlots tracks watchpoint slot occupancy.
+var wpSlots [4]bool
+
+const maxWatchpoints = 4
+
+func (s *Session) FindFreeWatchpointSlot() int {
+	for i := range maxWatchpoints {
+		if !wpSlots[i] {
+			return i
+		}
+	}
+	return -1
+}
+
+func (s *Session) IsWatchpointSlotUsed(slot int) bool {
+	if slot < 0 || slot >= maxWatchpoints {
+		return false
+	}
+	return wpSlots[slot]
+}
+
+// SetWatchpoint installs a hardware watchpoint.
+func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size int) error {
+	if slot < 0 || slot >= maxWatchpoints {
+		return fmt.Errorf("debug: watchpoint slot must be 0-%d", maxWatchpoints-1)
+	}
+	if wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d already in use", slot)
+	}
+	if size != 1 && size != 2 && size != 4 && size != 8 {
+		return fmt.Errorf("debug: watchpoint size must be 1, 2, 4, or 8")
+	}
+
+	// LoongArch debug registers: DBGWVR (watchpoint value) and DBGWCR (watchpoint control).
+	// Accessed via PTRACE_POKEUSER at architecture-specific offsets.
+	if err := ptracePokeUser(s.pid, uintptr(0x1000+slot*8), addr); err != nil {
+		return fmt.Errorf("debug: set watchpoint address: %w", err)
+	}
+
+	// DBGWCR: enable + type + size.
+	var wcr uint64 = 1 // enable
+	switch typ {
+	case WatchWrite:
+		wcr |= 1 << 3 // store
+	case WatchRead:
+		wcr |= 3 << 3 // load+store
+	}
+	var sizeBits uint64
+	switch size {
+	case 1:
+		sizeBits = 0
+	case 2:
+		sizeBits = 1
+	case 4:
+		sizeBits = 2
+	case 8:
+		sizeBits = 3
+	}
+	wcr |= sizeBits << 5
+
+	if err := ptracePokeUser(s.pid, uintptr(0x1001+slot*8), wcr); err != nil {
+		return fmt.Errorf("debug: set watchpoint control: %w", err)
+	}
+
+	wpSlots[slot] = true
+	return nil
+}
+
+func (s *Session) ClearWatchpoint(slot int) error {
+	if slot < 0 || slot >= maxWatchpoints {
+		return fmt.Errorf("debug: watchpoint slot must be 0-%d", maxWatchpoints-1)
+	}
+	if !wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d is not in use", slot)
+	}
+
+	if err := ptracePokeUser(s.pid, uintptr(0x1001+slot*8), 0); err != nil {
+		return err
+	}
+	wpSlots[slot] = false
+	return nil
+}
+
+func (s *Session) ClearAllWatchpoints() error {
+	for slot := 0; slot < maxWatchpoints; slot++ {
+		if wpSlots[slot] {
+			if err := s.ClearWatchpoint(slot); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func ptracePokeUser(pid int, offset uintptr, val uint64) error {
+	const ptracePokeuser = 6
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(ptracePokeuser),
+		uintptr(pid),
+		offset,
+		uintptr(val),
+		0, 0,
+	)
+	if errno != 0 {
+		return errno
+	}
+	return nil
+}
+
+func ptracePeekUser(pid int, offset uintptr) (uint64, error) {
+	const ptracePeekuser = 3
+	val, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(ptracePeekuser),
+		uintptr(pid),
+		offset,
+		0, 0, 0,
+	)
+	if errno != 0 {
+		return 0, errno
+	}
+	return uint64(val), nil
+}

debug/watchpoint_linux_riscv64.go

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && riscv64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+)
+
+// Hardware watchpoint support for RISC-V via Sdtrig trigger registers.
+// Uses PTRACE_POKEUSER/PEEKUSER to access debug registers.
+
+// WatchpointType selects what triggers the watchpoint.
+type WatchpointType int
+
+const (
+	WatchWrite WatchpointType = 1
+	WatchRead  WatchpointType = 3
+)
+
+// wpSlots tracks watchpoint slot occupancy.
+var wpSlots [4]bool
+
+const maxWatchpoints = 4
+
+func (s *Session) FindFreeWatchpointSlot() int {
+	for i := range maxWatchpoints {
+		if !wpSlots[i] {
+			return i
+		}
+	}
+	return -1
+}
+
+func (s *Session) IsWatchpointSlotUsed(slot int) bool {
+	if slot < 0 || slot >= maxWatchpoints {
+		return false
+	}
+	return wpSlots[slot]
+}
+
+// SetWatchpoint installs a hardware watchpoint.
+func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size int) error {
+	if slot < 0 || slot >= maxWatchpoints {
+		return fmt.Errorf("debug: watchpoint slot must be 0-%d", maxWatchpoints-1)
+	}
+	if wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d already in use", slot)
+	}
+	if size != 1 && size != 2 && size != 4 && size != 8 {
+		return fmt.Errorf("debug: watchpoint size must be 1, 2, 4, or 8")
+	}
+
+	// RISC-V trigger registers: tdata1 encodes type/control, tdata2 holds address.
+	// The exact encoding depends on the trigger implementation (Sdtrig).
+	// Use PTRACE_POKEUSER to write to the trigger CSRs via the kernel's
+	// debug register interface.
+	if err := ptracePokeUser(s.pid, uintptr(0x1000+slot*8), addr); err != nil {
+		return fmt.Errorf("debug: set watchpoint address: %w", err)
+	}
+
+	// tdata1: set match control.  Mode=2 (data match), select=0, action=1 (debug exception).
+	var tdata1 uint64 = 2 << 60 // type = match (2)
+	tdata1 |= 1 << 0            // action = enter debug mode
+	tdata1 |= 1 << 7            // store (write) trigger
+	if typ == WatchRead {
+		tdata1 |= 1 << 6 // load trigger
+	}
+	// Size encoding: 0=1byte, 1=2byte, 2=4byte, 3=8byte.
+	var sizeBits uint64
+	switch size {
+	case 1:
+		sizeBits = 0
+	case 2:
+		sizeBits = 1
+	case 4:
+		sizeBits = 2
+	case 8:
+		sizeBits = 3
+	}
+	tdata1 |= sizeBits << 16 // size field
+
+	if err := ptracePokeUser(s.pid, uintptr(0x1001+slot*8), tdata1); err != nil {
+		return fmt.Errorf("debug: set watchpoint control: %w", err)
+	}
+
+	wpSlots[slot] = true
+	return nil
+}
+
+func (s *Session) ClearWatchpoint(slot int) error {
+	if slot < 0 || slot >= maxWatchpoints {
+		return fmt.Errorf("debug: watchpoint slot must be 0-%d", maxWatchpoints-1)
+	}
+	if !wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d is not in use", slot)
+	}
+
+	// Disable by clearing tdata1.
+	if err := ptracePokeUser(s.pid, uintptr(0x1001+slot*8), 0); err != nil {
+		return err
+	}
+	wpSlots[slot] = false
+	return nil
+}
+
+func (s *Session) ClearAllWatchpoints() error {
+	for slot := 0; slot < maxWatchpoints; slot++ {
+		if wpSlots[slot] {
+			if err := s.ClearWatchpoint(slot); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func ptracePokeUser(pid int, offset uintptr, val uint64) error {
+	const ptracePokeuser = 6
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(ptracePokeuser),
+		uintptr(pid),
+		offset,
+		uintptr(val),
+		0, 0,
+	)
+	if errno != 0 {
+		return errno
+	}
+	return nil
+}
+
+func ptracePeekUser(pid int, offset uintptr) (uint64, error) {
+	const ptracePeekuser = 3
+	val, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(ptracePeekuser),
+		uintptr(pid),
+		offset,
+		0, 0, 0,
+	)
+	if errno != 0 {
+		return 0, errno
+	}
+	return uint64(val), nil
+}

docs/ARCHITECTURE.md

@@ -7,7 +7,7 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
 ## Design goals
 
 1. **A real AST, not a grammar hack.**  The linter, analyser, assembler and
-   language server all need to *reason* about assembly — not just colour it.
+   language server all need to *reason* about assembly, not just colour it.
    So the centre of the toolkit is a hand-written lexer and a parser that
    produce a typed AST with source positions on every node.
 2. **Architecture as data, not code.**  Per-architecture differences (amd64,
@@ -69,8 +69,8 @@ instruction, comment, preprocessor) and dispatches.  A malformed line is
 reported and skipped; it never aborts the file.
 
 Operands are parsed into a faithful, flat representation.  The amd64
-addressing modes — `reg`, `$imm`, `(base)`, `off(base)`, `(base)(index*scale)`,
-`name+off(FP)`, `name<>(SB)` — are all captured structurally, and the original
+addressing modes (`reg`, `$imm`, `(base)`, `off(base)`, `(base)(index*scale)`,
+`name+off(FP)`, `name<>(SB)`) are all captured structurally, and the original
 token text is retained for fidelity.
 
 A deliberate boundary: the AST records **syntax only**.  Whether a bare
@@ -80,8 +80,8 @@ arch-agnostic and its output deterministic.
 
 ### `arch`
 
-Register files are generated programmatically (the regular `R8`–`R15`,
-`X0`–`X15`, `Y0`–`Y15`, `Z0`–`Z31`, `K0`–`K7` ranges) plus the irregularly
+Register files are generated programmatically (the regular `R8`-`R15`,
+`X0`-`X15`, `Y0`-`Y15`, `Z0`-`Z31`, `K0`-`K7` ranges) plus the irregularly
 named registers listed explicitly.  Instruction names are **generated from the
 Go toolchain's own assembler source** (`cmd/internal/obj/<arch>/anames.go`,
 plus the common opcodes and the per-architecture front-end aliases such as the
@@ -95,18 +95,21 @@ fixed-arity instructions (`RET`, `NOP`, `JMP`, `CALL`) carry counts at all.
 
 ### `lint`
 
-Rules are conservative by design — silence beats a false positive.  The rules
+Rules are conservative by design: silence beats a false positive.  The rules
 are `unknown-instruction`, `operand-count`, `undefined-label`,
-`duplicate-label`, `missing-ret`, `missing-textflag-include`, `abi-argsize` and
-`unreachable-code`.  Every diagnostic carries a stable code so callers can
-disable rules individually, and arch-specific rules switch off entirely when
-the target architecture cannot be inferred from the file name.
+`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`,
+`unencodable-instruction` and `reserved-register-write`.  Every diagnostic carries a stable
+code so callers can disable rules individually, and arch-specific rules switch
+off entirely when the target architecture cannot be inferred from the file name.
 
 Two things keep the rules honest on real-world code:
 
 - **Pseudo-ops and macros are not instructions.**  `unknown-instruction` knows
   the assembler pseudo-ops (`BYTE`, `WORD`, `FUNCDATA`, `PCDATA`, …) and
-  recognises macro invocations — an in-file `#define` name, or any identifier
+  recognises macro invocations: an in-file `#define` name, or any identifier
   containing an underscore (no Plan 9 mnemonic ever does).
 - **Macro-heavy files get the label/RET heuristics turned off.**  Without a
   preprocessor, labels a macro defines are invisible, so `undefined-label` and
@@ -127,27 +130,27 @@ Two deeper analyses sit on top of the AST:
   parameters), and checks the total against the argument size declared in the
   `TEXT` directive.  It only runs for stack-argument functions (a non-zero
   declared arg area that is actually addressed through `FP`), and aborts
-  silently on a type whose size it cannot determine — so it never guesses.
+  silently on a type whose size it cannot determine, so it never guesses.
 - **`unreachable-code`.**  Code after a `RET` and before the next label is
   dead.  The check is suppressed for any function whose reachability cannot be
   decided statically: those using PC-relative jumps (`JMP 2(PC)`),
   register-indirect branches (`JALR`/`JR`/`JIRL`/`BR`/`BLR`), or living in a
-  file with `#ifdef` conditionals.  `UNDEF` is deliberately not a terminator —
+  file with `#ifdef` conditionals.  `UNDEF` is deliberately not a terminator:
   code after it is occasionally intentional metadata.
 - **`register-clobber` (register liveness).**  The linter builds the function's
   control-flow graph (basic blocks split at labels and after branches, with
   fall-through and jump-target edges), computes a conservative per-instruction
   register def/use, and runs the standard backward liveness iteration to a fixed
   point.  On top of that it flags writes to the registers the **Go ABI** fixes
-  across calls that are never saved and restored — calibrated from
+  across calls that are never saved and restored, calibrated from
   `cmd/compile/abi-internal.md`, *not* the platform ABI: Go's stack-based ABI0
-  has no System V style callee-saved registers (amd64 `BX`, `R12`–`R15` and
+  has no System V style callee-saved registers (amd64 `BX`, `R12`-`R15` and
   the like are caller-saved or permanent scratch, and hand-written kernels may
   clobber them freely).  The audited set is the frame pointer and the
-  the frame pointer, the goroutine pointer per architecture (amd64 `BP`/`R14`, arm64 `R18`/`R28`/
+  goroutine pointer per architecture (amd64 `BP`/`R14`, arm64 `R18`/`R28`/
   `R29`, riscv64 `X27`, loong64 `R22`); the goroutine pointer is reported only
-  when the function can reach the runtime — it is not `NOSPLIT` or makes a
-  call — since the ABI0 transition machinery restores it on those paths, and
+  when the function can reach the runtime (it is not `NOSPLIT` or makes a
+  call), since the ABI0 transition machinery restores it on those paths, and
   NOSPLIT call-free leaves may use it (the runtime's own assembly does).  It
   runs only on macro-free files, where
   no opaque macro can perform the save/restore.
@@ -159,13 +162,13 @@ Two deeper analyses sit on top of the AST:
 ### `format`
 
 The formatter works on the **token stream, not the AST**, so it preserves
-every line — comments and blanks included.  It normalises indentation, operand
+every line, comments and blanks included.  It normalises indentation, operand
 spacing, per-function mnemonic alignment and blank-line layout: a new block
 (a label, `TEXT` or `GLOBL`) is preceded by exactly one blank line (comments
 leading a block stay with it), runs of blanks collapse to one, and a `RET`
 terminates the body so the next function's doc comment stays at column 0.  It
 is idempotent and its output always round-trips through the parser.  With a
-directory argument — or none — it reformats every `.s` file below it in
+directory argument, or none, it reformats every `.s` file below it in
 place and lists the files changed, the way `go fmt` does (`.` and `_`
 directories are skipped).
 
@@ -175,13 +178,24 @@ The server speaks JSON-RPC 2.0 with `Content-Length` framing over any
 `io.Reader`/`io.Writer` (normally stdin/stdout).  It maintains an in-memory
 document store, republishes diagnostics on every change, and provides:
 
-- **completion** — instructions, registers, pseudo-registers, textflag macros
+- **completion**: instructions, registers, pseudo-registers, textflag macros
   and local labels;
-- **hover** — instruction summaries and register descriptions from `arch`;
-- **document symbols** — `TEXT` functions with their labels, plus `GLOBL`/`DATA`;
-- **semantic tokens** — syntax highlighting delivered as LSP semantic tokens,
+- **hover**: instruction summaries and register descriptions from `arch`;
+- **document symbols**: `TEXT` functions with their labels, plus `GLOBL`/`DATA`;
+- **semantic tokens**: syntax highlighting delivered as LSP semantic tokens,
   classified with the lexer plus `arch` (instructions, registers by class,
-  pseudo-registers, labels, immediates, comments, directives, textflag macros).
+  pseudo-registers, labels, immediates, comments, directives, textflag macros);
+- **navigation**: go-to-definition from a label reference to its definition,
+  find references, document highlights of every use of the symbol under the
+  cursor, rename, and workspace symbol search over the open documents;
+- **assists**: document formatting through the `format` package, inlay hints
+  (the frame size after the TEXT argument area), signature help (the callee's
+  `// func` signature while the cursor is on a `CALL`), and code actions
+  offering quick fixes for the `missing-ret` and `unused-label` diagnostics.
+- **document information**: pull diagnostics (`textDocument/diagnostic`),
+  #include document links (resolved against the document directory, then
+  `$GOROOT/pkg/include`) and folding ranges (one collapsible region per
+  TEXT function body).
 
 Semantic tokens are the key to editor-agnostic highlighting: the editor renders
 them from the standard LSP legend, so no editor-specific grammar is needed.
@@ -191,7 +205,7 @@ them from the standard LSP legend, so no editor-specific grammar is needed.
 The standalone assembler (Phase 2).  Its core is an amd64 instruction encoder:
 a REX/ModR-M/SIB/displacement/immediate engine plus the scalar instruction set,
 with the Plan 9 operand order (source first) mapped onto the x86 encoding.
-Every encoding is validated by decoding it again with `golang.org/x/arch` — the
+Every encoding is validated by decoding it again with `golang.org/x/arch`, the
 one module dependency, used in tests only and never linked into the binary.
 
 A **RISC-V encoder** (Phase 5, RV64IMAFDC + RVC compression) encodes the full
@@ -212,6 +226,17 @@ relocations).  Like the RISC-V encoder it is validated byte-for-byte against
 `GOARCH=loong64 go tool asm`, and its GOOBJ output is proven end-to-end by
 substituting it into a cross-compiled `go build` and linking with `cmd/link`.
 
+An **AArch64 encoder** (Phase 5, arm64) encodes the integer instruction set
+with the data-processing (shifted register and immediate forms), load/store
+(scaled unsigned immediate and unscaled9-bit immediate), conditional and
+unconditional branches, the MOV pseudo-instruction and its constant
+materialisation (MOVZ/MOVN/MOVK for wide immediates, ORR with logical bitmask
+encoding for values like `$1`), the FP/SP frame mapping (autosize =
+align16(frame+8), prologue using pre-index store for small frames and
+STP+SUB for large frames) and SB/global symbol references (ADRP+ADD pairs with
+R_ADDRARM64 relocations).  Like the other encoders it is validated
+byte-for-byte against `GOARCH=arm64 go tool asm`.
+
 On top of the encoder, `Assemble` walks a parsed `TEXT` body, converts each
 operand to an encoder operand, and lays the instructions out so local labels
 resolve to relative jump offsets: jumps start in the short (rel8) form and
@@ -220,12 +245,12 @@ fixed point, and jump-to-jump chains are folded (a conditional jump to a label
 whose only instruction is an unconditional jump is redirected to the ultimate
 target) exactly as the Go toolchain's linker does before it encodes branches.
 The `FP`/`SP` pseudo-
-registers are translated onto the hardware stack pointer — `x+N(FP)` becomes
+registers are translated onto the hardware stack pointer: `x+N(FP)` becomes
 `(N+8)(SP)` for a zero-frame function and `(N+frame+16)(SP)` once a frame
-pointer is set up, with the matching Go prologue/epilogue generated — so the
+pointer is set up, with the matching Go prologue/epilogue generated, so the
 output is byte-identical to the Go assembler for these cases.  SIMD is handled
-by a VEX (AVX/AVX2) encoder — the two- and three-byte VEX prefixes with XMM/YMM
-registers — across eight operand forms: the three-operand NDS form, the
+by a VEX (AVX/AVX2) encoder (the two- and three-byte VEX prefixes with XMM/YMM
+registers) across eight operand forms: the three-operand NDS form, the
 two-operand reg/rm form, the immediate-shift form (plus the variable-count
 shifts, which share the NDS shape with the count in an XMM register or
 memory), the immediate shuffle form (`VPSHUFD`, `VPERMQ`), the
@@ -233,24 +258,24 @@ three-operand-plus-immediate form (`VSHUFPD`,
 `VPERM2I128`, `VINSERTI128`), the lane-extract form (`VEXTRACTI128`,
 `VEXTRACTF128`, where the YMM source occupies the reg field and the XMM or
 memory destination r/m), the direction-sensitive moves (`VMOVDQU`, `VMOVUPD`,
-`VMOVD`, `VMOVQ`, `VMOVSD`), the floating-point and FMA arithmetic — the
+`VMOVD`, `VMOVQ`, `VMOVSD`), the floating-point and FMA arithmetic: the
 packed double operations (`VADDPD`/`VSUBPD`/`VMULPD`/`VDIVPD`/`VMINPD`/
 `VMAXPD`), the unpacks (`VUNPCKHPD`/`VUNPCKLPD`), the scalar SD and SS
 operations, `VMOVDDUP`, `VXORPD`, the width-changing conversions
 (`VCVTDQ2PS`, `VCVTPS2PD`, `VCVTDQ2PD`, and the `VCVTPD2DQX`/`Y` and
 `VCVTTPD2DQX`/`Y` spellings, whose length follows the wider source) and
-`VFMADD231PD` — and the no-operand `VZEROUPPER`, together with `VPERMD` and
+`VFMADD231PD`, and the no-operand `VZEROUPPER`, together with `VPERMD` and
 the scalar families (`CMOVcc`, `SETcc`, `LZCNT`/`TZCNT`, the extending moves,
-`CVTSx2SD`, `IMUL3`) and the EVEX (AVX-512) prefix — the four-byte prefix with
-5-bit register fields (Z0–Z31, X/Y 16–31, with the mod=11 quirk that carries
-rm[4] in X̄), opmask registers (K0–K7 as operands, mask destinations and
-explicit merging/zeroing masks — written the way Go writes them, as a K
+`CVTSx2SD`, `IMUL3`) and the EVEX (AVX-512) prefix, the four-byte prefix with
+5-bit register fields (Z0-Z31, X/Y 16-31, with the mod=11 quirk that carries
+rm[4] in X̄), opmask registers (K0-K7 as operands, mask destinations and
+explicit merging/zeroing masks, written the way Go writes them, as a K
 operand among the operands plus a `.Z` mnemonic suffix), and the compressed
-disp8×N displacement, whose multiplier follows the memory operand's size —
+disp8×N displacement, whose multiplier follows the memory operand's size,
 covering every instruction the go-flac and go-lz4 AVX2/AVX-512 kernels use,
 plus the common AVX-512 F/BW integer set, the floating-point and conversion
-set (the packed double and single arithmetic, the scalar SD/SS forms —
-whose EVEX encodings serve masked and zeroing use — `VMOVDDUP`, the
+set (the packed double and single arithmetic, the scalar SD/SS forms
+(whose EVEX encodings serve masked and zeroing use), `VMOVDDUP`, the
 replicating moves, and the width-changing conversions, including the
 `VCVTPD2DQ`/`VCVTTPD2DQ` family whose length follows the wider source
 operand), and the wider AVX-512 set: ternary logic, lane shuffles, inserts
@@ -260,21 +285,21 @@ expand/compress family, the broadcasts, the opmask-register instructions
 moves and the remaining extending/narrowing moves, the floating-point
 helper and conversion tail (VRCP14*, VRSQRT14*, VGETEXP*, VGETMANT*,
 VSCALEF*, VRNDSCALE*, VREDUCE*, VFIXUPIMM*, VRANGE*, VFPCLASS* with an
-opmask destination, and the VCVT* conversions — signed, unsigned and
+opmask destination, and the VCVT* conversions, signed, unsigned and
 truncating, including the length-suffixed X/Y spellings and the
 mask/vector conversions VPMOVM2*/VPMOV*2M, and the scalar conversions
 between vector and general-purpose registers (VCVT{,T}S{D,S}2SI{,Q} and
-the unsigned forms, VCVTSI2*/VCVTUSI2*), and gather/scatter with VSIB addressing — both the
+the unsigned forms, VCVTSI2*/VCVTUSI2*), and gather/scatter with VSIB addressing, both the
 VEX spelling with a vector mask register and the EVEX spelling with an
 explicit K mask, where the EVEX length follows the VSIB index register,
 not the data register.  The EVEX mnemonic
-suffixes — rounding modes (.RN_SAE/.RD_SAE/.RU_SAE/.RZ_SAE),
-suppress-all-exceptions (.SAE) and memory broadcast (.BCST) — set the EVEX
+suffixes (rounding modes (.RN_SAE/.RD_SAE/.RU_SAE/.RZ_SAE),
+suppress-all-exceptions (.SAE) and memory broadcast (.BCST)) set the EVEX
 b bit and the L'L rounding-control field (broadcast keeps the vector length
 and scales disp8 by the element size), and combine with the .Z zeroing
 suffix.  Every encoding is validated two ways: by
 round-trip decoding through `golang.org/x/arch`, and byte-for-byte against
-the machine code the real Go assembler emits — a comparison that holds for
+the machine code the real Go assembler emits, a comparison that holds for
 whole functions: all 27 functions of both kernels assemble to exactly the Go
 toolchain's bytes, the lone exception being the displacements of the
 static-constant loads, which the Go linker fills at link time.
@@ -288,14 +313,17 @@ the bytes are self-consistent at any base address.  References to symbols no
 object-file emitters turn the whole image into a linkable object: the ELF
 writer (`gasm asm --format elf`) lays the code and data out as `.text`/`.data`
 sections, exports a symbol per
-`TEXT` and `GLOBL` (the `<>` ones local, the rest global) and emit one
-PC-relative relocation per static-symbol reference — undefined external
-symbols included, so the output links with the system toolchain.  The GOOBJ
+`TEXT` and `GLOBL` (the `<>` ones local, the rest global), emits one
+PC-relative relocation per static-symbol reference, undefined external
+symbols included, and appends the DWARF5 debug sections
+(`.debug_abbrev`, `.debug_info`, `.debug_line`, `.debug_line_str`, and a
+`.debug_frame` CFI section on amd64) so `addr2line` and GDB/LLDB can debug
+the output.  The GOOBJ
 emitter (`gasm asm --format goobj`) writes the format the Go linker consumes
 directly: the functions as non-package symbols (the way `cmd/asm` records
 assembly symbols), the `GLOBL` data, one `FuncInfo` per function and the
-pc-value tables — `pcsp` built from the prologue and epilogue stack
-boundaries, plus flat `pcfile`, `pcline` and `pcinline` tables — so a
+pc-value tables (`pcsp` built from the prologue and epilogue stack
+boundaries, plus flat `pcfile`, `pcline` and `pcinline` tables), so a
 gasm-assembled object drops into a `go build` in place of the toolchain's.
 The object preamble (the version-and-experiment header the linker compares
 verbatim) is captured from the installed `go tool asm`, so the output is
@@ -303,18 +331,21 @@ always consistent with the toolchain that links it.  RISC-V and LoongArch
 GOOBJ emission share this emitter: the loong64 marker with
 R_LOONG64_ADDR_HI/LO relocation types, and the riscv64 marker with a single
 R_RISCV_PCREL_ITYPE/STYPE relocation per AUIPC pair (plus `R_RISCV_JAL` for
-`CALL sym(SB)`) — the model `cmd/asm`
-writes, not the ELF HI20/LO12 pair — and both link into a real `go build` for
+`CALL sym(SB)`), the model `cmd/asm`
+writes, not the ELF HI20/LO12 pair, and both link into a real `go build` for
 their `GOARCH`.  Per function, the emitter also writes the two DWARF
-symbols the linker's DWARF pass reads verbatim — the subprogram DIE
+symbols the linker's DWARF pass reads verbatim: the subprogram DIE
 (`SDWARFFCN`) and the `.debug_line` state-machine program (`SDWARFLINES`),
 both built the way `cmd/asm` builds them (the DIE carries the
 R_DWTXTADDR_U4 address reference; the line program one row per source-line
-change, in the same special-opcode encoding) — and the pc-value deltas are
+change, in the same special-opcode encoding), and the pc-value deltas are
 in the architecture's MinLC units, as the runtime's `pcvalue` expects.
-External cross-package references remain future work (the amd64 and RISC-V
-paths resolve them; LoongArch does not yet); the rest of Phase 2 is those
-and the remaining EVEX forms.
+Cross-package external references resolve on all four architectures: when
+`img.Externals` is non-empty, the GOOBJ emitter locates the referenced
+package's `.a` archive via `go list -json -export`, reads the GOOBJ symbol
+definitions the linker reads, and wires the resolved package and symbol
+indices into the emission, so a gasm-assembled object links against the
+compiled packages it references.
 
 ### `verify`
 
@@ -331,6 +362,19 @@ stack pointer in a package global and jumps to the target), and recovers
 control when the function RETs into `leaveJIT` (which restores the Go stack
 and returns).  A 64-byte pad below the return address accommodates the
 ABIInternal wrapper that the Go runtime interposes on assembly functions.
+Every supported architecture carries its own hand-written trampoline pair
+(`trampoline_amd64.s`, `trampoline_arm64.s`, `trampoline_riscv64.s`,
+`trampoline_loong64.s`).  The ABI-checked variant `CallChecked` exists for
+every architecture too: `enterJITChecked` plants sentinels in the registers
+the Go ABI fixes across calls (amd64 `BP`/`R14`, arm64 `R29`/`R28`, riscv64
+`X27`, loong64 `R22`; the latter two keep no hardware frame pointer) and the
+raw return trampoline `leaveJITCheckedRaw` verifies them, restoring the
+saved registers before Go code resumes.  riscv64 is validated end to
+end under qemu-user emulation; arm64 shares the same stack convention and
+fix; loong64 stays ground-truth-only until hardware validation (see
+docs/DECISIONS.md).  `gasm verify` runs the JIT checks when the host
+matches the kernel's architecture and the toolchain comparisons
+elsewhere.
 
 `Load` / `LoadSource` / `LoadAST` parse, assemble and map a `.s` file in one
 step, returning a `Kernel` whose `CallFunc` method marshals the argument block
@@ -339,22 +383,29 @@ assembler’s `Image.Bytes()` provides the code-and-data concatenation.
 
 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.  `gasm verify --fuzz` combines
+arguments to confirm the trampoline round-trips.  The `-smoke` and `-abi`
+sweeps run in parallel and each inside a child process, so a function that
+faults is reported without ending the sweep.  `gasm verify --fuzz` combines
 ABI checks (sentinel registers, canary, stack bounds) with differential fuzz
 testing, comparing the JIT-assembled kernel against the portable Go reference
 bit-for-bit while verifying the ABI contract on every iteration.  When a fuzz
 iteration crashes or mismatches, `FuzzResult.CrashInput` stores the exact input
 for reproducibility.  `gasm verify --call <func> --buf name:size:pattern`
 invokes a single function with user-supplied buffers (patterns: zero, ones,
-seq, or hex), printing the ABI0 argument block before and after the call —
+seq, or hex), printing the ABI0 argument block before and after the call,
 useful for partial functions (e.g. decoders) that crash on random input but
-should succeed on valid data.  `gasm verify --ground-truth` compares the
+should succeed on valid data; `--args name=value,...` supplies scalar
+arguments (decimal or `0x` hex) alongside the buffers.  `--save-corpus`
+records every input that crashes or mismatches as replayable JSON, and
+`--replay` re-runs saved entries in isolated child processes, reporting
+whether each reproduces.  `gasm verify
+--ground-truth` compares the
 assembled machine code byte-for-byte against `go tool asm` (relocation sites
 masked), reporting any encoding drift.
 
 ### `debug`
 
-The interactive debugger (Phase 4, linux/amd64).  It launches the target
+The interactive debugger (all four architectures).  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`
@@ -363,8 +414,15 @@ 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 (GPR + YMM/XMM via `PTRACE_GETFPREGS`),
 label resolution, named buffer allocation with pattern filling
-(`--buf name:size:pattern` — zero, ones, seq, or hex), and breakpoint
-management.
+(`--buf name:size:pattern`: zero, ones, seq, or hex), and breakpoint
+management.  Breakpoints accept conditions
+(`break <label> if <reg> <op> <val>`, including register-against-register
+comparisons), and hardware watchpoints work on all four architectures.
+For non-interactive use, `--script` runs REPL commands from a file (or
+stdin) and exits, `--timeout` kills the debuggee when a run hangs (the
+watchdog is armed before the ptrace attach, so a sandboxed debuggee cannot
+block it), and `--cover` runs to completion with a breakpoint on every
+label and reports which blocks executed.
 
 ## Extension points
 

docs/CLI.md

@@ -48,11 +48,13 @@ 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>`
 
-Assemble FILE (amd64) to machine code.
+Assemble FILE to machine code (amd64, arm64, riscv64, loong64).
 
 | Flag | Description |
 |------|-------------|
@@ -75,7 +77,10 @@ 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) |
+| `--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
@@ -85,18 +90,29 @@ 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>`
+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.
 
-Interactive debugger for JIT-assembled amd64 functions. Requires a
-compiled binary on `$PATH` (not `go run`).
+## `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:
 
@@ -110,7 +126,7 @@ REPL commands:
 | `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 |
+| `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) |
@@ -146,6 +162,27 @@ 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
@@ -154,5 +191,8 @@ 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, 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.

docs/DECISIONS.md

@@ -0,0 +1,111 @@
+# Deferred decisions
+
+Design decisions deliberately postponed, with enough context to pick them up
+again without re-deriving the analysis.  Each entry records what is deferred,
+why, the options on the table, and the trigger that should reopen it.
+
+---
+
+## GOOBJ external (cross-package) symbol references
+
+**Status:** resolved (v0.29.0+, 2026-08-07).
+
+**Approach taken.**  Instead of parsing the compiler's iexport data (which
+would have required either `golang.org/x/tools` or an in-house parser), the
+resolver reads the **GOOBJ data directly** from the target package's `.a`
+archive.  The `.a` file contains a `_go_.o` member whose GOOBJ s is the
+same one gasm writes; the parser reuses the same layout (`blkSymdef`,
+`blkNonpkgdef`, the string table), so no new dependency was needed.
+
+**How it works.**
+
+1. `go list -json -export <pkg>` finds the target package's `.a` file.
+2. `extractGOOBJ` reads the ar archive, finds the `_go_.o` member, skips
+   the `"go object …\n!\n"` preamble and parses the GOOBJ header.
+3. `goobjFile.symbols()` walks `blkSymdef` and `blkNonpkgdef` in definition
+   order (the same order the linker uses) to build the symbol-to-index
+   mapping.
+4. `resolveExternalSymbols` wires the resolved `{PkgIdx, SymIdx}` into the
+   GOOBJ emission.
+
+The resolver is invoked automatically when `img.Externals` is non-empty; it
+runs `go list` as a subprocess (consistent with `toolchainObjectPreamble`
+which already calls `go tool asm`).  All symbol data is cached per package
+for the lifetime of the GOOBJ emission.
+
+## 2026-08-30 non-amd64 JIT execution trampolines
+
+**Status:** resolved for riscv64 (validated end to end under qemu-user)
+and arm64 (fix in place, consistent with the observed frame convention);
+open for loong64 until hardware validation.
+
+**Root cause (found 2026-08-31).**  The trampolines advanced SP past the
+leave-address slot after loading it, while the assembled kernels read
+their first argument at SP+8 per the frame convention (the amd64 path
+already kept SP on that slot).  Removing the advance fixed riscv64
+immediately (plain and checked ABI tests pass under qemu-user); the
+arm64 kernel's pre-fix trace showed exactly the same SP+8 reading.  The
+apparent arm64/loong64 "crashes in the JIT" turned out to be dominated
+by an unrelated instability: the Go 1.26 and 1.27 runtimes crash under
+qemu-user arm64 emulation (GC worker start, identical signature with the
+JIT tests skipped, both qemu 7.2 and 10.2), and the Go loong64 runtime
+does not start at all.  `gasm verify` therefore keeps loong64 kernels on
+the ground-truth path until hardware validation; the GOARCH-guarded
+tests (`verify/jit_arch_test.go`, `verify/abi_arch_test.go`) are the
+hardware validation entry point.
+
+**State.**  The per-architecture trampolines compile for all targets, the
+kernels they execute are byte-for-byte correct against `go tool asm`, and
+under `qemu-aarch64` the arm64 kernel demonstrably executes and stores its
+result correctly.  The failure is on the return path into Go code: arm64
+and loong64 take a SIGSEGV after the kernel's RET (the Go-side unwind
+through `leaveJIT` and its interposed ABIInternal wrapper is the suspect),
+and riscv64 returns cleanly but with an untouched result area.  amd64 is
+unaffected (the checked trampoline saves and restores BP/R14 and the flow
+is validated end to end).
+
+**Evidence harness.**  `verify/jit_arch_test.go` (plain call) and
+`verify/abi_arch_test.go` (checked call) are GOARCH-guarded tests; build
+the test binary per target (`GOARCH=arm64 go test -c -o v.test ./verify/`)
+and run it under `qemu-aarch64-static` from the `verify/` directory.  A
+minimal reproducer pattern lives in the qemu exploration notes: verify
+loads, the kernel executes, the fault follows the return.
+
+**Fix direction.**  Compare the amd64 checked trampoline (GLOBL/DATA raw
+address, explicit SP/BP/R14 save-restore) against the arm64/riscv64/
+loong64 `leaveJIT` unwind, in particular the interaction with the
+ABIInternal wrapper that `reflect.ValueOf(leaveJIT).Pointer()` returns.
+The plain-call path (no sentinels) fails the same way, so the checked
+path is not the variable.
+
+---
+
+## 2026-08-29 tooling round
+
+- `lint abi0-register-args`: flags kernels whose `// func` parameters are
+  never read from the FP frame.  Motivated by a real latent bug: kernels
+  reading arguments from registers pass every test while the autogenerated
+  `F.abi0` wrapper happens to leave the caller's register values intact, and
+  break on a toolchain upgrade.
+- `lint nonportable-register-name`: the RAX/EAX register spellings are a gasm
+  extension; go tool asm rejects them, so files using them only link through
+  the gasm goobj path.
+- `lint unencodable-instruction`: a mnemonic in the architecture table that
+  `asm.Encodable` rejects is flagged at edit time instead of failing at
+  assembly time.
+- `audit-instructions`: black-box diff of the encoder against go tool asm.
+  As of this round the tables fully overlap on names; the audit exists to
+  catch drift in both directions (future supersets and future gaps).
+- `scaffold differential`: generates the direct-call differential skeleton
+  (two independent seed sets, output and in-place buffer comparison) that a
+  pipeline-level fuzz can never replace.
+- `verify --args`: scalar arguments for `-call`, closing the repro gap where
+  only buffers could be supplied.
+- `debug --script/--timeout/--cover`: headless debugging with a watchdog
+  armed before the ptrace attach (untracing sandboxes hang the attach), and
+  label-level block coverage for the "did my test ever enter that branch"
+  question.
+- Superset policy remains: gasm may accept spellings and encodings go tool
+  asm lacks, but such kernels ship only via `gasm asm --format goobj`; the
+  audit reports the superset surface.  The register-alias superset is warned
+  about by lint because the default `go build` path cannot consume it.

docs/DEFERRED.md

@@ -1,34 +0,0 @@
-# Deferred decisions
-
-Design decisions deliberately postponed, with enough context to pick them up
-again without re-deriving the analysis.  Each entry records what is deferred,
-why, the options on the table, and the trigger that should reopen it.
-
----
-
-## GOOBJ external (cross-package) symbol references
-
-**Status:** resolved (v0.29.0+, 2026-08-07).
-
-**Approach taken.**  Instead of parsing the compiler's iexport data (which
-would have required either `golang.org/x/tools` or an in-house parser), the
-resolver reads the **GOOBJ data directly** from the target package's `.a`
-archive.  The `.a` file contains a `_go_.o` member whose GOOBJ format is the
-same one gasm writes — the parser reuses the same layout (`blkSymdef`,
-`blkNonpkgdef`, the string table), so no new dependency was needed.
-
-**How it works.**
-
-1. `go list -json -export <pkg>` finds the target package's `.a` file.
-2. `extractGOOBJ` reads the ar archive, finds the `_go_.o` member, skips
-   the `"go object …\n!\n"` preamble and parses the GOOBJ header.
-3. `goobjFile.symbols()` walks `blkSymdef` and `blkNonpkgdef` in definition
-   order — the same order the linker uses — to build the symbol → index
-   mapping.
-4. `resolveExternalSymbols` wires the resolved `{PkgIdx, SymIdx}` into the
-   GOOBJ emission.
-
-The resolver is invoked automatically when `img.Externals` is non-empty; it
-runs `go list` as a subprocess (consistent with `toolchainObjectPreamble`
-which already calls `go tool asm`).  All symbol data is cached per package
-for the lifetime of the GOOBJ emission.

docs/DEVELOPMENT.md

@@ -4,8 +4,8 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
 
 ## Prerequisites
 
-- **Go** 1.26+ with `toolchain go1.26.5`
-- **just** — the command runner; every task below is a just recipe
+- **Go** 1.27+ with `toolchain go1.27.0`
+- **just**, the command runner; every task below is a just recipe
 - No external dependencies beyond the Go toolchain
 
 ## Quick Start
@@ -14,12 +14,17 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
 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 build     # go vet + gofmt, must pass with zero output
 just test      # full suite, race detector, 80 % coverage gate
 ```
 
 ## Just Recipes
 
+### `just install`
+
+`go mod download`.  The only module dependency, `golang.org/x/arch`, is
+used in tests only.
+
 ### `just build`
 
 Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
@@ -28,10 +33,13 @@ the minimum bar before any commit.
 ### `just test`
 
 ```sh
-go test -race -count=1 -coverprofile=coverage.out ./...
+go test -race -count=1 ./...
 ```
 
-Plus an `awk` gate that fails if total coverage is below 80 %.
+Plus a coverage run over the ten analysable packages (arch, asm, ast,
+format, lexer, lint, lsp, parser, token, verify; `debug` and `cmd/gasm`
+need hardware or are CLI glue) and an `awk` gate that fails if total
+coverage is below 80 %.
 
 ### `just fmt`
 
@@ -61,7 +69,7 @@ embedded via `-ldflags "-X main.version=..."`.
 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
+installation. Output is committed, with no runtime dependency on the
 toolchain.
 
 ### `just uninstall`
@@ -72,15 +80,15 @@ Removes `coverage.out`, the `gasm` binary, and `*.test` artefacts.
 
 ```sh
 go test -run TestVexGroundTruth ./asm/
-go test -run TestDifferentialLZ4Fuzz ./verify/
-go test -run TestFLACDecorrelate ./verify/
+go test -run TestGroundTruthBasic ./verify/
 go test -run TestGOObjectLinkAndRun ./asm/
+go test -run TestFuzzWideCopy ./verify/
 ```
 
 ## Debugger Note
 
 `gasm debug` spawns a child process from the binary on `$PATH`. It does
-not work with `go run` — install first:
+not work with `go run`; install first:
 
 ```sh
 just install-bin
@@ -101,7 +109,7 @@ 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)
+debug/              Interactive ptrace debugger (all four architectures)
 _gen/               Instruction table generator
 testdata/           Test fixtures
 docs/               Architecture, development, CLI reference

format/format.go

@@ -16,7 +16,7 @@ import (
 )
 
 // Source returns the canonical formatting of src.
-func Source(path, src string) string {
+func Source(src string) string {
 	lines := splitLines(lexer.Tokenize(src))
 
 	// First pass: classify each line and record, for every instruction, the

format/format_test.go

@@ -32,7 +32,7 @@ func TestGolden(t *testing.T) {
 		"\tVFMADD231PD Z14, Z12, Z10\n" +
 		"\tRET\n"
 
-	got := Source("f_amd64.s", in)
+	got := Source(in)
 	if got != want {
 		t.Fatalf("formatting mismatch:\n--- got ---\n%q\n--- want ---\n%q", got, want)
 	}
@@ -64,13 +64,13 @@ func TestDocCommentIndent(t *testing.T) {
 		"TEXT ·second(SB), NOSPLIT, $0\n" +
 		"\tRET\n"
 
-	got := Source("d_amd64.s", in)
+	got := Source(in)
 	if got != want {
 		t.Fatalf("formatting mismatch:\n--- got ---\n%q\n--- want ---\n%q", got, want)
 	}
 	// Body comments stay indented.
 	body := "#include \"textflag.h\"\nTEXT ·f(SB), NOSPLIT, $0\n// inside the body\nXORQ AX, AX\nRET\n"
-	gotBody := Source("b_amd64.s", body)
+	gotBody := Source(body)
 	if !strings.Contains(gotBody, "\t// inside the body\n") {
 		t.Fatalf("body comment must stay indented:\n%q", gotBody)
 	}
@@ -125,11 +125,11 @@ func TestBlankLines(t *testing.T) {
 		"GLOBL ·mask(SB), RODATA, $8\n" +
 		"DATA ·mask+0(SB)/4, $1\n"
 
-	got := Source("b_amd64.s", in)
+	got := Source(in)
 	if got != want {
 		t.Fatalf("formatting mismatch:\n--- got ---\n%q\n--- want ---\n%q", got, want)
 	}
-	if again := Source("b_amd64.s", got); again != got {
+	if again := Source(got); again != got {
 		t.Fatalf("not idempotent:\n%q", again)
 	}
 }
@@ -163,8 +163,8 @@ func TestIdempotent(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	once := Source("sample_amd64.s", string(src))
-	twice := Source("sample_amd64.s", once)
+	once := Source(string(src))
+	twice := Source(once)
 	if once != twice {
 		t.Fatal("formatting is not idempotent on the fixture")
 	}
@@ -179,7 +179,7 @@ func TestRoundTrip(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		formatted := Source(path, string(src))
+		formatted := Source(string(src))
 		if _, errs := parser.Parse(path, formatted); len(errs) > 0 {
 			t.Errorf("formatted %s no longer parses: %v", path, errs)
 		}

format/integration_test.go

@@ -29,7 +29,7 @@ func TestRoundTripRealGoLibraries(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		formatted := Source(path, string(src))
+		formatted := Source(string(src))
 		if _, errs := parser.Parse(path, formatted); len(errs) > 0 {
 			t.Errorf("formatted %s no longer parses: %v", path, errs)
 		}