blob: 35efa49a31b8e865b8997f149a52179d46a2a533 [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>Running &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 src="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.js"></script>
<script src="../_static/sphinx_tabs/tabs.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="Configuring" href="configuring.html" />
<link rel="prev" title="Compiling" href="compiling.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 current"><a class="current reference internal" href="#">Running</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#flashing">Flashing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#access-nuttshell">Access NuttShell</a></li>
<li class="toctree-l3"><a class="reference internal" href="#debugging">Debugging</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#advanced-debugging-with-jtag">Advanced Debugging with JTAG</a></li>
<li class="toctree-l4"><a class="reference internal" href="#debugging-shortcuts">Debugging Shortcuts</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="configuring.html">Configuring</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></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>Running</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/quickstart/running.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="running">
<span id="id1"></span><h1>Running<a class="headerlink" href="#running" title="Permalink to this headline"></a></h1>
<p>In order to finally run NuttX on your board, you first have to flash the NuttX
binary. As an easy start, it is recommended that you choose a well supported board
which also integrates the debugger/programmer in the board itself exposed via USB
connector.</p>
<p>A good choice is a Nucleo or Discovery board from ST Microelectronics,
as there is a wide choice of suported boards for the STM32 architecture in NuttX.
Also, these boards expose an UART port over the USB connection which allows you
to interact with NuttX via the interactive console without any extra hardware.
For the purposes of this guide, we will use the Nucleo F103RB board.</p>
<div class="section" id="flashing">
<h2>Flashing<a class="headerlink" href="#flashing" title="Permalink to this headline"></a></h2>
<p>There are various tools you can use to flash the NuttX binary to your Nucleo
board. One common option is to use <cite>openocd</cite> which supports a large number
of programmers and target microcontrollers.</p>
<p>To install the stable version of openocd you can do:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> apt install openocd
</pre></div>
</div>
<div class="admonition-todo admonition" id="id2">
<p class="admonition-title">Todo</p>
<p>add instructions for other platforms</p>
</div>
<p>You should note that openocd project has not made stable releases for long
time and support for newer hardware will probably be only available in the
latest Git version. To install it you should:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> git clone git://git.code.sf.net/p/openocd/code openocd
<span class="gp">$</span> <span class="nb">cd</span> openocd
<span class="gp">$</span> ./bootstrap
<span class="gp">$</span> ./configure --prefix install/
<span class="gp">$</span> make install
</pre></div>
</div>
<p>The resulting installation will be under <code class="docutils literal notranslate"><span class="pre">openocd/install</span></code>. You can add
<code class="docutils literal notranslate"><span class="pre">openocd/install/bin</span></code> to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p>
<p>Now, to flash the binary to your board, connect the USB cable and do:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> nuttx/
<span class="gp">$</span> openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c <span class="s1">&#39;init&#39;</span> <span class="se">\</span>
-c <span class="s1">&#39;program nuttx/nuttx.bin verify reset&#39;</span> -c <span class="s1">&#39;shutdown&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="access-nuttshell">
<h2>Access NuttShell<a class="headerlink" href="#access-nuttshell" title="Permalink to this headline"></a></h2>
<p>Once you flash your board, it will reset and offer a prompt over the serial
console. With the Nucleo board, you can simply open the terminal program
of your choice where you will see the <code class="docutils literal notranslate"><span class="pre">nsh&gt;</span></code> prompt:</p>
<div class="sphinx-tabs docutils container">
<div class="ui top attached tabular menu sphinx-menu docutils container">
<div class="active item sphinx-data-tab-cGljb2NvbSAoQ0xJKQ== docutils container">
<div class="docutils container">
<p>picocom (CLI)</p>
</div>
</div>
<div class="item sphinx-data-tab-Z3RrdGVybSAoR1VJKQ== docutils container">
<div class="docutils container">
<p>gtkterm (GUI)</p>
</div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment code-tab sphinx-data-tab-cGljb2NvbSAoQ0xJKQ== active docutils container">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> picocom -b <span class="m">115200</span> /dev/ttyUSB0
</pre></div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment code-tab sphinx-data-tab-Z3RrdGVybSAoR1VJKQ== docutils container">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> gtkterm -s <span class="m">115200</span> -p /dev/ttyUSB0
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="debugging">
<h2>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline"></a></h2>
<p>Using <code class="docutils literal notranslate"><span class="pre">openocd</span></code> you can also debug NuttX. To do so, first run:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg
</pre></div>
</div>
<p>which will start a GDB server. Then, start <code class="docutils literal notranslate"><span class="pre">gdb</span></code> as:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> nuttx/
<span class="gp">$</span> gdb-multiarch nuttx/nuttx
</pre></div>
</div>
<p>Inside <code class="docutils literal notranslate"><span class="pre">gdb</span></code> console, connect to the <code class="docutils literal notranslate"><span class="pre">openocd</span></code> server with:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) target extended-remote :3333
</pre></div>
</div>
<p>You can debug using standard <code class="docutils literal notranslate"><span class="pre">gdb</span></code> commands.</p>
<div class="section" id="advanced-debugging-with-jtag">
<h3>Advanced Debugging with JTAG<a class="headerlink" href="#advanced-debugging-with-jtag" title="Permalink to this headline"></a></h3>
<p>If your board does not have an embedded programmer and uses
<a class="reference external" href="https://en.wikipedia.org/wiki/JTAG">JTAG</a> connector instead,
things are a bit different. This guide assumes 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>.
JTAG is a set of standards that let you
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>
<ol class="arabic">
<li><p>Attach the Debugger Cables</p></li>
<li><p>Start the Debugger</p>
<p>Refer to your JTAG debugger’s documentation for information on how to start a GDB Server process that gdb can
communicate with to load code and start, stop, and step the embedded board’s CPU. Your command line may be
different from this one.</p>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed <span class="m">1000</span> -JTAGConf -1,-1
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Launch the GNU Debugger</p>
<p>In another terminal window, launch the GDB. In the case of this guide, this came with the
ARM Embedded GNU Toolchain we downloaded in the Install step.</p>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> nuttx/
<span class="gp">$</span> gdb-multiarch nuttx/nuttx
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Set gdb to talk with the J-Link</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) target extended-remote :2331
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Reset the board</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) mon reset
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>You may need to switch to the serial console to hit a key to stop the board from booting from its boot monitor
(U-Boot, in the case of the SAMA5 boards from Microchip).</p></li>
<li><p>Halt the board</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) mon halt
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Load nuttx</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) load nuttx
`/home/adamf/src/nuttx-sama5d36-xplained/nuttx/nuttx&#39; has changed; re-reading symbols.
Loading section .text, size 0x9eae4 lma 0x20008000
Loading section .ARM.exidx, size 0x8 lma 0x200a6ae4
Loading section .data, size 0x125c lma 0x200a6aec
Start address 0x20008040, load size 654664
Transfer rate: 75 KB/sec, 15587 bytes/write.
(gdb)
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Set a breakpoint</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) breakpoint nsh_main
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Start nuttx</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>(gdb) continue
Continuing.
Breakpoint 1, nsh_main (argc=1, argv=0x200ddfac) at nsh_main.c:208
208 sched_getparam(0, &amp;param);
(gdb) continue
Continuing.
</pre></div>
</div>
</div></blockquote>
</li>
</ol>
</div>
<div class="section" id="debugging-shortcuts">
<h3>Debugging Shortcuts<a class="headerlink" href="#debugging-shortcuts" title="Permalink to this headline"></a></h3>
<p>Note that you can abbreviate <code class="docutils literal notranslate"><span class="pre">gdb</span></code> commands, <code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">b</span></code> is a shortcut for
<code class="docutils literal notranslate"><span class="pre">information</span> <span class="pre">breakpoints</span></code>; <code class="docutils literal notranslate"><span class="pre">c</span></code> works the same as <code class="docutils literal notranslate"><span class="pre">continue</span></code>, etc.</p>
<hr class="docutils" />
<p>Next up is <a class="reference internal" href="configuring.html#configuring"><span class="std std-ref">Configuring</span></a>.</p>
</div>
</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>