The SAS/C Debugger — Advanced Topics¶

Beyond the basics of stepping and breakpoints, cdbg provides first-class support for the Amiga's runtime model: shared libraries, multitasking, AREXX-driven automation, and cross-debugging across a serial line. Source: Vol 2 Ch.5–8.

Debugging shared libraries¶

Vol 2 Ch.5. A shared library (.library opened via OpenLibrary()) is a separately loadable code module shared between processes. cdbg can attach to a library to set breakpoints, examine its data, and step through its functions.

Attaching to a library¶

cdbg lib:my.library              # debug the library code directly
cdbg --library lib:my.library    # alternative form

The library is loaded as if by OpenLibrary, and execution starts at its initialization function. The library is run in a private task; you do not need to launch a host program to debug it.

Symbol resolution¶

cdbg reads the library's resident structure and the .library file's hunk format. To find symbols in a private library that is not resident, the file must be present on the debug path. The debugger searches:

The current directory
The path in LIBS:
Paths in the SEARCHPATH environment variable
Paths given with set library-path at the cdbg prompt

Setting breakpoints in library code from a host program¶

Often you want to break inside a library function while running a host program. Compile the host with full debug info and run it under cdbg; the library's symbols are loaded automatically if the library file is on the search path.

(cdbg) break Open                # breaks at exec.library's Open()
(cdbg) break dos.library:Open    # explicit library qualifier
(cdbg) continue

cdbg will halt when any task enters Open() — useful, but can be noisy. Use info tasks to see what task hit the breakpoint.

Debugging multitasking programs¶

Vol 2 Ch.6. AmigaOS is preemptively multitasked. A program may spawn child tasks via CreateNewProc(), CreateTask(), or library functions that internally spawn tasks (the CON-Handler, the RAM-Handler, datatypes workers, the TCP/IP stack, ARexx hosts). A bug in a child task can be invisible from the parent's debugger.

Task model in `cdbg`¶

cdbg tracks the entire task tree:

(cdbg) info tasks
Task name         State    PC              Tid  Parent
main              stopped  0x40123456      1    0
CON-Handler       running  0x40200abc      4    1
worker            stopped  0x4012bcd0      5    1
(cdbg) task 4                    # switch to CON-Handler

cdbg follows Forbid()/Permit(), exceptions, signals, and breakpoints across all tasks it knows about.

Stopping a specific task¶

(cdbg) break Open                # breaks when any task enters Open
(cdbg) condition 1 tid == 4      # only break for task 4
(cdbg) task 4
(cdbg) continue                  # run task 4, others paused

Multitasking-specific gotchas¶

A breakpoint hit in one task does not pause other tasks. They continue running and may consume data, send messages, or modify state while you step in the debugged task. This is a feature: the system keeps "alive" so you can debug race conditions.
Signals (SIGBREAKF_CTRL_C etc.) can be sent to specific tasks with signal task 4 SIGBREAKF_CTRL_C.
Forbid/Permit is not held across cdbg commands. If you are stopped inside Forbid() and a higher-priority task is waiting, the system may deadlock waiting for Permit(). Use task to switch back to the main task before running for long.

AREXX Macros with CodeProbe¶

Vol 2 Ch.7. The full cdbg command set is accessible from AREXX, allowing automation, regression-test drivers, and integration with external tools.

The CodeProbe AREXX port¶

cdbg opens a port named CDBG. External programs send commands as AREXX strings:

/* Regression test driver */
ADDRESS CDBG
'break main'
'continue'
'WAITFORSTOP 30'              /* wait up to 30s for the program to stop */
if RC ~= 0 then do
  say 'Program did not reach main() in 30s'
  exit 10
end
'step 10'
'print result'
'quit'

Built-in AREXX commands¶

Command	Purpose
`BREAK`	Set a breakpoint
`CLEAR`	Remove a breakpoint
`CONTINUE`	Resume execution
`STEP` / `NEXT`	Single-step
`PRINT`	Evaluate expression
`SET`	Set debugger variable
`WAITFORSTOP`	Block until program stops, with timeout
`EVALUATE`	Parse an expression and return a numeric/string result
`QUIT`	Exit CodeProbe

WAITFORSTOP is the key command for scripted debugging: it makes AREXX pause without busy-waiting, so a test driver can run for hours without consuming CPU.

Cross-debugging¶

Vol 2 Ch.8. Cross-debugging runs cdbg on a host machine (typically a serial-connected development workstation) and the target program on a remote Amiga over a serial line. The host sends commands, the target returns state.

Setup¶

Both machines need a serial port configured at 9600–19200 baud, 8N1, with hardware flow control. The target runs a small stub that the host's cdbg connects to.

# On the target (after booting Workbench)
cdbg-stub -serial serial.device -unit 0 -baud 19200 myapp

# On the host
cdbg --remote serial.device --unit 0 --baud 19200 myapp

The myapp binary must be identical on both sides (or at least the same hunk layout — symbol tables are read from the host's copy).

When to use cross-debugging¶

The target crashes before any screen output is visible (early-boot bugs, exception handlers).
The target has no display (headless server, custom hardware).
You want to debug a release build that doesn't include a UI for the debugger.

Latency notes¶

Each cdbg command crosses the serial line twice (request + reply).
Single-stepping produces 2 RTTs per instruction; debugging a 1000-line function step-by-step takes minutes.
Prefer breakpoints and continue over step-by-step in cross-debug.

Vol 2 Ch.8 — Cross-debugger protocol¶

The cross-debugger uses a simple binary protocol. Packets are:

BREAKPOINT (host → target): set a software breakpoint
RESUME (host → target): continue execution
STOPPED (target → host): halt notification, with reason
READ_REGS / WRITE_REGS: register access
READ_MEM / WRITE_MEM: memory access
EVAL_EXPR: expression evaluation

The protocol is undocumented for end users; the source of cdbg-stub ships with the compiler in sc:debug/ for those who need to extend it.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search