Go to the first, previous, next, last section, table of contents.

Specifying a Debugging Target

A target is the execution environment occupied by your program. Often, runs in the same host environment as your program; in that case, the debugging target is specified as a side effect when you use the file or core commands. When you need more flexibility--for example, running on a physically separate host, or controlling a standalone system over a serial port or a realtime system over a TCP/IP connection--you can use the target command to specify one of the target types configured for (see section Commands for managing targets).

Active targets

There are three classes of targets: processes, core files, and executable files. can work concurrently on up to three active targets, one in each class. This allows you to (for example) start a process and inspect its activity without abandoning your work on a core file.

For example, if you execute `gdb a.out', then the executable file a.out is the only active target. If you designate a core file as well--presumably from a prior run that crashed and coredumped--then has two active targets and uses them in tandem, looking first in the corefile target, then in the executable file, to satisfy requests for memory addresses. (Typically, these two classes of target are complementary, since core files contain only a program's read-write memory--variables and so on--plus machine status, while executable files contain only the program text and initialized data.)

When you type run, your executable file becomes an active process target as well. When a process target is active, all commands requesting memory addresses refer to that target; addresses in an active core file or executable file target are obscured while the process target is active.

Use the core-file and exec-file commands to select a new core file or executable target (see section Commands to specify files). To specify as a target a process that is already running, use the attach command (see section Debugging an already-running process).

Commands for managing targets

target type parameters: Connects the host environment to a target machine or process. A target is typically a protocol for talking to debugging facilities. You use the argument type to specify the type or protocol of the target machine. Further parameters are interpreted by the target protocol, but typically include things like device names or host names to connect with, process numbers, and baud rates. The target command does not repeat if you press RET again after executing the command.
help target: Displays the names of all targets available. To display targets currently selected, use either info target or info files (see section Commands to specify files).
help target name: Describe a particular target, including any parameters necessary to select it.
set gnutarget args: uses its own library BFD to read your files. knows whether it is reading an executable, a core, or a .o file; however, you can specify the file format with the set gnutarget command. Unlike most target commands, with gnutarget the target refers to a program, not a machine. Warning: To specify a file format with set gnutarget, you must know the actual BFD name. See section Commands to specify files.
show gnutarget: Use the show gnutarget command to display what file format gnutarget is set to read. If you have not set gnutarget, will determine the file format for each file automatically, and show gnutarget displays `The current BDF target is "auto"'.

Here are some common targets (available, or not, depending on the GDB configuration):

