blob: 22743330183fc1a0e241fd3f49f6623f27a14ff7 [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Debugging &mdash; NuttX latest documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Directory Structure" href="organization.html" />
<link rel="prev" title="Configuring" href="configuring.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> NuttX
<img src="../_static/NuttX.png" class="logo" alt="Logo"/>
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select>
<option value="latest" selected="selected">latest</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Getting Started</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
<li class="toctree-l2"><a class="reference internal" href="install.html">Installing</a></li>
<li class="toctree-l2"><a class="reference internal" href="compiling.html">Compiling</a></li>
<li class="toctree-l2"><a class="reference internal" href="running.html">Running</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuring.html">Configuring</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Debugging</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#debug-logging">Debug Logging</a></li>
<li class="toctree-l3"><a class="reference internal" href="#changing-debug-settings-quickly">Changing Debug Settings Quickly</a></li>
<li class="toctree-l3"><a class="reference internal" href="#jtag-debugging">JTAG Debugging</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="organization.html">Directory Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="build_and_make.html">Build and Make Details</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../components/index.html">OS Components</a></li>
<li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../boards/index.html">Supported Boards</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
<li><a href="index.html">Getting Started</a> &raquo;</li>
<li>Debugging</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/quickstart/debugging.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="debugging">
<span id="id1"></span><h1>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline"></a></h1>
<p>Finding and fixing bugs is an important part of the hardware and software development process. Sometimes you also need
to use debugging techniques to understand how the system works. Two tools that are helpful are debug logging and
debugging using the GNU Debugger (gdb).</p>
<div class="section" id="debug-logging">
<h2>Debug Logging<a class="headerlink" href="#debug-logging" title="Permalink to this headline"></a></h2>
<p>NuttX has a powerful system logging facility (syslog) with <code class="docutils literal notranslate"><span class="pre">info</span></code>, <code class="docutils literal notranslate"><span class="pre">warn</span></code>, and <code class="docutils literal notranslate"><span class="pre">error</span></code> levels. You can enable
debugging for your build for the subsystem or feature by using the <code class="docutils literal notranslate"><span class="pre">menuconfig</span></code> system.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> make menuconfig
</pre></div>
</div>
<p>The debug options are available under <code class="docutils literal notranslate"><span class="pre">Build</span> <span class="pre">Setup</span></code> &gt; <code class="docutils literal notranslate"><span class="pre">Debug</span> <span class="pre">Options</span></code>. You will most likely have to enable the
following options:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">Enable</span> <span class="pre">Debug</span> <span class="pre">Features</span></code> — selecting this will turn on subsystem-level debugging options, they will become visible
on the page below. You can then select the ones you want.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Enable</span> <span class="pre">Error</span> <span class="pre">Output</span></code> — this will only log errors.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Enable</span> <span class="pre">Warnings</span> <span class="pre">Output</span></code> — this will log warnings and errors.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Enable</span> <span class="pre">Informational</span> <span class="pre">Debug</span> <span class="pre">Output</span></code> — this will produce informational output, warnings, and errors.</p></li>
</ul>
<p>You can then select from the subsystems that are available, Network, Scheduler, USB, etc. Note that you will need to
separately enable the subsystem elsewhere in the <code class="docutils literal notranslate"><span class="pre">menuconfig</span></code> system. To see the <code class="docutils literal notranslate"><span class="pre">CONFIG</span></code> define that is set,
use the arrow keys to highlight the subsystem (for instance, <code class="docutils literal notranslate"><span class="pre">Network</span> <span class="pre">Debug</span> <span class="pre">Features</span></code>) and type ‘?’. This will show
you that the C macro that is set is called <code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_NET</span></code>. <code class="docutils literal notranslate"><span class="pre">debug.h</span></code> defines the <code class="docutils literal notranslate"><span class="pre">netinfo()</span></code> logging
function that will log output if this macro is set. You can search the source code for <code class="docutils literal notranslate"><span class="pre">netinfo</span></code> to see how it is
used.</p>
<a class="reference internal image-reference" href="../_images/menuconfig-debug.png"><img alt="Screenshot of menuconfig system main screen" class="align-center" src="../_images/menuconfig-debug.png" style="width: 800px;" /></a>
<p>Note that enabling all these will produce an incredible amount of logging output. Enable the level you want and
the area you’re interested in, and leave the rest disabled, save the config, and then recompile. You can see the full
list of debug feature logging functions in the file
<a class="reference external" href="https://github.com/apache/incubator-nuttx/blob/master/include/debug.h">debug.h</a>.</p>
<p>Syslog timestamps can be enabled in the <code class="docutils literal notranslate"><span class="pre">menuconfig</span></code> system using <code class="docutils literal notranslate"><span class="pre">Device</span> <span class="pre">Drivers</span></code> &gt; <code class="docutils literal notranslate"><span class="pre">System</span> <span class="pre">Logging</span></code> &gt; <code class="docutils literal notranslate"><span class="pre">Prepend</span>
<span class="pre">timestamp</span> <span class="pre">to</span> <span class="pre">syslog</span> <span class="pre">message</span></code> (<code class="docutils literal notranslate"><span class="pre">CONFIG_SYSLOG_TIMESTAMP</span></code>).</p>
<p>You may need to do a little bit of experimenting to find the combination of logging settings that work for the problem
you’re trying to solve. See the file <a class="reference external" href="https://github.com/apache/incubator-nuttx/blob/master/include/debug.h">debug.h</a>
for available debug settings that are available. This can also be configured via the <code class="docutils literal notranslate"><span class="pre">menuconfig</span></code> system.</p>
<p>There are also subsystems that enable USB trace debugging, and you can log to memory too, if you need the logging to be
faster than what the console can output.</p>
</div>
<div class="section" id="changing-debug-settings-quickly">
<h2>Changing Debug Settings Quickly<a class="headerlink" href="#changing-debug-settings-quickly" title="Permalink to this headline"></a></h2>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">kconfig-tweak</span></code> script that comes with the <code class="docutils literal notranslate"><span class="pre">kconfig-frontends</span></code> tools to quickly change debug settings,
for instance turning them on or off before doing a build:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> kconfig-tweak --disable CONFIG_DEBUG_NET
<span class="gp">$</span> make olddefconfig <span class="c1"># needed to have the kconfig system check the config</span>
<span class="gp">$</span> kconfig-tweak --enable CONFIG_DEBUG_NET
<span class="gp">$</span> make olddefconfig
</pre></div>
</div>
<p>You can put a bunch of these into a simple script to configure the logging the way you want:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">#</span>!/bin/bash
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_ALERT</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_FEATURES</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_ERROR</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_WARN</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_INFO</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_ASSERTIONS</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_NET</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_NET_ERROR</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_NET_WARN</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_NET_INFO</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_SYMBOLS</span>
<span class="go">kconfig-tweak --disable CONFIG_DEBUG_NOOPT</span>
<span class="go">kconfig-tweak --disable CONFIG_SYSLOG_TIMESTAMP</span>
<span class="go">make oldconfig</span>
</pre></div>
</div>
</div>
<div class="section" id="jtag-debugging">
<h2>JTAG Debugging<a class="headerlink" href="#jtag-debugging" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/JTAG">JTAG</a> is a set of standards that specify a way to attach a hardware device to
your embedded board, and then remotely control the CPU. You can load code, start, stop, step through the program, and
examine variables and memory.</p>
<p>This guide assumes your board has a JTAG connector, and you have a JTAG hardware debugger like a
<a class="reference external" href="https://www.segger.com/products/debug-probes/j-link/">Segger J-Link</a> or <a class="reference external" href="http://openocd.org/doc-release/html/index.html">OpenOCD</a>.</p>
<p>The NuttX operating system uses <a class="reference external" href="https://en.wikipedia.org/wiki/Thread_(computing)">threads</a>, so you need a
thread-aware debugger to do more than load code, start, and stop it. A thread-aware debugger will allow you to switch
threads to the one that is running the code you’re interested in, for instance your application, or an operating system
network thread. So far, OpenOCD is the only supported NuttX thread-aware debugger.</p>
<p>You will need an OpenOCD-compatible hardware adapter, ideally a fast one (USB 2.0 High Speed). This guide assumes you
are using the <a class="reference external" href="https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/">Olimex ARM USB TINY H</a>.
(<a class="reference external" href="https://smile.amazon.com/Olimex-ARM-USB-TINY-H-Arm-Jtag/dp/B009UED630/">Olimex ARM USB TINY H on Amazon</a>.) Other
adapters may work, follow the OpenOCD instructions and the instructions that came with your adapter.</p>
<p>You’ll need to use the <a class="reference external" href="https://github.com/sony/openocd-nuttx">Sony fork of OpenOCD</a>. Download and install it
according to the OpenOCD instructions.</p>
<p>See this article for more info:
<a class="reference external" href="https://micro-ros.github.io/docs/tutorials/advanced/debugging_gdb_openocd/">Debugging a Apache NuttX target with GDB and OpenOCD</a>.</p>
<p>See the section <a class="reference internal" href="running.html#running"><span class="std std-ref">Running</span></a> for a brief tutorial on how to use GDB.</p>
<hr class="docutils" />
<p>Next up is <a class="reference internal" href="organization.html#organization"><span class="std std-ref">Directory Structure</span></a>.</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, The Apache Software Foundation
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>