.TH GASM-DEBUG 1 "2026-09-19" "gasm" "User Commands"
.SH NAME
gasm-debug \- interactive source-level debugger for JIT-assembled functions
.SH SYNOPSIS
.B gasm debug <file.s> \-\-func <name>
.SH DESCRIPTION
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.
.PP
With
.B \-\-script
the REPL commands run from a file and the session ends: the headless
mode CI and scripts use.
.B \-\-cover
runs to completion with a breakpoint on every instruction and reports
which executed and how often, the label-level coverage view.
.SH REPL COMMANDS
.TP
.B break \fIlabel|addr\fR [\fBif \fIreg op val\fR]
Set a breakpoint, optionally conditional on a register comparison
(register against register or immediate).
.TP
.B delete \fIlabel|addr\fR
Remove a breakpoint.
.TP
.B info break
List all breakpoints.
.TP
.BR step " [" n ], " s
Single-step n instructions; the default is 1.
.TP
.BR next ", " n
Step over a CALL.
.TP
.BR finish ", " fin
Run until the function returns.
.TP
.BR continue ", " c
Run until a breakpoint, watchpoint or exit.
.TP
.BR disas " [" n ], " u
Disassemble n instructions at PC.
.TP
.B regs
Print general-purpose and vector registers.
.TP
.B where
Show the source line and nearest label at PC.
.TP
.B stack
Show the stack near RSP (return address and ABI0 args).
.TP
.BR bt ", " backtrace
Backtrace: current frame plus return address.
.TP
.B x [\fIaddr\fR] [\fIlen\fR]
Hex-dump memory; the defaults are the current PC and 64 bytes.
.TP
.B w \fIaddr val...\fR
Write bytes to memory.
.TP
.B set \fIreg value\fR
Set a register.
.TP
.B watch \fIaddr\fR [\fBr|w\fR] [\fIsize\fR]
Set a hardware watchpoint; writes are watched by default.
.TP
.B unwatch [\fIslot\fR]
Clear one watchpoint, or all without an argument.
.TP
.BR labels ", " l
List function labels and offsets.
.TP
.BR help ", " h ", " ?
Show command help.
.TP
.BR quit ", " q
Kill the debuggee and exit.
.SH OPTIONS
.TP
.B \-args \fIfile\fR
File containing the ABI0 argument block.
.TP
.B \-buf \fIspec\fR
Buffer specification: name:size:pattern[,name:size:pattern...] where
pattern is zero, ones, seq, or hex.
.TP
.B \-cover
Run to completion with a breakpoint on every instruction and report
which executed and how often.
.TP
.B \-func \fIname\fR
Function to debug.
.TP
.B \-script \fIfile\fR
Run REPL commands from a file (one per line) and exit; - reads stdin.
.TP
.B \-timeout \fIduration\fR
Kill the debuggee after this duration (e.g. 30s); for headless --script
runs; a timeout exits 3.
.SH EXIT STATUS
Exits 0 when the scripted session completes, 1 when the debuggee crashes
or a check fails, and 3 when
.B \-\-timeout
kills the debuggee; the debugger is Linux-only.
.SH EXAMPLES
.nf
gasm debug \-\-func name k.s
gasm debug \-\-func name \-\-script cmds.txt \-\-timeout 30s k.s
gasm debug \-\-func name \-\-cover k.s
.fi
.SH SEE ALSO
.BR gasm (1),
.BR gasm\-verify (1)