Debug Kernel

Introduction

When you program AmigaOS, sooner or later you will need tools to help you debugging your applications (and not only yours) and find out why a program crashes or runs erratically. For that you have debuggers (gdb and db101), small tools to operate with debug outputs and level of debugging (like KDebug, DumpDebugBuffer, etc.), memory trackers (like MemGuard and MemGuardian) and bunch of other small utilities and tricks which help you to do debugging. One of those tricks, which is little known, is the fact that a debug version of the standard AmigaOS kernel is publicly released ready to use for third party developers (or advanced users willing to help debugging applications).

What is "debug kernel" exactly?

Debug kernel is the same kernel as the standard one, but with added code to help catching some of the most common programming errors. This additional code adds a slightly (yet non negligible) amount of bytes to the kernel size (around half a megabyte) and is slower. Thus it has been removed from the standard kernel for performance and optimization purposes and is generally not useful to the standard average user. Yet this debug kernel can prove itself to be very useful to programmers, especially it provides the following functionality:

1. Clobbering of succ/pred pointers when a Node is removed from a list.
   One common mistake when dealing with lists is to access successor and/or previous pointers from a removed node. While at first sight it may seems harmless it may reveal itself as a dreadful bug to spot because once a node has been removed from a list nothing guarantees you that the list has not be reworked/copied/reallocated or anything else. This will give you a bug that is very hard to reproduce or even non reproducible at all. As such one should NEVER access Succ/Prev pointers from a removed Node, instead if he needs to, he should access them prior the call to Remove(). To help spotting such errors the debug kernel will modify the ln_Succ/ln_Prev pointer to a given fixed invalid value thus the bug automatically becomes always reproducible. This will also help you spot the fact one is trying to free a Node twice.
2. "Munge" of memory. With this option the debug kernel will do additional action/tests on memory pointers. It will help spotting what really happen under the hood just by observing the DAR (or DEAR on 440ep and 460ex CPUs) value in the crash log:
   • If the value is 0x00000000 (or thereabouts), then you have accessed a null pointer (and you will see 0xABADCAFE in one or more registers);
   • If the value is 0xDEADBEEF (or thereabouts), then you have accessed some memory after it has been freed;
   • If the value is 0xCCCCCCCC (or thereabouts), then you have tried to free a Node a second time.

So, in other words, when you want to catch all those problems which you can't catch by just simply running MemGuard on a "plain" kernel, you should use the debug kernel. I.e. to say it more clear, when you develop anything you should be just on debug kernel (+MemGuard/MemGuardian at background ? or its all already in debug kernel?)

How to set it up

The kernel.debug file is already placed in the Kickstart directory with all the other kernel modules. By default this directory is "SYS:Kickstart/".

The preferred way to use the debug kernel is to edit your file kicklayout, duplicate the current layout and in this duplicate modify the line pointing to "kernel" so it points to "kernel.debug", do not forget to change the label associated with this new layout by adding 'debug' or something. This way you will be able to choose which configuration you want to boot at any time.

Once you have setup the use of the debug kernel, you must also add some commandline options to the kernel. Basically in order to activate the munge option of the debug kernel you must set the variable "os4_commandline" adds the keyword "munge". This part depends on your platform firmware, please report to your documentation to know how to do it, but you have to do something like os4_commandline='munge', if os4_commandline is already set with another value you can concatenate using space e.g. os4_commandline='serial munge' to have the debug output to serial port and the munge option activated.

The following kernel command line parameters are available:

serial

Output all debug via the serial port.

baudrate [N]

Sets the serial port baud rate to N.

debuglevel [N]

Set the debuglevel where N is a value from 0 to 10.

nofpuemu

Sets the AttnFlags in ExecBase to a 68020 without an FPU.

munge

Munges freed memory so that memory trashing can be found more easily when using a debug kernel. Does nothing on a release kernel.

Note
It is strongly recommended that you do not rename the kernel.debug file.

FAQ

None at the moment