mingw/info/gdb/remote-stub.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="remote%20stub">remote stub</a>,
  13 Previous:<a rel="previous" accesskey="p" href="NetWare.html#NetWare">NetWare</a>,
  14 Up:<a rel="up" accesskey="u" href="Remote-Debugging.html#Remote%20Debugging">Remote Debugging</a>
  15 <hr><br>
  16 </div>
  17
  18 <h3 class="section">Implementing a remote stub</h3>
  19
  20    <p>The stub files provided with GDB implement the target side of the
  21 communication protocol, and the GDB side is implemented in the
  22 GDB source file <code>remote.c</code>.  Normally, you can simply allow
  23 these subroutines to communicate, and ignore the details.  (If you're
  24 implementing your own stub file, you can still ignore the details: start
  25 with one of the existing stub files.  <code>sparc-stub.c</code> is the best
  26 organized, and therefore the easiest to read.)
  27
  28    <p>To debug a program running on another machine (the debugging
  29 <dfn>target</dfn> machine), you must first arrange for all the usual
  30 prerequisites for the program to run by itself.  For example, for a C
  31 program, you need:
  32
  33      <ol type=1 start=1>
  34 <li>A startup routine to set up the C runtime environment; these usually
  35 have a name like <code>crt0</code>.  The startup routine may be supplied by
  36 your hardware supplier, or you may have to write your own.
  37
  38      <li>A C subroutine library to support your program's
  39 subroutine calls, notably managing input and output.
  40
  41      <li>A way of getting your program to the other machine--for example, a
  42 download program.  These are often supplied by the hardware
  43 manufacturer, but you may have to write your own from hardware
  44 documentation.
  45         </ol>
  46
  47    <p>The next step is to arrange for your program to use a serial port to
  48 communicate with the machine where GDB is running (the <dfn>host</dfn>
  49 machine).  In general terms, the scheme looks like this:
  50
  51      <dl>
  52 <dt><em>On the host,</em>
  53      <dd>GDB already understands how to use this protocol; when everything
  54 else is set up, you can simply use the <code>target remote</code> command
  55 (see <a href="Targets.html#Targets">Specifying a Debugging Target</a>).
  56
  57      <br><dt><em>On the target,</em>
  58      <dd>you must link with your program a few special-purpose subroutines that
  59 implement the GDB remote serial protocol.  The file containing these
  60 subroutines is called  a <dfn>debugging stub</dfn>.
  61
  62      <p>On certain remote targets, you can use an auxiliary program
  63 <code>gdbserver</code> instead of linking a stub into your program.
  64 See <a href="Server.html#Server">Using the <code>gdbserver</code> program</a>, for details.
  65 </dl>
  66
  67    <p>The debugging stub is specific to the architecture of the remote
  68 machine; for example, use <code>sparc-stub.c</code> to debug programs on
  69 <small>SPARC</small> boards.
  70
  71    <p>These working remote stubs are distributed with GDB:
  72
  73      <dl>
  74
  75      <br><dt><code>i386-stub.c</code>
  76      <dd>For Intel 386 and compatible architectures.
  77
  78      <br><dt><code>m68k-stub.c</code>
  79      <dd>For Motorola 680x0 architectures.
  80
  81      <br><dt><code>sh-stub.c</code>
  82      <dd>For Hitachi SH architectures.
  83
  84      <br><dt><code>sparc-stub.c</code>
  85      <dd>For <small>SPARC</small> architectures.
  86
  87      <br><dt><code>sparcl-stub.c</code>
  88      <dd>For Fujitsu <small>SPARCLITE</small> architectures.
  89
  90    </dl>
  91
  92    <p>The <code>README</code> file in the GDB distribution may list other
  93 recently added stubs.
  94
  95 <ul class="menu">
  96 <li><a accesskey="1" href="Stub-Contents.html#Stub%20Contents">Stub Contents</a>:        What the stub can do for you
  97 <li><a accesskey="2" href="Bootstrapping.html#Bootstrapping">Bootstrapping</a>:        What you must do for the stub
  98 <li><a accesskey="3" href="Debug-Session.html#Debug%20Session">Debug Session</a>:        Putting it all together
  99 </ul>
 100
 101    </body></html>
 102