119370Spst README for GDBserver & GDBreplay 219370Spst by Stu Grossman and Fred Fish 319370Spst 419370SpstIntroduction: 519370Spst 619370SpstThis is GDBserver, a remote server for Un*x-like systems. It can be used to 719370Spstcontrol the execution of a program on a target system from a GDB on a different 819370Spsthost. GDB and GDBserver communicate using the standard remote serial protocol 919370Spstimplemented in remote.c, and various *-stub.c files. They communicate via 1019370Spsteither a serial line or a TCP connection. 1119370Spst 1219370SpstUsage (server (target) side): 1319370Spst 1419370SpstFirst, you need to have a copy of the program you want to debug put onto 1519370Spstthe target system. The program can be stripped to save space if needed, as 1619370SpstGDBserver doesn't care about symbols. All symbol handling is taken care of by 1719370Spstthe GDB running on the host system. 1819370Spst 1919370SpstTo use the server, you log on to the target system, and run the `gdbserver' 2019370Spstprogram. You must tell it (a) how to communicate with GDB, (b) the name of 2119370Spstyour program, and (c) its arguments. The general syntax is: 2219370Spst 2319370Spst target> gdbserver COMM PROGRAM [ARGS ...] 2419370Spst 2519370SpstFor example, using a serial port, you might say: 2619370Spst 2719370Spst target> gdbserver /dev/com1 emacs foo.txt 2819370Spst 2919370SpstThis tells gdbserver to debug emacs with an argument of foo.txt, and to 3019370Spstcommunicate with GDB via /dev/com1. Gdbserver now waits patiently for the 3119370Spsthost GDB to communicate with it. 3219370Spst 3319370SpstTo use a TCP connection, you could say: 3419370Spst 3519370Spst target> gdbserver host:2345 emacs foo.txt 3619370Spst 3719370SpstThis says pretty much the same thing as the last example, except that we are 3819370Spstgoing to communicate with the host GDB via TCP. The `host:2345' argument means 3919370Spstthat we are expecting to see a TCP connection from `host' to local TCP port 4019370Spst2345. (Currently, the `host' part is ignored.) You can choose any number you 4119370Spstwant for the port number as long as it does not conflict with any existing TCP 4219370Spstports on the target system. This same port number must be used in the host 4319370SpstGDBs `target remote' command, which will be described shortly. Note that if 4419370Spstyou chose a port number that conflicts with another service, gdbserver will 4519370Spstprint an error message and exit. 4619370Spst 4798944SobrienOn some targets, gdbserver can also attach to running programs. This is 4898944Sobrienaccomplished via the --attach argument. The syntax is: 4998944Sobrien 5098944Sobrien target> gdbserver COMM --attach PID 5198944Sobrien 5298944SobrienPID is the process ID of a currently running process. It isn't necessary 5398944Sobriento point gdbserver at a binary for the running process. 5498944Sobrien 5519370SpstUsage (host side): 5619370Spst 5719370SpstYou need an unstripped copy of the target program on your host system, since 5819370SpstGDB needs to examine it's symbol tables and such. Start up GDB as you normally 5919370Spstwould, with the target program as the first argument. (You may need to use the 6019370Spst--baud option if the serial line is running at anything except 9600 baud.) 6119370SpstIe: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only 6219370Spstnew command you need to know about is `target remote'. It's argument is either 6319370Spsta device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT 6419370Spstdescriptor. For example: 6519370Spst 6619370Spst (gdb) target remote /dev/ttyb 6719370Spst 6819370Spstcommunicates with the server via serial line /dev/ttyb, and: 6919370Spst 7019370Spst (gdb) target remote the-target:2345 7119370Spst 7219370Spstcommunicates via a TCP connection to port 2345 on host `the-target', where 7319370Spstyou previously started up gdbserver with the same port number. Note that for 7419370SpstTCP connections, you must start up gdbserver prior to using the `target remote' 7519370Spstcommand, otherwise you may get an error that looks something like 7619370Spst`Connection refused'. 7719370Spst 7898944SobrienBuilding gdbserver: 7919370Spst 8098944SobrienThe supported targets as of February 2002 are: 8198944Sobrien arm-*-linux-gnu 8298944Sobrien i386-*-linux-gnu 8398944Sobrien ia64-*-linux-gnu 8498944Sobrien m68k-*-linux-gnu 8598944Sobrien mips-*-linux-gnu 8698944Sobrien powerpc-*-linux-gnu 8798944Sobrien sh-*-linux-gnu 8898944Sobrien 8919370SpstConfiguring gdbserver you should specify the same machine for host and 9019370Spsttarget (which are the machine that gdbserver is going to run on. This 9119370Spstis not the same as the machine that gdb is going to run on; building 9219370Spstgdbserver automatically as part of building a whole tree of tools does 9319370Spstnot currently work if cross-compilation is involved (we don't get the 9419370Spstright CC in the Makefile, to start with)). 9519370Spst 9698944SobrienBuilding gdbserver for your target is very straightforward. If you build 9798944SobrienGDB natively on a target which gdbserver supports, it will be built 9898944Sobrienautomatically when you build GDB. You can also build just gdbserver: 9919370Spst 10098944Sobrien % mkdir obj 10198944Sobrien % cd obj 10298944Sobrien % path-to-gdbserver-sources/configure 10398944Sobrien % make 10419370Spst 10598944SobrienIf you prefer to cross-compile to your target, then you can also build 10698944Sobriengdbserver that way. In a Bourne shell, for example: 10719370Spst 10898944Sobrien % export CC=your-cross-compiler 10998944Sobrien % path-to-gdbserver-sources/configure your-target-name 11098944Sobrien % make 11119370Spst 11219370SpstUsing GDBreplay: 11319370Spst 11419370SpstA special hacked down version of gdbserver can be used to replay remote 11519370Spstdebug log files created by gdb. Before using the gdb "target" command to 11619370Spstinitiate a remote debug session, use "set remotelogfile <filename>" to tell 11719370Spstgdb that you want to make a recording of the serial or tcp session. Note 11819370Spstthat when replaying the session, gdb communicates with gdbreplay via tcp, 11919370Spstregardless of whether the original session was via a serial link or tcp. 12019370Spst 12119370SpstOnce you are done with the remote debug session, start gdbreplay and 12219370Spsttell it the name of the log file and the host and port number that gdb 12319370Spstshould connect to (typically the same as the host running gdb): 12419370Spst 12519370Spst $ gdbreplay logfile host:port 12619370Spst 12719370SpstThen start gdb (preferably in a different screen or window) and use the 12819370Spst"target" command to connect to gdbreplay: 12919370Spst 13019370Spst (gdb) target remote host:port 13119370Spst 13219370SpstRepeat the same sequence of user commands to gdb that you gave in the 13319370Spstoriginal debug session. Gdb should not be able to tell that it is talking 13419370Spstto gdbreplay rather than a real target, all other things being equal. Note 13519370Spstthat gdbreplay echos the command lines to stderr, as well as the contents of 13619370Spstthe packets it sends and receives. The last command echoed by gdbreplay is 13719370Spstthe next command that needs to be typed to gdb to continue the session in 13819370Spstsync with the original session. 139