Google Git
Sign in
apache / mynewt-site / 8528acea806ecedcedbaec90568a1524b3ae623d / . / master / os / modules / split / split.html
blob: 8e14fb4644ef77bc82f9a37a9fdedeba63ccc0e4 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Split Images &mdash; Apache Mynewt latest documentation</title>
<link rel="shortcut icon" href="../../../_static/mynewt-logo-only-newt32x32.png"/>
<link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/sphinx_theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/bootstrap-3.0.3.min.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/v2.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/custom.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/restructuredtext.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/overrides.css" type="text/css" />
<link rel="index" title="Index"
href="../../../genindex.html"/>
<link rel="search" title="Search" href="../../../search.html"/>
<link rel="top" title="Apache Mynewt latest documentation" href="../../../index.html"/>
<link rel="up" title="OS User Guide" href="../../os_user_guide.html"/>
<link rel="next" title="Porting Mynewt OS" href="../../core_os/porting/port_os.html"/>
<link rel="prev" title="Bootloader" href="../bootloader/bootloader.html"/>
<script src="../../../_static/js/modernizr.min.js"></script>
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="not-front page-documentation" role="document" >
<div id="wrapper">
<div class="container">
<div id="banner" class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="../../../_static/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released September 7, 2023)
</div>
</div>
</div>
</div>
<header>
<nav id="navbar" class="navbar navbar-inverse" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li class="important">
<a href="/quick-start/">Quick Start</a>
</li>
<li>
<a href="/about/">About</a>
</li>
<li>
<a href="/talks/">Talks</a>
</li>
<li class="active">
<a href="/documentation/">Documentation</a>
</li>
<li>
<a href="/download/">Download</a>
</li>
<li>
<a href="/community/">Community</a>
</li>
<li>
<a href="/events/">Events</a>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
</ul>
</div>
</div>
</nav>
</header>
<!-- STARTS MAIN CONTENT -->
<div id="main-content">
<div id="breadcrumb">
<div class="container">
<a href="/documentation/">Docs</a> /
<a href="../../os_user_guide.html">OS User Guide</a> /
Split Images
<div class="sourcelink">
<a href="https://github.com/apache/mynewt-core/edit/master/docs/os/modules/split/split.rst" class="icon icon-github"
rel="nofollow"> Edit on GitHub</a>
</div>
</div>
</div>
<!-- STARTS CONTAINER -->
<div class="container">
<!-- STARTS .content -->
<div id="content" class="row">
<!-- STARTS .container-sidebar -->
<div class="container-sidebar col-xs-12 col-sm-3">
<div id="docSidebar" class="sticky-container">
<div role="search" class="sphinx-search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search documentation" class="search-documentation" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<!-- Note: only works when deployed -->
<select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest" selected>
Version: latest
</option>
<option value="/v1_11_0" >
Version: 1.11.0
</option>
<option value="/v1_10_0" >
Version: 1.10.0
</option>
<option value="/v1_9_0" >
Version: 1.9.0
</option>
<option value="/v1_8_0" >
Version: 1.8.0
</option>
<option value="/v1_7_0" >
Version: 1.7.0
</option>
<option value="/v1_6_0" >
Version: 1.6.0
</option>
<option value="/v1_5_0" >
Version: 1.5.0
</option>
<option value="/v1_4_0" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select>
<div class="region region-sidebar">
<div class="docs-menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../get_started/index.html">Setup &amp; Get Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../concepts.html">Concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../tutorials/tutorials.html">Tutorials</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../external_links.html">Third-party Resources</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../os_user_guide.html">OS User Guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../core_os/mynewt_os.html">Kernel</a></li>
<li class="toctree-l2"><a class="reference internal" href="../system_modules.html">System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../hal/hal.html">Hardware Abstraction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bootloader/bootloader.html">Secure Bootloader</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Split Images</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../core_os/porting/port_os.html">Porting Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../baselibc.html">Baselibc</a></li>
<li class="toctree-l2"><a class="reference internal" href="../drivers/driver.html">Drivers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devmgmt/newtmgr.html">Device Management with Newt Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mcumgr/mcumgr.html">Device Management with MCUmgr</a></li>
<li class="toctree-l2"><a class="reference internal" href="../imgmgr/imgmgr.html">Image Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sysinitconfig/sysinitconfig.html">Compile-Time Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sysinitdown/sysinitdown.html">System Initialization and Shutdown</a></li>
<li class="toctree-l2"><a class="reference internal" href="../extcmd/extcmd.html">Build-Time Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../fs/fs.html">File System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../fcb/fcb.html">Flash Circular Buffer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sensor_framework/sensor_framework.html">Sensor Framework</a></li>
<li class="toctree-l2"><a class="reference internal" href="../testutil/testutil.html">Test Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../json/json.html">JSON</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mfg/mfg.html">Manufacturing support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../bsp/index.html">Board support</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../network/index.html">BLE User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../newt/index.html">Newt Tool Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../newtmgr/index.html">Newt Manager Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../mynewt_faq/index.html">Mynewt FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../misc/index.html">Appendix</a></li>
</ul>
</div>
</div>
</div>
<!-- ENDS STICKY CONTAINER -->
</div>
<!-- ENDS .container-sidebar -->
<div class="col-xs-12 col-sm-9">
<div class="">
<div class="rst-content">
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="split-images">
<h1>Split Images<a class="headerlink" href="#split-images" title="Permalink to this headline"></a></h1>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline"></a></h2>
<p>The split image mechanism divides a target into two separate images: one
capable of image upgrade; the other containing application code. By
isolating upgrade functionality to a separate image, the application can
support over-the-air upgrade without dedicating flash space to network
stack and management code.</p>
</div>
<div class="section" id="concept">
<h2>Concept<a class="headerlink" href="#concept" title="Permalink to this headline"></a></h2>
<p>Mynewt supports three image setups:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Setup</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Single</p></td>
<td><p>One large image; upgrade not supported.</p></td>
</tr>
<tr class="row-odd"><td><p>Unified</p></td>
<td><p>Two standalone images.</p></td>
</tr>
<tr class="row-even"><td><p>Split</p></td>
<td><p>Kernel in slot 0; application in slot 1.</p></td>
</tr>
</tbody>
</table>
<p>Each setup has its tradeoffs. The Single setup gives you the most flash
space, but doesn’t allow you to upgrade after manufacturing. The Unified
setup allows for a complete failover in case a bad image gets uploaded,
but requires a lot of redundancy in each image, limiting the amount of
flash available to the application. The Split setup sits somewhere
between these two options.</p>
<p>Before exploring the split setup in more detail, it might be helpful to
get a basic understanding of the Mynewt boot sequence. The boot process
is summarized below.</p>
<div class="section" id="boot-sequence-single">
<h3>Boot Sequence - Single<a class="headerlink" href="#boot-sequence-single" title="Permalink to this headline"></a></h3>
<p>In the Single setup, there is no boot loader. Instead, the image is
placed at address 0. The hardware boots directly into the image code.
Upgrade is not possible because there is no boot loader to move an
alternate image into place.</p>
</div>
<div class="section" id="boot-sequence-unified">
<h3>Boot Sequence - Unified<a class="headerlink" href="#boot-sequence-unified" title="Permalink to this headline"></a></h3>
<p>In the Unified setup, the boot loader is placed at address 0. At
startup, the boot loader arranges for the correct image to be in image
slot 0, which may entail swapping the contents of the two image slots.
Finally, the boot loader jumps to the image in slot 0.</p>
</div>
<div class="section" id="boot-sequence-split">
<h3>Boot Sequence - Split<a class="headerlink" href="#boot-sequence-split" title="Permalink to this headline"></a></h3>
<p>The Split setup differs from the other setups mainly in that a target is
not fully contained in a single image. Rather, the target is partitioned
among two separate images: the <em>loader</em>, and the <em>application</em>.
Functionality is divided among these two images as follows:</p>
<ol class="arabic simple">
<li><p>Loader:</p>
<ul class="simple">
<li><p>Mynewt OS.</p></li>
<li><p>Network stack for connectivity during upgrade e.g. BLE stack.</p></li>
<li><p>Anything else required for image upgrade.</p></li>
</ul>
</li>
<li><p>Application:</p>
<ul class="simple">
<li><p>Parts of Mynewt not required for image upgrade.</p></li>
<li><p>Application-specific code.</p></li>
</ul>
</li>
</ol>
<p>The loader image serves three purposes:</p>
<ol class="arabic simple">
<li><p><em>Second-stage boot loader:</em> it jumps into the application image at
start up.</p></li>
<li><p><em>Image upgrade server:</em> the user can upgrade to a new loader +
application combo, even if an application image is not currently
running.</p></li>
<li><p><em>Functionality container:</em> the application image can directly access
all the code present in the loader image</p></li>
</ol>
<p>From the perspective of the boot loader, a loader image is identical to
a plain unified image. What makes a loader image different is a change
to its start up sequence: rather than starting the Mynewt OS, it jumps
to the application image in slot 1 if one is present.</p>
</div>
</div>
<div class="section" id="tutorial">
<h2>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline"></a></h2>
<div class="section" id="building-a-split-image">
<h3>Building a Split Image<a class="headerlink" href="#building-a-split-image" title="Permalink to this headline"></a></h3>
<p>We will be referring to the Nordic PCA10028 (nRF51 DK) for examples in
this document. Let’s take a look at this board’s flash map (defined in
<code class="docutils literal notranslate"><span class="pre">hw/bsp/nrf51dk/bsp.yml</span></code>):</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 44%" />
<col style="width: 29%" />
<col style="width: 27%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Name</p></th>
<th class="head"><p>Offset</p></th>
<th class="head"><p>Size (kB)</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Boot loader</p></td>
<td><p>0x00000000</p></td>
<td><p>16</p></td>
</tr>
<tr class="row-odd"><td><p>Reboot log</p></td>
<td><p>0x00004000</p></td>
<td><p>16</p></td>
</tr>
<tr class="row-even"><td><p>Image slot 0</p></td>
<td><p>0x00008000</p></td>
<td><p>110</p></td>
</tr>
<tr class="row-odd"><td><p>Image slot 1</p></td>
<td><p>0x00023800</p></td>
<td><p>110</p></td>
</tr>
<tr class="row-even"><td><p>Image scratch</p></td>
<td><p>0x0003f000</p></td>
<td><p>2</p></td>
</tr>
<tr class="row-odd"><td><p>Flash file system</p></td>
<td><p>0x0003f800</p></td>
<td><p>2</p></td>
</tr>
</tbody>
</table>
<p>The application we will be building is
<a class="reference external" href="../../tutorials/bleprph">bleprph</a>. First, we create a target to tie
our BSP and application together.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>newt target create bleprph-nrf51dk
newt target set bleprph-nrf51dk \
app=@apache-mynewt-core/apps/bleprph \
bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028 \
build_profile=optimized \
syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
</div>
<p>The two syscfg settings disable bluetooth security and keep the code
size down.</p>
<p>We can verify the target using the <code class="docutils literal notranslate"><span class="pre">target</span> <span class="pre">show</span></code> command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newt target show bleprph-nrf51dk
targets/bleprph-nrf51dk
app=@apache-mynewt-core/apps/bleprph
bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028
build_profile=optimized
syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
</div>
<p>Next, build the target:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newt build bleprph-nrf51dk
Building target targets/bleprph-nrf51dk
# [...]
Target successfully built: targets/bleprph-nrf51dk
</pre></div>
</div>
<p>With our target built, we can view a code size breakdown using the
<code class="docutils literal notranslate"><span class="pre">newt</span> <span class="pre">size</span> <span class="pre">&lt;target&gt;</span></code> command. In the interest of brevity, the smaller
entries are excluded from the below output:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newt size bleprph-nrf51dk
Size of Application Image: app
FLASH RAM
2446 1533 apps_bleprph.a
1430 104 boot_bootutil.a
1232 0 crypto_mbedtls.a
1107 0 encoding_cborattr.a
2390 0 encoding_tinycbor.a
1764 0 fs_fcb.a
2959 697 hw_drivers_nimble_nrf51.a
4126 108 hw_mcu_nordic_nrf51xxx.a
8161 4049 kernel_os.a
2254 38 libc_baselibc.a
2612 0 libgcc.a
2232 24 mgmt_imgmgr.a
1499 44 mgmt_newtmgr_nmgr_os.a
23918 1930 net_nimble_controller.a
28537 2779 net_nimble_host.a
2207 205 sys_config.a
1074 197 sys_console_full.a
3268 97 sys_log.a
1296 0 time_datetime.a
objsize
text data bss dec hex filename
105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf
</pre></div>
</div>
<p>The full image text size is about 103kB (where 1kB = 1024 bytes). With
an image slot size of 110kB, this leaves only about 7kB of flash for
additional application code and data. Not good. This is the situation we
would be facing if we were using the Unified setup.</p>
<p>The Split setup can go a long way in solving our problem. Our unified
bleprph image consists mostly of components that get used during an
image upgrade. By using the Split setup, we turn the unified image into
two separate images: the loader and the application. The functionality
related to image upgrade can be delegated to the loader image, freeing
up a significant amount of flash in the application image slot.</p>
<p>Let’s create a new target to use with the Split setup. We designate a
target as a split target by setting the <code class="docutils literal notranslate"><span class="pre">loader</span></code> variable. In our
example, we are going to use <code class="docutils literal notranslate"><span class="pre">bleprph</span></code> as the loader, and <code class="docutils literal notranslate"><span class="pre">splitty</span></code>
as the application. <code class="docutils literal notranslate"><span class="pre">bleprph</span></code> makes sense as a loader because it
contains the BLE stack and everything else required for an image
upgrade.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>newt target create split-nrf51dk
newt target set split-nrf51dk \
loader=@apache-mynewt-core/apps/bleprph \
app=@apache-mynewt-core/apps/splitty \
bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028 \
build_profile=optimized \
syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
</div>
<p>Verify that the target looks correct:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newt target show split-nrf51dk
targets/split-nrf51dk
app=@apache-mynewt-core/apps/splitty
bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028
build_profile=optimized
loader=@apache-mynewt-core/apps/bleprph
syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
</div>
<p>Now, let’s build the new target:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newt build split-nrf51dk
Building target targets/split-nrf51dk
# [...]
Target successfully built: targets/split-nrf51dk
</pre></div>
</div>
<p>And look at the size breakdown (again, smaller entries are removed):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newt size split-nrf51dk
Size of Application Image: app
FLASH RAM
3064 251 sys_shell.a
objsize
text data bss dec hex filename
4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf
Size of Loader Image: loader
FLASH RAM
2446 1533 apps_bleprph.a
1430 104 boot_bootutil.a
1232 0 crypto_mbedtls.a
1107 0 encoding_cborattr.a
2390 0 encoding_tinycbor.a
1764 0 fs_fcb.a
3168 705 hw_drivers_nimble_nrf51.a
4318 109 hw_mcu_nordic_nrf51xxx.a
8285 4049 kernel_os.a
2274 38 libc_baselibc.a
2612 0 libgcc.a
2232 24 mgmt_imgmgr.a
1491 44 mgmt_newtmgr_nmgr_os.a
25169 1946 net_nimble_controller.a
31397 2827 net_nimble_host.a
2259 205 sys_config.a
1318 202 sys_console_full.a
3424 97 sys_log.a
1053 60 sys_stats.a
1296 0 time_datetime.a
objsize
text data bss dec hex filename
112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf
</pre></div>
</div>
<p>The size command shows two sets of output: one for the application, and
another for the loader. The addition of the split functionality did make
bleprph slightly bigger, but notice how small the application is: 4.5
kB! Where before we only had 7 kB left, now we have 105.5 kB.
Furthermore, all the functionality in the loader is available to the
application at any time. For example, if your application needs
bluetooth functionality, it can use the BLE stack present in the loader
instead of containing its own copy.</p>
<p>Finally, let’s deploy the split image to our Nordic PCA10028 (nRF51 DK) board.
The procedure here is the same as if we were using the Unified setup, i.e.,
via either the <code class="docutils literal notranslate"><span class="pre">newt</span> <span class="pre">load</span></code> or <code class="docutils literal notranslate"><span class="pre">newt</span> <span class="pre">run</span></code> command.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/repos/mynewt/core]$ newt load split-nrf51dk 0
Loading app image into slot 2
Loading loader image into slot 1
</pre></div>
</div>
</div>
</div>
<div class="section" id="image-management">
<h2>Image Management<a class="headerlink" href="#image-management" title="Permalink to this headline"></a></h2>
<div class="section" id="retrieve-current-state-image-list">
<h3>Retrieve Current State (image list)<a class="headerlink" href="#retrieve-current-state-image-list" title="Permalink to this headline"></a></h3>
<p>Image management in the split setup is a bit more complicated than in
the unified setup. You can determine a device’s image management state
with the <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">list</span></code> command. Here is how a device responds
to this command after our loader + application combo has been deployed:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list
Images:
slot=0
version: 0.0.0
bootable: true
flags: active confirmed
hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b
slot=1
version: 0.0.0
bootable: false
flags:
hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f
Split status: matching
</pre></div>
</div>
<p>There are several interesting things about this response:</p>
<ol class="arabic simple">
<li><p><em>Two images:</em> This is expected; we deployed both a loader image and
an application image.</p></li>
<li><p><em>bootable flag:</em> Notice slot 0’s bootable flag is set, while slot 1’s
is not. This tells us that slot 0 contains a loader and slot 1
contains an application. If an image is bootable, it can be booted
directly from the boot loader. Non-bootable images can only be
started from a loader image.</p></li>
<li><p><em>flags:</em> Slot 0 is <code class="docutils literal notranslate"><span class="pre">active</span></code> and <code class="docutils literal notranslate"><span class="pre">confirmed</span></code>; none of slot 1’s
flags are set. The <code class="docutils literal notranslate"><span class="pre">active</span></code> flag indicates that the image is
currently running; the <code class="docutils literal notranslate"><span class="pre">confirmed</span></code> flag indicates that the image
will continue to be used on subsequent reboots. Slot 1’s lack of
enabled flags indicates that the image is not being used at all.</p></li>
<li><p><em>Split status:</em> The split status field tells you if the loader and
application are compatible. A loader + application combo is
compatible only if both images were built at the same time with
<code class="docutils literal notranslate"><span class="pre">newt</span></code>. If the loader and application are not compatible, the
loader will not boot into the application.</p></li>
</ol>
<div class="section" id="enabling-a-split-application">
<h4>Enabling a Split Application<a class="headerlink" href="#enabling-a-split-application" title="Permalink to this headline"></a></h4>
<p>By default, the application image in slot 1 is disabled. This is
indicated in the <code class="docutils literal notranslate"><span class="pre">image</span> <span class="pre">list</span></code> response above. When you deploy a loader
/ application combo to your device, the application image won’t actually
run. Instead, the loader will act as though an application image is not
present and remain in “loader mode”. Typically, a device in loader mode
simply acts as an image management server, listening for an image
upgrade or a request to activate the application image.</p>
<p>Use the following command sequence to enable the split application
image:</p>
<ol class="arabic simple">
<li><p>Tell device to “test out” the application image on next boot
(<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">test</span> <span class="pre">&lt;application-image-hash&gt;</span></code>).</p></li>
<li><p>Reboot device (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">reset</span></code>).</p></li>
<li><p>Make above change permanent (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">confirm</span></code>).</p></li>
</ol>
<p>After the above sequence, a <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">list</span></code> command elicits the
following response:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm
Images:
slot=0
version: 0.0.0
bootable: true
flags: active confirmed
hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b
slot=1
version: 0.0.0
bootable: false
flags: active confirmed
hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f
Split status: matching
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">active</span> <span class="pre">confirmed</span></code> flags value on both slots indicates that both
images are permanently running.</p>
</div>
<div class="section" id="image-upgrade">
<h4>Image Upgrade<a class="headerlink" href="#image-upgrade" title="Permalink to this headline"></a></h4>
<p>First, let’s review of the image upgrade process for the Unified setup.
The user upgrades to a new image in this setup with the following steps:</p>
</div>
</div>
<div class="section" id="image-upgrade-unified">
<h3>Image Upgrade - Unified<a class="headerlink" href="#image-upgrade-unified" title="Permalink to this headline"></a></h3>
<ol class="arabic simple">
<li><p>Upload new image to slot 1 (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">upload</span> <span class="pre">&lt;filename&gt;</span></code>).</p></li>
<li><p>Tell device to “test out” the new image on next boot
(<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">test</span> <span class="pre">&lt;image-hash&gt;</span></code>).</p></li>
<li><p>Reboot device (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">reset</span></code>).</p></li>
<li><p>Make new image permanent (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">confirm</span></code>).</p></li>
</ol>
</div>
<div class="section" id="image-upgrade-split">
<h3>Image Upgrade - Split<a class="headerlink" href="#image-upgrade-split" title="Permalink to this headline"></a></h3>
<p>The image upgrade process is a bit more complicated in the Split setup.
It is more complicated because two images need to be upgraded (loader
and application) rather than just one. The split upgrade process is
described below:</p>
<ol class="arabic simple">
<li><p>Disable split functionality; we need to deactivate the application
image in slot 1 (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">test</span> <span class="pre">&lt;current-loader-hash&gt;</span></code>).</p></li>
<li><p>Reboot device (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">reset</span></code>).</p></li>
<li><p>Make above change permanent (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">confirm</span></code>).</p></li>
<li><p>Upload new loader to slot 1 (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">upload</span> <span class="pre">&lt;filename&gt;</span></code>).</p></li>
<li><p>Tell device to “test out” the new loader on next boot
(<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">test</span> <span class="pre">&lt;new-loader-hash&gt;</span></code>).</p></li>
<li><p>Reboot device (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">reset</span></code>).</p></li>
<li><p>Make above change of loader permanent (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">confirm</span></code>).</p></li>
<li><p>Upload new application to slot 1
(<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">upload</span> <span class="pre">&lt;filename&gt;</span></code>).</p></li>
<li><p>Tell device to “test out” the new application on next boot
(<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">test</span> <span class="pre">&lt;new-application-hash&gt;</span></code>).</p></li>
<li><p>Reboot device (<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">reset</span></code>).</p></li>
<li><p>Make above change of application permanent
(<code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">confirm</span></code>).</p></li>
</ol>
<p>When performing this process manually, it may be helpful to use
<code class="docutils literal notranslate"><span class="pre">image</span> <span class="pre">list</span></code> to check the image management state as you go.</p>
</div>
</div>
<div class="section" id="syscfg">
<h2>Syscfg<a class="headerlink" href="#syscfg" title="Permalink to this headline"></a></h2>
<p>Syscfg is Mynewt’s system-wide configuration mechanism. In a split
setup, there is a single umbrella syscfg configuration that applies to
both the loader and the application. Consequently, overriding a value in
an application-only package potentially affects the loader (and
vice-versa).</p>
</div>
<div class="section" id="loaders">
<h2>Loaders<a class="headerlink" href="#loaders" title="Permalink to this headline"></a></h2>
<p>The following applications have been enabled as loaders. You may choose
to build your own loader application, and these can serve as samples.</p>
<ul class="simple">
<li><p>&#64;apache-mynewt-core/apps/slinky</p></li>
<li><p>&#64;apache-mynewt-core/apps/bleprph</p></li>
</ul>
</div>
<div class="section" id="split-apps">
<h2>Split Apps<a class="headerlink" href="#split-apps" title="Permalink to this headline"></a></h2>
<p>The following applications have been enabled as split applications. If
you choose to build your own split application these can serve as
samples. Note that slinky can be either a loader image or an application
image.</p>
<ul class="simple">
<li><p>&#64;apache-mynewt-core/apps/slinky</p></li>
<li><p>&#64;apache-mynewt-core/apps/splitty</p></li>
</ul>
</div>
<div class="section" id="theory-of-operation">
<h2>Theory of Operation<a class="headerlink" href="#theory-of-operation" title="Permalink to this headline"></a></h2>
<p>A split image is built as follows:</p>
<p>First newt builds the application and loader images separately to ensure
they are consistent (no errors) and to generate elf files which can
inform newt of the symbols used by each part.</p>
<p>Then newt collects the symbols used by both application and loader in
two ways. It collects the set of symbols from the <code class="docutils literal notranslate"><span class="pre">.elf</span></code> files. It
also collects all the possible symbols from the <code class="docutils literal notranslate"><span class="pre">.a</span></code> files for each
application.</p>
<p>Newt builds the set of packages that the two applications share. It
ensures that all the symbols used in those packages are matching. NOTE:
because of features and #ifdefs, its possible for the two package to
have symbols that are not the same. In this case newt generates an error
and will not build a split image.</p>
<p>Then newt creates the list of symbols that the two applications share
from those packages (using the .elf files).</p>
<p>Newt re-links the loader to ensure all of these symbols are present in
the loader application (by forcing the linker to include them in the
<code class="docutils literal notranslate"><span class="pre">.elf</span></code>).</p>
<p>Newt builds a special copy of the loader.elf with only these symbols
(and the handful of symbols discussed in the linking section above).</p>
<p>Finally, newt links the application, replacing the common .a libraries
with the special loader.elf image during the link.</p>
</div>
</div>
</div>
</div>
<div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation">
<a href="../../core_os/porting/port_os.html" class="btn btn-neutral float-right" title="Porting Mynewt OS" accesskey="n">Next: Porting Mynewt OS <span class="fa fa-arrow-circle-right"></span></a>
<a href="../bootloader/bootloader.html" class="btn btn-neutral" title="Bootloader" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: Bootloader</a>
</div>
</div>
</div>
</div>
<!-- ENDS CONTENT SECTION -->
</div>
<!-- ENDS .content -->
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<img src="../../../_static/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt project logo are either
registered trademarks or trademarks of the Apache Software Foundation in the United States and other countries.
</small>
<a href="">
<img src="../../../_static/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
</div>
</div>
</footer>
</div>
<!-- ENDS #wrapper -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../../',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
LINK_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../_static/js/bootstrap-3.0.3.min.js"></script>
<script type="text/javascript" src="../../../_static/js/affix.js"></script>
<script type="text/javascript" src="../../../_static/js/main.js"></script>
</body>
</html>