On the Internet you can find a lot of GDB tutorials; ranging from the simple ones, which give you a basic reference for GDB, up to the big tutorials and documentation (including the official ones). Of course, none of these are written in the context of Amiga OS4, because for the rest of word AmigaOS is very obscure, and as result all those GDB tutorials are oriented towards x86/UNIX, or occasionally PPC/Sparc/Alpha based Unixes (although those still look pretty much the same, as it is still UNIX). In the case of Amiga OS4, the SDK documentation just includes the official GDB docs, which cover just the GDB itself without taking Amiga OS4 into account. Some of you may remember that GDB on Amiga OS4 worked reasonably well on the early versions of the OS, prior to the first releases of OS4.1, which brought a lot of changes, some of which caused GDB to stop working properly. But with the release of Amiga OS4.1 update 3, GDB once again started to work more-or-less as expected, and lately (with release of Update 4) it is usable again. As result, all of the information in this article are based on the GDB from latest SDK 53.20 (GDB version 6.3, 2005.07.19 build) and Amiga OS4.1 update4.

GDB is not just a simple debugger or disassembler, but a full debug environment that gives you the ability to debug your program in real time, disassemble your code, dump or disassemble memory areas, attach to running processes (e.g. a commodity that is already running), step through source code or assembler instructions, set breakpoints on labels or addresses, display variable values, and just about anything else a serious programmer may need. So of what use is GDB to a beginner programmer? Why have GDB on Amiga OS at all? Put simply, GDB enables you to determine exactly what is happening inside your program, and help you figure out why it runs into trouble. For example, if you wrote a program, but it doesn't work how you expected it to, and/or it crashes. You can use GDB to set a breakpoint somewhere before the problem, and launch the program. The program will run until it reaches the breakpoint, and then you can check the state of the program, its variables, dump memory buffers, inspect the stack and see exactly what is going on. Then, after you have investigated everything you need to look at, you can continue execution of the program, or step over the code (either at source code or machine code level), to see what is happening. GDB on Amiga OS4 is also good for any research of work, for example you can find out at which address OS4 loads a relocated ELF, which addresses it uses for kernel areas, what happens when programs calls the system parts of OS and so on. Of course, it is entirely possible to do some non-interactive debugging without GDB, like plain disassembly (with "objdump" for example), but static disassembly is not real time debugging, so you can't check what happens exactly at a given moment of a program's execution. Sometimes it is useful to be able to use a debugger when you have no documentation to hand, and don't know how some functions behave, or what they return and where. Also, it can sometimes be the case that even the documentation is wrong and the debugger can help you confirm exactly what is wrong to fill out a proper bug-report or for creating a patch/fix. When using GDB, it is necessary to include debugging information in the binary. This information will you to reference functions and variables by their names, and set breakpoints at named functions, like at "main()" to debug from the start of your program, or function "foo()". It is possible to debug binaries which have no debugging information at all, but then you will not be able to follow the high-level source code (usually C/C++), and will only be able to examine the assembly code. Without debug information you are usually forced to start at the "_start" label, which is where the all real code start (which is in the C/C++ library startup code for C/C++ programs). GCC has many flags to specify the kind of debugging information to be included in the binary, including -g, -ggdb, -gstabs and -gstabs+. The only flag which is recommended for use on Amiga OS4 is -gstabs. So, whenever you wish to create a binary with debugging information, you should add "-gstabs". Other ones may or may not work, but to avoid any issues just use "-gstabs". The same is true if you want to just use "addr2line" to find the address of a crash from a stack trace.

In the above example, we compiled a binary with debug information, and ran the binary inside the debugger. The "-q" (or "--quiet") option on the command line just tells GDB not to print version information on startup. For basic debugging, you need to know how to set a breakpoint, how to step over the code, and how to view code, variable and memory contents. The most useful commands for beginners are: run, break, disassemble, next, step, stepi and continue. For all the GDB commands you always have some short names, like b for break, r for run, disas for disassembly, si for stepi and so on. Lets cover the most common scenarios:

Just running a program in the debugger isn't very useful - we need to pause execution and examine the state of the code at a particular point. For that, we use the "breakpoint" command ("break" or "b" for short). For example:

Here we have set a breakpoint at beginning of program, displayed the current breakpoints (there is only the one we just set), then ran the program. The program execution stopped at the beginning of the main function (this is called "hitting a breakpoint"), and returned to the GDB prompt. Once at the GDB prompt, you can disable or enable any breakpoint (via "enable" and "disable" commands), as well as removing it with the "clear" command.

Once you have hit a breakpoint, you can have fine control over the execution of the program, using the following commands:

In that example we examine the source of the program via the "list" command, set break at main(), and then step over the main function. As you can see, printf() also calls the __Newlibcall() function (which is part of the newlib libc.a). You could also debug to see what exactly it does, which argument it takes and what happens after. By the way; when you are stepping with stepi (i.e. per instruction) and you reach a "bctrl" instruction, then, via stepi you will jump into the kernel, which is probably not what you want, so to jump over that kind of instruction, and to avoid entering to kernel, you can just do:

When you reach a point in your program where a crash happens, you might want to see how your C function looks "for real", in assembly language. For this, you use the "disassemble" command (or "disas" for short):

Of course for real work you should know at least the basics of PowerPC assembly. You might want to read a book on this (the best one is called the "green book", check the links section), but even without deep knowledge you can see that there some magic happens, then a jump to "printf", and then the rest of the code performs a clean exit (return 0). Those strange values at the <main+20> and <main+24> are offsets to our "hello world" buffer.

As you should know, assembly language is a set of instructions that the CPU understands directly. The PowerPC architecture is designed to manipulate data inside CPU registers. It has 32 general registers, 32 floating point registers, and some special ones. So, with every single "stepi", some registers will change their state, and that can be seen by the:

With this information, you can get to know exactly which data is placed in the registers, which memory regions they point to or what values they have. You can also dump any memory to which your program has access, and to do this you use the "x" command (short for "examine"). The options for this command are the size and format of data to dump and an address where the data you are interested in resides. This can be pretty helpful when you want to know what kind of data you have in the stack, or an array. Lets take a look at that example:

We set a breakpoint at main(), just to have ability to run and disassemble the main function. We then set a breakpoint at the "crclr" instruction before the jump to printf, and continued execution. We then hit the breakpoint, which means that the CPU stopped just before executing the instruction at 0x7f974224. The instructions just before that (at addresses 0x7f97421c and 0x7f974220) calculated an address and stored it in register 3 (r3). We viewed the contents of r3 with the "info reg r3" command, and saw that it contained "0x6579a038". We then examined the memory at that address as a string, and we can see that it is our "just hello" string, so we can see that the first argument to printf is placed in r3.

So now, even at this point, you can already start to do some real-time debugging on OS4. Of course, this article only covers a few commands and examples. GDB has hundreds of commands with all kinds of features and possibilities, but hopefully this small guide will help to get you started. Sure, to use GDB fully, you should know PowerPC assembly language, C, and how it all works at low-level, but you don't have to know all that for GDB to be useful. Hopefully this has helped you get started. If that there is demand, I will write more articles to explain more aspects of our GDB, its different features and abilities. Thanks for reading, and for Peter Gordon for proof-reading and helping with corrections.