Commit | Line | Data |
---|---|---|
4b9583de SG |
1 | This is a test line for tags testing. |
2 | ||
17f087a8 SG |
3 | README for GDBserver |
4 | by Stu Grossman | |
5 | ||
6 | Introduction: | |
7 | ||
8 | This is GDBserver, a remote server for Un*x-like systems. It can be used to | |
4b9583de | 9 | control the execution of a program on a target system from a GDB on a different |
17f087a8 | 10 | host. GDB and GDBserver communicate using the standard remote serial protocol |
4b9583de | 11 | implemented in remote.c, and various *-stub.c files. They communicate via |
17f087a8 SG |
12 | either a serial line or a TCP connection. |
13 | ||
14 | Usage (server (target) side): | |
15 | ||
4b9583de SG |
16 | First, you need to have a copy of the program you want to debug put onto |
17 | the target system. The program can be stripped to save space if needed, as | |
18 | GDBserver doesn't care about symbols. All symbol handling is taken care of by | |
19 | the GDB running on the host system. | |
20 | ||
21 | To use the server, you log on to the target system, and run the `gdbserver' | |
22 | program. You must tell it (a) how to communicate with GDB, (b) the name of | |
23 | your program, and (c) its arguments. The general syntax is: | |
24 | ||
25 | target> gdbserver COMM PROGRAM [ARGS ...] | |
17f087a8 | 26 | |
4b9583de | 27 | For example, using a serial port, you might say: |
17f087a8 SG |
28 | |
29 | target> gdbserver /dev/com1 emacs foo.txt | |
30 | ||
4b9583de SG |
31 | This tells gdbserver to debug emacs with an argument of foo.txt, and to |
32 | communicate with GDB via /dev/com1. Gdbserver now waits patiently for the | |
33 | host GDB to communicate with it. | |
17f087a8 SG |
34 | |
35 | To use a TCP connection, you could say: | |
36 | ||
37 | target> gdbserver host:2345 emacs foo.txt | |
38 | ||
39 | This says pretty much the same thing as the last example, except that we are | |
4b9583de SG |
40 | going to communicate with the host GDB via TCP. The `host:2345' argument means |
41 | that we are expecting to see a TCP connection from `host' to local TCP port | |
42 | 2345. (Currently, the `host' part is ignored.) You can choose any number you | |
43 | want for the port number as long as it does not conflict with any existing TCP | |
44 | ports on the target system. This same port number must be used in the host | |
45 | GDBs `target remote' command, which will be described shortly. Note that if | |
46 | you chose a port number that conflicts with another service, gdbserver will | |
47 | print an error message and exit. | |
17f087a8 SG |
48 | |
49 | Usage (host side): | |
50 | ||
4b9583de SG |
51 | You need an unstripped copy of the target program on your host system, since |
52 | GDB needs to examine it's symbol tables and such. Start up GDB as you normally | |
53 | would, with the target program as the first argument. (You may need to use the | |
54 | --baud option if the serial line is running at anything except 9600 baud.) | |
55 | Ie: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only | |
56 | new command you need to know about is `target remote'. It's argument is either | |
57 | a device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT | |
58 | descriptor. For example: | |
17f087a8 SG |
59 | |
60 | (gdb) target remote /dev/ttyb | |
61 | ||
4b9583de | 62 | communicates with the server via serial line /dev/ttyb, and: |
17f087a8 SG |
63 | |
64 | (gdb) target remote the-target:2345 | |
65 | ||
4b9583de SG |
66 | communicates via a TCP connection to port 2345 on host `the-target', where |
67 | you previously started up gdbserver with the same port number. Note that for | |
68 | TCP connections, you must start up gdbserver prior to using the `target remote' | |
69 | command, otherwise you may get an error that looks something like | |
70 | `Connection refused'. | |
17f087a8 SG |
71 | |
72 | Building: | |
73 | ||
74 | Currently, the only target system supported by the server is Lynx. To build | |
75 | the server for Lynx, make a new copy of the distribution onto a disk that is | |
76 | NFS shared with the Lynx system. Lets say that's in a directory called xyzzy. | |
77 | Then, follow these steps under the host system: | |
78 | ||
79 | 1) cd xyzzy/gdb/gdbserver | |
80 | 2) ../../configure --target i386-none-lynx | |
81 | ||
82 | When that completes, do the following on the Lynx system: | |
83 | ||
84 | 3) cd xyzzy/gdb/gdbserver | |
85 | 4) make CC=gcc | |
86 | ||
87 | It should build with only a minor complaint about NULL being redefined. That's | |
88 | a LynxOS problem, and can be ignored. | |
89 | ||
90 | It's also possible that you may have a cross-compiler to Lynx. In that case, | |
91 | you can skip the stuff about NFS. You would replace steps 3 & 4 with: | |
92 | ||
93 | make CC=lynx-target-compiler... |