Documentation: Debugging Crashes
Sometimes software crashes and you end up with an obscure-looking error message on the screen. As we’re releasing bits of RISC OS and don’t have the resources to thoroughly test everything, it’s quite possible that people will find some of these have bugs and crash.
This page is a brief guide on how to attempt to grab some debugging information which can be sent to us (or the software author) in order to help us or others find and fix the bug.
Common serious error messages tend to say stuff like this:
"Abort on data transfer..."
"Prefetch abort..."
"Address exception..."that kind of thing. These messages usually have some other numbers or odd looking stuff in them. Telling the software author just the first bit really won’t help them to fix the bug; they need more information.
What leads up to the crash?
Your first step is to try to get the bug so that you can roughly repeat it. Once you’ve managed that, you should know the rough sequence of events that you go through before it happens.
This is easier than it sounds, of course. Some bugs are obscure and you only see them the once and others seem to happen at random intervals. Your only hope of debugging those types of bug is to be prepared in advance – as explained below.
If you can repeat a crash through some sequence of actions, that sequence is usually of great importance to the software author so will be among the first useful bits of information you can give them.
Being ready for a crash
Next, you should load a couple of debugging modules which we have published on our download pages. These modules are called:
- DebugTools
- DebugButton
You can either double-click them to load them or you can put them into your !Boot.Choices.Boot.PreDesk directory so that they are loaded every time your computer boots.
The first module provides lots of debugging features which are mostly useful to programmers but one in particular which is used in this explanation (called *Where).
The second will add a button called “Debug” to the error box for all ‘serious’ errors (these are the types of errors which normally have “Describe” and “Quit” buttons).
If these two modules are running at the time of the crash, you can get lots of important information.
When the crash happens
Right, if the crash leads to an error box which says “Describe”, “Quit” or “Continue” you should click on the “Describe” button.
A new error box will appear – make a note (on paper) of the full error message. You should now see the “Debug” button, click on it and a special window will open. This is a command line, where you can type debugging commands.
The sequence of commands you can do might look like this:
| *Spool $.capture | – copies any further text into a file |
| *Modules | – outputs a big list of all loaded modules |
| *Where | – outputs information about last serious error |
| *ShowRegs | – outputs some internal CPU state information |
| *Spool | – closes the text capture file |
You can exit the debug window by typing *quit and pressing return.
Sending the report to the author
If you look at the contents of your main hard drive (normally the one with !Boot on it) you should find the capture file – we called it ‘capture’ in the example above. This is actually just a text file which can be viewed in Edit, Zap or StrongED.
Send that file along with your description of the events surrounding the crash to the software author and they will have a much better chance of figuring out what went wrong.
The ROOL bug database
You will notice a set of links along the top of our web site. One of these says “Bugs” and takes you to our bug database. Anyone can add bug reports, edit bug reports or comment on existing bugs.
To do that, you simply need to register an account with our web site (see the “Log in” link top-right) so that we know who reported which bugs. Asking people to register with our site also helps to stop people from filling the bug database with spam!
Once you’ve logged into our site, you can simply create a new bug report where you enter the main information about the bug. It is also possible to attach files to your bug report (such as the ‘capture’ file described above).
Be sure to have a quick scan first through the bugs that are already in the database – someone may already have spotted and reported the same issue as you.
Thanks for your help!
