2. Getting started

The Calypsi debugger is a command line tool named dbnut. Running it from the command line with the ``–help`` option will give a sign-on message and display accepted options:

Calypsi debugger for Hewlett-Packard Nut version 5.16

Usage: dbnut [--version] [-i|--interpreter INTERPRETER] [--nh] [--nx]
             [-e|--eval-command COMMAND] [-t|--tty TTY] [--batch]
             [--logging-enable] [--logging-to-file PATH] [--logging-overwrite]
             [--silent] [-p|--port PORT-NUMBER] [--disable-web-server]
             [--load-module FILE] [--save-state FILE] [--extended-ram] [FILE]
  use 'dbnut --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 '~/.dbnut'
  --nx                     Do not read any '.dbnut' 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
  -p,--port PORT-NUMBER    Port number, defaults to '8080'
  --disable-web-server     Do not start any web server
  --load-module FILE       Load module file (.mod extension)
  --save-state FILE        Where to save calculator state (defaults to
                           '/home/hth/.dbnut/hp41.state')
  --extended-ram           Provide RAM in the 400-FFF range (NEWT style RAM
                           memory)
  -h,--help                Show this help text

2.1. User interface

The debugger simulates an HP-41 calculator internally, but in order to control the calculator we need to be able to push button and watch the display. Rather than opening a traditional graphical user interface, the debugger relies on web technologies and starts a web server.

HP-41 web application

The web application, or HP-41 front end is included in the installation under hp41-ui/hp41.html. Simply open it in any web browser and it will connect to the debugger.

The source code for the user interface project can also be found at dbnut-ui.

Note

You should only have one HP-41 web application front end open at any time. Having multiple ones will cause them to fight over which is the user interface as the debugger expects to talk to a single front end. If this happens a notification will be written to the debugger console output. Simply close one of the front ends if this occurs.

Protocol

The web server acts on simple JSON-RPC commands passed over a web socket. Typically key presses are passed from the web application and notifications about display updates are passed back. The user interface is in other words quite dumb. All processing takes place in the debugger.

2.2. Starting

The Calypsi debugger simulates the HP-41 Nut processor with an attached HP-41 memory system. In order to do anything meaningful you need to provide a mainframe (operating system) image. Such image contains the internal ROMs of the HP-41 and is not included with this product.

The minimal command line to start the Calypsi debugger in a meaningful way is:

$ dbnut --load-module 41cv.mod

Where 41cv.mod is the mainframe as a module file. The Calypsi debugger can also be started as an HP-41CX using an appropriate module file.

Note

Extended memory and the clock chip is currently supported, but the beeper is not.

You can plug in other modules as well, simply specify each one using the --load-module option:

$ dbnut --load-module 41cx.mod --load-module ppc.mod --load-module zenrom.mod

To debug your own module at MCODE level you should build it using the -g option to produce debugging information. The linker will normally produce an ELF/DWARF executable image with the .elf extension that can be loaded by the Calypsi debugger:

$ dbnut --load-module 41cx.mod myimage.elf

Command line

Once the Calypsi debugger is started it responds with:

$ dbnut --load-module 41cx.mod myimage
Calypsi debugger for Nut
listening for user interface connections on port 8080
(dbnut)

The debugger announces its presence and opens a web server for the user interface. The (dbnut) text is the command prompt indicating that it is ready for commands.

At this point the debugger is ready to start a debug session with the modules specified by --load-module options loaded. However, the simulated process does not yet exist.

To start the program and create a process for it, simply run it with the run (or just r) command:

(dbnut) r
running

The debug process is created and execution starts, however it does not get so far as the calculator starts in sleep. To wake it up, press the ON button on the calculator user interface.

Note that after the running message, you will not get the prompt back. This is because the calculator is active. To take control again in the debugger, press Ctrl-c in debugger console window.

(dbnut) r
running
^C
program received signal SIGINT, interrupt
0x0000
(dbnut)

The running program received an interrupt signal at address 0x0000. The debugger is now in control and is ready for more commands as indicated by that the prompt is back.

To terminate the session and leave the debugger, use the quit command (or q for short).

More on running from the command line can be found in Console command line.

Machine interface

The MI (Machine Interface) is intended for debugger front-ends like Visual Studio Code. To start the Calypsi debugger in MI mode, add the -i mi or --interpreter mi to the command line:

$ dbnut --load-module 41cx.mod -i mi myimage

If you try it you will find that the MI mode is quite a bit less friendly than the command console. However, it does provide additional commands and some commands provide additional information that are not given in the console mode. For a very experienced user it may sometimes be desirable to issue an MI command, but that is better done using the console command interpreter-exec MI "command" which invokes an MI command from the console. This provides you with the usual powerful console mode and allows occasional use of MI commands, should the need arise.

Note

Switching between console and MI modes once the debugger is started is not possible. However, both modes provide a command that allows a command to be issued in a specified command interpreter.