- README for GDBserver
- by Stu Grossman
+ README for GDBserver & GDBreplay
+ by Stu Grossman and Fred Fish
Introduction:
This is GDBserver, a remote server for Un*x-like systems. It can be used to
-control the execution of a program on a target host from a GDB on a different
+control the execution of a program on a target system from a GDB on a different
host. GDB and GDBserver communicate using the standard remote serial protocol
-implemented in remote.c, and various *-stub.c files. They can communicate via
+implemented in remote.c, and various *-stub.c files. They communicate via
either a serial line or a TCP connection.
+For more information about GDBserver, see the GDB manual.
+
Usage (server (target) side):
-First, you will need to have a copy of the program to be debugged put onto
-the target system. It can be stripped if you need to save space. This is ok
-because GDBserver doesn't care about symbols, all of that stuff is taken care
-of by the GDB running on the host system.
+First, you need to have a copy of the program you want to debug put onto
+the target system. The program can be stripped to save space if needed, as
+GDBserver doesn't care about symbols. All symbol handling is taken care of by
+the GDB running on the host system.
+
+To use the server, you log on to the target system, and run the `gdbserver'
+program. You must tell it (a) how to communicate with GDB, (b) the name of
+your program, and (c) its arguments. The general syntax is:
-To use the server, you will need to log on to the target system, and run the
-server program. You will need to tell it how to communicate with GDB, the
-name of the program to be debugged, and it's arguments. For example, using a
-serial port, you might say:
+ target> gdbserver COMM PROGRAM [ARGS ...]
+
+For example, using a serial port, you might say:
target> gdbserver /dev/com1 emacs foo.txt
-This tells gdbserver to debug emacs with an argument of foo.txt. The server
-will communicate with GDB via /dev/com1. GDBserver will now wait patiently
-for GDB to communicate with it.
+This tells GDBserver to debug emacs with an argument of foo.txt, and to
+communicate with GDB via /dev/com1. GDBserver now waits patiently for the
+host GDB to communicate with it.
To use a TCP connection, you could say:
target> gdbserver host:2345 emacs foo.txt
This says pretty much the same thing as the last example, except that we are
-now going to communicate with GDB via TCP. The `host:2345' argument means that
-we are expecting to see a TCP connection from `host' to local TCP port 2345.
-Currently, the host part is ignored. You can choose any number you want for
-the port number as long as it does not conflict with any existing ports on your
-system. This same port number will also be used in the GDB `target remote'
-command, which we will discuss later. Note that it's safe to chose a number
-that conflicts, gdbserver will just print an error message and exit.
-
-Usage (host side):
-
-You should have a copy of the target program on your host system, since GDB
-will need it to examine symbol tables and such. You should start up GDB just
-as you normally would, with the target program as the first argument. Ie:
-`gdb target-prog'. After that, you will only need to know about one new
-command. This is `target remote'. It's argument is either a device name
-(preferably of a serial device, like /dev/ttyb), or a host:port descriptor.
-For example:
-
- (gdb) target remote /dev/ttyb
-
-will communicate with the server via the hardware serial line /dev/ttyb, and:
-
- (gdb) target remote the-target:2345
+going to communicate with the host GDB via TCP. The `host:2345' argument means
+that we are expecting to see a TCP connection from `host' to local TCP port
+2345. (Currently, the `host' part is ignored.) You can choose any number you
+want for the port number as long as it does not conflict with any existing TCP
+ports on the target system. This same port number must be used in the host
+GDBs `target remote' command, which will be described shortly. Note that if
+you chose a port number that conflicts with another service, GDBserver will
+print an error message and exit.
-will communicate via a TCP connection to port 2345 on host `the-target', where
-you have already started up gdbserver with the same port number. Note that you
-must start up gdbserver prior to using the target command, otherwise you will
-get an error that looks something like `Connection refused'.
+On some targets, GDBserver can also attach to running programs. This is
+accomplished via the --attach argument. The syntax is:
-Building:
+ target> gdbserver --attach COMM PID
-Currently, the only target system supported by the server is Lynx. To build
-the server for Lynx, make a new copy of the distribution onto a disk that is
-NFS shared with the Lynx system. Lets say that's in a directory called xyzzy.
-Then, follow these steps under the host system:
+PID is the process ID of a currently running process. It isn't necessary
+to point GDBserver at a binary for the running process.
- 1) cd xyzzy/gdb/gdbserver
- 2) ../../configure --target i386-none-lynx
+Usage (host side):
-When that completes, do the following on the Lynx system:
+You need an unstripped copy of the target program on your host system, since
+GDB needs to examine it's symbol tables and such. Start up GDB as you normally
+would, with the target program as the first argument. (You may need to use the
+--baud option if the serial line is running at anything except 9600 baud.)
+Ie: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only
+new command you need to know about is `target remote'. It's argument is either
+a device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT
+descriptor. For example:
- 3) cd xyzzy/gdb/gdbserver
- 4) make CC=gcc
+ (gdb) target remote /dev/ttyb
-It should build with only a minor complaint about NULL being redefined. That's
-a LynxOS problem, and can be ignored.
+communicates with the server via serial line /dev/ttyb, and:
-It's also possible that you may have a cross-compiler to Lynx. In that case,
-you can skip the stuff about NFS. You would replace steps 3 & 4 with:
+ (gdb) target remote the-target:2345
- make CC=lynx-target-compiler...
+communicates via a TCP connection to port 2345 on host `the-target', where
+you previously started up GDBserver with the same port number. Note that for
+TCP connections, you must start up GDBserver prior to using the `target remote'
+command, otherwise you may get an error that looks something like
+`Connection refused'.
+
+Building GDBserver:
+
+The supported targets as of November 2006 are:
+ arm-*-linux*
+ bfin-*-uclinux
+ bfin-*-linux-uclibc
+ crisv32-*-linux*
+ cris-*-linux*
+ i[34567]86-*-cygwin*
+ i[34567]86-*-linux*
+ i[34567]86-*-mingw*
+ ia64-*-linux*
+ m32r*-*-linux*
+ m68*-*-linux*
+ m68*-*-uclinux*
+ mips*64*-*-linux*
+ mips*-*-linux*
+ powerpc[64]-*-linux*
+ s390[x]-*-linux*
+ sh-*-linux*
+ spu*-*-*
+ x86_64-*-linux*
+
+Configuring GDBserver you should specify the same machine for host and
+target (which are the machine that GDBserver is going to run on. This
+is not the same as the machine that GDB is going to run on; building
+GDBserver automatically as part of building a whole tree of tools does
+not currently work if cross-compilation is involved (we don't get the
+right CC in the Makefile, to start with)).
+
+Building GDBserver for your target is very straightforward. If you build
+GDB natively on a target which GDBserver supports, it will be built
+automatically when you build GDB. You can also build just GDBserver:
+
+ % mkdir obj
+ % cd obj
+ % path-to-gdbserver-sources/configure
+ % make
+
+If you prefer to cross-compile to your target, then you can also build
+GDBserver that way. In a Bourne shell, for example:
+
+ % export CC=your-cross-compiler
+ % path-to-gdbserver-sources/configure your-target-name
+ % make
+
+Using GDBreplay:
+
+A special hacked down version of GDBserver can be used to replay remote
+debug log files created by GDB. Before using the GDB "target" command to
+initiate a remote debug session, use "set remotelogfile <filename>" to tell
+GDB that you want to make a recording of the serial or tcp session. Note
+that when replaying the session, GDB communicates with GDBreplay via tcp,
+regardless of whether the original session was via a serial link or tcp.
+
+Once you are done with the remote debug session, start GDBreplay and
+tell it the name of the log file and the host and port number that GDB
+should connect to (typically the same as the host running GDB):
+
+ $ gdbreplay logfile host:port
+
+Then start GDB (preferably in a different screen or window) and use the
+"target" command to connect to GDBreplay:
+
+ (gdb) target remote host:port
+
+Repeat the same sequence of user commands to GDB that you gave in the
+original debug session. GDB should not be able to tell that it is talking
+to GDBreplay rather than a real target, all other things being equal. Note
+that GDBreplay echos the command lines to stderr, as well as the contents of
+the packets it sends and receives. The last command echoed by GDBreplay is
+the next command that needs to be typed to GDB to continue the session in
+sync with the original session.
projects / deliverable / binutils-gdb.git / blobdiff