

****************
Remote debugging
****************

This chapter describes how to set up remote debugging to a target. In this
scenario, the debugger runs on the host and connects to, controlling, an
application on actual hardware.

The gdbserver protocol is used for communication. It can be implemented
by a small agent on the target or a bridge process on the host that
translates between gdbserver and hardware-specific protocols.


Serial port
===========

Target debug support can be implemented by placing a small debug agent
software on the target. The RS-232 serial port can be used for this.
Since most host computers lack these ports, a USB-to-serial converter
(e.g., FTDI USB-RS232, often with bare wires requiring a soldered
connector) can be used.

Most major operating systems include drivers for the FTDI USB-RS232 cable.
If you choose other cables, you may need to install a driver, which you can
obtain from the USB-RS232 cable vendor.

Finding the device
------------------

On Linux and macOS, the serial port is typically found in ``/dev/ttyUSBn``,
``/dev/ttySn``, or similar. Use the ``dmesg`` command to query for USB devices:

.. code-block:: sh

   $ sudo dmesg | grep USB
   ...
   [109191.143623] ftdi_sio 1-1:1.0: FTDI USB Serial Device converter detected
   [109191.151619] usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB1

Here you can see that a FTDI serial device is attached to ``/dev/ttyUSB1``.

.. note::

   If you solder a serial port connector, be careful about which pin
   numbering. Also note that a DB-25 connector has the receive
   and transmit pins (numbers 2 and 3) are wired oppositely compared to a
   DE-9 connector.

Setting the speed
-----------------

The speed can be set with the ``--serial-speed`` command-line option, which
defaults to 115200 if not specified.

Testing the port
----------------

If you have the ``screen`` utility program installed it can be started
with parameters to test that the serial port works:

.. code-block:: sh

   $ screen /dev/ttyUSB1 115200

Once started, you can verify debugger agent responsiveness by pressing
any character; a ``$S13#b7`` packet reply confirms it.

You can exit by pressing Control-A followed by a backslash (``c-a \``).
Some `screen` versions require Control-A followed by Control-backslash.


Installing the agent
--------------------

The Calypsi remote debugger agent for the serial port must be downloaded,
built, and executed on the target hardware. Download it from
`<https://github.com/hth313/Calypsi-remote-debug>`_.


Starting the debugger
---------------------

Once the debugger agent runs on the hardware and the communications
channel is configured, you can start the Calypsi ``db6502`` using:

.. code-block:: sh

   $ db6502 --target-remote /dev/ttyUSB1 application.elf


