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.

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 Output

There are two ways to change the kernel's default console output:

1. Using the firmware to pass the serial parameter to the kernel.
2. Using the KDebug command from a shell.

Each Amiga's firmware has a different method for setting firmware variables and that will not be covered here. What is important is that you pass the serial parameter to the kernel. Usually the os4_commandline variable is the correct one to use.

You may also change the kernel console output default using the KDebug command. The following will change the console to the default serial port:

KDebug console serial

To switch back to using the private memory buffer use:

KDebug console memory

Sashimi

The Sashimi tool can be used to redirect the kernel console output to a window which can be very convenient when a serial link is not available.

To use Sashimi right now type the following into a shell:

Run >NIL: Sashimi CONSOLE

This will immediately open a window where the output will be going from now on.

It is important to remember that this window will not survive a reboot or system crash. If you want to save the output then you need to save it to a file using CTRL-F.

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.