Go to the previous, next section.
This chapter discusses how to start , and how to get out of it. (The essentials: type `' to start GDB, and type quit or C-d to exit.)
Invoke by running the program . Once started,
reads commands from the terminal until you tell it to exit.
You can also run with a variety of arguments and options,
to specify more of your debugging environment at the outset.
The most usual way to start is with one argument, specifying an executable program:
program
You can also start with both an executable program and a core file specified:
program core
You can, instead, specify a process ID as a second argument, if you want to debug a running process:
program 1234
would attach to process 1234
(unless you also have a file
named `1234'; does check for a core file first).
Taking advantage of the second command-line argument requires a fairly complete operating system; when you use as a remote debugger attached to a bare board, there may not be any notion of "process", and there is often no way to get a core dump.
You can further control how starts up by using command-line options. itself can remind you of the options available.
Type
-help
to display all available options and briefly describe their use (` -h' is a shorter equivalent).
All options and command line arguments you give are processed in sequential order. The order makes a difference when the `-x' option is used.
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 :
sparc-stub.c
m68k-stub.c
i386-stub.c
The `README' file in the distribution may list other recently added stubs.
The debugging stub for your architecture supplies these three subroutines:
set_debug_traps
handle_exception
to run when your
program stops. You must call this subroutine explicitly near the
beginning of your program.
handle_exception
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
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.
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()
getchar
for your target system; a
different name is used to allow you to distinguish the two if you wish.
void putDebugChar(int)
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)
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 themself without
help from exceptionHandler
.
void flush_i_cache()
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)
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.
In summary, when your program is ready to debug, you must follow these steps.
getDebugChar
,putDebugChar
,flush_i_cache
,memset
,exceptionHandler
.
set_debug_traps(); breakpoint();
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.
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.
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 the commands currently supported:
g
G
maddr,count
Maddr,count:...
c
caddr
s
saddr
k
?
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.
target sim
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
), this debugging target provides three additional items
of information as specially named registers:
cycles
insts
time
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.
When starts, it reads any arguments other than options as specifying an executable file and core file (or process ID). This is the same as if the arguments were specified by the `-se' and `-c' options respectively. ( reads the first argument that does not have an associated option flag as equivalent to the `-se' option followed by that argument; and the second argument that does not have an associated option flag, if any, as equivalent to the `-c' option followed by that argument.)
Many options have both long and short forms; both are shown in the following list. also recognizes the long forms if you truncate them, so long as enough of the option is present to be unambiguous. (If you prefer, you can flag option arguments with `--' rather than `-', though we illustrate the more usual convention.)
-symbols file
-s file
-exec file
-e file
-se file
-core file
-c file
-c number
attach
command
(unless there is a file in core-dump format named number, in which
case `-c' specifies that file as a core dump to read).
-command file
-x file
-directory directory
-d directory
-m
-mapped
mmap
system call, you can use this option
to have write the symbols from your
program into a reusable file in the current directory. If the program you are debugging is
called `/tmp/fred', the mapped symbol file is `./fred.syms'.
Future debugging sessions notice the presence of this file,
and can quickly map in symbol information from it, rather than reading
the symbol table from the executable program.
The `.syms' file is specific to the host machine where is run. It holds an exact image of the internal symbol table. It cannot be shared across multiple host platforms.
-r
-readnow
The -mapped
and -readnow
options are typically combined in
order to build a `.syms' file that contains complete symbol
information. (See section Commands to specify files, for information
on `.syms' files.) A simple GDB invocation to do nothing but build
a `.syms' file for future use is:
gdb -batch -nx -mapped -readnow programname
You can run in various alternative modes--for example, in batch mode or quiet mode.
-nx
-n
-quiet
-q
-batch
0
after processing all the
command files specified with `-x' (and all commands from
initialization files, if not inhibited with `-n'). Exit with
nonzero status if an error occurs in executing the commands
in the command files.
Batch mode may be useful for running as a filter, for example to download and run a program on another computer; in order to make this more useful, the message
Program exited normally.
(which is ordinarily issued whenever a program running under control terminates) is not issued when running in batch mode.
-cd directory
-fullname
-f
quit
quit
command (abbreviated q
), or type
an end-of-file character (usually C-d).
An interrupt (often C-c) does not exit from , but rather terminates the action of any command that is in progress and returns to command level. It is safe to type the interrupt character at any time because does not allow it to take effect until a time when it is safe.
If you have been using to control an attached process or
device, you can release it with the detach
command
(see section Debugging an already-running process).
If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend ; you can
just use the shell
command.
shell command string
SHELL
determines which
shell to run. Otherwise uses /bin/sh
.
The utility make
is often needed in development environments.
You do not have to use the shell
command for this purpose in
:
make make-args
make
program with the specified
arguments. This is equivalent to `shell make make-args'.