

*********************
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.

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.

.. index:: debugger; starting

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:

.. code-block:: console

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

.. code-block:: console

    $ db65816 --version
    Calypsi debugger for 65816 version 5.16


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.

.. code-block:: shell-session

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

.. index:: debugger; command interpreter

``--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 :ref:`semi-hosted` for details.

.. index:: debugger; logging

``--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.
