/usr/share/doc/openocd/openocd.html/GDB-and-OpenOCD.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- 
This User's Guide documents
release 0.7.0,
dated 4 May 2013,
of the Open On-Chip Debugger (OpenOCD).

Copyright (C) 2008 The OpenOCD Project
Copyright (C) 2007-2008 Spencer Oliver spen@spen-soft.co.uk
Copyright (C) 2008-2010 Oyvind Harboe oyvind.harboe@zylin.com
Copyright (C) 2008 Duane Ellis openocd@duaneellis.com
Copyright (C) 2009-2010 David Brownell

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>OpenOCD User&rsquo;s Guide: GDB and OpenOCD</title>

<meta name="description" content="OpenOCD User&rsquo;s Guide: GDB and OpenOCD">
<meta name="keywords" content="OpenOCD User&rsquo;s Guide: GDB and OpenOCD">
<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="OpenOCD-Concept-Index.html#OpenOCD-Concept-Index" rel="index" title="OpenOCD Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Tcl-Scripting-API.html#Tcl-Scripting-API" rel="next" title="Tcl Scripting API">
<link href="TFTP.html#TFTP" rel="previous" title="TFTP">
<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="GDB-and-OpenOCD"></a>
<div class="header">
<p>
Next: <a href="Tcl-Scripting-API.html#Tcl-Scripting-API" accesskey="n" rel="next">Tcl Scripting API</a>, Previous: <a href="TFTP.html#TFTP" accesskey="p" rel="previous">TFTP</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="OpenOCD-Concept-Index.html#OpenOCD-Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="GDB-and-OpenOCD-1"></a>
<h2 class="chapter">21 GDB and OpenOCD</h2>
<a name="index-GDB-1"></a>
<p>OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
Setting up GDB to work with OpenOCD can involve several components:
</p>
<ul>
<li> The OpenOCD server support for GDB may need to be configured.
See <a href="Daemon-Configuration.html#gdbconfiguration">GDB Configuration</a>.
</li><li> GDB&rsquo;s support for OpenOCD may need configuration,
as shown in this chapter.
</li><li> If you have a GUI environment like Eclipse,
that also will probably need to be configured.
</li></ul>

<p>Of course, the version of GDB you use will need to be one which has
been built to know about the target CPU you&rsquo;re using. It&rsquo;s probably
part of the tool chain you&rsquo;re using. For example, if you are doing
cross-development for ARM on an x86 PC, instead of using the native
x86 <code>gdb</code> command you might use <code>arm-none-eabi-gdb</code>
if that&rsquo;s the tool chain used to compile your code.
</p>
<a name="Connecting-to-GDB"></a>
<h3 class="section">21.1 Connecting to GDB</h3>
<a name="index-Connecting-to-GDB"></a>
<p>Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
instance GDB 6.3 has a known bug that produces bogus memory access
errors, which has since been fixed; see
<a href="http://osdir.com/ml/gdb.bugs.discuss/2004-12/msg00018.html">http://osdir.com/ml/gdb.bugs.discuss/2004-12/msg00018.html</a>
</p>
<p>OpenOCD can communicate with GDB in two ways:
</p>
<ol>
<li> A socket (TCP/IP) connection is typically started as follows:
<div class="example">
<pre class="example">target remote localhost:3333
</pre></div>
<p>This would cause GDB to connect to the gdbserver on the local pc using port 3333.
</p>
<p>It is also possible to use the GDB extended remote protocol as follows:
</p><div class="example">
<pre class="example">target extended-remote localhost:3333
</pre></div>
</li><li> A pipe connection is typically started as follows:
<div class="example">
<pre class="example">target remote | openocd -c &quot;gdb_port pipe; log_output openocd.log&quot;
</pre></div>
<p>This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
session. log_output sends the log output to a file to ensure that the pipe is
not saturated when using higher debug level outputs.
</p></li></ol>

<p>To list the available OpenOCD commands type <code>monitor help</code> on the
GDB command line.
</p>
<a name="Sample-GDB-session-startup"></a>
<h3 class="section">21.2 Sample GDB session startup</h3>

<p>With the remote protocol, GDB sessions start a little differently
than they do when you&rsquo;re debugging locally.
Here&rsquo;s an examples showing how to start a debug session with a
small ARM program.
In this case the program was linked to be loaded into SRAM on a Cortex-M3.
Most programs would be written into flash (address 0) and run from there.
</p>
<div class="example">
<pre class="example">$ arm-none-eabi-gdb example.elf
(gdb) target remote localhost:3333
Remote debugging using localhost:3333
...
(gdb) monitor reset halt
...
(gdb) load
Loading section .vectors, size 0x100 lma 0x20000000
Loading section .text, size 0x5a0 lma 0x20000100
Loading section .data, size 0x18 lma 0x200006a0
Start address 0x2000061c, load size 1720
Transfer rate: 22 KB/sec, 573 bytes/write.
(gdb) continue
Continuing.
...
</pre></div>

<p>You could then interrupt the GDB session to make the program break,
type <code>where</code> to show the stack, <code>list</code> to show the
code around the program counter, <code>step</code> through code,
set breakpoints or watchpoints, and so on.
</p>
<a name="Configuring-GDB-for-OpenOCD"></a>
<h3 class="section">21.3 Configuring GDB for OpenOCD</h3>

