25. Debugger introduction¶
The Calypsi tool chain debugger is a source code debugger that enables you to observe program execution. It offers both interactive and script-based control. Modeled after command-line debuggers like GDB and LLDB, it shares many similarities, making it familiar to users of those tools.
25.1. Command line debugger¶
A command-line debugger provides powerful commands that are easy to
remember and understand. You can use descriptive commands like
step, break and continue rather than a set of bindings to
function keys and other more or less cryptic key bindings. Thanks to
short forms and repeating the last command with a return key press, you
can execute common and repetitive actions with single or few keystrokes.
The debugger also supports various front-ends like Visual Studio Code, Eclipse, and Emacs, leveraging the GNU project’s MI (Machine Interface) protocol for this integration.
The debugger also provides powerful scripting abilities via the Lua language. You can use Lua to configure debugging sessions, create your own commands and even make your own debugger plug-ins. The debugger offers powerful scripting via Lua. You can use Lua to configure debugging sessions, create custom commands, and develop debugger plug-ins. This is possible because the complete debugger functional API is exposed to Lua. The Lua API further extends capabilities by allowing definition of new console commands and subscription to internal debugger event notifications.
Thus, with the Calypsi debugger, you gain the advantages of both the command-line environment and integrated graphical development environments.
25.2. Running the debugger¶
The debugger’s interface is command-line based, allowing use from a terminal or connection to an IDE.
Basic invocation¶
The debugger is started in the following way:
$ db65816 [options] [debug-file] [options]
As everything on the command line is optional you can start the debugger without arguments. This will put you in an interactive debugger session:
$ db65816
Typically, specify the application program to debug on the command line:
$ db65816 application.elf
Command line options and the application to debug can appear in any order on the command line.
Command line options are optional arguments that tune debugger behavior, always starting with a dash. Two variants exist: single- letter options with one dash, and long descriptive options with two.
To display the version of the debugger, use --version:
$ db65816 --version
Calypsi debugger for 65816 version 5.16
25.3. Command line options¶
This section covers the db65816 command-line options in detail.
Options overview¶
Use the --help option to display the available command-line options.
$ db65816 --help
Calypsi debugger for 65816 version 5.16
Usage: db65816 [--version] [-i|--interpreter INTERPRETER] [--nh] [--nx]
[-e|--eval-command COMMAND] [-t|--tty TTY] [--batch]
[--logging-enable] [--logging-to-file PATH] [--logging-overwrite]
[--silent] [--extra-memory HEX-RANGE] [--stop-on-program-run]
[--terminate-on-program-exit] [--exit-breakpoint] [--core CORE]
[--target TARGET] [--program-start SYMBOL]
[--semi-hosted-root PATH] [--target-remote DEVICE]
[--serial-speed SPEED] [FILE]
use 'db65816 --help' for detailed help
Available options:
--version Display version number
-i,--interpreter INTERPRETER
Select command interpreter, one of 'Console', 'MI' or
'MI2' (defaults to 'Console')
--nh Do not read '~/.db65816'
--nx Do not read any '.db65816' file in any directory
-e,--eval-command COMMAND
Execute a single command (can be specified many
times)
-t,--tty TTY Use TTY for input/output by the program being
debugged
--batch Exit after processing options
--logging-enable Enable logging from start
--logging-to-file PATH Enable logging from start to specified file
--logging-overwrite Enable logging from start and overwrite the file
--silent Generate less messages
--extra-memory HEX-RANGE Additional memory ranges to create (simulator use)
--stop-on-program-run Stop and take control immediately when program is
started
--terminate-on-program-exit
Terminate execution of debugger if debuggee exits
(implies --exit-breakpoint)
--exit-breakpoint Insert a breakpoint at 'exit()' to detect program
termination
--core CORE Core, one of '65816' (defaults to '65816')
--target TARGET Target system, one of 'C256', 'F256' or 'SNES'
(defaults to embedded/ROM use, if omitted)
--program-start SYMBOL Program start symbol, defaults to '__program_start'
--semi-hosted-root PATH Root directory of the semi-hosted file system
--target-remote DEVICE Use remote device to communicate with target
--serial-speed SPEED Set serial speed, one of 9600, 19200, 38400, 57600 or
115200 (defaults to 115200)
-h,--help Show this help text
Options in detail¶
--interpreter, -i¶
Use this option to specify the interpreter to use. The debugger can execute either with a console interpreter or a machine interface (MI) interpreter. The console interpreter is suitable for interactive debugger sessions from the command line, which is the default. The machine interface interpreter is used when the debugger is controlled by an IDE.
--eval-command, -e¶
This option specifies a command to execute before the interactive session gains control. It can be used multiple times to specify multiple commands.
--batch¶
Terminate the debugger session after all --eval-command commands
have been processed. This is useful for automated debugger execution
from scripts.
--tty, -t¶
Specifies the application’s console tty. If the application writes
to or reads from the standard stream, this provides the tty device
for that operation.
If not specified, console output from the application is written to the console interaction. In MI mode such console output is marked so that the IDE can see that it is stream output from the application.
--semi-hosted-root¶
Specifies the host-side directory serving as the target’s semi-hosted file system. Defaults to the current directory. See Semi-hosting for details.
--logging-enable¶
Enables logging at debugger startup.
--logging-to-file¶
Specifies the logging output file.
--logging-overwrite¶
Specifies whether logging to the file should append or overwrite previously existing log file content.
--extra-memory¶
Specifies additional memory areas not part in the application that exists on a simulated target.
Memories in the simulator are normally created based on the memories found in the debug application image. This option allows additional memory regions to be created.
--stop-on-program-run¶
When the program starts, immediately take control and stop execution.
This enables debugging from the very beginning (before main() is
reached) without needing to set a breakpoint.
--terminate-on-program-exit¶
If the application exits, the debugger session also terminates. The default behavior is for the debugger to notify of the exit and remain active.
--exit-breakpoint¶
Insert a breakpoint at the exit() function. This option is not
needed if you link with debug stubs, as exit handling is provided.
--target-remote¶
Specifies the communications device to connect to a target for debugging. This disables the built-in simulator and configures the debugger for remote debugging via the gdbserver protocol, typically used for debugging on real hardware.
--serial-speed¶
Set the speed of the target remote communications serial port defined
with --target-remote. The speed defaults to 115200.
--program-start¶
This symbol defines the program’s first executable instruction. For a standard C project, avoid changing this setting.
--core¶
Specifies the core used.
--target¶
Specifies a certain target system.