AmiWest 2013 Lesson 1

How to Crash

As any Amiga programmer knows, crashing an Amiga isn't very difficult. The trick is to figure out why it crashed and how to find that line in your source code which caused the problem. This lesson will focus on how to help programmers locate and fix bugs quickly using the tools available.

Prerequisites

Install the Sashimi tool somewhere in your system path. Then edit your S:User-Startup file and add the following line:

Run >NIL: Sashimi CONSOLE BUFK=1024 NOPROMPT ASKEXIT ASKSAVE

See the Sashimi documentation for what all the options means.

Meet the Reapers

When your Amiga crashes two main things happen:

1. Exec's Reaper is notified of the crash and tries to handle the crash.
2. Reaper then launches Grim Reaper which attempts to try and handle the crash.

Exec Reaper

The Reaper is always running in the background and is waiting for something to do. It is launched by the Exec kernel. When Exec runs into a problem it notifies Reaper which is then responsible for handling the crash. Reaper has no GUI but it does have some limited amount of control via DOS environment variables. For information this can be found in the Exec Debug section.

Output from Reaper is to the default serial port. If you don't have the serial port hooked up or use a tool like Sashimi to capture the output then you would probably never know the Reaper even existed.

It is important to know about the Reaper because sometimes the Grim Reaper may not be able to be launched. This can happen when working with GUI applications which crash badly for example.

The Grim Reaper

The Grim Reaper is the tool most Amiga users get a visit from sooner or later. It is launched by the Reaper which is built into the kernel. The Grim Reaper is an application that resides in the SYS:System directory. As such, it requires many more system resources to function like DOS, BOOPSI, input.device and usually USB. If you have a crash which causes a total system freeze or the GUI is not usable you must resort back to the Reaper for assistance.

When the Grim Reaper opens up it displays a nice GUI with plenty of information about the crash site.

Underneath The Covers
Both Reaper and the Grim Reaper utilize debugging functions provided by Exec to perform a stack trace and interpret debug symbols. See exec.doc in your SDK and look for StackTrace(), ObtainDebugSymbol(), ReleaseDebugSymbol(), ReadTaskContext() and WriteTaskContext().

Capturing Debug Output

Interpreting the debug output of the Grim Reaper can be rather daunting and that is what we will be exploring.

Here is an example program from which we will start working:

#include <exec/types.h>
 
int main()
{
	uint32 *zero = 0;
	*zero = 0;
	return 0;
}

Although simple, this program will enable us to explore how to read the Reaper (serial port) and Grim Reaper (GUI) output. We will show you how to turn debugging symbols on and off. The stack trace will be our first stop on the road to figuring out just what happened and why.

There is also the Exec Debug Kernel which will be using to help us with debugging our programs.