The stub files provided with gdb implement the target side of the
communication protocol, and the gdb side is implemented in the
gdb source file remote.c. Normally, you can simply allow
these subroutines to communicate, and ignore the details. (If you're
implementing your own stub file, you can still ignore the details: start
with one of the existing stub files. sparc-stub.c is the best
organized, and therefore the easiest to read.)
To debug a program running on another machine (the debugging
target machine), you must first arrange for all the usual
prerequisites for the program to run by itself. For example, for a C
program, you need:
A startup routine to set up the C runtime environment; these usually
have a name like crt0. The startup routine may be supplied by
your hardware supplier, or you may have to write your own.
A C subroutine library to support your program's
subroutine calls, notably managing input and output.
A way of getting your program to the other machine--for example, a
download program. These are often supplied by the hardware
manufacturer, but you may have to write your own from hardware
documentation.
The next step is to arrange for your program to use a serial port to
communicate with the machine where gdb is running (the host
machine). In general terms, the scheme looks like this:
On the host,
{No value for `
<listitem>GDBN'} already understands how to use this protocol; when everything
else is set up, you can simply use the target remote command
(refer to Chapter 18 Specifying a Debugging Target).
On the target,
you must link with your program a few special-purpose subroutines that
implement the gdb remote serial protocol. The file containing these
subroutines is called a debugging stub.
On certain remote targets, you can use an auxiliary program
gdbserver instead of linking a stub into your program. Refer to Section 19.2 Using the gdbserverprogram, for details.
The debugging stub is specific to the architecture of the remote
machine; for example, use sparc-stub.c to debug programs on
sparc boards.
These working remote stubs are distributed with gdb:
i386-stub.c
For Intel 386 and compatible architectures.
m68k-stub.c
For Motorola 680x0 architectures.
sh-stub.c
For Hitachi SH architectures.
sparc-stub.c
For sparc architectures.
sparcl-stub.c
For Fujitsu sparclite architectures.
The README file in the gdb distribution may list other
recently added stubs.
19.5.1. What the stub can do for you
The debugging stub for your architecture supplies these three
subroutines:
set_debug_traps
This routine arranges for handle_exception to run when your
program stops. You must call this subroutine explicitly near the
beginning of your program.
handle_exception
This is the central workhorse, but your program never calls it
explicitly--the setup code arranges for handle_exception to
run when a trap is triggered.
handle_exception takes control when your program stops during
execution (for example, on a breakpoint), and mediates communications
with gdb on the host machine. This is where the communications
protocol is implemented; handle_exception acts as the gdb
representative on the target machine. It begins by sending summary
information on the state of your program, then continues to execute,
retrieving and transmitting any information gdb needs, until you
execute a gdb command that makes your program resume; at that point,
handle_exception returns control to your own code on the target
machine.
breakpoint
Use this auxiliary subroutine to make your program contain a
breakpoint. Depending on the particular situation, this may be the only
way for gdb to get control. For instance, if your target
machine has some sort of interrupt button, you won't need to call this;
pressing the interrupt button transfers control to
handle_exception--in effect, to gdb. On some machines,
simply receiving characters on the serial port may also trigger a trap;
again, in that situation, you don't need to call breakpoint from
your own program--simply running target remote from the host
gdb session gets control.
Call breakpoint if none of these is true, or if you simply want
to make certain your program stops at a predetermined point for the
start of your debugging session.
19.5.2. What you must do for the stub
The debugging stubs that come with gdb are set up for a particular
chip architecture, but they have no information about the rest of your
debugging target machine.
First of all you need to tell the stub how to communicate with the
serial port.
int getDebugChar()
Write this subroutine to read a single character from the serial port.
It may be identical to getchar for your target system; a
different name is used to allow you to distinguish the two if you wish.
void putDebugChar(int)
Write this subroutine to write a single character to the serial port.
It may be identical to putchar for your target system; a
different name is used to allow you to distinguish the two if you wish.
If you want gdb to be able to stop your program while it is
running, you need to use an interrupt-driven serial driver, and arrange
for it to stop when it receives a ^C (\003, the control-C
character). That is the character which gdb uses to tell the
remote system to stop.
Getting the debugging target to return the proper status to gdb
probably requires changes to the standard stub; one quick and dirty way
is to just execute a breakpoint instruction (the "dirty" part is that
gdb reports a SIGTRAP instead of a SIGINT).
Write this function to install exception_address in the exception
handling tables. You need to do this because the stub does not have any
way of knowing what the exception handling tables on your target system
are like (for example, the processor's table might be in rom,
containing entries which point to a table in ram).
exception_number is the exception number which should be changed;
its meaning is architecture-dependent (for example, different numbers
might represent divide by zero, misaligned access, etc). When this
exception occurs, control should be transferred directly to
exception_address, and the processor state (stack, registers,
and so on) should be just as it is when a processor exception occurs. So if
you want to use a jump instruction to reach exception_address, it
should be a simple jump, not a jump to subroutine.
For the 386, exception_address should be installed as an interrupt
gate so that interrupts are masked while the handler runs. The gate
should be at privilege level 0 (the most privileged level). The
sparc and 68k stubs are able to mask interrupts themselves without
help from exceptionHandler.
void flush_i_cache()
On sparc and sparclite only, write this subroutine to flush the
instruction cache, if any, on your target machine. If there is no
instruction cache, this subroutine may be a no-op.
On target machines that have instruction caches, gdb requires this
function to make certain that the state of your program is stable.
You must also make sure this library routine is available:
void *memset(void *, int, int)
This is the standard library function memset that sets an area of
memory to a known value. If you have one of the free versions of
libc.a, memset can be found there; otherwise, you must
either obtain it from your hardware manufacturer, or write your own.
If you do not use the GNU C compiler, you may need other standard
library subroutines as well; this varies from one stub to another,
but in general the stubs are likely to use any of the common library
subroutines which gcc generates as inline code.
19.5.3. Putting it all together
In summary, when your program is ready to debug, you must follow these
steps.
For the 680x0 stub only, you need to provide a variable called
exceptionHook. Normally you just use:
void (*exceptionHook)() = 0;
but if before calling set_debug_traps, you set it to point to a
function in your program, that function is called when
gdb continues after stopping on a trap (for example, bus
error). The function indicated by exceptionHook is called with
one parameter: an int which is the exception number.
Compile and link together: your program, the gdb debugging stub for
your target architecture, and the supporting subroutines.
Make sure you have a serial connection between your target machine and
the gdb host, and identify the serial port on the host.
Download your program to your target machine (or get it there by
whatever means the manufacturer provides), and start it.
