doc/gdb/Bootstrapping.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 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." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Bootstrapping</title>

<meta name="description" content="Debugging with GDB: Bootstrapping">
<meta name="keywords" content="Debugging with GDB: Bootstrapping">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Remote-Stub.html#Remote-Stub" rel="up" title="Remote Stub">
<link href="Debug-Session.html#Debug-Session" rel="next" title="Debug Session">
<link href="Stub-Contents.html#Stub-Contents" rel="previous" title="Stub Contents">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Bootstrapping"></a>
<div class="header">
<p>
Next: <a href="Debug-Session.html#Debug-Session" accesskey="n" rel="next">Debug Session</a>, Previous: <a href="Stub-Contents.html#Stub-Contents" accesskey="p" rel="previous">Stub Contents</a>, Up: <a href="Remote-Stub.html#Remote-Stub" accesskey="u" rel="up">Remote Stub</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="What-You-Must-Do-for-the-Stub"></a>
<h4 class="subsection">20.5.2 What You Must Do for the Stub</h4>

<a name="index-remote-stub_002c-support-routines"></a>
<p>The debugging stubs that come with <small>GDB</small> 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>
<dl compact="compact">
<dt><code>int getDebugChar()</code></dt>
<dd><a name="index-getDebugChar"></a>
<p>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>
</dd>
<dt><code>void putDebugChar(int)</code></dt>
<dd><a name="index-putDebugChar"></a>
<p>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.
</p></dd>
</dl>

<a name="index-control-C_002c-and-remote-debugging"></a>
<a name="index-interrupting-remote-targets"></a>
<p>If you want <small>GDB</small> 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> (&lsquo;<samp>\003</samp>&rsquo;, the control-C
character).  That is the character which <small>GDB</small> uses to tell the
remote system to stop.
</p>
<p>Getting the debugging target to return the proper status to <small>GDB</small>
probably requires changes to the standard stub; one quick and dirty way
is to just execute a breakpoint instruction (the &ldquo;dirty&rdquo; part is that
<small>GDB</small> reports a <code>SIGTRAP</code> instead of a <code>SIGINT</code>).
</p>
<p>Other routines you need to supply are:
</p>
<dl compact="compact">
<dt><code>void exceptionHandler (int <var>exception_number</var>, void *<var>exception_address</var>)</code></dt>
<dd><a name="index-exceptionHandler"></a>
<p>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&rsquo;s table might be in <small>ROM</small>,
containing entries which point to a table in <small>RAM</small>).
The <var>exception_number</var> specifies the exception 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>
<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
<small>SPARC</small> and 68k stubs are able to mask interrupts themselves without
help from <code>exceptionHandler</code>.
</p>
</dd>
<dt><code>void flush_i_cache()</code></dt>
<dd><a name="index-flush_005fi_005fcache"></a>
<p>On <small>SPARC</small> and <small>SPARCLITE</small> 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>
<p>On target machines that have instruction caches, <small>GDB</small> requires this
function to make certain that the state of your program is stable.
</p></dd>
</dl>

<p>You must also make sure this library routine is available:
</p>
<dl compact="compact">
<dt><code>void *memset(void *, int, int)</code></dt>
<dd><a name="index-memset"></a>
<p>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.
</p></dd>
</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><small>GCC</small></code> generates as inline code.
</p>

<hr>
<div class="header">
<p>
Next: <a href="Debug-Session.html#Debug-Session" accesskey="n" rel="next">Debug Session</a>, Previous: <a href="Stub-Contents.html#Stub-Contents" accesskey="p" rel="previous">Stub Contents</a>, Up: <a href="Remote-Stub.html#Remote-Stub" accesskey="u" rel="up">Remote Stub</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>