Commit | Line | Data |
---|---|---|
17f087a8 SG |
1 | README for GDBserver |
2 | by Stu Grossman | |
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 host 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 can communicate via | |
10 | either a serial line or a TCP connection. | |
11 | ||
12 | Usage (server (target) side): | |
13 | ||
14 | First, you will need to have a copy of the program to be debugged put onto | |
15 | the target system. It can be stripped if you need to save space. This is ok | |
16 | because GDBserver doesn't care about symbols, all of that stuff is taken care | |
17 | of by the GDB running on the host system. | |
18 | ||
19 | To use the server, you will need to log on to the target system, and run the | |
20 | server program. You will need to tell it how to communicate with GDB, the | |
21 | name of the program to be debugged, and it's arguments. For example, using a | |
22 | serial port, you might say: | |
23 | ||
24 | target> gdbserver /dev/com1 emacs foo.txt | |
25 | ||
26 | This tells gdbserver to debug emacs with an argument of foo.txt. The server | |
27 | will communicate with GDB via /dev/com1. GDBserver will now wait patiently | |
28 | for GDB to communicate with it. | |
29 | ||
30 | To use a TCP connection, you could say: | |
31 | ||
32 | target> gdbserver host:2345 emacs foo.txt | |
33 | ||
34 | This says pretty much the same thing as the last example, except that we are | |
35 | now going to communicate with GDB via TCP. The `host:2345' argument means that | |
36 | we are expecting to see a TCP connection from `host' to local TCP port 2345. | |
37 | Currently, the host part is ignored. You can choose any number you want for | |
38 | the port number as long as it does not conflict with any existing ports on your | |
39 | system. This same port number will also be used in the GDB `target remote' | |
40 | command, which we will discuss later. Note that it's safe to chose a number | |
41 | that conflicts, gdbserver will just print an error message and exit. | |
42 | ||
43 | Usage (host side): | |
44 | ||
45 | You should have a copy of the target program on your host system, since GDB | |
46 | will need it to examine symbol tables and such. You should start up GDB just | |
47 | as you normally would, with the target program as the first argument. Ie: | |
48 | `gdb target-prog'. After that, you will only need to know about one new | |
49 | command. This is `target remote'. It's argument is either a device name | |
50 | (preferably of a serial device, like /dev/ttyb), or a host:port descriptor. | |
51 | For example: | |
52 | ||
53 | (gdb) target remote /dev/ttyb | |
54 | ||
55 | will communicate with the server via the hardware serial line /dev/ttyb, and: | |
56 | ||
57 | (gdb) target remote the-target:2345 | |
58 | ||
59 | will communicate via a TCP connection to port 2345 on host `the-target', where | |
60 | you have already started up gdbserver with the same port number. Note that you | |
61 | must start up gdbserver prior to using the target command, otherwise you will | |
62 | get an error that looks something like `Connection refused'. | |
63 | ||
64 | Building: | |
65 | ||
66 | Currently, the only target system supported by the server is Lynx. To build | |
67 | the server for Lynx, make a new copy of the distribution onto a disk that is | |
68 | NFS shared with the Lynx system. Lets say that's in a directory called xyzzy. | |
69 | Then, follow these steps under the host system: | |
70 | ||
71 | 1) cd xyzzy/gdb/gdbserver | |
72 | 2) ../../configure --target i386-none-lynx | |
73 | ||
74 | When that completes, do the following on the Lynx system: | |
75 | ||
76 | 3) cd xyzzy/gdb/gdbserver | |
77 | 4) make CC=gcc | |
78 | ||
79 | It should build with only a minor complaint about NULL being redefined. That's | |
80 | a LynxOS problem, and can be ignored. | |
81 | ||
82 | It's also possible that you may have a cross-compiler to Lynx. In that case, | |
83 | you can skip the stuff about NFS. You would replace steps 3 & 4 with: | |
84 | ||
85 | make CC=lynx-target-compiler... |