Showing changes from revision #9 to #10: Added | Removed | Changed

Generally speaking, RISC OS lacks the powerful IDEs and debugging tools that are found on other platforms. But, that doesn’t mean that you’re completely in the dark when it comes to debugging code.

The Debugger Module

The Debugger module is built in to every ROM image and includes:

• A disassembler
• Support for assembler-level breakpoints
• The ability to read/write arbitrary memory
• The ability to view the registers at the time of the last unhandled CPU abort/exception
• The Exception Dump feature, for capturing and unwinding stack traces when unhandled CPU aborts/exceptions occur

GDBServer

If you’re using GCC, it should be possible to run GDBServer on RISC OS and use GDB to debug programs from a remote machine.

Reporter

Reporter is a well-established debugging aid, capable of being used either as a simple logging tool, or as a system-wide monitoring system for tracking many RISC OS specific events. In particular, it has many features designed to aid the debugging of BASIC programs.

SysLog

A RISC OS version of syslog, implemented as a module, is available. This provides an easy-to-use logging system, although it isn’t particularly well suited to low-level code (e.g. interrupt handlers).

DebugLib

DebugLib is a C library for debug logging that was developed and used internally by Acorn, and is now available in the ROOL source tree. It supports a large number of log output backends, making it suitable for a wide variety of purposes. However, since it’s mainly an “internal” thing, it might not be straightforward to build and use it outside of a RISC OS source tree.

DADebug

DADebug is a simple module that implements a log buffer in a dynamic area. What separates it from other debugging tools is its simplicity – which also makes it a popular logging choice for low-level code where file, network, or serial output would be too slow or otherwise be unsuitable. The module is located in ROOL source tree, and has a couple of build-time options which can be tweaked in order to customise the module for specific situations.

DebugButtn

The DebugButtn module is another tool which adds an extra “Debug” button onto error boxes for serious errors. Clicking this button will drop you into a command line where you can do useful stuff like *Where and *Memory whilst the task which crashed is still paged into memory.

Pre-built versions of DebugButtn are available in the Bonus Binaries download available from the misc downloads page

DebugTools

DebugTools is another module which provides a number of utility *Commands which can be used to examine or alter low-level elements of the system state, e.g. vector and IRQ claimants.

Pre-built versions of DebugTools are available in the Bonus Binaries download available from the misc downloads page

HangWatch

The HangWatch module, available in the ROOL source tree, implements a watchdog timer by using a HAL timer that’s configured to generate FIQ interrupts. Since RISC OS rarely uses FIQs, this makes it a fairly reliable watchdog system. When the watchdog timer expires, the system will be halted and a configurable core dump will be output via HAL_DebugTX (i.e. via the serial port).

The primary use is in debugging total system lock-ups (e.g. when the system becomes stuck in a state where IRQs are permanently disabled), or other situations where the system becomes unresponsive. However, since it relies on HAL_DebugTX, you will typically need to build your own ROM image in order to enable support for the debug calls in the HAL.

ZeroPain

The ZeroPain module allows for tracking of reads & writes to “zero page” (the first 16K of RAM, from &0 to &4000), on systems where high processor vectors/zero-page relocation is in effect. Currently, its logging facilities are slightly more advanced than those used by the Debugger in its exception dumps.

Pre-built versions of ZeroPain are available in the Bonus Binaries download available from the misc downloads page

HAL debug API / kernel debug terminal

If you’re capable of building your own ROMs, then the HAL debug API and kernel debug terminal are two other debugging methods that will be available to you.

• HAL_DebugRX and HAL_DebugTX are two HAL entry points that can be used for debugging using simple character I/O. In most HALs they will be used to send and receive characters over the serial port, typically using a 115200 baud, 8n1 connection with no flow control. By default, mature HALs will have these entry points disabled, so you’ll have to enable them by changing the relevant option in the HAL sources.
  • Apart from the main debug switch, you may also have to change a setting elsewhere in order to prevent RISC OS trying to drive the appropriate serial port as a regular serial port, otherwise you may lose your debug functionality partway through ROM module initialisation. E.g. if the serial port is normally exposed via the HAL UART API , removing DualSerial and/or SerialDeviceDriver from the components file will be sufficient.
• The kernel has a DebugTerminal option in hdr.Options which will cause HAL_DebugRX and HAL_DebugTX to be used by OS_ReadC & OS_WriteC. This is useful for if a hardware port doesn’t have a working keyboard input driver, or if it doesn’t have a working display driver, or if you just want to log the IO to another machine.

FIQProf/profanal

FIQprof and profanal are two complementary tools for performing system-wide, sample-based profiling (FIQprof), and for analysing those profiles (profanal). Similar to HangWatch, FIQprof makes use of a HAL timer that’s been configured to generate FIQs, making it suitable for use with profiling IRQ handlers.

Current versions of the tools aren’t really suitable for profiling Wimp apps, as the profiler doesn’t have the ability to record what the current task handle is. But for single-tasking apps or module code it should be fine.

For system-wide profiling, the tools are best used with ROMs which you’ve built yourself, since they’re able to load the symbol files that the build system leaves behind in the build tree.

Hdr:Debug, Hdr:NdrDebug

Hdr:Debug and Hdr:NdrDebug are a couple of debug logging libraries for assembler components, available from the standard Hdr include path. Most assembler components in Git are capable of using one or the other, but each one supports a number of different output backends, so the distinction rarely matters.

One thing to be wary of is that some output backends require the executable binary to be writable – which is a problem if that binary happens to be a ROM module. The typical workaround for this is to temporarily make ROM writable, by having Kernel.s.HAL map it with different access privileges (e.g. replace ‘AP_ROM’ with ‘AP_Read’). If you’re able to soft load the module you’re working on, then this shouldn’t be an issue.