17.4 Implementing a Remote Stub

The stub files provided with No value for GDBN implement the target side of the communication protocol, and the No value for GDBN side is implemented in the No value for GDBN 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:

1. 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.
2. A C subroutine library to support your program's subroutine calls, notably managing input and output.
3. 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 No value for GDBN is running (the host machine). In general terms, the scheme looks like this:

On the host,

No value for GDBN already understands how to use this protocol; when everything else is set up, you can simply use the ‘target remote’ command (see section Specifying a Debugging Target).

On the target,

you must link with your program a few special-purpose subroutines that implement the No value for GDBN 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. See section Using the gdbserver Program, 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 No value for GDBN:

i386-stub.c

For Intel 386 and compatible architectures.

m68k-stub.c

For Motorola 680x0 architectures.

sh-stub.c

For Renesas SH architectures.

sparc-stub.c

For SPARC architectures.

sparcl-stub.c

For Fujitsu SPARCLITE architectures.

The ‘README’ file in the No value for GDBN distribution may list other recently added stubs.