780 lines
33 KiB
HTML
780 lines
33 KiB
HTML
<HTML>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<!-- Created on November, 11 2002 by texi2html 1.64 -->
|
|
<!--
|
|
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
|
|
Karl Berry <karl@freefriends.org>
|
|
Olaf Bachmann <obachman@mathematik.uni-kl.de>
|
|
and many others.
|
|
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
|
|
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
|
|
|
|
-->
|
|
<HEAD>
|
|
<TITLE>Debugging with GDB: Remote Debugging</TITLE>
|
|
|
|
<META NAME="description" CONTENT="Debugging with GDB: Remote Debugging">
|
|
<META NAME="keywords" CONTENT="Debugging with GDB: Remote Debugging">
|
|
<META NAME="resource-type" CONTENT="document">
|
|
<META NAME="distribution" CONTENT="global">
|
|
<META NAME="Generator" CONTENT="texi2html 1.64">
|
|
|
|
</HEAD>
|
|
|
|
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
|
|
|
|
<A NAME="SEC136"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC135"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC137"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_3.html#SEC6"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H1> 17. Debugging remote programs </H1>
|
|
<!--docid::SEC136::-->
|
|
<P>
|
|
|
|
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
|
|
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_18.html#SEC137">17.1 Using the <CODE>gdbserver</CODE> program</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Using the gdbserver program</TD></TR>
|
|
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_18.html#SEC138">17.2 Using the <CODE>gdbserve.nlm</CODE> program</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Using the gdbserve.nlm program</TD></TR>
|
|
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_18.html#SEC139">17.3 Implementing a remote stub</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
|
|
</TABLE></BLOCKQUOTE>
|
|
<P>
|
|
|
|
<A NAME="Server"></A>
|
|
<HR SIZE="6">
|
|
<A NAME="SEC137"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC138"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H2> 17.1 Using the <CODE>gdbserver</CODE> program </H2>
|
|
<!--docid::SEC137::-->
|
|
<P>
|
|
|
|
<A NAME="IDX615"></A>
|
|
<A NAME="IDX616"></A>
|
|
<CODE>gdbserver</CODE> is a control program for Unix-like systems, which
|
|
allows you to connect your program with a remote GDB via
|
|
<CODE>target remote</CODE>---but without linking in the usual debugging stub.
|
|
</P><P>
|
|
|
|
<CODE>gdbserver</CODE> is not a complete replacement for the debugging stubs,
|
|
because it requires essentially the same operating-system facilities
|
|
that GDB itself does. In fact, a system that can run
|
|
<CODE>gdbserver</CODE> to connect to a remote GDB could also run
|
|
GDB locally! <CODE>gdbserver</CODE> is sometimes useful nevertheless,
|
|
because it is a much smaller program than GDB itself. It is
|
|
also easier to port than all of GDB, so you may be able to get
|
|
started more quickly on a new system by using <CODE>gdbserver</CODE>.
|
|
Finally, if you develop code for real-time systems, you may find that
|
|
the tradeoffs involved in real-time operation make it more convenient to
|
|
do as much development work as possible on another system, for example
|
|
by cross-compiling. You can use <CODE>gdbserver</CODE> to make a similar
|
|
choice for debugging.
|
|
</P><P>
|
|
|
|
GDB and <CODE>gdbserver</CODE> communicate via either a serial line
|
|
or a TCP connection, using the standard GDB remote serial
|
|
protocol.
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><EM>On the target machine,</EM>
|
|
<DD>you need to have a copy of the program you want to debug.
|
|
<CODE>gdbserver</CODE> does not need your program's symbol table, so you can
|
|
strip the program if necessary to save space. GDB on the host
|
|
system does all the symbol handling.
|
|
<P>
|
|
|
|
To use the server, you must tell it how to communicate with GDB;
|
|
the name of your program; and the arguments for your program. The usual
|
|
syntax is:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target> gdbserver <VAR>comm</VAR> <VAR>program</VAR> [ <VAR>args</VAR> <small>...</small> ]
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<VAR>comm</VAR> is either a device name (to use a serial line) or a TCP
|
|
hostname and portnumber. For example, to debug Emacs with the argument
|
|
<SAMP>`foo.txt'</SAMP> and communicate with GDB over the serial port
|
|
<TT>`/dev/com1'</TT>:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target> gdbserver /dev/com1 emacs foo.txt
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<CODE>gdbserver</CODE> waits passively for the host GDB to communicate
|
|
with it.
|
|
</P><P>
|
|
|
|
To use a TCP connection instead of a serial line:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target> gdbserver host:2345 emacs foo.txt
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
The only difference from the previous example is the first argument,
|
|
specifying that you are communicating with the host GDB via
|
|
TCP. The <SAMP>`host:2345'</SAMP> argument means that <CODE>gdbserver</CODE> is to
|
|
expect a TCP connection from machine <SAMP>`host'</SAMP> to local TCP port 2345.
|
|
(Currently, the <SAMP>`host'</SAMP> part is ignored.) You can choose any number
|
|
you want for the port number as long as it does not conflict with any
|
|
TCP ports already in use on the target system (for example, <CODE>23</CODE> is
|
|
reserved for <CODE>telnet</CODE>).<A NAME="DOCF5" HREF="gdb_fot.html#FOOT5">(5)</A> You must use the same port number with the host GDB
|
|
<CODE>target remote</CODE> command.
|
|
</P><P>
|
|
|
|
On some targets, <CODE>gdbserver</CODE> can also attach to running programs.
|
|
This is accomplished via the <CODE>--attach</CODE> argument. The syntax is:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target> gdbserver <VAR>comm</VAR> --attach <VAR>pid</VAR>
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<VAR>pid</VAR> is the process ID of a currently running process. It isn't necessary
|
|
to point <CODE>gdbserver</CODE> at a binary for the running process.
|
|
</P><P>
|
|
|
|
<DT><EM>On the GDB host machine,</EM>
|
|
<DD>you need an unstripped copy of your program, since GDB needs
|
|
symbols and debugging information. Start up GDB as usual,
|
|
using the name of the local copy of your program as the first argument.
|
|
(You may also need the <SAMP>`--baud'</SAMP> option if the serial line is
|
|
running at anything other than 9600bps.) After that, use <CODE>target
|
|
remote</CODE> to establish communications with <CODE>gdbserver</CODE>. Its argument
|
|
is either a device name (usually a serial device, like
|
|
<TT>`/dev/ttyb'</TT>), or a TCP port descriptor in the form
|
|
<CODE><VAR>host</VAR>:<VAR>PORT</VAR></CODE>. For example:
|
|
<P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) target remote /dev/ttyb
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
communicates with the server via serial line <TT>`/dev/ttyb'</TT>, and
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) target remote the-target:2345
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
communicates via a TCP connection to port 2345 on host <TT>`the-target'</TT>.
|
|
For TCP connections, you must start up <CODE>gdbserver</CODE> prior to using
|
|
the <CODE>target remote</CODE> command. Otherwise you may get an error whose
|
|
text depends on the host system, but which usually looks something like
|
|
<SAMP>`Connection refused'</SAMP>.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="NetWare"></A>
|
|
<HR SIZE="6">
|
|
<A NAME="SEC138"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC137"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC139"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC139"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H2> 17.2 Using the <CODE>gdbserve.nlm</CODE> program </H2>
|
|
<!--docid::SEC138::-->
|
|
<P>
|
|
|
|
<A NAME="IDX617"></A>
|
|
<CODE>gdbserve.nlm</CODE> is a control program for NetWare systems, which
|
|
allows you to connect your program with a remote GDB via
|
|
<CODE>target remote</CODE>.
|
|
</P><P>
|
|
|
|
GDB and <CODE>gdbserve.nlm</CODE> communicate via a serial line,
|
|
using the standard GDB remote serial protocol.
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><EM>On the target machine,</EM>
|
|
<DD>you need to have a copy of the program you want to debug.
|
|
<CODE>gdbserve.nlm</CODE> does not need your program's symbol table, so you
|
|
can strip the program if necessary to save space. GDB on the
|
|
host system does all the symbol handling.
|
|
<P>
|
|
|
|
To use the server, you must tell it how to communicate with
|
|
GDB; the name of your program; and the arguments for your
|
|
program. The syntax is:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>load gdbserve [ BOARD=<VAR>board</VAR> ] [ PORT=<VAR>port</VAR> ]
|
|
[ BAUD=<VAR>baud</VAR> ] <VAR>program</VAR> [ <VAR>args</VAR> <small>...</small> ]
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<VAR>board</VAR> and <VAR>port</VAR> specify the serial line; <VAR>baud</VAR> specifies
|
|
the baud rate used by the connection. <VAR>port</VAR> and <VAR>node</VAR> default
|
|
to 0, <VAR>baud</VAR> defaults to 9600bps.
|
|
</P><P>
|
|
|
|
For example, to debug Emacs with the argument <SAMP>`foo.txt'</SAMP>and
|
|
communicate with GDB over serial port number 2 or board 1
|
|
using a 19200bps connection:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<DT><EM>On the GDB host machine,</EM>
|
|
<DD>you need an unstripped copy of your program, since GDB needs
|
|
symbols and debugging information. Start up GDB as usual,
|
|
using the name of the local copy of your program as the first argument.
|
|
(You may also need the <SAMP>`--baud'</SAMP> option if the serial line is
|
|
running at anything other than 9600bps. After that, use <CODE>target
|
|
remote</CODE> to establish communications with <CODE>gdbserve.nlm</CODE>. Its
|
|
argument is a device name (usually a serial device, like
|
|
<TT>`/dev/ttyb'</TT>). For example:
|
|
<P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) target remote /dev/ttyb
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
communications with the server via serial line <TT>`/dev/ttyb'</TT>.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="remote stub"></A>
|
|
<HR SIZE="6">
|
|
<A NAME="SEC139"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC138"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC140"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H2> 17.3 Implementing a remote stub </H2>
|
|
<!--docid::SEC139::-->
|
|
<P>
|
|
|
|
<A NAME="IDX618"></A>
|
|
<A NAME="IDX619"></A>
|
|
<A NAME="IDX620"></A>
|
|
The stub files provided with GDB implement the target side of the
|
|
communication protocol, and the GDB side is implemented in the
|
|
GDB source file <TT>`remote.c'</TT>. Normally, you can simply allow
|
|
these subroutines to communicate, and ignore the details. (If you're
|
|
implementing your own stub file, you can still ignore the details: start
|
|
with one of the existing stub files. <TT>`sparc-stub.c'</TT> is the best
|
|
organized, and therefore the easiest to read.)
|
|
</P><P>
|
|
|
|
<A NAME="IDX621"></A>
|
|
To debug a program running on another machine (the debugging
|
|
<EM>target</EM> machine), you must first arrange for all the usual
|
|
prerequisites for the program to run by itself. For example, for a C
|
|
program, you need:
|
|
</P><P>
|
|
|
|
<OL>
|
|
<LI>
|
|
A startup routine to set up the C runtime environment; these usually
|
|
have a name like <TT>`crt0'</TT>. The startup routine may be supplied by
|
|
your hardware supplier, or you may have to write your own.
|
|
<P>
|
|
|
|
<LI>
|
|
A C subroutine library to support your program's
|
|
subroutine calls, notably managing input and output.
|
|
<P>
|
|
|
|
<LI>
|
|
A way of getting your program to the other machine--for example, a
|
|
download program. These are often supplied by the hardware
|
|
manufacturer, but you may have to write your own from hardware
|
|
documentation.
|
|
</OL>
|
|
<P>
|
|
|
|
The next step is to arrange for your program to use a serial port to
|
|
communicate with the machine where GDB is running (the <EM>host</EM>
|
|
machine). In general terms, the scheme looks like this:
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><EM>On the host,</EM>
|
|
<DD>GDB already understands how to use this protocol; when everything
|
|
else is set up, you can simply use the <SAMP>`target remote'</SAMP> command
|
|
(see section <A HREF="gdb_17.html#SEC130">Specifying a Debugging Target</A>).
|
|
<P>
|
|
|
|
<DT><EM>On the target,</EM>
|
|
<DD>you must link with your program a few special-purpose subroutines that
|
|
implement the GDB remote serial protocol. The file containing these
|
|
subroutines is called a <EM>debugging stub</EM>.
|
|
<P>
|
|
|
|
On certain remote targets, you can use an auxiliary program
|
|
<CODE>gdbserver</CODE> instead of linking a stub into your program.
|
|
See section <A HREF="gdb_18.html#SEC137">Using the <CODE>gdbserver</CODE> program</A>, for details.
|
|
</DL>
|
|
<P>
|
|
|
|
The debugging stub is specific to the architecture of the remote
|
|
machine; for example, use <TT>`sparc-stub.c'</TT> to debug programs on
|
|
SPARC boards.
|
|
</P><P>
|
|
|
|
<A NAME="IDX622"></A>
|
|
These working remote stubs are distributed with GDB:
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>i386-stub.c</CODE>
|
|
<DD><A NAME="IDX623"></A>
|
|
<A NAME="IDX624"></A>
|
|
<A NAME="IDX625"></A>
|
|
For Intel 386 and compatible architectures.
|
|
<P>
|
|
|
|
<DT><CODE>m68k-stub.c</CODE>
|
|
<DD><A NAME="IDX626"></A>
|
|
<A NAME="IDX627"></A>
|
|
<A NAME="IDX628"></A>
|
|
For Motorola 680x0 architectures.
|
|
<P>
|
|
|
|
<DT><CODE>sh-stub.c</CODE>
|
|
<DD><A NAME="IDX629"></A>
|
|
<A NAME="IDX630"></A>
|
|
<A NAME="IDX631"></A>
|
|
For Hitachi SH architectures.
|
|
<P>
|
|
|
|
<DT><CODE>sparc-stub.c</CODE>
|
|
<DD><A NAME="IDX632"></A>
|
|
<A NAME="IDX633"></A>
|
|
For SPARC architectures.
|
|
<P>
|
|
|
|
<DT><CODE>sparcl-stub.c</CODE>
|
|
<DD><A NAME="IDX634"></A>
|
|
<A NAME="IDX635"></A>
|
|
<A NAME="IDX636"></A>
|
|
For Fujitsu SPARCLITE architectures.
|
|
<P>
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
The <TT>`README'</TT> file in the GDB distribution may list other
|
|
recently added stubs.
|
|
</P><P>
|
|
|
|
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
|
|
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_18.html#SEC140">17.3.1 What the stub can do for you</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
|
|
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_18.html#SEC141">17.3.2 What you must do for the stub</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
|
|
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_18.html#SEC142">17.3.3 Putting it all together</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
|
|
</TABLE></BLOCKQUOTE>
|
|
<P>
|
|
|
|
<A NAME="Stub Contents"></A>
|
|
<HR SIZE="6">
|
|
<A NAME="SEC140"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC139"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC141"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC139"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H3> 17.3.1 What the stub can do for you </H3>
|
|
<!--docid::SEC140::-->
|
|
<P>
|
|
|
|
<A NAME="IDX637"></A>
|
|
The debugging stub for your architecture supplies these three
|
|
subroutines:
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><CODE>set_debug_traps</CODE>
|
|
<DD><A NAME="IDX638"></A>
|
|
<A NAME="IDX639"></A>
|
|
This routine arranges for <CODE>handle_exception</CODE> to run when your
|
|
program stops. You must call this subroutine explicitly near the
|
|
beginning of your program.
|
|
<P>
|
|
|
|
<DT><CODE>handle_exception</CODE>
|
|
<DD><A NAME="IDX640"></A>
|
|
<A NAME="IDX641"></A>
|
|
This is the central workhorse, but your program never calls it
|
|
explicitly--the setup code arranges for <CODE>handle_exception</CODE> to
|
|
run when a trap is triggered.
|
|
<P>
|
|
|
|
<CODE>handle_exception</CODE> takes control when your program stops during
|
|
execution (for example, on a breakpoint), and mediates communications
|
|
with GDB on the host machine. This is where the communications
|
|
protocol is implemented; <CODE>handle_exception</CODE> acts as the GDB
|
|
representative on the target machine. It begins by sending summary
|
|
information on the state of your program, then continues to execute,
|
|
retrieving and transmitting any information GDB needs, until you
|
|
execute a GDB command that makes your program resume; at that point,
|
|
<CODE>handle_exception</CODE> returns control to your own code on the target
|
|
machine.
|
|
</P><P>
|
|
|
|
<DT><CODE>breakpoint</CODE>
|
|
<DD><A NAME="IDX642"></A>
|
|
Use this auxiliary subroutine to make your program contain a
|
|
breakpoint. Depending on the particular situation, this may be the only
|
|
way for GDB to get control. For instance, if your target
|
|
machine has some sort of interrupt button, you won't need to call this;
|
|
pressing the interrupt button transfers control to
|
|
<CODE>handle_exception</CODE>---in effect, to GDB. On some machines,
|
|
simply receiving characters on the serial port may also trigger a trap;
|
|
again, in that situation, you don't need to call <CODE>breakpoint</CODE> from
|
|
your own program--simply running <SAMP>`target remote'</SAMP> from the host
|
|
GDB session gets control.
|
|
<P>
|
|
|
|
Call <CODE>breakpoint</CODE> if none of these is true, or if you simply want
|
|
to make certain your program stops at a predetermined point for the
|
|
start of your debugging session.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="Bootstrapping"></A>
|
|
<HR SIZE="6">
|
|
<A NAME="SEC141"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC140"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC142"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC142"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC139"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H3> 17.3.2 What you must do for the stub </H3>
|
|
<!--docid::SEC141::-->
|
|
<P>
|
|
|
|
<A NAME="IDX643"></A>
|
|
The debugging stubs that come with GDB are set up for a particular
|
|
chip architecture, but they have no information about the rest of your
|
|
debugging target machine.
|
|
</P><P>
|
|
|
|
First of all you need to tell the stub how to communicate with the
|
|
serial port.
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><CODE>int getDebugChar()</CODE>
|
|
<DD><A NAME="IDX644"></A>
|
|
Write this subroutine to read a single character from the serial port.
|
|
It may be identical to <CODE>getchar</CODE> for your target system; a
|
|
different name is used to allow you to distinguish the two if you wish.
|
|
<P>
|
|
|
|
<DT><CODE>void putDebugChar(int)</CODE>
|
|
<DD><A NAME="IDX645"></A>
|
|
Write this subroutine to write a single character to the serial port.
|
|
It may be identical to <CODE>putchar</CODE> for your target system; a
|
|
different name is used to allow you to distinguish the two if you wish.
|
|
</DL>
|
|
<P>
|
|
|
|
<A NAME="IDX646"></A>
|
|
<A NAME="IDX647"></A>
|
|
If you want GDB to be able to stop your program while it is
|
|
running, you need to use an interrupt-driven serial driver, and arrange
|
|
for it to stop when it receives a <CODE>^C</CODE> (<SAMP>`\003'</SAMP>, the control-C
|
|
character). That is the character which GDB uses to tell the
|
|
remote system to stop.
|
|
</P><P>
|
|
|
|
Getting the debugging target to return the proper status to GDB
|
|
probably requires changes to the standard stub; one quick and dirty way
|
|
is to just execute a breakpoint instruction (the "dirty" part is that
|
|
GDB reports a <CODE>SIGTRAP</CODE> instead of a <CODE>SIGINT</CODE>).
|
|
</P><P>
|
|
|
|
Other routines you need to supply are:
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><CODE>void exceptionHandler (int <VAR>exception_number</VAR>, void *<VAR>exception_address</VAR>)</CODE>
|
|
<DD><A NAME="IDX648"></A>
|
|
Write this function to install <VAR>exception_address</VAR> in the exception
|
|
handling tables. You need to do this because the stub does not have any
|
|
way of knowing what the exception handling tables on your target system
|
|
are like (for example, the processor's table might be in ROM,
|
|
containing entries which point to a table in RAM).
|
|
<VAR>exception_number</VAR> is the exception number which should be changed;
|
|
its meaning is architecture-dependent (for example, different numbers
|
|
might represent divide by zero, misaligned access, etc). When this
|
|
exception occurs, control should be transferred directly to
|
|
<VAR>exception_address</VAR>, and the processor state (stack, registers,
|
|
and so on) should be just as it is when a processor exception occurs. So if
|
|
you want to use a jump instruction to reach <VAR>exception_address</VAR>, it
|
|
should be a simple jump, not a jump to subroutine.
|
|
<P>
|
|
|
|
For the 386, <VAR>exception_address</VAR> should be installed as an interrupt
|
|
gate so that interrupts are masked while the handler runs. The gate
|
|
should be at privilege level 0 (the most privileged level). The
|
|
SPARC and 68k stubs are able to mask interrupts themselves without
|
|
help from <CODE>exceptionHandler</CODE>.
|
|
</P><P>
|
|
|
|
<DT><CODE>void flush_i_cache()</CODE>
|
|
<DD><A NAME="IDX649"></A>
|
|
On SPARC and SPARCLITE only, write this subroutine to flush the
|
|
instruction cache, if any, on your target machine. If there is no
|
|
instruction cache, this subroutine may be a no-op.
|
|
<P>
|
|
|
|
On target machines that have instruction caches, GDB requires this
|
|
function to make certain that the state of your program is stable.
|
|
</DL>
|
|
<P>
|
|
|
|
You must also make sure this library routine is available:
|
|
</P><P>
|
|
|
|
<DL COMPACT>
|
|
<DT><CODE>void *memset(void *, int, int)</CODE>
|
|
<DD><A NAME="IDX650"></A>
|
|
This is the standard library function <CODE>memset</CODE> that sets an area of
|
|
memory to a known value. If you have one of the free versions of
|
|
<CODE>libc.a</CODE>, <CODE>memset</CODE> can be found there; otherwise, you must
|
|
either obtain it from your hardware manufacturer, or write your own.
|
|
</DL>
|
|
<P>
|
|
|
|
If you do not use the GNU C compiler, you may need other standard
|
|
library subroutines as well; this varies from one stub to another,
|
|
but in general the stubs are likely to use any of the common library
|
|
subroutines which <CODE>gcc</CODE> generates as inline code.
|
|
</P><P>
|
|
|
|
<A NAME="Debug Session"></A>
|
|
<HR SIZE="6">
|
|
<A NAME="SEC142"></A>
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC141"> < </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> > </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC139"> Up </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<H3> 17.3.3 Putting it all together </H3>
|
|
<!--docid::SEC142::-->
|
|
<P>
|
|
|
|
<A NAME="IDX651"></A>
|
|
In summary, when your program is ready to debug, you must follow these
|
|
steps.
|
|
</P><P>
|
|
|
|
<OL>
|
|
<LI>
|
|
Make sure you have defined the supporting low-level routines
|
|
(see section <A HREF="gdb_18.html#SEC141">What you must do for the stub</A>):
|
|
<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"><CODE>getDebugChar</CODE>, <CODE>putDebugChar</CODE>,
|
|
<CODE>flush_i_cache</CODE>, <CODE>memset</CODE>, <CODE>exceptionHandler</CODE>.
|
|
</pre></td></tr></table><P>
|
|
|
|
<LI>
|
|
Insert these lines near the top of your program:
|
|
<P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>set_debug_traps();
|
|
breakpoint();
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<LI>
|
|
For the 680x0 stub only, you need to provide a variable called
|
|
<CODE>exceptionHook</CODE>. Normally you just use:
|
|
<P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>void (*exceptionHook)() = 0;
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
but if before calling <CODE>set_debug_traps</CODE>, you set it to point to a
|
|
function in your program, that function is called when
|
|
<CODE>GDB</CODE> continues after stopping on a trap (for example, bus
|
|
error). The function indicated by <CODE>exceptionHook</CODE> is called with
|
|
one parameter: an <CODE>int</CODE> which is the exception number.
|
|
</P><P>
|
|
|
|
<LI>
|
|
Compile and link together: your program, the GDB debugging stub for
|
|
your target architecture, and the supporting subroutines.
|
|
<P>
|
|
|
|
<LI>
|
|
Make sure you have a serial connection between your target machine and
|
|
the GDB host, and identify the serial port on the host.
|
|
<P>
|
|
|
|
<LI>
|
|
Download your program to your target machine (or get it there by
|
|
whatever means the manufacturer provides), and start it.
|
|
<P>
|
|
|
|
<LI>
|
|
To start remote debugging, run GDB on the host machine, and specify
|
|
as an executable file the program that is running in the remote machine.
|
|
This tells GDB how to find your program's symbols and the contents
|
|
of its pure text.
|
|
<P>
|
|
|
|
<LI>
|
|
<A NAME="IDX652"></A>
|
|
Establish communication using the <CODE>target remote</CODE> command.
|
|
Its argument specifies how to communicate with the target
|
|
machine--either via a devicename attached to a direct serial line, or a
|
|
TCP or UDP port (usually to a terminal server which in turn has a serial line
|
|
to the target). For example, to use a serial line connected to the
|
|
device named <TT>`/dev/ttyb'</TT>:
|
|
<P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target remote /dev/ttyb
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
<A NAME="IDX653"></A>
|
|
To use a TCP connection, use an argument of the form
|
|
<CODE><VAR>host</VAR>:<VAR>port</VAR></CODE> or <CODE>tcp:<VAR>host</VAR>:<VAR>port</VAR></CODE>.
|
|
For example, to connect to port 2828 on a
|
|
terminal server named <CODE>manyfarms</CODE>:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target remote manyfarms:2828
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
If your remote target is actually running on the same machine as
|
|
your debugger session (e.g. a simulator of your target running on
|
|
the same host), you can omit the hostname. For example, to connect
|
|
to port 1234 on your local machine:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target remote :1234
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
Note that the colon is still required here.
|
|
</P><P>
|
|
|
|
<A NAME="IDX654"></A>
|
|
To use a UDP connection, use an argument of the form
|
|
<CODE>udp:<VAR>host</VAR>:<VAR>port</VAR></CODE>. For example, to connect to UDP port 2828
|
|
on a terminal server named <CODE>manyfarms</CODE>:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target remote udp:manyfarms:2828
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
When using a UDP connection for remote debugging, you should keep in mind
|
|
that the `U' stands for "Unreliable". UDP can silently drop packets on
|
|
busy or unreliable networks, which will cause havoc with your debugging
|
|
session.
|
|
</P><P>
|
|
|
|
</OL>
|
|
<P>
|
|
|
|
Now you can use all the usual commands to examine and change data and to
|
|
step and continue the remote program.
|
|
</P><P>
|
|
|
|
To resume the remote program and stop debugging it, use the <CODE>detach</CODE>
|
|
command.
|
|
</P><P>
|
|
|
|
<A NAME="IDX655"></A>
|
|
<A NAME="IDX656"></A>
|
|
Whenever GDB is waiting for the remote program, if you type the
|
|
interrupt character (often <KBD>C-C</KBD>), GDB attempts to stop the
|
|
program. This may or may not succeed, depending in part on the hardware
|
|
and the serial drivers the remote system uses. If you type the
|
|
interrupt character once again, GDB displays this prompt:
|
|
</P><P>
|
|
|
|
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Interrupted while waiting for the program.
|
|
Give up (and stop debugging it)? (y or n)
|
|
</FONT></pre></td></tr></table></P><P>
|
|
|
|
If you type <KBD>y</KBD>, GDB abandons the remote debugging session.
|
|
(If you decide you want to try again later, you can use <SAMP>`target
|
|
remote'</SAMP> again to connect once more.) If you type <KBD>n</KBD>, GDB
|
|
goes back to waiting.
|
|
</P><P>
|
|
|
|
<A NAME="Configurations"></A>
|
|
<HR SIZE="6">
|
|
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
|
|
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC136"> << </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_19.html#SEC143"> >> </A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_35.html#SEC643">Index</A>]</TD>
|
|
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
|
|
</TR></TABLE>
|
|
<BR>
|
|
<FONT SIZE="-1">
|
|
|
|
<address>
|
|
|
|
<p>Please send FSF & GNU inquiries & questions to <a
|
|
href="mailto:gnu@gnu.org">gnu@gnu.org</a>. There are also <a
|
|
href="http://www.gnu.org/home.html#ContactInfo">other ways to
|
|
contact</a> the FSF.</p>
|
|
|
|
<p>These pages are maintained by <a
|
|
href="http://www.gnu.org/software/gdb/">the GDB developers</a>.</p>
|
|
|
|
<p>Copyright Free Software Foundation, Inc., 59 Temple Place - Suite
|
|
330, Boston, MA 02111, USA.</p>
|
|
|
|
<p>Verbatim copying and distribution of this entire article is
|
|
permitted in any medium, provided this notice is preserved.</p>
|
|
|
|
</address>
|
|
|
|
This document was generated
|
|
by <I>GDB Administrator</I> on <I>November, 11 2002</I>
|
|
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
|
|
"><I>texi2html</I></A>
|
|
|
|
</BODY>
|
|
</HTML>
|