Commit | Line | Data |
---|---|---|
c906108c SS |
1 | README for GDBserver & GDBreplay |
2 | by Stu Grossman and Fred Fish | |
3 | ||
4 | Introduction: | |
5 | ||
6 | This is GDBserver, a remote server for Un*x-like systems. It can be used to | |
7 | control the execution of a program on a target system from a GDB on a different | |
8 | host. GDB and GDBserver communicate using the standard remote serial protocol | |
9 | implemented in remote.c, and various *-stub.c files. They communicate via | |
10 | either a serial line or a TCP connection. | |
11 | ||
12 | Usage (server (target) side): | |
13 | ||
14 | First, you need to have a copy of the program you want to debug put onto | |
15 | the target system. The program can be stripped to save space if needed, as | |
16 | GDBserver doesn't care about symbols. All symbol handling is taken care of by | |
17 | the GDB running on the host system. | |
18 | ||
19 | To use the server, you log on to the target system, and run the `gdbserver' | |
20 | program. You must tell it (a) how to communicate with GDB, (b) the name of | |
21 | your program, and (c) its arguments. The general syntax is: | |
22 | ||
23 | target> gdbserver COMM PROGRAM [ARGS ...] | |
24 | ||
25 | For example, using a serial port, you might say: | |
26 | ||
27 | target> gdbserver /dev/com1 emacs foo.txt | |
28 | ||
29 | This tells gdbserver to debug emacs with an argument of foo.txt, and to | |
30 | communicate with GDB via /dev/com1. Gdbserver now waits patiently for the | |
31 | host GDB to communicate with it. | |
32 | ||
33 | To use a TCP connection, you could say: | |
34 | ||
35 | target> gdbserver host:2345 emacs foo.txt | |
36 | ||
37 | This says pretty much the same thing as the last example, except that we are | |
38 | going to communicate with the host GDB via TCP. The `host:2345' argument means | |
39 | that we are expecting to see a TCP connection from `host' to local TCP port | |
40 | 2345. (Currently, the `host' part is ignored.) You can choose any number you | |
41 | want for the port number as long as it does not conflict with any existing TCP | |
42 | ports on the target system. This same port number must be used in the host | |
43 | GDBs `target remote' command, which will be described shortly. Note that if | |
44 | you chose a port number that conflicts with another service, gdbserver will | |
45 | print an error message and exit. | |
46 | ||
84563040 DJ |
47 | On some targets, gdbserver can also attach to running programs. This is |
48 | accomplished via the --attach argument. The syntax is: | |
49 | ||
50 | target> gdbserver COMM --attach PID | |
51 | ||
52 | PID is the process ID of a currently running process. It isn't necessary | |
53 | to point gdbserver at a binary for the running process. | |
54 | ||
c906108c SS |
55 | Usage (host side): |
56 | ||
57 | You need an unstripped copy of the target program on your host system, since | |
58 | GDB needs to examine it's symbol tables and such. Start up GDB as you normally | |
59 | would, with the target program as the first argument. (You may need to use the | |
60 | --baud option if the serial line is running at anything except 9600 baud.) | |
61 | Ie: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only | |
62 | new command you need to know about is `target remote'. It's argument is either | |
63 | a device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT | |
64 | descriptor. For example: | |
65 | ||
66 | (gdb) target remote /dev/ttyb | |
67 | ||
68 | communicates with the server via serial line /dev/ttyb, and: | |
69 | ||
70 | (gdb) target remote the-target:2345 | |
71 | ||
72 | communicates via a TCP connection to port 2345 on host `the-target', where | |
73 | you previously started up gdbserver with the same port number. Note that for | |
74 | TCP connections, you must start up gdbserver prior to using the `target remote' | |
75 | command, otherwise you may get an error that looks something like | |
76 | `Connection refused'. | |
77 | ||
84563040 DJ |
78 | Building gdbserver: |
79 | ||
80 | The supported targets as of February 2002 are: | |
81 | arm-*-linux-gnu | |
82 | i386-*-linux-gnu | |
83 | ia64-*-linux-gnu | |
84 | m68k-*-linux-gnu | |
85 | mips-*-linux-gnu | |
86 | powerpc-*-linux-gnu | |
87 | sh-*-linux-gnu | |
c906108c SS |
88 | |
89 | Configuring gdbserver you should specify the same machine for host and | |
90 | target (which are the machine that gdbserver is going to run on. This | |
91 | is not the same as the machine that gdb is going to run on; building | |
92 | gdbserver automatically as part of building a whole tree of tools does | |
93 | not currently work if cross-compilation is involved (we don't get the | |
94 | right CC in the Makefile, to start with)). | |
95 | ||
84563040 DJ |
96 | Building gdbserver for your target is very straightforward. If you build |
97 | GDB natively on a target which gdbserver supports, it will be built | |
98 | automatically when you build GDB. You can also build just gdbserver: | |
c906108c | 99 | |
84563040 DJ |
100 | % mkdir obj |
101 | % cd obj | |
102 | % path-to-gdbserver-sources/configure | |
103 | % make | |
c906108c | 104 | |
84563040 DJ |
105 | If you prefer to cross-compile to your target, then you can also build |
106 | gdbserver that way. In a Bourne shell, for example: | |
c906108c | 107 | |
84563040 DJ |
108 | % export CC=your-cross-compiler |
109 | % path-to-gdbserver-sources/configure your-target-name | |
110 | % make | |
c906108c SS |
111 | |
112 | Using GDBreplay: | |
113 | ||
114 | A special hacked down version of gdbserver can be used to replay remote | |
115 | debug log files created by gdb. Before using the gdb "target" command to | |
116 | initiate a remote debug session, use "set remotelogfile <filename>" to tell | |
117 | gdb that you want to make a recording of the serial or tcp session. Note | |
118 | that when replaying the session, gdb communicates with gdbreplay via tcp, | |
119 | regardless of whether the original session was via a serial link or tcp. | |
120 | ||
121 | Once you are done with the remote debug session, start gdbreplay and | |
122 | tell it the name of the log file and the host and port number that gdb | |
123 | should connect to (typically the same as the host running gdb): | |
124 | ||
125 | $ gdbreplay logfile host:port | |
126 | ||
127 | Then start gdb (preferably in a different screen or window) and use the | |
128 | "target" command to connect to gdbreplay: | |
129 | ||
130 | (gdb) target remote host:port | |
131 | ||
132 | Repeat the same sequence of user commands to gdb that you gave in the | |
133 | original debug session. Gdb should not be able to tell that it is talking | |
134 | to gdbreplay rather than a real target, all other things being equal. Note | |
135 | that gdbreplay echos the command lines to stderr, as well as the contents of | |
136 | the packets it sends and receives. The last command echoed by gdbreplay is | |
137 | the next command that needs to be typed to gdb to continue the session in | |
138 | sync with the original session. |