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

27.1. 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:

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

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

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

Note

The application will start in normal mode (also called user mode) with interrupts enabled. This mimics a situation where the application has been loaded by an operating system. You can also start the application in supervisor mode with the interrupt mask set to 7 using the --supervisor-run command-line option.