<p>OpenOCD supports the gdb <samp>qSupported</samp> packet, this enables information
to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical information includes
packet size and the device&rsquo;s memory map.
You do not need to configure the packet size by hand,
and the relevant parts of the memory map should be automatically
set up when you declare (NOR) flash banks.
</p>
<p>However, there are other things which GDB can&rsquo;t currently query.
You may need to set those up by hand.
As OpenOCD starts up, you will often see a line reporting
something like:
</p>
<div class="example">
<pre class="example">Info : lm3s.cpu: hardware has 6 breakpoints, 4 watchpoints
</pre></div>

<p>You can pass that information to GDB with these commands:
</p>
<div class="example">
<pre class="example">set remote hardware-breakpoint-limit 6
set remote hardware-watchpoint-limit 4
</pre></div>

<p>With that particular hardware (Cortex-M3) the hardware breakpoints
only work for code running from flash memory. Most other ARM systems
do not have such restrictions.
</p>
<p>Another example of useful GDB configuration came from a user who
found that single stepping his Cortex-M3 didn&rsquo;t work well with IRQs
and an RTOS until he told GDB to disable the IRQs while stepping:
</p>
<div class="example">
<pre class="example">define hook-step
mon cortex_m maskisr on
end
define hookpost-step
mon cortex_m maskisr off
end
</pre></div>

<p>Rather than typing such commands interactively, you may prefer to
save them in a file and have GDB execute them as it starts, perhaps
using a <samp>.gdbinit</samp> in your project directory or starting GDB
using <code>gdb -x filename</code>.
</p>
<a name="Programming-using-GDB"></a>
<h3 class="section">21.4 Programming using GDB</h3>
<a name="index-Programming-using-GDB"></a>
<a name="programmingusinggdb"></a>
<p>By default the target memory map is sent to GDB. This can be disabled by
the following OpenOCD configuration option:
</p><div class="example">
<pre class="example">gdb_memory_map disable
</pre></div>
<p>For this to function correctly a valid flash configuration must also be set
in OpenOCD. For faster performance you should also configure a valid
working area.
</p>
<p>Informing GDB of the memory map of the target will enable GDB to protect any
flash areas of the target and use hardware breakpoints by default. This means
that the OpenOCD option <code>gdb_breakpoint_override</code> is not required when
using a memory map. See <a href="Daemon-Configuration.html#gdbbreakpointoverride">gdb_breakpoint_override</a>.
</p>
<p>To view the configured memory map in GDB, use the GDB command <samp>info mem</samp>
All other unassigned addresses within GDB are treated as RAM.
</p>
<p>GDB 6.8 and higher set any memory area not in the memory map as inaccessible.
This can be changed to the old behaviour by using the following GDB command
</p><div class="example">
<pre class="example">set mem inaccessible-by-default off
</pre></div>

<p>If <code>gdb_flash_program enable</code> is also used, GDB will be able to
program any flash memory using the vFlash interface.
</p>
<p>GDB will look at the target memory map when a load command is given, if any
areas to be programmed lie within the target flash area the vFlash packets
will be used.
</p>
<p>If the target needs configuring before GDB programming, an event
script can be executed:
</p><div class="example">
<pre class="example">$_TARGETNAME configure -event EVENTNAME BODY
</pre></div>

<p>To verify any flash programming the GDB command <samp>compare-sections</samp>
can be used.
<a name="usingopenocdsmpwithgdb"></a></p><a name="Using-OpenOCD-SMP-with-GDB"></a>
<h3 class="section">21.5 Using OpenOCD SMP with GDB</h3>
<a name="index-SMP-1"></a>
<p>For SMP support following GDB serial protocol packet have been defined :
</p><ul>
<li> j - smp status request
</li><li> J - smp set request
</li></ul>

<p>OpenOCD implements :
</p><ul>
<li> <samp>jc</samp> packet for reading core id displayed by
GDB connection. Reply is <samp>XXXXXXXX</samp> (8 hex digits giving core id) or
 <samp>E01</samp> for target not smp.
</li><li> <samp>JcXXXXXXXX</samp> (8 hex digits) packet for setting core id displayed at next GDB continue
(core id -1 is reserved for returning to normal resume mode). Reply <samp>E01</samp>
for target not smp or <samp>OK</samp> on success.
</li></ul>

<p>Handling of this packet within GDB can be done :
</p><ul>
<li> by the creation of an internal variable (i.e <samp>_core</samp>) by mean
of function allocate_computed_value allowing following GDB command.
<div class="example">
<pre class="example">set $_core 1
#Jc01 packet is sent
print $_core
#jc packet is sent and result is affected in $
</pre></div>

</li><li> by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
core id 0 and 1 see <a href="Config-File-Guidelines.html#definecputargetsworkinginsmp">Define CPU targets working in SMP</a>).

<div class="example">
<pre class="example"># toggle0 : force display of coreid 0
define toggle0
maint packet Jc0
continue
main packet Jc-1
end
# toggle1 : force display of coreid 1
define toggle1
maint packet Jc1
continue
main packet Jc-1
end
</pre></div>
</li></ul>


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



</body>
</html>
openocd 0.7.0-2 / usr / share / doc / openocd / openocd.html / GDB-and-OpenOCD.html
