Doc for gdbserver!

gdb/gdbserver/README

@@ -0,0 +1,85 @@
+			README for GDBserver
+			  by Stu Grossman
+
+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
+host.  GDB and GDBserver communicate using the standard remote serial protocol
+implemented in remote.c, and various *-stub.c files.  They can communicate via
+either a serial line or a TCP connection.
+
+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.
+
+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 /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.
+
+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
+
+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'.
+
+Building:
+
+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:
+
+	1) cd xyzzy/gdb/gdbserver
+	2) ../../configure --target i386-none-lynx
+
+When that completes, do the following on the Lynx system:
+
+	3) cd xyzzy/gdb/gdbserver
+	4) make CC=gcc
+
+It should build with only a minor complaint about NULL being redefined.  That's
+a LynxOS problem, and can be ignored.
+
+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:
+
+	make CC=lynx-target-compiler...