Debugging

<texit>\index{Debugging}</texit> In a perfect world we wouldn't need this chapter. In a realistic world, however, one has to take into account possible errors. While every care has taken to make the framework of the MSR as error-free as possible, there still are bugs left. For sure. But usually they are difficult to find. So, if your module doesn't work, chances are big that you don't use the framework as it's supposed to be. This chapter will help you finding where the bug is. It is then up to you to find how it has to be fixed.

When the software-radio runs in real-time, it is very difficult to debug the radio. This is due to the fact that no delay is permitted in either radio, or else synchronisation will be lost. On the other hand, in user-space, we don't have this issue. If one radio is stopped, all other radios will be stopped, too, and synchronisation will NOT be lost. For this reason, debugging in user-space is usually the only way to debug a misbehaving module.

This section gives an overview of how to use the GDB to detect some simple errors, like division by zero, or other exceptions.

<texit>\index{Debugging!Tests}</texit> The first thing to do when a module doesn't run and stops with a segmentation fault is to use make debug instead of make user. This will call the GNU-debugger, run the module and stop on the offending instruction. The most common commands after this are:

ba

show the backtrace, where the most recent function is on top

print

prints a variable of the current context

up

moves one function deeper on the stack. If it stops on a function you don't know, you can use up a couple of times until you are in the MSR

list

lists the current context. Takes as argument a file and it's line-number, like list sdb.c:234

<texit>\index{Debugging!Simulation}</texit> When running a simulation of two radios, the above doesn't work anymore. You have to start a channel-server, and the two radios. The most simple way to so is to run the server and the BS in one window, and the MS in another window.

Sometimes the two radios behave nicely, but it is only after changing some configuration-value with the visualize-tool that the system crashes. For this reason we start a visualize-tool in a third window, after the BS and MS are started. shell1, shell2 and shell3 denote three different windows or shells.

shell1:SRadio/Radios/Simple/BS$ make server debug
shell2:SRadio/Radios/Simple/MS$ make debug
shell3:SRadio/Radios/Simple$ make show

This starts the server and the BS, then starts the MS. The third line starts the visualize-tool, if you wish to do so. If an error is encountered, gdb will stop in one of the two windows, and you can use the commands described above to see what is wrong.

<texit>\index{Debugging!ddd}</texit> For better debugging, for example if your module doesn't crash, but doesn't do what you expect it to do, you can use ddd. To start it, you go to the same directory where usually you type make user and type make ddd. After this, you have to type break main.c:36 and press F3 to start the program. Once it stops on the breakpoint, all necessary libraries have been loaded and also the modules you want to debug (given that you didn't make any errors in setting up the Makefile).

Now you can enter the name of a function to debug on top in the white box and press on lookup to the right of the box. Clicking with the right mouse-button on a line you can set a breakpoint. Repeat this procedure as often as necessary, then click on cont and watch what happens. next, step, right-clicking on variables are other nice options to take. Try it, break it. Debugging is an art!

DO NOT type run in the command-line of ddd. This runs the program without any command-line options that have been carefully crafted to work with ddd. Do use the run-button or the menu Program-\textgreater{Run Again}. Optionally you can use the F3-key.