target exec program: An executable file. `target exec program' is the same as `exec-file program'.
target core filename: A core dump file. `target core filename' is the same as `core-file filename'.
target remote dev: Remote serial target in GDB-specific protocol. The argument dev specifies what serial device to use for the connection (e.g. `/dev/ttya'). @xref{Remote, ,Remote debugging}. target remote now supports the load command. This is only useful if you have some other way of getting the stub to the target system, and you can put it somewhere in memory where it won't get clobbered by the download.
target sim: CPU simulator. @xref{Simulator,,Simulated CPU Target}.

The following targets are all CPU-specific, and only available for specific configurations.

target abug dev: ABug ROM monitor for M68K.
target adapt dev: Adapt monitor for A29K.
target amd-eb dev speed PROG: Remote PC-resident AMD EB29K board, attached over serial lines. dev is the serial device, as for target remote; speed allows you to specify the linespeed; and PROG is the name of the program to be debugged, as it appears to DOS on the PC. @xref{EB29K Remote, ,The EBMON protocol for AMD29K}.
target array dev: Array Tech LSI33K RAID controller board.
target bug dev: BUG monitor, running on a MVME187 (m88k) board.
target cpu32bug dev: CPU32BUG monitor, running on a CPU32 (M68K) board.
target dbug dev: dBUG ROM monitor for Motorola ColdFire.
target ddb dev: NEC's DDB monitor for Mips Vr4300.
target dink32 dev: DINK32 ROM monitor for PowerPC.
target e7000 dev: E7000 emulator for Hitachi H8 and SH.
target es1800 dev: ES-1800 emulator for M68K.
target est dev: EST-300 ICE monitor, running on a CPU32 (M68K) board.
target hms dev: A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. Use special commands device and speed to control the serial line and the communications speed used. @xref{Hitachi Remote,, and Hitachi Microprocessors}.
target lsi dev: LSI ROM monitor for Mips.
target m32r dev: Mitsubishi M32R/D ROM monitor.
target mips dev: IDT/SIM ROM monitor for Mips.
target mon960 dev: MON960 monitor for Intel i960.
target nindy devicename: An Intel 960 board controlled by a Nindy Monitor. devicename is the name of the serial device to use for the connection, e.g. `/dev/ttya'. @xref{i960-Nindy Remote, , with a remote i960 (Nindy)}.
target nrom dev: NetROM ROM emulator. This target only supports downloading.
target op50n dev: OP50N monitor, running on an OKI HPPA board.
target pmon dev: PMON ROM monitor for Mips.
target ppcbug dev
target ppcbug1 dev: PPCBUG ROM monitor for PowerPC.
target r3900 dev: Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
target rdi dev: ARM Angel monitor, via RDI library interface.
target rdp dev: ARM Demon monitor.
target rom68k dev: ROM 68K monitor, running on an M68K IDP board.
target rombug dev: ROMBUG ROM monitor for OS/9000.
target sds dev: SDS monitor, running on a PowerPC board (such as Motorola's ADS).
target sparclite dev: Fujitsu sparclite boards, used only for the purpose of loading. You must use an additional command to debug the program. For example: target remote dev using standard remote protocol.
target sh3 dev
target sh3e dev: Hitachi SH-3 and SH-3E target systems.
target st2000 dev speed: A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. dev is the name of the device attached to the ST2000 serial line; speed is the communication line speed. The arguments are not used if is configured to connect to the ST2000 using TCP or Telnet. @xref{ST2000 Remote,, with a Tandem ST2000}.
target udi keyword: Remote AMD29K target, using the AMD UDI protocol. The keyword argument specifies which 29K board or simulator to use. @xref{UDI29K Remote,,The UDI protocol for AMD29K}.
target vxworks machinename: A VxWorks system, attached via TCP/IP. The argument machinename is the target system's machine name or IP address. @xref{VxWorks Remote, , and VxWorks}.
target w89k dev: W89K monitor, running on a Winbond HPPA board.

Many remote targets require you to download the executable's code once you've successfully established a connection.

load filename: The file is loaded at whatever address is specified in the executable. For some object file formats, you can specify the load address when you link the program; for other formats, like a.out, the object file format specifies a fixed address. load does not repeat if you press RET again after using it.

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 :

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 distribution may list other recently added stubs.

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 on the host machine. This is where the communications protocol is implemented; handle_exception acts as the 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 needs, until you execute a 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 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 . 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 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.

What you must do for the stub

The debugging stubs that come with 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 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 uses to tell the remote system to stop.

Getting the debugging target to return the proper status to probably requires changes to the standard stub; one quick and dirty way is to just execute a breakpoint instruction (the "dirty" part is that reports a SIGTRAP instead of a SIGINT).

Other routines you need to supply are:

void exceptionHandler (int exception_number, void *exception_address): 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 interrup themselves without help from exceptionHandler.
void flush_i_cache(): (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, 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.

Putting it all together

In summary, when your program is ready to debug, you must follow these steps.

Make sure you have the supporting low-level routines (see section What you must do for the stub):
```
getDebugChar, putDebugChar,
flush_i_cache, memset, exceptionHandler.
```
Insert these lines near the top of your program:
```
set_debug_traps();
breakpoint();
```
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 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 debugging stub for your target architecture, and the supporting subroutines.
Make sure you have a serial connection between your target machine and the 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.
To start remote debugging, run on the host machine, and specify as an executable file the program that is running in the remote machine. This tells how to find your program's symbols and the contents of its pure text. Then establish communication using the target remote command. Its argument specifies how to communicate with the target machine--either via a devicename attached to a direct serial line, or a TCP port (usually to a terminal server which in turn has a serial line to the target). For example, to use a serial line connected to the device named `/dev/ttyb':
```
target remote /dev/ttyb
```
To use a TCP connection, use an argument of the form host:port. For example, to connect to port 2828 on a terminal server named manyfarms:
```
target remote manyfarms:2828
```

Now you can use all the usual commands to examine and change data and to step and continue the remote program.

To resume the remote program and stop debugging it, use the detach command.

Whenever is waiting for the remote program, if you type the interrupt character (often C-C), attempts to stop the program. This may or may not succeed, depending in part on the hardware and the serial drivers the remote system uses. If you type the interrupt character once again, displays this prompt:

Interrupted while waiting for the program.
Give up (and stop debugging it)?  (y or n)

If you type y, abandons the remote debugging session. (If you decide you want to try again later, you can use `target remote' again to connect once more.) If you type n, goes back to waiting.

Communication protocol

The stub files provided with implement the target side of the communication protocol, and the side is implemented in the 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.)

However, there may be occasions when you need to know something about the protocol--for example, if there is only one serial port to your target machine, you might want your program to do something special if it recognizes a packet meant for .

All commands and responses (other than acknowledgements, which are single characters) are sent as a packet which includes a checksum. A packet is introduced with the character `$', and ends with the character `#' followed by a two-digit checksum:

$packet info#checksum

checksum is computed as the modulo 256 sum of the packet info characters.

When either the host or the target machine receives a packet, the first response expected is an acknowledgement: a single character, either `+' (to indicate the package was received correctly) or `-' (to request retransmission).

The host () sends commands, and the target (the debugging stub incorporated in your program) sends data in response. The target also sends data when your program stops.

Command packets are distinguished by their first character, which identifies the kind of command.

These are some of the commands currently supported (for a complete list of commands, look in `gdb/remote.c.'):

g: Requests the values of CPU registers.
G: Sets the values of CPU registers.
maddr,count: Read count bytes at location addr.
Maddr,count:...: Write count bytes at location addr.
c
caddr: Resume execution at the current address (or at addr if supplied).
s
saddr: Step the target program for one instruction, from either the current program counter or from addr if supplied.
k: Kill the target program.
?: Report the most recent signal. To allow you to take advantage of the signal handling commands, one of the functions of the debugging stub is to report CPU traps as the corresponding POSIX signal values.
T: Allows the remote stub to send only the registers that needs to make a quick decision about single-stepping or conditional breakpoints. This eliminates the need to fetch the entire register set for each instruction being stepped through. now implements a write-through cache for registers and only re-reads the registers if the target has run.

If you have trouble with the serial connection, you can use the command set remotedebug. This makes report on all packets sent back and forth across the serial line to the remote machine. The packet-debugging information is printed on the standard output stream. set remotedebug off turns it off, and show remotedebug shows you its current state.

Using the E7000 in-circuit emulator

You can use the E7000 in-circuit emulator to develop code for either the Hitachi SH or the H8/300H. Use one of these forms of the `target e7000' command to connect to your E7000:

target e7000 port speed: Use this form if your E7000 is connected to a serial port. The port argument identifies what serial port to use (for example, `com2'). The third argument is the line speed in bits per second (for example, `9600').
target e7000 hostname: If your E7000 is installed as a host on a TCP/IP network, you can just specify its hostname; uses telnet to connect.

Special commands for Hitachi micros

Some commands are available only on the H8/300 or the H8/500 configurations:

set machine h8300
set machine h8300h: Condition for one of the two variants of the H8/300 architecture with `set machine'. You can use `show machine' to check which variant is currently in effect.
set memory mod
show memory: Specify which H8/500 memory model (mod) you are using with `set memory'; check which memory model is in effect with `show memory'. The accepted values for mod are small, big, medium, and compact.

target sim args: Debug programs on a simulated CPU. If the simulator supports setup options, specify them via args.

After specifying this target, you can debug programs for the simulated CPU in the same style as programs for your host computer; use the file command to load a new program image, the run command to run your program, and so on.

As well as making available all the usual machine registers (see info reg), the Z8000 simulator provides three additional items of information as specially named registers:

cycles: Counts clock-ticks in the simulator.
insts: Counts instructions run in the simulator.
time: Execution time in 60ths of a second.

You can refer to these values in expressions with the usual conventions; for example, `b fputc if $cycles>5000' sets a conditional breakpoint that suspends only after at least 5000 simulated clock ticks.

Go to the first, previous, next, last section, table of contents.