<html lang="en">
<head>
<title>Stub Contents - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Remote-Stub.html#Remote-Stub" title="Remote Stub">
<link rel="next" href="Bootstrapping.html#Bootstrapping" title="Bootstrapping">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Stub-Contents"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Bootstrapping.html#Bootstrapping">Bootstrapping</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Remote-Stub.html#Remote-Stub">Remote Stub</a>
<hr>
</div>

<h4 class="subsection">20.5.1 What the Stub Can Do for You</h4>

<p><a name="index-remote-serial-stub-1132"></a>The debugging stub for your architecture supplies these three
subroutines:

     <dl>
<dt><code>set_debug_traps</code><dd><a name="index-set_005fdebug_005ftraps-1133"></a><a name="index-remote-serial-stub_002c-initialization-1134"></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.

     <br><dt><code>handle_exception</code><dd><a name="index-handle_005fexception-1135"></a><a name="index-remote-serial-stub_002c-main-routine-1136"></a>This is the central workhorse, but your program never calls it
explicitly&mdash;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 <span class="sc">gdb</span> on the host machine.  This is where the communications
protocol is implemented; <code>handle_exception</code> acts as the <span class="sc">gdb</span>
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 <span class="sc">gdb</span> needs, until you
execute a <span class="sc">gdb</span> command that makes your program resume; at that point,
<code>handle_exception</code> returns control to your own code on the target
machine.

     <br><dt><code>breakpoint</code><dd><a name="index-g_t_0040code_007bbreakpoint_007d-subroutine_002c-remote-1137"></a>Use this auxiliary subroutine to make your program contain a
breakpoint.  Depending on the particular situation, this may be the only
way for <span class="sc">gdb</span> 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>&mdash;in effect, to <span class="sc">gdb</span>.  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&mdash;simply running &lsquo;<samp><span class="samp">target remote</span></samp>&rsquo; from the host
<span class="sc">gdb</span> 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>

   </body></html>