Accreted Drivel

Steven Tattersall's personal blog

hrdb (Hatari Remote Debugger GUI)

Created on: 2021-08-07

Posted in atari hatari debugging


Contents

Introduction

hrdb is my debugger GUI for Hatari. It runs as a standalone Qt C++ application, which connects to a custom build of Hatari using a simple TCP protocol. It should support Windows, Mac and Linux platforms.

WARNING This application is a personal and experimental project. It might not be maintained, will be updated according to my whim, and is not associated with the main Hatari team.

The tool currently only supports 68000-based machines (Atari ST/STe). Currently work is focussed on making the workflow optimal with standard ST/STe setups, rather than supporting all the Atari 16-bit range. The emphasis is on a fast update speed and a keyboard control style similar to traditional ST debuggers like MonST and Bugaboo.

hrdb screenshot

The changes to the Hatari codebase are as minimal as possible. It should be possible to merge fixes and improvements from the Hatari repository, without breaking the remote debugger.

Building or Downloading

To download a prebuilt version for Windows, go here and download the hrdb-0.001-win64.zip file. No install is needed. hrdb is built against Visual Studio 2019 Community Edition, so might require the runtime installer.

Windows/Mac

It is possible to build the code using the Github repo. You must use the branches "debugger-extensions" or "one_with_everything" to get the hrdb functionality. Building Hatari uses the normal Hatari build system (CMake and make).

Building Hatari for these platforms is not straightforward. Building hrdb uses the standard Qt build process.

For clues about building Hatari on Windows, see my article here. It can also be built using MSys2/MinGW on Windows, or Cygwin.

The hrdb application uses only the code in the tools/hrdb path, and uses the standard Qt application build process, either using qmake or via Qt Creator if you want to make changes yourself.

To build hrdb, you will need a version Qt 5.11 or later. On Mac, Qt5 can be installed using brew. On Windows it will require the Qt installer, or building Qt from source.

Linux and Building From Source

Building Hatari from source normally involves the "configure" script and then running "make install". This process is detailed in the normal Hatari source code distribution README.

To build hrdb, most Linux distributions offer Qt 5 as a packaged install.

On Debian, I use

sudo apt-get install build-essential libgl1-mesa-dev  # for standard C++ build tools, optional
sudo apt-get install qt5-default

Then to build:

git clone https://github.com/tattlemuss/hatari.git
git checkout debugger-extensions
cd tools/hrdb
qmake .
make

Using Hatari and hrdb

Important! You must use the version of Hatari in the hrdb release; normal versions do not have the correct network debugger support.

There are 2 main ways you can use the debugger with Hatari:

  1. Run Hatari as normal. Hatari will open up a listening connection on port 56001 and will take control operations from this network port rather than the command-line debugger Hatari normally uses. You can then run hrdb at your leisure (e.g. if you hit an exception) and it will attempt to connect to Hatari.
  2. Run hrdb and use the "Run..." dialog to launch Hatari with command line options. hrdb will run Hatari and connect immediately. Optionally you can force Hatari to break on startup or when a program is loaded.

The User Interface

hrdb has several main UI elements. All are dockable with the exception of the Register View.

Register View

Register view on Linux

The Register View is a standard display of the next instruction and register values. It also contains the buttons to control the main CPU start/stop/step behaviour.

Buttons

The coloured rectangle reflects the status of Hatari: grey is "not connected", green is "running" and red is "stopped".

The following will control running the program:

Next instruction

The view shows the disassembled instruction at the current PC. If the instruction is a conditional branch, it will display [TAKEN] or [NOT TAKEN] depending on the Status Register's condition codes.

It will also decode the Effective Addresses for the instruction, if applicable, and show their values and optionally symbol names if available.

Registers

The main CPU registers are displayed as hexadecimal. Using mouseover will display register values as decimal, binary and ASCII.

If a register value has changed while the CPU is active, it will be displayed in red.

Hovering over register values will show the previous value (if different), and the values as decimal, binary and ASCII.

Right-clicking on values will give a context memory, where values can be used as the base addresses for Disassembly or Memory windows.

Disassembly Window

Disassembly view on Linux

The Disassembly Window shows disassembly of the specified region of memory. To give it keyboard focus, click on the disassembly area, or press Alt+D for Disassembly View 1.

The Up/Down/PageUp/PageDown keys allow scrolling through memory. The active cursor row is highlighted.

The key shortcuts for start/stop/step as described in the Registers View are still active while using this view. The "Follow PC" option makes the top line of the disassembly reflect the current Program Counter.

If Hatari symbols are loaded, they will be displayed in the first column of the disassembly.

The column after the disassembly is a "comments column" which tries to evaluate Effective Address calculations for the operands, and match them to symbols (if loaded.)

Active breakpoints using a simple "PC=xxx" expression are shown with a red circle.

Ctrl+B toggles a PC Breakpoint at the active cursor row.

Ctrl+H, meaning "Run to Here", sets a breakpoint at the current cursor instruction and starts execution. The breakpoint will be deleted when hit.

Right-clicking on a row gives the following options:

Memory Window

Memory view on Linux

The Memory Window shows a hexadecimal and ASCII view of the specified region of memory. To give it keyboard focus, click on the disassembly area, or press Alt+M for Memory View 1.

You can select whether to view the data as Bytes, Words or Longwords using the Combo Box. You can also lock the memory address to an expression (e.g. "a1" or "a7-$20") which will update as the CPU changes.

If a byte of memory has changed while the CPU is active, it will be displayed in red. The hrdb application caches the visible memory contents when the CPU is started and compares with when it stopped, so this highlighting isn't available for the entirety of memory, only your active view.

The Up/Down/Left/Right/PageUp/PageDown keys allow moving through memory. The active cursor row/column is highlighted.

Entering hex values (0-9 or A-F) will edit the nybble under the cursor and update the memory in Hatari.

Graphics Inspector

Graphics Inspector

The Graphics Inspector allows you to view Hatari's memory as 1, 2 or 4-bitplane images. It is not the final Hatari screen which is displayed in the Hatari UI (with all raster effects etc).

It is possible to lock the base address of the view to the current video pointer registers ($ff8201 etc), and use the current video palette. However you can override these settings to allow custom sizes, formats and palettes.

Pressing Alt+G moves keyboard focus to the displayed image. Using the cursor keys and PageUp/PageDown allow you to scroll around memory. Shift+Up/Down moves by 8 rows of memory.

Since it can view a large amount of data in one go, this view is updated shortly after the CPU stops, so there is a minor delay to updates when stepping etc.

This view is useful for debugging things like intermediate data buffers, preshifted sprites, or the backbuffer screen that your code is writing to.

Keyboard Shortcuts

The up-to-date set of shortcuts is available here. This is a copy:

Normal focus

(always active unless in dialog, text boxes)

Disassembly focus

Back to Index