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

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. More information about this can be found in the Exec Debug section.

Output from Reaper is directed to the default kernel console. Normally, this means the output is invisible unless you know to look for it.

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. Output can be to the default kernel console and/or a file.

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

It can be very frustrating when you have a crash but no way to capture the crash output. We will now explore your options to make sure you get something to work from.

Kernel Console

Since kernel 51.44, all debug output is placed into a special private memory buffer. That means Reaper and Grim Reaper and any other output from the kernel does not appear to go anywhere. You can dump the contents of this private memory buffer using the DumpDebugBuffer command.

Open a shell and type

DumpDebugBuffer

If an Amiga programmer has nothing else he has this debug memory buffer to work with. The buffer is designed to survive a warm reboot.

Serial

The absolute best way to capture debug output is via the serial port. Ideally, that means a direct serial port to serial port connection. See the Advanced Serial Debugging Guide for all the gory details.

We won't be using actual serial ports at AmiWest due to the complexity involved with having another computer to capture the output. When debugging low level things like device drivers, etc. another computer to capture serial output is absolutely essential.

Changing the Kernel Console

The kernel console defaults to writing into a debug buffer.

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.