116 lines
2.9 KiB
Groff
116 lines
2.9 KiB
Groff
.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)
|