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:

$ db68k [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:

$ db68k

Typically, specify the application program to debug on the command line:

$ db68k 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:

$ db68k --version
Calypsi debugger for Motorola 68000 version 5.16

25.3. Command line options

This section covers the db68k command-line options in detail.

Options overview

Use the --help option to display the available command-line options.

$ db68k --help
Calypsi debugger for Motorola 68000 version 5.16

Usage: db68k [--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] [--supervisor-run] [--program-start SYMBOL]
             [--semi-hosted-root PATH] [--target-remote DEVICE]
             [--serial-speed SPEED] [FILE]
  use 'db68k --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 '~/.db68k'
  --nx                     Do not read any '.db68k' 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 '68000', '68010', '68020', '68030',
                           '68040', '68060' or '68080' (defaults to '68000')
  --target TARGET          Target system, one of 'Amiga', 'A2560U', 'A2560K' or
                           'TOS' (defaults to embedded/ROM use, if omitted)
  --supervisor-run         Run program in supervisor mode (on-target debugging
                           only)
  --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.

--supervisor-run

This option is relevant when connecting to a remote target system and tells the remote system that the application must be started in supervisor mode with interrupts disabled. The application will by default start in normal mode with interrupts enabled to mimic that the application has been loaded by some operating system.

This option is ignored by the simulator which starts the application as if a reset occurred.