You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2017/01/12 05:44:35 UTC
[1/5] incubator-mynewt-site git commit: Split image documentation
updated
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/asf-site cbe9ead1f -> 7eec48971
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/latest/os/modules/devmgmt/newtmgr/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/devmgmt/newtmgr/index.html b/latest/os/modules/devmgmt/newtmgr/index.html
index ee52f96..1704b41 100644
--- a/latest/os/modules/devmgmt/newtmgr/index.html
+++ b/latest/os/modules/devmgmt/newtmgr/index.html
@@ -556,7 +556,7 @@
<li>Use the <code>oicmgr</code> package if interoperability and standards-based connectivity for device interaction is your primary requirement. This package supports the OIC (Open Interconnect Consortium) Specification 1.1.0 framework from Open Connectivity Foundation (OCF). </li>
</ol>
<h3 id="invoking-newt-manager-commands">Invoking Newt Manager commands</h3>
-<p>The diagram below indicates the two options available to the application developer to issue Newt Manager commands ('newtmgr commmands<code>) on a Mynewt device. The application may leverage the</code>newtmgr<code>framework or the</code>oicmgr` framework to call the newtmgr commands. The latter is described in the next chapter.</p>
+<p>The diagram below indicates the two options available to the application developer to issue Newt Manager (<code>newtmgr</code>) commands on a Mynewt device. The application may leverage the <code>newtmgr</code> framework or the <code>oicmgr</code> framework to call the newtmgr commands. The latter is described in the next chapter.</p>
<p><img alt="Device Management" src="../device-mgmt.png" /></p>
<h3 id="newtmgr">newtmgr</h3>
<p>The newtmgr framework uses a simple request and response message format to send commands to the device. A message
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/latest/os/modules/fs/fs/fs/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/fs/fs/fs/index.html b/latest/os/modules/fs/fs/fs/index.html
index fe6fa96..52923fc 100644
--- a/latest/os/modules/fs/fs/fs/index.html
+++ b/latest/os/modules/fs/fs/fs/index.html
@@ -612,45 +612,35 @@
<h1 id="file-system-abstraction">File System Abstraction</h1>
<p>Mynewt provides a file system abstraction layer (<code>fs/fs</code>) to allow client code to be file system agnostic. By accessing the file system via the <code>fs/fs</code> API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the <code>fs/fs</code> API rather than accessing the underlying file system directly.</p>
<h3 id="description">Description</h3>
-<p>Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the <code>fs/fs</code> package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the <strong>app</strong> package must depend on a specific file system package, while <strong>library</strong> packages should only depend on <code>fs/fs</code>.</p>
-<p>The following example illustrates how file system dependencies should be managed. In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called <code>fs/nffs</code> (Newtron Flash File System). The app explicitly initializes nffs via calls to <code>nffs_init()</code>, <code>nffs_detect()</code> and <code>nffs_format()</code>.</p>
+<p>Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the
+<code>fs/fs</code> package.
+In terms of the Mynewt hierarchy, an <strong>app</strong> package must depend on a specific file system package, while <strong>library</strong> packages should only depend on <code>fs/fs</code>.</p>
+<p>Applications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.
+In the following example, the <a href="../../nffs/nffs/"><code>Newtron Flash File System</code></a>
+is used.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># repos/apache-mynewt-core/apps/slinky/pkg.yml
pkg.name: repos/apache-mynewt-core/apps/slinky
pkg.deps:
- - fs/nffs
-
-# [...]
+ - fs/fs # include the file operations interfaces
+ - fs/nffs # include the NFFS filesystem implementation
</pre></div>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/* repos/apache-mynewt-core/apps/slinky/src/main.c */</span>
-
-<span style="color: #633820">#include "nffs/nffs.h"</span>
-
-<span style="color: #A90D91">int</span>
-<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
-{
- <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
- <span style="color: #A90D91">int</span> <span style="color: #000000">cnt</span>;
- <span style="color: #A90D91">struct</span> <span style="color: #000000">nffs_area_desc</span> <span style="color: #000000">descs</span>[<span style="color: #000000">NFFS_AREA_MAX</span>];
-
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_init</span>();
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># repos/apache-mynewt-core/apps/slinky/syscfg.yml
+# [...]
+ # Package: apps/<example app>
+# [...]
+ CONFIG_NFFS: 1 # initialize and configure NFFS into the system
+# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues
+# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect
- <span style="color: #000000">cnt</span> <span style="color: #000000">=</span> <span style="color: #000000">NFFS_AREA_MAX</span>;
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">flash_area_to_nffs_desc</span>(<span style="color: #000000">FLASH_AREA_NFFS</span>, <span style="color: #000000">&cnt</span>, <span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
- <span style="color: #A90D91">if</span> (<span style="color: #000000">nffs_detect</span>(<span style="color: #000000">descs</span>) <span style="color: #000000">==</span> <span style="color: #000000">FS_ECORRUPT</span>) {
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_format</span>(<span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
- }
- <span style="color: #177500">// [...]</span>
-}
+# [...]
</pre></div>
-<p>On the other hand, code which uses the file system after it has been initialized need only depend on <code>fs/fs</code>. For example, the <code>libs/imgmgr</code> package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the <code>fs/fs</code> package.</p>
+<p>Consult the documentation for <a href="../../nffs/nffs/"><code>nffs</code></a> for a more detailed explanation of NFFS_DETECT_FAIL</p>
+<p>Code which uses the file system after the system has been initialized need only depend on <code>fs/fs</code>. For example, the <code>libs/imgmgr</code> package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the <code>fs/fs</code> package.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># repos/apache-mynewt-core/libs/imgmgr/pkg.yml
pkg.name: libs/imgmgr
pkg.deps:
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/latest/os/modules/fs/nffs/nffs/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/fs/nffs/nffs/index.html b/latest/os/modules/fs/nffs/nffs/index.html
index 6457073..3271f94 100644
--- a/latest/os/modules/fs/nffs/nffs/index.html
+++ b/latest/os/modules/fs/nffs/nffs/index.html
@@ -627,72 +627,19 @@
<p><strong>Regarding property 2:</strong> Furthermore, some flash hardware imposes a restriction with regards to writes: writes within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.</p>
<p>Thus, each area must comprise a discrete number of blocks.</p>
<h4 id="initialization">Initialization</h4>
-<p>Before nffs can be used, it must be initialized. There are two means of initializing an nffs file system:</p>
+<p>As part of overall system initialization, mynewt re-initialized the filesystem as follows:</p>
<ol>
-<li>Restore an existing file system via detection.</li>
-<li>Create a new file system via formatting.</li>
+<li>Restores an existing file system via detection.</li>
+<li>Creates a new file system via formatting.</li>
</ol>
<p>A typical initialization sequence is the following:</p>
<ol>
<li>Detect an nffs file system in a specific region of flash.</li>
-<li>If no file system was detected, format a new file system in the same flash region.</li>
+<li>If no file system was detected, if configured to do so, format a new file system in the same flash region.</li>
</ol>
-<p>Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of <a href="../nffs_area_desc/">struct nffs_area_desc</a>.</p>
-<p>Typically, a product's flash layout is exposed via its BSP-specific <code>bsp_flash_dev()</code> function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the <code>struct nffs_area_desc[]</code> that nffs requires. The below example, taken from the slinky project, illustrates the nffs initialization procedure.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/*** hw/hal/include/hal/flash_map.h */</span>
-
-<span style="color: #177500">/*</span>
-<span style="color: #177500"> * Flash area types</span>
-<span style="color: #177500"> */</span>
-<span style="color: #633820">#define FLASH_AREA_BOOTLOADER 0</span>
-<span style="color: #633820">#define FLASH_AREA_IMAGE_0 1</span>
-<span style="color: #633820">#define FLASH_AREA_IMAGE_1 2</span>
-<span style="color: #633820">#define FLASH_AREA_IMAGE_SCRATCH 3</span>
-<span style="color: #633820">#define FLASH_AREA_NFFS 4</span>
-</pre></div>
-
-
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/*** project/slinky/src/main.c */</span>
-
-<span style="color: #A90D91">int</span>
-<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
-{
- <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
- <span style="color: #A90D91">int</span> <span style="color: #000000">cnt</span>;
-
- <span style="color: #177500">/* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */</span>
- <span style="color: #A90D91">struct</span> <span style="color: #000000">nffs_area_desc</span> <span style="color: #000000">descs</span>[<span style="color: #000000">NFFS_AREA_MAX</span>];
-
- <span style="color: #177500">/* Initialize nffs's internal state. */</span>
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_init</span>();
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
-
- <span style="color: #177500">/* Convert the set of flash blocks we intend to use for nffs into an array</span>
-<span style="color: #177500"> * of nffs area descriptors.</span>
-<span style="color: #177500"> */</span>
- <span style="color: #000000">cnt</span> <span style="color: #000000">=</span> <span style="color: #000000">NFFS_AREA_MAX</span>;
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">flash_area_to_nffs_desc</span>(<span style="color: #000000">FLASH_AREA_NFFS</span>, <span style="color: #000000">&cnt</span>, <span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
-
- <span style="color: #177500">/* Attempt to restore an existing nffs file system from flash. */</span>
- <span style="color: #A90D91">if</span> (<span style="color: #000000">nffs_detect</span>(<span style="color: #000000">descs</span>) <span style="color: #000000">==</span> <span style="color: #000000">FS_ECORRUPT</span>) {
- <span style="color: #177500">/* No valid nffs instance detected; format a new one. */</span>
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_format</span>(<span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
- }
- <span style="color: #177500">/* [ ... ] */</span>
-}
-</pre></div>
-
-
+<p>Note that in the latter case, the behavior is controlled with a variable in the syscfg.yml file. If NFFS_DETECT_FAIL is set to 1, the system ignores NFFS filesystem detection issues, but unless a new filesystem is formatted manually, all filesystem access will fail. If NFFS_DETECT_FAIL is set to 2, the system will format a new filesystem - note however this effectively deletes all existing data in the NFFS flash areas.</p>
+<p>Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of <a href="../nffs_area_desc/">struct nffs_area_desc</a> configured as part of the BSP configureation.</p>
<p>After nffs has been initialized, the application can access the file system via the <a href="../../fs/fs/">file system abstraction layer</a>.</p>
-<h3 id="configuration">Configuration</h3>
-<p>The nffs file system is configured by populating fields in a global <a href="../nffs_config/">struct nffs_config</a> instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs_init().</p>
-<p>The global <code>struct nffs_config</code> instance is exposed in <code>nffs/nffs.h</code> as follows:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">extern</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">nffs_config</span> <span style="color: #000000">nffs_config</span>;
-</pre></div>
-
-
<h3 id="data-structures">Data Structures</h3>
<p>The <code>fs/nffs</code> package exposes the following data structures:</p>
<table>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/latest/os/modules/split/split/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/split/split/index.html b/latest/os/modules/split/split/index.html
index 0847857..5ebbfc8 100644
--- a/latest/os/modules/split/split/index.html
+++ b/latest/os/modules/split/split/index.html
@@ -543,384 +543,435 @@
<h1 id="split-images">Split Images</h1>
<h2 id="description">Description</h2>
-<p>Split images allow the user to build the application content separate from the library content by
-splitting an application into two pieces:</p>
-<ul>
-<li>A "loader" which contains a separate application that can perform upgrades and manage split images.
-The "loader" resides in slot 1.</li>
-<li>A "split app" which contains the main application content and references the libraries in the loader
-by static linkage. The "split app" resides in slot 2.</li>
-</ul>
-<h2 id="goals">Goals</h2>
-<p>The goal of split images is to allow a larger application to run along with large components of
-mynewt such as <a href="../../../../network/ble/ble_intro/">nimble BLE stack</a> and <a href="../../fs/nffs/nffs/">neutron flash file system(nffs)</a>.</p>
+<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>
<h2 id="concept">Concept</h2>
-<p>In a typical mynewt application, an application is contained wholly within an image slot. Typically
-there are at least two image slots since the image runs from one slot while uploading new code into
-the second slot. Each image is capable of erasing and uploading another image. Each image is completely
-stand-alone; that is, each image contains all of the libraries and components that it needs.</p>
-<p>On a typical 256 kbyte flash, a flash layout might look like this:</p>
+<p>Mynewt supports three image setups:</p>
<table>
<thead>
<tr>
-<th>Name</th>
-<th>Size</th>
+<th>Setup</th>
+<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
-<td>bootloader</td>
-<td>16 k</td>
-</tr>
-<tr>
-<td>image slot 1</td>
-<td>108 k</td>
+<td>Single</td>
+<td>One large image; upgrade not supported.</td>
</tr>
<tr>
-<td>image slot 2</td>
-<td>108 k</td>
+<td>Unified</td>
+<td>Two standalone images.</td>
</tr>
<tr>
-<td>scratch</td>
-<td>8 k</td>
-</tr>
-<tr>
-<td>Flash file system</td>
-<td>16 k</td>
+<td>Split</td>
+<td>Kernel in slot 0; application in slot 1.</td>
</tr>
</tbody>
</table>
-<p>Now, suppose the desired image contains:</p>
+<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>
+<h4 id="boot-sequence-single">Boot Sequence - Single</h4>
+<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>
+<h4 id="boot-sequence-unified">Boot Sequence - Unified</h4>
+<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>
+<h4 id="boot-sequence-split">Boot Sequence - Split</h4>
+<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>
+<li>
+<p>Loader: </p>
+<ul>
+<li>Mynewt OS.</li>
+<li>Network stack for connectivity during upgrade e.g. BLE stack.</li>
+<li>Anything else required for image upgrade.</li>
+</ul>
+</li>
+<li>
+<p>Application:</p>
+<ul>
+<li>Parts of Mynewt not required for image upgrade.</li>
+<li>Application-specific code.</li>
+</ul>
+</li>
+</ol>
+<p>The loader image serves three purposes:</p>
+<ol>
+<li><em>Second-stage boot loader:</em> it jumps into the application image at
+ start up.</li>
+<li><em>Image upgrade server:</em> the user can upgrade to a new loader + application
+ combo, even if an application image is not currently running.</li>
+<li><em>Functionality container:</em> the application image can directly access all the
+ code present in the loader image</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>
+<h2 id="tutorial">Tutorial</h2>
+<h3 id="building-a-split-image">Building a Split Image</h3>
+<p>We will be referring to the nRF51dk for examples in this document. Let's take
+a look at this board's flash map (defined in <code>hw/bsp/nrf51dk/bsp.yml</code>):</p>
<table>
<thead>
<tr>
-<th>Package</th>
-<th>Size</th>
+<th>Name</th>
+<th>Offset</th>
+<th>Size (kB)</th>
</tr>
</thead>
<tbody>
<tr>
-<td>nimble</td>
-<td>69 k</td>
+<td>Boot loader</td>
+<td>0x00000000</td>
+<td>16</td>
</tr>
<tr>
-<td>os</td>
-<td>6 k</td>
+<td>Reboot log</td>
+<td>0x00004000</td>
+<td>16</td>
</tr>
<tr>
-<td>logging</td>
-<td>3 k</td>
+<td>Image slot 0</td>
+<td>0x00008000</td>
+<td>110</td>
</tr>
<tr>
-<td>imagemgr</td>
-<td>3 k</td>
+<td>Image slot 1</td>
+<td>0x00023800</td>
+<td>110</td>
</tr>
<tr>
-<td>config</td>
-<td>3 k</td>
+<td>Image scratch</td>
+<td>0x0003f000</td>
+<td>2</td>
</tr>
<tr>
-<td>nffs</td>
-<td>15 k</td>
-</tr>
-<tr>
-<td>newtmgr</td>
-<td>7 k</td>
+<td>Flash file system</td>
+<td>0x0003f800</td>
+<td>2</td>
</tr>
</tbody>
</table>
-<p>which total 106k. With an image slot size of 108k this leaves only a small amount of code space
-remaining for the application.</p>
-<p>However, we can see that these packages contain everything you need to upgrade and configure, so
-if we build a stand-alone loader with these components, we can build the app as a split image and
-get the entire second image slot to store application code and constant data.</p>
-<h2 id="when-do-i-use-split-images">When do I use split images</h2>
-<p>If your application fits into the available image slots, there is no advantage to using split
-images. In general, split images are harder to debug and more complicated to upload. However
-for a larger application, there may not be enough flash space to have two copies of the entire
-application. This is when split image becomes necessary.</p>
-<h2 id="how-do-i-tell-newt-i-am-building-a-split-image">How do I tell Newt I am building a split image?</h2>
-<p>Newt looks for the variable <code>loader</code> in your target file. If it finds <code>loader</code> variable, it
-will build a split image. For example,</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">targets/app
- app=@apache-mynewt-core/apps/splitty
- loader=@apache-mynewt-core/apps/slinky
- bsp=@apache-mynewt-core/hw/bsp/nrf52dk
+<p>The application we will be building is <a href="../../../tutorials/bleprph">bleprph</a>.
+First, we create a target to tie our BSP and application together.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">newt target create bleprph-nrf51dk
+newt target set bleprph-nrf51dk \
+ app=@apache-mynewt-core/apps/bleprph \
+ bsp=@apache-mynewt-core/hw/bsp/nrf51dk \
+ build_profile=optimized \
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
+</pre></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>target show</code> command:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt target show bleprph-nrf51dk
+targets/bleprph-nrf51dk
+ app=@apache-mynewt-core/apps/bleprph
+ bsp=@apache-mynewt-core/hw/bsp/nrf51dk
build_profile=optimized
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
-<p>shows an application called splitty which uses slinky as its loader.</p>
-<h2 id="platforms">Platforms</h2>
-<p>Split image requires BSP support. The following BSPs support split images:</p>
-<ul>
-<li>hw/bsp/arduino_primo_nrf52</li>
-<li>hw/bsp/bmd300eval</li>
-<li>hw/bsp/nrf51-blenano</li>
-<li>hw/bsp/nrf51dk</li>
-<li>hw/bsp/nrf51dk-16kbram</li>
-<li>hw/bsp/nrf52dk</li>
-</ul>
-<h2 id="loaders">Loaders</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>
-<li>@apache-mynewt-core/apps/slinky</li>
-<li>@apache-mynewt-core/apps/bleprph</li>
-</ul>
-<h2 id="split-apps">Split Apps</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 a split app image.</p>
-<ul>
-<li>@apache-mynewt-core/apps/slinky</li>
-<li>@apache-mynewt-core/apps/splitty</li>
-</ul>
-<h2 id="theory-of-operation">Theory of Operation</h2>
-<p>A split image is built as follows:</p>
-<p>First newt builds the <code>app</code> and <code>loader</code> 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 <code>app</code> and <code>loader</code> in two ways. It collects the set of
-symbols from the <code>.elf</code> files. It also collects all the possible symbols from the <code>.a</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>.elf</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>
-<h2 id="design">Design</h2>
-<h3 id="bootloader">Bootloader</h3>
-<p>The <a href="../../bootloader/bootloader/">bootloader</a> has been modified to support "non bootable" images like split app images. A flag in
-the image header denotes the image as "non-bootable". When this flag is set, the bootloader will
-not boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable,
-split app images are not.</p>
-<h3 id="newt">Newt</h3>
-<p>Newt builds a split image when the token <code>loader=@apache-mynewt-core/apps/slinky</code> is present in the target file.</p>
-<p>Newt has a <code>Builder</code> object that is responsible for building an image. This features a <code>targetBuilder</code>
-object that contains two builders (one for the app and one for the loader).</p>
-<p>The <code>Builder</code> object has been expanded to include options for building as part of a split image.
-<em> Ability to specify the linker file during the link
-</em> Ability to specify a set of keep_symbols during the link</p>
-<p>Newt commands like download, size, create-image have been expanded to perform operations twice
-(once for loader and once for app) if the loader target is present.</p>
-<p>During normal single-image builds, the <code>targetBuilder</code> initializes and builds the application
-<code>builder</code>. During the split image build, the <code>targetBuilder</code> performs the steps outlined in the
-section above using the two <code>builder</code>s for the loader and app.</p>
-<p>Special symbol and link features are designed as follows:</p>
-<ul>
-<li>Newt uses objdump to parse the symbol maps in the <code>.a</code> and <code>.elf</code> files.</li>
-<li>Newt uses the <code>--undefined=</code> option of the linker to force the loader to keep symbols used by
-the app (but not used by the linker)</li>
-<li>Newt uses objcopy with the <code>-K</code> (keep) option when building the special linker <code>.elf</code>.</li>
-<li>Newt uses the <code>--just-symbols</code> option of the linker to link against the loader <code>.elf</code> file.</li>
-</ul>
-<h4 id="newt-create-image">newt create-image</h4>
-<p><code>create-image</code> uses two different methods to compute the image hash for standard and split images.<br />
-For split images, the hash is computed starting with the 32-byte hash of the loader, then continuing
-with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically.</p>
-<h4 id="newt-errors">newt errors</h4>
-<p>Newt has several new build errors when building split images.</p>
-<ul>
-<li>Linker script undefined. If the BSP for your application does not define a split image linker script
-the build will fail.</li>
-</ul>
-<p>If newt finds that the same library (for example libs/os) has a different implementaiton in the loader
-and app, it will generate an error and fail to build. These differences can arise when <code>#ifdef</code> or features
-are included in one app and not the other. For example, it the loader includes <code>libs/console/stubs</code> and the
-app includes <code>libs/console/full</code> this may change implementations of certain functions within other packages.</p>
-<h3 id="image-manifest">Image manifest</h3>
-<p>newt builds a single manifest for split images, adding extra tags to the manifest when the image is a split image.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> "loader": "slinky.img",
- "loader_hash": "55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0",
- "loader_pkgs": [
- ...
- ]
+<p>Next, build the target:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt build bleprph-nrf51dk
+Building target targets/bleprph-nrf51dk
+# [...]
+Target successfully built: targets/bleprph-nrf51dk
</pre></div>
-<p>The manifest lists packages in both the loader and app. The app package list only contains those
-packages that reside in the app image itself.</p>
-<h3 id="libsbootutil">libs/bootutil</h3>
-<p>Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies
-that it matches the loader image in slot 1 and then fetches the entry information for the split app.</p>
-<h3 id="libssplit">libs/split</h3>
-<p>A small split image library was created to provide newtmgr commands for split image and to hold the
-configuration for split image. See newtmgr below for details.</p>
-<p>It also contains the function used by a loader to validate and boot a split image.</p>
-<h3 id="appsslinky">apps/slinky</h3>
-<p>A sample app that can be built as a split image with slinky.</p>
-<h2 id="tips-when-building-split-images">Tips when Building Split images</h2>
-<p><strong>To be added</strong></p>
-<h2 id="adding-bsp-support-for-split-images">Adding BSP support for split images</h2>
-<p>A BSP needs additional components to be "split image ready".</p>
-<p>The split image requires a special linker script. The split image needs to run from the second image
-partition (since it's using the loader library that is linked to be placed in the first partition).<br />
-It needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it).</p>
-<p>The startup of the split image is different than a typical image. It needs to copy <code>.data</code> from the
-loader image, and zero the loader image bss. For this, it must reference symbols defined in the linker
-script of the loader. It has a special entry symbol that differentiates it from the entry symbol in the
-loader application.</p>
-<p>Several of the bsp scripts need to handle additional agruments to deal with the two images produced
-by newt when building split images - mainly download and debug.</p>
-<p>Add the following components to enable your BSP for split images:</p>
-<ol>
-<li>A split image linker file</li>
-<li>A startup file for the split image</li>
-<li>A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as <code>pkg.part2linkerscript: "split-nrf52dk.ld</code> for example.</li>
-<li>Modified download script</li>
-<li>Modified sbrk functionality</li>
-</ol>
-<p>An example can be found in the <code>/hw/bsp/nrf52dk</code></p>
-<h3 id="split-image-linker-script">split image linker script</h3>
-<p>The split image linker script must have the following.</p>
-<p>The split linker must be linked to run from the second flash image slot. For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">MEMORY</span>
-{
- <span style="color: #000000">FLASH</span> (<span style="color: #000000">rx</span>) <span style="color: #000000">:</span> <span style="color: #000000">ORIGIN</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x00042000</span>, <span style="color: #000000">LENGTH</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x3a000</span>
- <span style="color: #000000">RAM</span> (<span style="color: #000000">rwx</span>) <span style="color: #000000">:</span> <span style="color: #000000">ORIGIN</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x20000000</span>, <span style="color: #000000">LENGTH</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x10000</span>
-}
+<p>With our target built, we can view a code size breakdown using the <code>newt size <target></code> command. In the interest of brevity, the smaller entries are excluded from the below output:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
-<p>The split linker must define the entry symbol as Reset_Handler_split. For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">ENTRY</span>(<span style="color: #000000">Reset_Handler_split</span>)
+<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>loader</code> variable. In our example, we are
+going to use <code>bleprph</code> as the loader, and <code>splitty</code> as the application.
+<code>bleprph</code> makes sense as a loader because it contains the BLE stack and
+everything else required for an image upgrade.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">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/nrf51dk \
+ build_profile=optimized \
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
-<p>The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional
-vector entries are part of the loader and are not needed in the split image. The bootloader accesses these
-entries at the beginning of the image slot (first 2 words). For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> .text :
- {
- __split_isr_vector_start = .;
- KEEP(*(.isr_vector_split))
- __split_isr_vector_end = .;
- ...
- }
+<p>Verify that the target looks correct:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt target show split-nrf51dk
+targets/split-nrf51dk
+ app=@apache-mynewt-core/apps/splitty
+ bsp=@apache-mynewt-core/hw/bsp/nrf51dk
+ build_profile=optimized
+ loader=@apache-mynewt-core/apps/bleprph
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
-<p>The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are
-both using RAM). Note, the two apps don't run at the same time, but the loader has global data that its
-libraries use. This cannot be overwritten by the application. An example linker section that accomplishes
-this can be found in <code>/hw/bsp/nrf52dk/split-nrf52dk.ld</code>. When linking against the loader, the loader exports
-the following symbosl which can be used by the split app code:</p>
-<ul>
-<li><code>__HeapBase_loader</code></li>
-<li><code>__bss_start___loader</code></li>
-<li><code>__bss_end___loader</code></li>
-<li><code>__etext_loader</code></li>
-<li><code>__data_start___loader</code></li>
-<li><code>__data_end___loader</code></li>
-</ul>
-<p>The split app linker can use <code>__HeapBase_loader</code> to skip RAM used by the loader as follows.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #177500">/* save RAM used by the split image. This assumes that</span>
-<span style="color: #177500"> * the loader uses all the RAM up to its HeapBase */</span>
- .<span style="color: #000000">loader_ram_contents</span> :
- {
- <span style="color: #000000">_loader_ram_start</span> <span style="color: #000000">=</span> .;
-
- <span style="color: #177500">/* this symbol comes from the loader linker */</span>
- . <span style="color: #000000">=</span> . <span style="color: #000000">+</span> (<span style="color: #000000">ABSOLUTE</span>(<span style="color: #000000">__HeapBase_loader</span>) <span style="color: #000000">-</span> <span style="color: #000000">_loader_ram_start</span>);
- <span style="color: #000000">_loader_ram_end</span> <span style="color: #000000">=</span> .;
- } <span style="color: #000000">></span> <span style="color: #000000">RAM</span>
+<p>Now, let's build the new target:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt build split-nrf51dk
+Building target targets/split-nrf51dk
+# [...]
+Target successfully built: targets/split-nrf51dk
</pre></div>
-<h3 id="split-image-startup-code">split image startup code</h3>
-<p>The split application needs separate startup code to intialize the split image before running main. The
-split image is specially linked so that <code>_start</code> and <code>main</code> are included individually for the loader and split app.</p>
-<p>The split app startup code must have the following.</p>
-<ol>
-<li>A definition of the split image vector table (first two words).</li>
-<li>The entry point function to start the code <code>Reset_Handler_split</code></li>
-<li>Code that copies the <code>.data</code> section for the loader from Flash to RAM</li>
-<li>Code that zeros the <code>.bss</code> section for the loader.</li>
-<li>Code that calls <code>_sbrkInit</code> to set the heap pointers for the application (see below)</li>
-<li>Code that calls the <code>bsp_slot_init_split_application</code> function (see below)</li>
-</ol>
-<p>An example can be found in the <code>/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s</code></p>
-<h3 id="download-script">Download script</h3>
-<p>The download script needs to be modified to include support for passing the image slot number in the build.<br />
-Image slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers.</p>
-<p>See and example in <code>/hw/bsp/bmd300eval/bmd300eval_download.sh</code>.</p>
-<h3 id="sbrk-functionality">Sbrk functionality</h3>
-<p>Split image (either a loader or app) references a single set of heap managment functions. But the heap location and
-size is different depending which image is running. Special functionality is needed to handle the dynamic
-setting of the heap base and limit.</p>
-<p>Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk
-needs to be dynamically initialized with these values from the startup code.</p>
-<p>See an example in <code>/hw/bsp/bmd300eval/src/sbrk.c</code> in the core repository. The function <code>_sbrkInit</code> must be
-called from the startup code of the split image and normal image startup code with the appropriate
-values of heap base and limit.</p>
-<h3 id="slot-init">Slot Init</h3>
-<p>A global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as
-the combined loader/app image. Its the responsibility of the startup code to set this global variable.</p>
-<p>See <code>hw/bsp/bmd300eval/src/os_bsp.c</code> for and implementation of the functionality.</p>
-<h2 id="newtmgr-and-split-images">newtmgr and split Images</h2>
-<p>newtmgr has support for split images.</p>
-<p><code>newtmgr image list</code> lists the current images in the flash. Its clear from the output that some images are non-bootable. For example.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Images:
- slot=1
- version=1.2.3
- bootable=true
- hash=55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0
- slot=2
- version=1.2.3
- bootable=false
- hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe
+<p>And look at the size breakdown (again, smaller entries are removed):</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
-<p>The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the <code>boot2</code>
-command to instruct mynewt to boot slot 2.</p>
-<p>Instead, use the new <code>split status</code> command to see the status of split images and to set their boot status.<br />
-The split status command with no arguments returns status of the split image. The Split Value tells the loader
-how to boot the split app. Options are:</p>
-<ul>
-<li><code>none</code> Don't boot the split application. Just remain running in the loader.</li>
-<li><code>test</code> Boot the split application, but revert back to the loader on the next reset.</li>
-<li><code>run</code> Boot the split application.</li>
-</ul>
-<p>The split status command also verified the hash of the split application (using the hash of the loader
-as shown above) and returns the status of the check (matching or non-matching).</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">newtmgr -c connection split status
- Split value is none
- Split status is matching
+<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 nRF51dk board. The procedure here
+is the same as if we were using the Unified setup, i.e., via either the <code>newt load</code> or <code>newt run</code> command.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/repos/mynewt/core]$ newt load split-nrf51dk 0
+Loading app image into slot 2
+Loading loader image into slot 1
</pre></div>
-<p>When the split image application is running, the active hash in the <code>boot2</code> command will match the
-hash of the split application (in slot 2). For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">prompt$ newtmgr -c foo1 image boot
- Test image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0
- Main image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0
- Active img: 1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe
+<h3 id="image-management">Image Management</h3>
+<h4 id="retrieve-current-state-image-list">Retrieve Current State (image list)</h4>
+<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>newtmgr image list</code> command. Here is how a device responds to this command
+after our loader + application combo has been deployed:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
-<h2 id="upgrading-a-split-image-with-newtmgr">Upgrading a split image with newtmgr</h2>
-<p>When running via newt, the <code>newt load</code> command will load both parts of a split image, the loader and application.</p>
-<p>When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the
-split app in <code>run</code> mode the following sequence will upgrade</p>
+<p>There are several interesting things about this response:</p>
<ol>
-<li>newtmgr split status none</li>
-<li>newtmgr reboot</li>
-<li>newtmgr image upload <filename of new loader></li>
-<li>newtmgr image boot2 <hash of new loader></li>
-<li>newtmgr reboot</li>
-<li>newtmgr image upload <filename of new split app></li>
-<li>newtmgr split status test</li>
-<li>newtmgr reboot</li>
-<li>newtmgr boot2 (check status to ensure new app is running)</li>
-<li>newtmgr split status run</li>
+<li><em>Two images:</em> This is expected; we deployed both a loader image and an
+application image.</li>
+<li><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.</li>
+<li><em>flags:</em> Slot 0 is <code>active</code> and <code>confirmed</code>; none of slot 1's flags are set.
+The <code>active</code> flag indicates that the image is currently running; the
+<code>confirmed</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.</li>
+<li><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>newt</code>. If the loader and
+application are not compatible, the loader will not boot into the application.</li>
</ol>
-<p>This upgrade is robust. In all steps there is a loader image that is capable of upgrading (or reverting) images.</p>
+<h3 id="enabling-a-split-application">Enabling a Split Application</h3>
+<p>By default, the application image in slot 1 is disabled. This is indicated in
+the <code>image list</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>
+<li>Tell device to "test out" the application image on next boot (<code>newtmgr image test <application-image-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change permanent (<code>newtmgr image confirm</code>).</li>
+</ol>
+<p>After the above sequence, a <code>newtmgr image list</code> command elicits the following response:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
+
+
+<p>The <code>active confirmed</code> flags value on both slots indicates that both images are
+permanently running.</p>
+<h3 id="image-upgrade">Image Upgrade</h3>
+<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>
+<h4 id="image-upgrade-unified">Image Upgrade - Unified</h4>
+<ol>
+<li>Upload new image to slot 1 (<code>newtmgr image upload <filename></code>).</li>
+<li>Tell device to "test out" the new image on next boot (<code>newtmgr image test <image-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make new image permanent (<code>newtmgr image confirm</code>).</li>
+</ol>
+<h4 id="image-upgrade-split">Image Upgrade - Split</h4>
+<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>
+<li>Disable split functionality; we need to deactivate the application image in
+ slot 1 (<code>newtmgr image test <current-loader-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change permanent (<code>newtmgr image confirm</code>).</li>
+<li>Upload new loader to slot 1 (<code>newtmgr image upload <filename></code>).</li>
+<li>Tell device to "test out" the new loader on next boot (<code>newtmgr image test <new-loader-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change of loader permanent (<code>newtmgr image confirm</code>).</li>
+<li>Upload new application to slot 1 (<code>newtmgr image upload <filename></code>).</li>
+<li>Tell device to "test out" the new application on next boot (<code>newtmgr image test <new-application-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change of application permanent (<code>newtmgr image confirm</code>).</li>
+</ol>
+<p>When performing this process manually, it may be helpful to use <code>image list</code> to
+check the image management state as you go.</p>
+<h2 id="syscfg">Syscfg</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>
+<h2 id="loaders">Loaders</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>
+<li>@apache-mynewt-core/apps/slinky</li>
+<li>@apache-mynewt-core/apps/bleprph</li>
+</ul>
+<h2 id="split-apps">Split Apps</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>
+<li>@apache-mynewt-core/apps/slinky</li>
+<li>@apache-mynewt-core/apps/splitty</li>
+</ul>
+<h2 id="theory-of-operation">Theory of Operation</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>.elf</code> files. It also collects all the
+possible symbols from the <code>.a</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>.elf</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 class="row">
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/latest/sitemap.xml
----------------------------------------------------------------------
diff --git a/latest/sitemap.xml b/latest/sitemap.xml
index b33136b..f74161b 100644
--- a/latest/sitemap.xml
+++ b/latest/sitemap.xml
@@ -4,7 +4,7 @@
<url>
<loc>http://mynewt.apache.org/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -13,7 +13,7 @@
<url>
<loc>http://mynewt.apache.org/pages/ble/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -22,7 +22,7 @@
<url>
<loc>http://mynewt.apache.org/quick-start/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -30,7 +30,7 @@
<url>
<loc>http://mynewt.apache.org/about/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -38,7 +38,7 @@
<url>
<loc>http://mynewt.apache.org/talks/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -46,7 +46,7 @@
<url>
<loc>http://mynewt.apache.org/download/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -54,7 +54,7 @@
<url>
<loc>http://mynewt.apache.org/community/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -62,7 +62,7 @@
<url>
<loc>http://mynewt.apache.org/events/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -71,7 +71,7 @@
<url>
<loc>http://mynewt.apache.org/os/introduction/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -83,7 +83,7 @@
<url>
<loc>http://mynewt.apache.org/os/get_started/vocabulary/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -123,13 +123,13 @@
<url>
<loc>http://mynewt.apache.org/faq/how_to_edit_docs/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://mynewt.apache.org/faq/answers/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/sitemap.xml
----------------------------------------------------------------------
diff --git a/sitemap.xml b/sitemap.xml
index 23d65a6..9558e8c 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -4,7 +4,7 @@
<url>
<loc>http://mynewt.apache.org/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -13,13 +13,13 @@
<url>
<loc>http://mynewt.apache.org/pages/ble/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://mynewt.apache.org/pages/securitybullets/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -28,7 +28,7 @@
<url>
<loc>http://mynewt.apache.org/quick-start/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -36,7 +36,7 @@
<url>
<loc>http://mynewt.apache.org/about/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -44,7 +44,7 @@
<url>
<loc>http://mynewt.apache.org/talks/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -52,7 +52,7 @@
<url>
<loc>http://mynewt.apache.org/download/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -60,7 +60,7 @@
<url>
<loc>http://mynewt.apache.org/community/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -68,7 +68,7 @@
<url>
<loc>http://mynewt.apache.org/events/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -77,7 +77,7 @@
<url>
<loc>http://mynewt.apache.org/os/introduction/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -89,7 +89,7 @@
<url>
<loc>http://mynewt.apache.org/os/get_started/vocabulary/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -129,13 +129,13 @@
<url>
<loc>http://mynewt.apache.org/faq/how_to_edit_docs/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://mynewt.apache.org/faq/answers/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/v0_9_0/sitemap.xml
----------------------------------------------------------------------
diff --git a/v0_9_0/sitemap.xml b/v0_9_0/sitemap.xml
index 23d65a6..9558e8c 100644
--- a/v0_9_0/sitemap.xml
+++ b/v0_9_0/sitemap.xml
@@ -4,7 +4,7 @@
<url>
<loc>http://mynewt.apache.org/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -13,13 +13,13 @@
<url>
<loc>http://mynewt.apache.org/pages/ble/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://mynewt.apache.org/pages/securitybullets/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -28,7 +28,7 @@
<url>
<loc>http://mynewt.apache.org/quick-start/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -36,7 +36,7 @@
<url>
<loc>http://mynewt.apache.org/about/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -44,7 +44,7 @@
<url>
<loc>http://mynewt.apache.org/talks/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -52,7 +52,7 @@
<url>
<loc>http://mynewt.apache.org/download/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -60,7 +60,7 @@
<url>
<loc>http://mynewt.apache.org/community/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -68,7 +68,7 @@
<url>
<loc>http://mynewt.apache.org/events/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -77,7 +77,7 @@
<url>
<loc>http://mynewt.apache.org/os/introduction/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -89,7 +89,7 @@
<url>
<loc>http://mynewt.apache.org/os/get_started/vocabulary/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -129,13 +129,13 @@
<url>
<loc>http://mynewt.apache.org/faq/how_to_edit_docs/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://mynewt.apache.org/faq/answers/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
[3/5] incubator-mynewt-site git commit: Split image documentation
updated
Posted by ad...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/develop/os/modules/devmgmt/newtmgr/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/devmgmt/newtmgr/index.html b/develop/os/modules/devmgmt/newtmgr/index.html
index 1663dde..91a82fd 100644
--- a/develop/os/modules/devmgmt/newtmgr/index.html
+++ b/develop/os/modules/devmgmt/newtmgr/index.html
@@ -556,7 +556,7 @@
<li>Use the <code>oicmgr</code> package if interoperability and standards-based connectivity for device interaction is your primary requirement. This package supports the OIC (Open Interconnect Consortium) Specification 1.1.0 framework from Open Connectivity Foundation (OCF). </li>
</ol>
<h3 id="invoking-newt-manager-commands">Invoking Newt Manager commands</h3>
-<p>The diagram below indicates the two options available to the application developer to issue Newt Manager commands ('newtmgr commmands<code>) on a Mynewt device. The application may leverage the</code>newtmgr<code>framework or the</code>oicmgr` framework to call the newtmgr commands. The latter is described in the next chapter.</p>
+<p>The diagram below indicates the two options available to the application developer to issue Newt Manager (<code>newtmgr</code>) commands on a Mynewt device. The application may leverage the <code>newtmgr</code> framework or the <code>oicmgr</code> framework to call the newtmgr commands. The latter is described in the next chapter.</p>
<p><img alt="Device Management" src="../device-mgmt.png" /></p>
<h3 id="newtmgr">newtmgr</h3>
<p>The newtmgr framework uses a simple request and response message format to send commands to the device. A message
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/develop/os/modules/fs/fs/fs/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/fs/fs/fs/index.html b/develop/os/modules/fs/fs/fs/index.html
index 67284b4..9bdc78b 100644
--- a/develop/os/modules/fs/fs/fs/index.html
+++ b/develop/os/modules/fs/fs/fs/index.html
@@ -612,45 +612,35 @@
<h1 id="file-system-abstraction">File System Abstraction</h1>
<p>Mynewt provides a file system abstraction layer (<code>fs/fs</code>) to allow client code to be file system agnostic. By accessing the file system via the <code>fs/fs</code> API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the <code>fs/fs</code> API rather than accessing the underlying file system directly.</p>
<h3 id="description">Description</h3>
-<p>Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the <code>fs/fs</code> package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the <strong>app</strong> package must depend on a specific file system package, while <strong>library</strong> packages should only depend on <code>fs/fs</code>.</p>
-<p>The following example illustrates how file system dependencies should be managed. In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called <code>fs/nffs</code> (Newtron Flash File System). The app explicitly initializes nffs via calls to <code>nffs_init()</code>, <code>nffs_detect()</code> and <code>nffs_format()</code>.</p>
+<p>Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the
+<code>fs/fs</code> package.
+In terms of the Mynewt hierarchy, an <strong>app</strong> package must depend on a specific file system package, while <strong>library</strong> packages should only depend on <code>fs/fs</code>.</p>
+<p>Applications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.
+In the following example, the <a href="../../nffs/nffs/"><code>Newtron Flash File System</code></a>
+is used.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># repos/apache-mynewt-core/apps/slinky/pkg.yml
pkg.name: repos/apache-mynewt-core/apps/slinky
pkg.deps:
- - fs/nffs
-
-# [...]
+ - fs/fs # include the file operations interfaces
+ - fs/nffs # include the NFFS filesystem implementation
</pre></div>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/* repos/apache-mynewt-core/apps/slinky/src/main.c */</span>
-
-<span style="color: #633820">#include "nffs/nffs.h"</span>
-
-<span style="color: #A90D91">int</span>
-<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
-{
- <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
- <span style="color: #A90D91">int</span> <span style="color: #000000">cnt</span>;
- <span style="color: #A90D91">struct</span> <span style="color: #000000">nffs_area_desc</span> <span style="color: #000000">descs</span>[<span style="color: #000000">NFFS_AREA_MAX</span>];
-
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_init</span>();
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># repos/apache-mynewt-core/apps/slinky/syscfg.yml
+# [...]
+ # Package: apps/<example app>
+# [...]
+ CONFIG_NFFS: 1 # initialize and configure NFFS into the system
+# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues
+# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect
- <span style="color: #000000">cnt</span> <span style="color: #000000">=</span> <span style="color: #000000">NFFS_AREA_MAX</span>;
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">flash_area_to_nffs_desc</span>(<span style="color: #000000">FLASH_AREA_NFFS</span>, <span style="color: #000000">&cnt</span>, <span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
- <span style="color: #A90D91">if</span> (<span style="color: #000000">nffs_detect</span>(<span style="color: #000000">descs</span>) <span style="color: #000000">==</span> <span style="color: #000000">FS_ECORRUPT</span>) {
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_format</span>(<span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
- }
- <span style="color: #177500">// [...]</span>
-}
+# [...]
</pre></div>
-<p>On the other hand, code which uses the file system after it has been initialized need only depend on <code>fs/fs</code>. For example, the <code>libs/imgmgr</code> package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the <code>fs/fs</code> package.</p>
+<p>Consult the documentation for <a href="../../nffs/nffs/"><code>nffs</code></a> for a more detailed explanation of NFFS_DETECT_FAIL</p>
+<p>Code which uses the file system after the system has been initialized need only depend on <code>fs/fs</code>. For example, the <code>libs/imgmgr</code> package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the <code>fs/fs</code> package.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># repos/apache-mynewt-core/libs/imgmgr/pkg.yml
pkg.name: libs/imgmgr
pkg.deps:
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/develop/os/modules/fs/nffs/nffs/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/fs/nffs/nffs/index.html b/develop/os/modules/fs/nffs/nffs/index.html
index 56e6c66..faee256 100644
--- a/develop/os/modules/fs/nffs/nffs/index.html
+++ b/develop/os/modules/fs/nffs/nffs/index.html
@@ -627,72 +627,19 @@
<p><strong>Regarding property 2:</strong> Furthermore, some flash hardware imposes a restriction with regards to writes: writes within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.</p>
<p>Thus, each area must comprise a discrete number of blocks.</p>
<h4 id="initialization">Initialization</h4>
-<p>Before nffs can be used, it must be initialized. There are two means of initializing an nffs file system:</p>
+<p>As part of overall system initialization, mynewt re-initialized the filesystem as follows:</p>
<ol>
-<li>Restore an existing file system via detection.</li>
-<li>Create a new file system via formatting.</li>
+<li>Restores an existing file system via detection.</li>
+<li>Creates a new file system via formatting.</li>
</ol>
<p>A typical initialization sequence is the following:</p>
<ol>
<li>Detect an nffs file system in a specific region of flash.</li>
-<li>If no file system was detected, format a new file system in the same flash region.</li>
+<li>If no file system was detected, if configured to do so, format a new file system in the same flash region.</li>
</ol>
-<p>Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of <a href="../nffs_area_desc/">struct nffs_area_desc</a>.</p>
-<p>Typically, a product's flash layout is exposed via its BSP-specific <code>bsp_flash_dev()</code> function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the <code>struct nffs_area_desc[]</code> that nffs requires. The below example, taken from the slinky project, illustrates the nffs initialization procedure.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/*** hw/hal/include/hal/flash_map.h */</span>
-
-<span style="color: #177500">/*</span>
-<span style="color: #177500"> * Flash area types</span>
-<span style="color: #177500"> */</span>
-<span style="color: #633820">#define FLASH_AREA_BOOTLOADER 0</span>
-<span style="color: #633820">#define FLASH_AREA_IMAGE_0 1</span>
-<span style="color: #633820">#define FLASH_AREA_IMAGE_1 2</span>
-<span style="color: #633820">#define FLASH_AREA_IMAGE_SCRATCH 3</span>
-<span style="color: #633820">#define FLASH_AREA_NFFS 4</span>
-</pre></div>
-
-
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/*** project/slinky/src/main.c */</span>
-
-<span style="color: #A90D91">int</span>
-<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
-{
- <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
- <span style="color: #A90D91">int</span> <span style="color: #000000">cnt</span>;
-
- <span style="color: #177500">/* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */</span>
- <span style="color: #A90D91">struct</span> <span style="color: #000000">nffs_area_desc</span> <span style="color: #000000">descs</span>[<span style="color: #000000">NFFS_AREA_MAX</span>];
-
- <span style="color: #177500">/* Initialize nffs's internal state. */</span>
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_init</span>();
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
-
- <span style="color: #177500">/* Convert the set of flash blocks we intend to use for nffs into an array</span>
-<span style="color: #177500"> * of nffs area descriptors.</span>
-<span style="color: #177500"> */</span>
- <span style="color: #000000">cnt</span> <span style="color: #000000">=</span> <span style="color: #000000">NFFS_AREA_MAX</span>;
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">flash_area_to_nffs_desc</span>(<span style="color: #000000">FLASH_AREA_NFFS</span>, <span style="color: #000000">&cnt</span>, <span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
-
- <span style="color: #177500">/* Attempt to restore an existing nffs file system from flash. */</span>
- <span style="color: #A90D91">if</span> (<span style="color: #000000">nffs_detect</span>(<span style="color: #000000">descs</span>) <span style="color: #000000">==</span> <span style="color: #000000">FS_ECORRUPT</span>) {
- <span style="color: #177500">/* No valid nffs instance detected; format a new one. */</span>
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">nffs_format</span>(<span style="color: #000000">descs</span>);
- <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
- }
- <span style="color: #177500">/* [ ... ] */</span>
-}
-</pre></div>
-
-
+<p>Note that in the latter case, the behavior is controlled with a variable in the syscfg.yml file. If NFFS_DETECT_FAIL is set to 1, the system ignores NFFS filesystem detection issues, but unless a new filesystem is formatted manually, all filesystem access will fail. If NFFS_DETECT_FAIL is set to 2, the system will format a new filesystem - note however this effectively deletes all existing data in the NFFS flash areas.</p>
+<p>Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of <a href="../nffs_area_desc/">struct nffs_area_desc</a> configured as part of the BSP configureation.</p>
<p>After nffs has been initialized, the application can access the file system via the <a href="../../fs/fs/">file system abstraction layer</a>.</p>
-<h3 id="configuration">Configuration</h3>
-<p>The nffs file system is configured by populating fields in a global <a href="../nffs_config/">struct nffs_config</a> instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs_init().</p>
-<p>The global <code>struct nffs_config</code> instance is exposed in <code>nffs/nffs.h</code> as follows:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">extern</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">nffs_config</span> <span style="color: #000000">nffs_config</span>;
-</pre></div>
-
-
<h3 id="data-structures">Data Structures</h3>
<p>The <code>fs/nffs</code> package exposes the following data structures:</p>
<table>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/develop/os/modules/split/split/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/split/split/index.html b/develop/os/modules/split/split/index.html
index 1016b14..fa8e91b 100644
--- a/develop/os/modules/split/split/index.html
+++ b/develop/os/modules/split/split/index.html
@@ -543,384 +543,435 @@
<h1 id="split-images">Split Images</h1>
<h2 id="description">Description</h2>
-<p>Split images allow the user to build the application content separate from the library content by
-splitting an application into two pieces:</p>
-<ul>
-<li>A "loader" which contains a separate application that can perform upgrades and manage split images.
-The "loader" resides in slot 1.</li>
-<li>A "split app" which contains the main application content and references the libraries in the loader
-by static linkage. The "split app" resides in slot 2.</li>
-</ul>
-<h2 id="goals">Goals</h2>
-<p>The goal of split images is to allow a larger application to run along with large components of
-mynewt such as <a href="../../../../network/ble/ble_intro/">nimble BLE stack</a> and <a href="../../fs/nffs/nffs/">neutron flash file system(nffs)</a>.</p>
+<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>
<h2 id="concept">Concept</h2>
-<p>In a typical mynewt application, an application is contained wholly within an image slot. Typically
-there are at least two image slots since the image runs from one slot while uploading new code into
-the second slot. Each image is capable of erasing and uploading another image. Each image is completely
-stand-alone; that is, each image contains all of the libraries and components that it needs.</p>
-<p>On a typical 256 kbyte flash, a flash layout might look like this:</p>
+<p>Mynewt supports three image setups:</p>
<table>
<thead>
<tr>
-<th>Name</th>
-<th>Size</th>
+<th>Setup</th>
+<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
-<td>bootloader</td>
-<td>16 k</td>
-</tr>
-<tr>
-<td>image slot 1</td>
-<td>108 k</td>
+<td>Single</td>
+<td>One large image; upgrade not supported.</td>
</tr>
<tr>
-<td>image slot 2</td>
-<td>108 k</td>
+<td>Unified</td>
+<td>Two standalone images.</td>
</tr>
<tr>
-<td>scratch</td>
-<td>8 k</td>
-</tr>
-<tr>
-<td>Flash file system</td>
-<td>16 k</td>
+<td>Split</td>
+<td>Kernel in slot 0; application in slot 1.</td>
</tr>
</tbody>
</table>
-<p>Now, suppose the desired image contains:</p>
+<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>
+<h4 id="boot-sequence-single">Boot Sequence - Single</h4>
+<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>
+<h4 id="boot-sequence-unified">Boot Sequence - Unified</h4>
+<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>
+<h4 id="boot-sequence-split">Boot Sequence - Split</h4>
+<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>
+<li>
+<p>Loader: </p>
+<ul>
+<li>Mynewt OS.</li>
+<li>Network stack for connectivity during upgrade e.g. BLE stack.</li>
+<li>Anything else required for image upgrade.</li>
+</ul>
+</li>
+<li>
+<p>Application:</p>
+<ul>
+<li>Parts of Mynewt not required for image upgrade.</li>
+<li>Application-specific code.</li>
+</ul>
+</li>
+</ol>
+<p>The loader image serves three purposes:</p>
+<ol>
+<li><em>Second-stage boot loader:</em> it jumps into the application image at
+ start up.</li>
+<li><em>Image upgrade server:</em> the user can upgrade to a new loader + application
+ combo, even if an application image is not currently running.</li>
+<li><em>Functionality container:</em> the application image can directly access all the
+ code present in the loader image</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>
+<h2 id="tutorial">Tutorial</h2>
+<h3 id="building-a-split-image">Building a Split Image</h3>
+<p>We will be referring to the nRF51dk for examples in this document. Let's take
+a look at this board's flash map (defined in <code>hw/bsp/nrf51dk/bsp.yml</code>):</p>
<table>
<thead>
<tr>
-<th>Package</th>
-<th>Size</th>
+<th>Name</th>
+<th>Offset</th>
+<th>Size (kB)</th>
</tr>
</thead>
<tbody>
<tr>
-<td>nimble</td>
-<td>69 k</td>
+<td>Boot loader</td>
+<td>0x00000000</td>
+<td>16</td>
</tr>
<tr>
-<td>os</td>
-<td>6 k</td>
+<td>Reboot log</td>
+<td>0x00004000</td>
+<td>16</td>
</tr>
<tr>
-<td>logging</td>
-<td>3 k</td>
+<td>Image slot 0</td>
+<td>0x00008000</td>
+<td>110</td>
</tr>
<tr>
-<td>imagemgr</td>
-<td>3 k</td>
+<td>Image slot 1</td>
+<td>0x00023800</td>
+<td>110</td>
</tr>
<tr>
-<td>config</td>
-<td>3 k</td>
+<td>Image scratch</td>
+<td>0x0003f000</td>
+<td>2</td>
</tr>
<tr>
-<td>nffs</td>
-<td>15 k</td>
-</tr>
-<tr>
-<td>newtmgr</td>
-<td>7 k</td>
+<td>Flash file system</td>
+<td>0x0003f800</td>
+<td>2</td>
</tr>
</tbody>
</table>
-<p>which total 106k. With an image slot size of 108k this leaves only a small amount of code space
-remaining for the application.</p>
-<p>However, we can see that these packages contain everything you need to upgrade and configure, so
-if we build a stand-alone loader with these components, we can build the app as a split image and
-get the entire second image slot to store application code and constant data.</p>
-<h2 id="when-do-i-use-split-images">When do I use split images</h2>
-<p>If your application fits into the available image slots, there is no advantage to using split
-images. In general, split images are harder to debug and more complicated to upload. However
-for a larger application, there may not be enough flash space to have two copies of the entire
-application. This is when split image becomes necessary.</p>
-<h2 id="how-do-i-tell-newt-i-am-building-a-split-image">How do I tell Newt I am building a split image?</h2>
-<p>Newt looks for the variable <code>loader</code> in your target file. If it finds <code>loader</code> variable, it
-will build a split image. For example,</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">targets/app
- app=@apache-mynewt-core/apps/splitty
- loader=@apache-mynewt-core/apps/slinky
- bsp=@apache-mynewt-core/hw/bsp/nrf52dk
+<p>The application we will be building is <a href="../../../tutorials/bleprph">bleprph</a>.
+First, we create a target to tie our BSP and application together.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">newt target create bleprph-nrf51dk
+newt target set bleprph-nrf51dk \
+ app=@apache-mynewt-core/apps/bleprph \
+ bsp=@apache-mynewt-core/hw/bsp/nrf51dk \
+ build_profile=optimized \
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
+</pre></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>target show</code> command:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt target show bleprph-nrf51dk
+targets/bleprph-nrf51dk
+ app=@apache-mynewt-core/apps/bleprph
+ bsp=@apache-mynewt-core/hw/bsp/nrf51dk
build_profile=optimized
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
-<p>shows an application called splitty which uses slinky as its loader.</p>
-<h2 id="platforms">Platforms</h2>
-<p>Split image requires BSP support. The following BSPs support split images:</p>
-<ul>
-<li>hw/bsp/arduino_primo_nrf52</li>
-<li>hw/bsp/bmd300eval</li>
-<li>hw/bsp/nrf51-blenano</li>
-<li>hw/bsp/nrf51dk</li>
-<li>hw/bsp/nrf51dk-16kbram</li>
-<li>hw/bsp/nrf52dk</li>
-</ul>
-<h2 id="loaders">Loaders</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>
-<li>@apache-mynewt-core/apps/slinky</li>
-<li>@apache-mynewt-core/apps/bleprph</li>
-</ul>
-<h2 id="split-apps">Split Apps</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 a split app image.</p>
-<ul>
-<li>@apache-mynewt-core/apps/slinky</li>
-<li>@apache-mynewt-core/apps/splitty</li>
-</ul>
-<h2 id="theory-of-operation">Theory of Operation</h2>
-<p>A split image is built as follows:</p>
-<p>First newt builds the <code>app</code> and <code>loader</code> 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 <code>app</code> and <code>loader</code> in two ways. It collects the set of
-symbols from the <code>.elf</code> files. It also collects all the possible symbols from the <code>.a</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>.elf</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>
-<h2 id="design">Design</h2>
-<h3 id="bootloader">Bootloader</h3>
-<p>The <a href="../../bootloader/bootloader/">bootloader</a> has been modified to support "non bootable" images like split app images. A flag in
-the image header denotes the image as "non-bootable". When this flag is set, the bootloader will
-not boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable,
-split app images are not.</p>
-<h3 id="newt">Newt</h3>
-<p>Newt builds a split image when the token <code>loader=@apache-mynewt-core/apps/slinky</code> is present in the target file.</p>
-<p>Newt has a <code>Builder</code> object that is responsible for building an image. This features a <code>targetBuilder</code>
-object that contains two builders (one for the app and one for the loader).</p>
-<p>The <code>Builder</code> object has been expanded to include options for building as part of a split image.
-<em> Ability to specify the linker file during the link
-</em> Ability to specify a set of keep_symbols during the link</p>
-<p>Newt commands like download, size, create-image have been expanded to perform operations twice
-(once for loader and once for app) if the loader target is present.</p>
-<p>During normal single-image builds, the <code>targetBuilder</code> initializes and builds the application
-<code>builder</code>. During the split image build, the <code>targetBuilder</code> performs the steps outlined in the
-section above using the two <code>builder</code>s for the loader and app.</p>
-<p>Special symbol and link features are designed as follows:</p>
-<ul>
-<li>Newt uses objdump to parse the symbol maps in the <code>.a</code> and <code>.elf</code> files.</li>
-<li>Newt uses the <code>--undefined=</code> option of the linker to force the loader to keep symbols used by
-the app (but not used by the linker)</li>
-<li>Newt uses objcopy with the <code>-K</code> (keep) option when building the special linker <code>.elf</code>.</li>
-<li>Newt uses the <code>--just-symbols</code> option of the linker to link against the loader <code>.elf</code> file.</li>
-</ul>
-<h4 id="newt-create-image">newt create-image</h4>
-<p><code>create-image</code> uses two different methods to compute the image hash for standard and split images.<br />
-For split images, the hash is computed starting with the 32-byte hash of the loader, then continuing
-with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically.</p>
-<h4 id="newt-errors">newt errors</h4>
-<p>Newt has several new build errors when building split images.</p>
-<ul>
-<li>Linker script undefined. If the BSP for your application does not define a split image linker script
-the build will fail.</li>
-</ul>
-<p>If newt finds that the same library (for example libs/os) has a different implementaiton in the loader
-and app, it will generate an error and fail to build. These differences can arise when <code>#ifdef</code> or features
-are included in one app and not the other. For example, it the loader includes <code>libs/console/stubs</code> and the
-app includes <code>libs/console/full</code> this may change implementations of certain functions within other packages.</p>
-<h3 id="image-manifest">Image manifest</h3>
-<p>newt builds a single manifest for split images, adding extra tags to the manifest when the image is a split image.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> "loader": "slinky.img",
- "loader_hash": "55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0",
- "loader_pkgs": [
- ...
- ]
+<p>Next, build the target:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt build bleprph-nrf51dk
+Building target targets/bleprph-nrf51dk
+# [...]
+Target successfully built: targets/bleprph-nrf51dk
</pre></div>
-<p>The manifest lists packages in both the loader and app. The app package list only contains those
-packages that reside in the app image itself.</p>
-<h3 id="libsbootutil">libs/bootutil</h3>
-<p>Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies
-that it matches the loader image in slot 1 and then fetches the entry information for the split app.</p>
-<h3 id="libssplit">libs/split</h3>
-<p>A small split image library was created to provide newtmgr commands for split image and to hold the
-configuration for split image. See newtmgr below for details.</p>
-<p>It also contains the function used by a loader to validate and boot a split image.</p>
-<h3 id="appsslinky">apps/slinky</h3>
-<p>A sample app that can be built as a split image with slinky.</p>
-<h2 id="tips-when-building-split-images">Tips when Building Split images</h2>
-<p><strong>To be added</strong></p>
-<h2 id="adding-bsp-support-for-split-images">Adding BSP support for split images</h2>
-<p>A BSP needs additional components to be "split image ready".</p>
-<p>The split image requires a special linker script. The split image needs to run from the second image
-partition (since it's using the loader library that is linked to be placed in the first partition).<br />
-It needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it).</p>
-<p>The startup of the split image is different than a typical image. It needs to copy <code>.data</code> from the
-loader image, and zero the loader image bss. For this, it must reference symbols defined in the linker
-script of the loader. It has a special entry symbol that differentiates it from the entry symbol in the
-loader application.</p>
-<p>Several of the bsp scripts need to handle additional agruments to deal with the two images produced
-by newt when building split images - mainly download and debug.</p>
-<p>Add the following components to enable your BSP for split images:</p>
-<ol>
-<li>A split image linker file</li>
-<li>A startup file for the split image</li>
-<li>A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as <code>pkg.part2linkerscript: "split-nrf52dk.ld</code> for example.</li>
-<li>Modified download script</li>
-<li>Modified sbrk functionality</li>
-</ol>
-<p>An example can be found in the <code>/hw/bsp/nrf52dk</code></p>
-<h3 id="split-image-linker-script">split image linker script</h3>
-<p>The split image linker script must have the following.</p>
-<p>The split linker must be linked to run from the second flash image slot. For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">MEMORY</span>
-{
- <span style="color: #000000">FLASH</span> (<span style="color: #000000">rx</span>) <span style="color: #000000">:</span> <span style="color: #000000">ORIGIN</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x00042000</span>, <span style="color: #000000">LENGTH</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x3a000</span>
- <span style="color: #000000">RAM</span> (<span style="color: #000000">rwx</span>) <span style="color: #000000">:</span> <span style="color: #000000">ORIGIN</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x20000000</span>, <span style="color: #000000">LENGTH</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x10000</span>
-}
+<p>With our target built, we can view a code size breakdown using the <code>newt size <target></code> command. In the interest of brevity, the smaller entries are excluded from the below output:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
-<p>The split linker must define the entry symbol as Reset_Handler_split. For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">ENTRY</span>(<span style="color: #000000">Reset_Handler_split</span>)
+<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>loader</code> variable. In our example, we are
+going to use <code>bleprph</code> as the loader, and <code>splitty</code> as the application.
+<code>bleprph</code> makes sense as a loader because it contains the BLE stack and
+everything else required for an image upgrade.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">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/nrf51dk \
+ build_profile=optimized \
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
-<p>The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional
-vector entries are part of the loader and are not needed in the split image. The bootloader accesses these
-entries at the beginning of the image slot (first 2 words). For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> .text :
- {
- __split_isr_vector_start = .;
- KEEP(*(.isr_vector_split))
- __split_isr_vector_end = .;
- ...
- }
+<p>Verify that the target looks correct:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt target show split-nrf51dk
+targets/split-nrf51dk
+ app=@apache-mynewt-core/apps/splitty
+ bsp=@apache-mynewt-core/hw/bsp/nrf51dk
+ build_profile=optimized
+ loader=@apache-mynewt-core/apps/bleprph
+ syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0
</pre></div>
-<p>The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are
-both using RAM). Note, the two apps don't run at the same time, but the loader has global data that its
-libraries use. This cannot be overwritten by the application. An example linker section that accomplishes
-this can be found in <code>/hw/bsp/nrf52dk/split-nrf52dk.ld</code>. When linking against the loader, the loader exports
-the following symbosl which can be used by the split app code:</p>
-<ul>
-<li><code>__HeapBase_loader</code></li>
-<li><code>__bss_start___loader</code></li>
-<li><code>__bss_end___loader</code></li>
-<li><code>__etext_loader</code></li>
-<li><code>__data_start___loader</code></li>
-<li><code>__data_end___loader</code></li>
-</ul>
-<p>The split app linker can use <code>__HeapBase_loader</code> to skip RAM used by the loader as follows.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #177500">/* save RAM used by the split image. This assumes that</span>
-<span style="color: #177500"> * the loader uses all the RAM up to its HeapBase */</span>
- .<span style="color: #000000">loader_ram_contents</span> :
- {
- <span style="color: #000000">_loader_ram_start</span> <span style="color: #000000">=</span> .;
-
- <span style="color: #177500">/* this symbol comes from the loader linker */</span>
- . <span style="color: #000000">=</span> . <span style="color: #000000">+</span> (<span style="color: #000000">ABSOLUTE</span>(<span style="color: #000000">__HeapBase_loader</span>) <span style="color: #000000">-</span> <span style="color: #000000">_loader_ram_start</span>);
- <span style="color: #000000">_loader_ram_end</span> <span style="color: #000000">=</span> .;
- } <span style="color: #000000">></span> <span style="color: #000000">RAM</span>
+<p>Now, let's build the new target:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/tmp/myproj2]$ newt build split-nrf51dk
+Building target targets/split-nrf51dk
+# [...]
+Target successfully built: targets/split-nrf51dk
</pre></div>
-<h3 id="split-image-startup-code">split image startup code</h3>
-<p>The split application needs separate startup code to intialize the split image before running main. The
-split image is specially linked so that <code>_start</code> and <code>main</code> are included individually for the loader and split app.</p>
-<p>The split app startup code must have the following.</p>
-<ol>
-<li>A definition of the split image vector table (first two words).</li>
-<li>The entry point function to start the code <code>Reset_Handler_split</code></li>
-<li>Code that copies the <code>.data</code> section for the loader from Flash to RAM</li>
-<li>Code that zeros the <code>.bss</code> section for the loader.</li>
-<li>Code that calls <code>_sbrkInit</code> to set the heap pointers for the application (see below)</li>
-<li>Code that calls the <code>bsp_slot_init_split_application</code> function (see below)</li>
-</ol>
-<p>An example can be found in the <code>/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s</code></p>
-<h3 id="download-script">Download script</h3>
-<p>The download script needs to be modified to include support for passing the image slot number in the build.<br />
-Image slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers.</p>
-<p>See and example in <code>/hw/bsp/bmd300eval/bmd300eval_download.sh</code>.</p>
-<h3 id="sbrk-functionality">Sbrk functionality</h3>
-<p>Split image (either a loader or app) references a single set of heap managment functions. But the heap location and
-size is different depending which image is running. Special functionality is needed to handle the dynamic
-setting of the heap base and limit.</p>
-<p>Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk
-needs to be dynamically initialized with these values from the startup code.</p>
-<p>See an example in <code>/hw/bsp/bmd300eval/src/sbrk.c</code> in the core repository. The function <code>_sbrkInit</code> must be
-called from the startup code of the split image and normal image startup code with the appropriate
-values of heap base and limit.</p>
-<h3 id="slot-init">Slot Init</h3>
-<p>A global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as
-the combined loader/app image. Its the responsibility of the startup code to set this global variable.</p>
-<p>See <code>hw/bsp/bmd300eval/src/os_bsp.c</code> for and implementation of the functionality.</p>
-<h2 id="newtmgr-and-split-images">newtmgr and split Images</h2>
-<p>newtmgr has support for split images.</p>
-<p><code>newtmgr image list</code> lists the current images in the flash. Its clear from the output that some images are non-bootable. For example.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Images:
- slot=1
- version=1.2.3
- bootable=true
- hash=55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0
- slot=2
- version=1.2.3
- bootable=false
- hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe
+<p>And look at the size breakdown (again, smaller entries are removed):</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
-<p>The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the <code>boot2</code>
-command to instruct mynewt to boot slot 2.</p>
-<p>Instead, use the new <code>split status</code> command to see the status of split images and to set their boot status.<br />
-The split status command with no arguments returns status of the split image. The Split Value tells the loader
-how to boot the split app. Options are:</p>
-<ul>
-<li><code>none</code> Don't boot the split application. Just remain running in the loader.</li>
-<li><code>test</code> Boot the split application, but revert back to the loader on the next reset.</li>
-<li><code>run</code> Boot the split application.</li>
-</ul>
-<p>The split status command also verified the hash of the split application (using the hash of the loader
-as shown above) and returns the status of the check (matching or non-matching).</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">newtmgr -c connection split status
- Split value is none
- Split status is matching
+<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 nRF51dk board. The procedure here
+is the same as if we were using the Unified setup, i.e., via either the <code>newt load</code> or <code>newt run</code> command.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/repos/mynewt/core]$ newt load split-nrf51dk 0
+Loading app image into slot 2
+Loading loader image into slot 1
</pre></div>
-<p>When the split image application is running, the active hash in the <code>boot2</code> command will match the
-hash of the split application (in slot 2). For example:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">prompt$ newtmgr -c foo1 image boot
- Test image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0
- Main image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0
- Active img: 1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe
+<h3 id="image-management">Image Management</h3>
+<h4 id="retrieve-current-state-image-list">Retrieve Current State (image list)</h4>
+<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>newtmgr image list</code> command. Here is how a device responds to this command
+after our loader + application combo has been deployed:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
-<h2 id="upgrading-a-split-image-with-newtmgr">Upgrading a split image with newtmgr</h2>
-<p>When running via newt, the <code>newt load</code> command will load both parts of a split image, the loader and application.</p>
-<p>When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the
-split app in <code>run</code> mode the following sequence will upgrade</p>
+<p>There are several interesting things about this response:</p>
<ol>
-<li>newtmgr split status none</li>
-<li>newtmgr reboot</li>
-<li>newtmgr image upload <filename of new loader></li>
-<li>newtmgr image boot2 <hash of new loader></li>
-<li>newtmgr reboot</li>
-<li>newtmgr image upload <filename of new split app></li>
-<li>newtmgr split status test</li>
-<li>newtmgr reboot</li>
-<li>newtmgr boot2 (check status to ensure new app is running)</li>
-<li>newtmgr split status run</li>
+<li><em>Two images:</em> This is expected; we deployed both a loader image and an
+application image.</li>
+<li><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.</li>
+<li><em>flags:</em> Slot 0 is <code>active</code> and <code>confirmed</code>; none of slot 1's flags are set.
+The <code>active</code> flag indicates that the image is currently running; the
+<code>confirmed</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.</li>
+<li><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>newt</code>. If the loader and
+application are not compatible, the loader will not boot into the application.</li>
</ol>
-<p>This upgrade is robust. In all steps there is a loader image that is capable of upgrading (or reverting) images.</p>
+<h3 id="enabling-a-split-application">Enabling a Split Application</h3>
+<p>By default, the application image in slot 1 is disabled. This is indicated in
+the <code>image list</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>
+<li>Tell device to "test out" the application image on next boot (<code>newtmgr image test <application-image-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change permanent (<code>newtmgr image confirm</code>).</li>
+</ol>
+<p>After the above sequence, a <code>newtmgr image list</code> command elicits the following response:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">[~/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>
+
+
+<p>The <code>active confirmed</code> flags value on both slots indicates that both images are
+permanently running.</p>
+<h3 id="image-upgrade">Image Upgrade</h3>
+<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>
+<h4 id="image-upgrade-unified">Image Upgrade - Unified</h4>
+<ol>
+<li>Upload new image to slot 1 (<code>newtmgr image upload <filename></code>).</li>
+<li>Tell device to "test out" the new image on next boot (<code>newtmgr image test <image-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make new image permanent (<code>newtmgr image confirm</code>).</li>
+</ol>
+<h4 id="image-upgrade-split">Image Upgrade - Split</h4>
+<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>
+<li>Disable split functionality; we need to deactivate the application image in
+ slot 1 (<code>newtmgr image test <current-loader-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change permanent (<code>newtmgr image confirm</code>).</li>
+<li>Upload new loader to slot 1 (<code>newtmgr image upload <filename></code>).</li>
+<li>Tell device to "test out" the new loader on next boot (<code>newtmgr image test <new-loader-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change of loader permanent (<code>newtmgr image confirm</code>).</li>
+<li>Upload new application to slot 1 (<code>newtmgr image upload <filename></code>).</li>
+<li>Tell device to "test out" the new application on next boot (<code>newtmgr image test <new-application-hash></code>).</li>
+<li>Reboot device (<code>newtmgr reset</code>).</li>
+<li>Make above change of application permanent (<code>newtmgr image confirm</code>).</li>
+</ol>
+<p>When performing this process manually, it may be helpful to use <code>image list</code> to
+check the image management state as you go.</p>
+<h2 id="syscfg">Syscfg</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>
+<h2 id="loaders">Loaders</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>
+<li>@apache-mynewt-core/apps/slinky</li>
+<li>@apache-mynewt-core/apps/bleprph</li>
+</ul>
+<h2 id="split-apps">Split Apps</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>
+<li>@apache-mynewt-core/apps/slinky</li>
+<li>@apache-mynewt-core/apps/splitty</li>
+</ul>
+<h2 id="theory-of-operation">Theory of Operation</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>.elf</code> files. It also collects all the
+possible symbols from the <code>.a</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>.elf</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 class="row">
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/develop/sitemap.xml
----------------------------------------------------------------------
diff --git a/develop/sitemap.xml b/develop/sitemap.xml
index b33136b..f74161b 100644
--- a/develop/sitemap.xml
+++ b/develop/sitemap.xml
@@ -4,7 +4,7 @@
<url>
<loc>http://mynewt.apache.org/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -13,7 +13,7 @@
<url>
<loc>http://mynewt.apache.org/pages/ble/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -22,7 +22,7 @@
<url>
<loc>http://mynewt.apache.org/quick-start/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -30,7 +30,7 @@
<url>
<loc>http://mynewt.apache.org/about/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -38,7 +38,7 @@
<url>
<loc>http://mynewt.apache.org/talks/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -46,7 +46,7 @@
<url>
<loc>http://mynewt.apache.org/download/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -54,7 +54,7 @@
<url>
<loc>http://mynewt.apache.org/community/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -62,7 +62,7 @@
<url>
<loc>http://mynewt.apache.org/events/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -71,7 +71,7 @@
<url>
<loc>http://mynewt.apache.org/os/introduction/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -83,7 +83,7 @@
<url>
<loc>http://mynewt.apache.org/os/get_started/vocabulary/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
@@ -123,13 +123,13 @@
<url>
<loc>http://mynewt.apache.org/faq/how_to_edit_docs/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://mynewt.apache.org/faq/answers/</loc>
- <lastmod>2017-01-06</lastmod>
+ <lastmod>2017-01-11</lastmod>
<changefreq>daily</changefreq>
</url>
[4/5] incubator-mynewt-site git commit: Split image documentation
updated
Posted by ad...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/develop/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json
index e12bf10..8c7d2ba 100644
--- a/develop/mkdocs/search_index.json
+++ b/develop/mkdocs/search_index.json
@@ -5052,7 +5052,7 @@
},
{
"location": "/os/modules/split/split/",
- "text": "Split Images\n\n\nDescription\n\n\nSplit images allow the user to build the application content separate from the library content by \nsplitting an application into two pieces:\n\n\n\n\nA \"loader\" which contains a separate application that can perform upgrades and manage split images. \nThe \"loader\" resides in slot 1.\n\n\nA \"split app\" which contains the main application content and references the libraries in the loader \nby static linkage. The \"split app\" resides in slot 2.\n\n\n\n\nGoals\n\n\nThe goal of split images is to allow a larger application to run along with large components of \nmynewt such as \nnimble BLE stack\n and \nneutron flash file system(nffs)\n.\n\n\nConcept\n\n\nIn a typical mynewt application, an application is contained wholly within an image slot. Typically \nthere are at least two image slots since the image runs from one slot while uploading new code into \nthe second slot. Each image is capable of erasing and uploading ano
ther image. Each image is completely \nstand-alone; that is, each image contains all of the libraries and components that it needs.\n\n\nOn a typical 256 kbyte flash, a flash layout might look like this:\n\n\n\n\n\n\n\n\nName\n\n\nSize\n\n\n\n\n\n\n\n\n\n\nbootloader\n\n\n16 k\n\n\n\n\n\n\nimage slot 1\n\n\n108 k\n\n\n\n\n\n\nimage slot 2\n\n\n108 k\n\n\n\n\n\n\nscratch\n\n\n8 k\n\n\n\n\n\n\nFlash file system\n\n\n16 k\n\n\n\n\n\n\n\n\nNow, suppose the desired image contains:\n\n\n\n\n\n\n\n\nPackage\n\n\nSize\n\n\n\n\n\n\n\n\n\n\nnimble\n\n\n69 k\n\n\n\n\n\n\nos\n\n\n6 k\n\n\n\n\n\n\nlogging\n\n\n3 k\n\n\n\n\n\n\nimagemgr\n\n\n3 k\n\n\n\n\n\n\nconfig\n\n\n3 k\n\n\n\n\n\n\nnffs\n\n\n15 k\n\n\n\n\n\n\nnewtmgr\n\n\n7 k\n\n\n\n\n\n\n\n\nwhich total 106k. With an image slot size of 108k this leaves only a small amount of code space \nremaining for the application.\n\n\nHowever, we can see that these packages contain everything you need to upgrade and configure, so \nif we build a stan
d-alone loader with these components, we can build the app as a split image and \nget the entire second image slot to store application code and constant data.\n\n\nWhen do I use split images\n\n\nIf your application fits into the available image slots, there is no advantage to using split \nimages. In general, split images are harder to debug and more complicated to upload. However \nfor a larger application, there may not be enough flash space to have two copies of the entire \napplication. This is when split image becomes necessary.\n\n\nHow do I tell Newt I am building a split image?\n\n\nNewt looks for the variable \nloader\n in your target file. If it finds \nloader\n variable, it \nwill build a split image. For example,\n\n\ntargets/app\n app=@apache-mynewt-core/apps/splitty\n loader=@apache-mynewt-core/apps/slinky\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\nshows an application called splitty which uses slinky as its loader.\n\
n\nPlatforms\n\n\nSplit image requires BSP support. The following BSPs support split images:\n\n\n\n\nhw/bsp/arduino_primo_nrf52\n\n\nhw/bsp/bmd300eval\n\n\nhw/bsp/nrf51-blenano\n\n\nhw/bsp/nrf51dk\n\n\nhw/bsp/nrf51dk-16kbram\n\n\nhw/bsp/nrf52dk\n\n\n\n\nLoaders\n\n\nThe following applications have been enabled as loaders. You may choose to build your own loader \napplication, and these can serve as samples.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/bleprph\n\n\n\n\nSplit Apps\n\n\nThe following applications have been enabled as split applications. If you choose to build your own \nsplit application these can serve as samples. Note that slinky can be either a loader image or a split app image.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/splitty\n\n\n\n\nTheory of Operation\n\n\nA split image is built as follows:\n\n\nFirst newt builds the \napp\n and \nloader\n images separately to ensure they are consistent (no errors) and \n
to generate elf files which can inform newt of the symbols used by each part.\n\n\nThen newt collects the symbols used by both \napp\n and \nloader\n in two ways. It collects the set of \nsymbols from the \n.elf\n files. It also collects all the possible symbols from the \n.a\n files for \neach application.\n\n\nNewt builds the set of packages that the two applications share. It ensures that all the symbols \nused in those packages are matching. NOTE: because of features and #ifdefs, its possible for the \ntwo package to have symbols that are not the same. In this case newt generates an error and will \nnot build a split image.\n\n\nThen newt creates the list of symbols that the two applications share from those packages (using the .elf files).\n\n\nNewt re-links the loader to ensure all of these symbols are present in the loader application (by \nforcing the linker to include them in the \n.elf\n).\n\n\nNewt builds a special copy of the loader.elf with only these symbols (and t
he handful of symbols \ndiscussed in the linking section above).\n\n\nFinally, newt links the application, replacing the common .a libraries with the special loader.elf \nimage during the link.\n\n\nDesign\n\n\nBootloader\n\n\nThe \nbootloader\n has been modified to support \"non bootable\" images like split app images. A flag in \nthe image header denotes the image as \"non-bootable\". When this flag is set, the bootloader will \nnot boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, \nsplit app images are not.\n\n\nNewt\n\n\nNewt builds a split image when the token \nloader=@apache-mynewt-core/apps/slinky\n is present in the target file.\n\n\nNewt has a \nBuilder\n object that is responsible for building an image. This features a \ntargetBuilder\n \nobject that contains two builders (one for the app and one for the loader).\n\n\nThe \nBuilder\n object has been expanded to include options for building as part of a split image.\n\n Ab
ility to specify the linker file during the link\n\n Ability to specify a set of keep_symbols during the link\n\n\nNewt commands like download, size, create-image have been expanded to perform operations twice \n(once for loader and once for app) if the loader target is present.\n\n\nDuring normal single-image builds, the \ntargetBuilder\n initializes and builds the application \n\nbuilder\n. During the split image build, the \ntargetBuilder\n performs the steps outlined in the \nsection above using the two \nbuilder\ns for the loader and app.\n\n\nSpecial symbol and link features are designed as follows:\n\n\n\n\nNewt uses objdump to parse the symbol maps in the \n.a\n and \n.elf\n files.\n\n\nNewt uses the \n--undefined=\n option of the linker to force the loader to keep symbols used by \nthe app (but not used by the linker)\n\n\nNewt uses objcopy with the \n-K\n (keep) option when building the special linker \n.elf\n.\n\n\nNewt uses the \n--just-symbols\n option of the linker to
link against the loader \n.elf\n file.\n\n\n\n\nnewt create-image\n\n\ncreate-image\n uses two different methods to compute the image hash for standard and split images.\n\nFor split images, the hash is computed starting with the 32-byte hash of the loader, then continuing \nwith the hashing algorithm used by the standard application. This ensures that the split app can be \"validated\" against a loader image specifically.\n\n\nnewt errors\n\n\nNewt has several new build errors when building split images.\n\n\n\n\nLinker script undefined. If the BSP for your application does not define a split image linker script \nthe build will fail.\n\n\n\n\nIf newt finds that the same library (for example libs/os) has a different implementaiton in the loader \nand app, it will generate an error and fail to build. These differences can arise when \n#ifdef\n or features \nare included in one app and not the other. For example, it the loader includes \nlibs/console/stubs\n and the \napp include
s \nlibs/console/full\n this may change implementations of certain functions within other packages.\n\n\nImage manifest\n\n\nnewt builds a single manifest for split images, adding extra tags to the manifest when the image is a split image.\n\n\n \nloader\n: \nslinky.img\n,\n \nloader_hash\n: \n55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n,\n \nloader_pkgs\n: [\n ...\n ]\n\n\n\n\n\nThe manifest lists packages in both the loader and app. The app package list only contains those \npackages that reside in the app image itself.\n\n\nlibs/bootutil\n\n\nBootutil has been expanded to include a function that looks for a split app image in slot 2, verifies \nthat it matches the loader image in slot 1 and then fetches the entry information for the split app.\n\n\nlibs/split\n\n\nA small split image library was created to provide newtmgr commands for split image and to hold the \nconfiguration for split image. See newtmgr below for details.\n\n\nIt also
contains the function used by a loader to validate and boot a split image.\n\n\napps/slinky\n\n\nA sample app that can be built as a split image with slinky.\n\n\nTips when Building Split images\n\n\nTo be added\n\n\nAdding BSP support for split images\n\n\nA BSP needs additional components to be \"split image ready\".\n\n\nThe split image requires a special linker script. The split image needs to run from the second image \npartition (since it's using the loader library that is linked to be placed in the first partition).\n\nIt needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it).\n\n\nThe startup of the split image is different than a typical image. It needs to copy \n.data\n from the \nloader image, and zero the loader image bss. For this, it must reference symbols defined in the linker \nscript of the loader. It has a special entry symbol that differentiates it from the entry symbol in the \nloader application
.\n\n\nSeveral of the bsp scripts need to handle additional agruments to deal with the two images produced \nby newt when building split images - mainly download and debug.\n\n\nAdd the following components to enable your BSP for split images:\n\n\n\n\nA split image linker file\n\n\nA startup file for the split image\n\n\nA property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as \npkg.part2linkerscript: \"split-nrf52dk.ld\n for example.\n\n\nModified download script\n\n\nModified sbrk functionality\n\n\n\n\nAn example can be found in the \n/hw/bsp/nrf52dk\n\n\nsplit image linker script\n\n\nThe split image linker script must have the following.\n\n\nThe split linker must be linked to run from the second flash image slot. For example:\n\n\nMEMORY\n\n{\n \nFLASH\n (\nrx\n) \n:\n \nORIGIN\n \n=\n \n0x00042000\n, \nLENGTH\n \n=\n \n0x3a000\n\n \nRAM\n (\nrwx\n) \n:\n \nORIGIN\n \n=\n \n0x20000000\n, \nLENGTH\n \n=\n \n0
x10000\n\n}\n\n\n\n\n\nThe split linker must define the entry symbol as Reset_Handler_split. For example:\n\n\nENTRY\n(\nReset_Handler_split\n)\n\n\n\n\n\nThe split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional \nvector entries are part of the loader and are not needed in the split image. The bootloader accesses these \nentries at the beginning of the image slot (first 2 words). For example:\n\n\n .text :\n {\n __split_isr_vector_start = .;\n KEEP(*(.isr_vector_split))\n __split_isr_vector_end = .;\n ... \n } \n\n\n\n\n\nThe split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are \nboth using RAM). Note, the two apps don't run at the same time, but the loader has global data that its \nlibraries use. This cannot be overwritten by the application. An example linker section that accomplishes \nthis can be found in \n/hw/bsp/nrf52dk/split-nr
f52dk.ld\n. When linking against the loader, the loader exports \nthe following symbosl which can be used by the split app code:\n\n\n\n\n__HeapBase_loader\n\n\n__bss_start___loader\n\n\n__bss_end___loader\n\n\n__etext_loader\n\n\n__data_start___loader\n\n\n__data_end___loader\n\n\n\n\nThe split app linker can use \n__HeapBase_loader\n to skip RAM used by the loader as follows.\n\n\n \n/* save RAM used by the split image. This assumes that\n\n\n * the loader uses all the RAM up to its HeapBase */\n\n .\nloader_ram_contents\n :\n {\n \n_loader_ram_start\n \n=\n .;\n\n \n/* this symbol comes from the loader linker */\n\n . \n=\n . \n+\n (\nABSOLUTE\n(\n__HeapBase_loader\n) \n-\n \n_loader_ram_start\n);\n \n_loader_ram_end\n \n=\n .;\n } \n \nRAM\n\n\n\n\n\n\nsplit image startup code\n\n\nThe split application needs separate startup code to intialize the split image before running main. The \nsplit image is specially linked so that \n_start\n and \
nmain\n are included individually for the loader and split app.\n\n\nThe split app startup code must have the following.\n\n\n\n\nA definition of the split image vector table (first two words).\n\n\nThe entry point function to start the code \nReset_Handler_split\n\n\nCode that copies the \n.data\n section for the loader from Flash to RAM\n\n\nCode that zeros the \n.bss\n section for the loader.\n\n\nCode that calls \n_sbrkInit\n to set the heap pointers for the application (see below)\n\n\nCode that calls the \nbsp_slot_init_split_application\n function (see below)\n\n\n\n\nAn example can be found in the \n/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s\n\n\nDownload script\n\n\nThe download script needs to be modified to include support for passing the image slot number in the build.\n\nImage slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers.\n\n\nSee and example in \n/hw/bsp/bmd300eval/bmd300eval_download.sh\n.\n\n\nSbrk functionality
\n\n\nSplit image (either a loader or app) references a single set of heap managment functions. But the heap location and \nsize is different depending which image is running. Special functionality is needed to handle the dynamic \nsetting of the heap base and limit.\n\n\nInstead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk \nneeds to be dynamically initialized with these values from the startup code.\n\n\nSee an example in \n/hw/bsp/bmd300eval/src/sbrk.c\n in the core repository. The function \n_sbrkInit\n must be \ncalled from the startup code of the split image and normal image startup code with the appropriate \nvalues of heap base and limit.\n\n\nSlot Init\n\n\nA global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as \nthe combined loader/app image. Its the responsibility of the startup code to set this global variable.\n\n\nSee \nhw/bsp/bmd300eval/src/os_bsp.c\n for and imple
mentation of the functionality.\n\n\nnewtmgr and split Images\n\n\nnewtmgr has support for split images.\n\n\nnewtmgr image list\n lists the current images in the flash. Its clear from the output that some images are non-bootable. For example.\n\n\nImages:\n slot=1\n version=1.2.3\n bootable=true\n hash=55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n slot=2\n version=1.2.3\n bootable=false\n hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe\n\n\n\n\n\nThe bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the \nboot2\n \ncommand to instruct mynewt to boot slot 2.\n\n\nInstead, use the new \nsplit status\n command to see the status of split images and to set their boot status.\n\nThe split status command with no arguments returns status of the split image. The Split Value tells the loader \nhow to boot the split app. Options are:\n\n\n\n\nnone\n Don't boot the split applica
tion. Just remain running in the loader.\n\n\ntest\n Boot the split application, but revert back to the loader on the next reset.\n\n\nrun\n Boot the split application.\n\n\n\n\nThe split status command also verified the hash of the split application (using the hash of the loader \nas shown above) and returns the status of the check (matching or non-matching).\n\n\nnewtmgr -c connection split status\n Split value is none\n Split status is matching\n\n\n\n\n\nWhen the split image application is running, the active hash in the \nboot2\n command will match the \nhash of the split application (in slot 2). For example:\n\n\nprompt$ newtmgr -c foo1 image boot\n Test image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Main image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Active img: 1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe\n\n\n\n\n\nUpgrading a split image with newtmgr\n\n\nWhen running via newt, the \nnewt loa
d\n command will load both parts of a split image, the loader and application.\n\n\nWhen running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the \nsplit app in \nrun\n mode the following sequence will upgrade\n\n\n\n\nnewtmgr split status none\n\n\nnewtmgr reboot\n\n\nnewtmgr image upload \n\n\nnewtmgr image boot2 \n\n\nnewtmgr reboot\n\n\nnewtmgr image upload \n\n\nnewtmgr split status test\n\n\nnewtmgr reboot\n\n\nnewtmgr boot2 (check status to ensure new app is running)\n\n\nnewtmgr split status run\n\n\n\n\nThis upgrade is robust. In all steps there is a loader image that is capable of upgrading (or reverting) images.",
+ "text": "Split Images\n\n\nDescription\n\n\nThe split image mechanism divides a target into two separate images: one\ncapable of image upgrade; the other containing application code. By isolating\nupgrade functionality to a separate image, the application can support\nover-the-air upgrade without dedicating flash space to network stack and\nmanagement code. \n\n\nConcept\n\n\nMynewt supports three image setups:\n\n\n\n\n\n\n\n\nSetup\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nSingle\n\n\nOne large image; upgrade not supported.\n\n\n\n\n\n\nUnified\n\n\nTwo standalone images.\n\n\n\n\n\n\nSplit\n\n\nKernel in slot 0; application in slot 1.\n\n\n\n\n\n\n\n\nEach setup has its tradeoffs. The Single setup gives you the most flash space,\nbut doesn't allow you to upgrade after manufacturing. The Unified setup allows\nfor a complete failover in case a bad image gets uploaded, but requires a lot\nof redundancy in each image, limiting the amount of flash available to the\napplicat
ion. The Split setup sits somewhere between these two options.\n\n\nBefore exploring the split setup in more detail, it might be helpful to get a\nbasic understanding of the Mynewt boot sequence. The boot process is\nsummarized below.\n\n\nBoot Sequence - Single\n\n\nIn the Single setup, there is no boot loader. Instead, the image is placed at\naddress 0. The hardware boots directly into the image code. Upgrade is not\npossible because there is no boot loader to move an alternate image into place.\n\n\nBoot Sequence - Unified\n\n\nIn the Unified setup, the boot loader is placed at address 0. At startup, the\nboot loader arranges for the correct image to be in image slot 0, which may\nentail swapping the contents of the two image slots. Finally, the boot loader\njumps to the image in slot 0.\n\n\nBoot Sequence - Split\n\n\nThe Split setup differs from the other setups mainly in that a target is not\nfully contained in a single image. Rather, the target is partitioned among tw
o\nseparate images: the \nloader\n, and the \napplication\n. Functionality is divided\namong these two images as follows:\n\n\n\n\n\n\nLoader: \n\n\n\n\nMynewt OS.\n\n\nNetwork stack for connectivity during upgrade e.g. BLE stack.\n\n\nAnything else required for image upgrade.\n\n\n\n\n\n\n\n\nApplication:\n\n\n\n\nParts of Mynewt not required for image upgrade.\n\n\nApplication-specific code.\n\n\n\n\n\n\n\n\nThe loader image serves three purposes:\n\n\n\n\nSecond-stage boot loader:\n it jumps into the application image at\n start up.\n\n\nImage upgrade server:\n the user can upgrade to a new loader + application\n combo, even if an application image is not currently running.\n\n\nFunctionality container:\n the application image can directly access all the\n code present in the loader image\n\n\n\n\nFrom the perspective of the boot loader, a loader image is identical to a plain\nunified image. What makes a loader image different is a change to its start up\nsequence: rather
than starting the Mynewt OS, it jumps to the application image\nin slot 1 if one is present.\n\n\nTutorial\n\n\nBuilding a Split Image\n\n\nWe will be referring to the nRF51dk for examples in this document. Let's take\na look at this board's flash map (defined in \nhw/bsp/nrf51dk/bsp.yml\n):\n\n\n\n\n\n\n\n\nName\n\n\nOffset\n\n\nSize (kB)\n\n\n\n\n\n\n\n\n\n\nBoot loader\n\n\n0x00000000\n\n\n16\n\n\n\n\n\n\nReboot log\n\n\n0x00004000\n\n\n16\n\n\n\n\n\n\nImage slot 0\n\n\n0x00008000\n\n\n110\n\n\n\n\n\n\nImage slot 1\n\n\n0x00023800\n\n\n110\n\n\n\n\n\n\nImage scratch\n\n\n0x0003f000\n\n\n2\n\n\n\n\n\n\nFlash file system\n\n\n0x0003f800\n\n\n2\n\n\n\n\n\n\n\n\nThe application we will be building is \nbleprph\n.\nFirst, we create a target to tie our BSP and application together.\n\n\nnewt target create bleprph-nrf51dk\nnewt target set bleprph-nrf51dk \\\n app=@apache-mynewt-core/apps/bleprph \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk
\\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nThe two syscfg settings disable bluetooth security and keep the code size down.\n\n\nWe can verify the target using the \ntarget show\n command:\n\n\n[~/tmp/myproj2]$ newt target show bleprph-nrf51dk\ntargets/bleprph-nrf51dk\n app=@apache-mynewt-core/apps/bleprph\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nNext, build the target:\n\n\n[~/tmp/myproj2]$ newt build bleprph-nrf51dk\nBuilding target targets/bleprph-nrf51dk\n# [...]\nTarget successfully built: targets/bleprph-nrf51dk\n\n\n\n\n\nWith our target built, we can view a code size breakdown using the \nnewt size \ntarget\n command. In the interest of brevity, the smaller entries are excluded from the below output:\n\n\n[~/tmp/myproj2]$ newt size bleprph-nrf51dk\nSize of Application Image: app\n FLA
SH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 2959 697 hw_drivers_nimble_nrf51.a\n 4126 108 hw_mcu_nordic_nrf51xxx.a\n 8161 4049 kernel_os.a\n 2254 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1499 44 mgmt_newtmgr_nmgr_os.a\n 23918 1930 net_nimble_controller.a\n 28537 2779 net_nimble_host.a\n 2207 205 sys_config.a\n 1074 197 sys_console_full.a\n 3268 97 sys_log.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf\n\n\n\n\n\nThe full image text size is about 103kB (where 1kB = 1024 bytes). With an image slot size of 110kB,\nthis leaves only about 7kB of flash for addition
al application code and data.\nNot good. This is the situation we would be facing if we were using the\nUnified setup.\n\n\nThe Split setup can go a long way in solving our problem. Our unified bleprph\nimage consists mostly of components that get used during an image upgrade. By\nusing the Split setup, we turn the unified image into two separate images: the\nloader and the application. The functionality related to image upgrade can be\ndelegated to the loader image, freeing up a significant amount of flash in the\napplication image slot.\n\n\nLet's create a new target to use with the Split setup. We designate a target\nas a split target by setting the \nloader\n variable. In our example, we are\ngoing to use \nbleprph\n as the loader, and \nsplitty\n as the application.\n\nbleprph\n makes sense as a loader because it contains the BLE stack and\neverything else required for an image upgrade.\n\n\nnewt target create split-nrf51dk\nnewt target set split-nrf51dk
\\\n loader=@apache-mynewt-core/apps/bleprph \\\n app=@apache-mynewt-core/apps/splitty \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nVerify that the target looks correct:\n\n\n[~/tmp/myproj2]$ newt target show split-nrf51dk\ntargets/split-nrf51dk\n app=@apache-mynewt-core/apps/splitty\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n loader=@apache-mynewt-core/apps/bleprph\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nNow, let's build the new target:\n\n\n[~/tmp/myproj2]$ newt build split-nrf51dk\nBuilding target targets/split-nrf51dk\n# [...]\nTarget successfully built: targets/split-nrf51dk\n\n\n\n\n\nAnd look at the size breakdown (again, smaller entries are removed):\n\n\n[~/tmp/myproj2]$ newt size split-nrf51dk\nSize of Application Image: app\n FLASH
RAM\n 3064 251 sys_shell.a\n\nobjsize\n text data bss dec hex filename\n 4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf\n\nSize of Loader Image: loader\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 3168 705 hw_drivers_nimble_nrf51.a\n 4318 109 hw_mcu_nordic_nrf51xxx.a\n 8285 4049 kernel_os.a\n 2274 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1491 44 mgmt_newtmgr_nmgr_os.a\n 25169 1946 net_nimble_controller.a\n 31397 2827 net_nimble_host.a\n 2259 205 sys_config.a\n 1318 202 sys_console_full.a\n 3424 97 sys_log.a\n 1053 60 sys_stats.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n
112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf\n\n\n\n\n\nThe size command shows two sets of output: one for the application, and another\nfor the loader. The addition of the split functionality did make bleprph\nslightly bigger, but notice how small the application is: 4.5 kB! Where before\nwe only had 7 kB left, now we have 105.5 kB. Furthermore, all the\nfunctionality in the loader is available to the application at any time. For\nexample, if your application needs bluetooth functionality, it can use the BLE\nstack present in the loader instead of containing its own copy.\n\n\nFinally, let's deploy the split image to our nRF51dk board. The procedure here\nis the same as if we were using the Unified setup, i.e., via either the \nnewt load\n or \nnewt run\n command.\n\n\n[~/repos/mynewt/core]$ newt load split-nrf51dk 0\nLoading app image into slot 2\nLoading loader image into slot 1\n\n\n\n\n\nImage Managem
ent\n\n\nRetrieve Current State (image list)\n\n\nImage management in the split setup is a bit more complicated than in the\nunified setup. You can determine a device's image management state with the\n\nnewtmgr image list\n command. Here is how a device responds to this command\nafter our loader + application combo has been deployed:\n\n\n[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags:\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching\n\n\n\n\n\nThere are several interesting things about this response:\n\n\n\n\nTwo images:\n This is expected; we deployed both a loader image and an\napplication image.\n\n\nbootable flag:\n Notice slot 0's bootable flag is set, while slot 1's is\nnot. This tells us that slot 0
contains a loader and slot 1 contains an\napplication. If an image is bootable, it can be booted directly from the boot\nloader. Non-bootable images can only be started from a loader image.\n\n\nflags:\n Slot 0 is \nactive\n and \nconfirmed\n; none of slot 1's flags are set.\nThe \nactive\n flag indicates that the image is currently running; the\n\nconfirmed\n flag indicates that the image will continue to be used on\nsubsequent reboots. Slot 1's lack of enabled flags indicates that the image is\nnot being used at all.\n\n\nSplit status:\n The split status field tells you if the loader and\napplication are compatible. A loader + application combo is compatible only if\nboth images were built at the same time with \nnewt\n. If the loader and\napplication are not compatible, the loader will not boot into the application.\n\n\n\n\nEnabling a Split Application\n\n\nBy default, the application image in slot 1 is disabled. This is indicated in\nthe \nimage list\n response above. Wh
en you deploy a loader / application combo\nto your device, the application image won't actually run. Instead, the loader\nwill act as though an application image is not present and remain in \"loader\nmode\". Typically, a device in loader mode simply acts as an image management\nserver, listening for an image upgrade or a request to activate the application\nimage.\n\n\nUse the following command sequence to enable the split application image:\n\n\n\n\nTell device to \"test out\" the application image on next boot (\nnewtmgr image test \napplication-image-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change permanent (\nnewtmgr image confirm\n).\n\n\n\n\nAfter the above sequence, a \nnewtmgr image list\n command elicits the following response:\n\n\n[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n s
lot=1\n version: 0.0.0\n bootable: false\n flags: active confirmed\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching\n\n\n\n\n\nThe \nactive confirmed\n flags value on both slots indicates that both images are\npermanently running.\n\n\nImage Upgrade\n\n\nFirst, let's review of the image upgrade process for the Unified setup. The\nuser upgrades to a new image in this setup with the following steps:\n\n\nImage Upgrade - Unified\n\n\n\n\nUpload new image to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new image on next boot (\nnewtmgr image test \nimage-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake new image permanent (\nnewtmgr image confirm\n).\n\n\n\n\nImage Upgrade - Split\n\n\nThe image upgrade process is a bit more complicated in the Split setup. It is\nmore complicated because two images need to be upgraded (loader and\napplication) rather than just one. The split up
grade process is described\nbelow:\n\n\n\n\nDisable split functionality; we need to deactivate the application image in\n slot 1 (\nnewtmgr image test \ncurrent-loader-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change permanent (\nnewtmgr image confirm\n).\n\n\nUpload new loader to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new loader on next boot (\nnewtmgr image test \nnew-loader-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change of loader permanent (\nnewtmgr image confirm\n).\n\n\nUpload new application to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new application on next boot (\nnewtmgr image test \nnew-application-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change of application permanent (\nnewtmgr image confirm\n).\n\n\n\n\nWhen performing this process manually, it may be helpful to use \nimage list\n to\ncheck the image management
state as you go.\n\n\nSyscfg\n\n\nSyscfg is Mynewt's system-wide configuration mechanism. In a split setup,\nthere is a single umbrella syscfg configuration that applies to both the loader\nand the application. Consequently, overriding a value in an application-only\npackage potentially affects the loader (and vice-versa).\n\n\nLoaders\n\n\nThe following applications have been enabled as loaders. You may choose to\nbuild your own loader application, and these can serve as samples.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/bleprph\n\n\n\n\nSplit Apps\n\n\nThe following applications have been enabled as split applications. If you\nchoose to build your own split application these can serve as samples. Note\nthat slinky can be either a loader image or an application image.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/splitty\n\n\n\n\nTheory of Operation\n\n\nA split image is built as follows:\n\n\nFirst newt builds the applicatio
n and loader images separately to ensure they\nare consistent (no errors) and to generate elf files which can inform newt of\nthe symbols used by each part.\n\n\nThen newt collects the symbols used by both application and loader in two ways.\nIt collects the set of symbols from the \n.elf\n files. It also collects all the\npossible symbols from the \n.a\n files for each application.\n\n\nNewt builds the set of packages that the two applications share. It ensures\nthat all the symbols used in those packages are matching. NOTE: because of\nfeatures and #ifdefs, its possible for the two package to have symbols that are\nnot the same. In this case newt generates an error and will not build a split\nimage.\n\n\nThen newt creates the list of symbols that the two applications share from\nthose packages (using the .elf files).\n\n\nNewt re-links the loader to ensure all of these symbols are present in the\nloader application (by forcing the linker to include them in the \n.elf\n).\n\n\nN
ewt builds a special copy of the loader.elf with only these symbols (and the\nhandful of symbols discussed in the linking section above).\n\n\nFinally, newt links the application, replacing the common .a libraries with the\nspecial loader.elf image during the link.",
"title": "toc"
},
{
@@ -5062,138 +5062,88 @@
},
{
"location": "/os/modules/split/split/#description",
- "text": "Split images allow the user to build the application content separate from the library content by \nsplitting an application into two pieces: A \"loader\" which contains a separate application that can perform upgrades and manage split images. \nThe \"loader\" resides in slot 1. A \"split app\" which contains the main application content and references the libraries in the loader \nby static linkage. The \"split app\" resides in slot 2.",
+ "text": "The split image mechanism divides a target into two separate images: one\ncapable of image upgrade; the other containing application code. By isolating\nupgrade functionality to a separate image, the application can support\nover-the-air upgrade without dedicating flash space to network stack and\nmanagement code.",
"title": "Description"
},
{
- "location": "/os/modules/split/split/#goals",
- "text": "The goal of split images is to allow a larger application to run along with large components of \nmynewt such as nimble BLE stack and neutron flash file system(nffs) .",
- "title": "Goals"
- },
- {
"location": "/os/modules/split/split/#concept",
- "text": "In a typical mynewt application, an application is contained wholly within an image slot. Typically \nthere are at least two image slots since the image runs from one slot while uploading new code into \nthe second slot. Each image is capable of erasing and uploading another image. Each image is completely \nstand-alone; that is, each image contains all of the libraries and components that it needs. On a typical 256 kbyte flash, a flash layout might look like this: Name Size bootloader 16 k image slot 1 108 k image slot 2 108 k scratch 8 k Flash file system 16 k Now, suppose the desired image contains: Package Size nimble 69 k os 6 k logging 3 k imagemgr 3 k config 3 k nffs 15 k newtmgr 7 k which total 106k. With an image slot size of 108k this leaves only a small amount of code space \nremaining for the application. However, we can see that these packages contain everything you need to
upgrade and configure, so \nif we build a stand-alone loader with these components, we can build the app as a split image and \nget the entire second image slot to store application code and constant data.",
+ "text": "Mynewt supports three image setups: Setup Description Single One large image; upgrade not supported. Unified Two standalone images. Split Kernel in slot 0; application in slot 1. Each setup has its tradeoffs. The Single setup gives you the most flash space,\nbut doesn't allow you to upgrade after manufacturing. The Unified setup allows\nfor a complete failover in case a bad image gets uploaded, but requires a lot\nof redundancy in each image, limiting the amount of flash available to the\napplication. The Split setup sits somewhere between these two options. Before exploring the split setup in more detail, it might be helpful to get a\nbasic understanding of the Mynewt boot sequence. The boot process is\nsummarized below.",
"title": "Concept"
},
{
- "location": "/os/modules/split/split/#when-do-i-use-split-images",
- "text": "If your application fits into the available image slots, there is no advantage to using split \nimages. In general, split images are harder to debug and more complicated to upload. However \nfor a larger application, there may not be enough flash space to have two copies of the entire \napplication. This is when split image becomes necessary.",
- "title": "When do I use split images"
- },
- {
- "location": "/os/modules/split/split/#how-do-i-tell-newt-i-am-building-a-split-image",
- "text": "Newt looks for the variable loader in your target file. If it finds loader variable, it \nwill build a split image. For example, targets/app\n app=@apache-mynewt-core/apps/splitty\n loader=@apache-mynewt-core/apps/slinky\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized shows an application called splitty which uses slinky as its loader.",
- "title": "How do I tell Newt I am building a split image?"
- },
- {
- "location": "/os/modules/split/split/#platforms",
- "text": "Split image requires BSP support. The following BSPs support split images: hw/bsp/arduino_primo_nrf52 hw/bsp/bmd300eval hw/bsp/nrf51-blenano hw/bsp/nrf51dk hw/bsp/nrf51dk-16kbram hw/bsp/nrf52dk",
- "title": "Platforms"
- },
- {
- "location": "/os/modules/split/split/#loaders",
- "text": "The following applications have been enabled as loaders. You may choose to build your own loader \napplication, and these can serve as samples. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/bleprph",
- "title": "Loaders"
+ "location": "/os/modules/split/split/#boot-sequence-single",
+ "text": "In the Single setup, there is no boot loader. Instead, the image is placed at\naddress 0. The hardware boots directly into the image code. Upgrade is not\npossible because there is no boot loader to move an alternate image into place.",
+ "title": "Boot Sequence - Single"
},
{
- "location": "/os/modules/split/split/#split-apps",
- "text": "The following applications have been enabled as split applications. If you choose to build your own \nsplit application these can serve as samples. Note that slinky can be either a loader image or a split app image. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/splitty",
- "title": "Split Apps"
+ "location": "/os/modules/split/split/#boot-sequence-unified",
+ "text": "In the Unified setup, the boot loader is placed at address 0. At startup, the\nboot loader arranges for the correct image to be in image slot 0, which may\nentail swapping the contents of the two image slots. Finally, the boot loader\njumps to the image in slot 0.",
+ "title": "Boot Sequence - Unified"
},
{
- "location": "/os/modules/split/split/#theory-of-operation",
- "text": "A split image is built as follows: First newt builds the app and loader images separately to ensure they are consistent (no errors) and \nto generate elf files which can inform newt of the symbols used by each part. Then newt collects the symbols used by both app and loader in two ways. It collects the set of \nsymbols from the .elf files. It also collects all the possible symbols from the .a files for \neach application. Newt builds the set of packages that the two applications share. It ensures that all the symbols \nused in those packages are matching. NOTE: because of features and #ifdefs, its possible for the \ntwo package to have symbols that are not the same. In this case newt generates an error and will \nnot build a split image. Then newt creates the list of symbols that the two applications share from those packages (using the .elf files). Newt re-links the loader to ensure all of these symbols are present in the loader application
(by \nforcing the linker to include them in the .elf ). Newt builds a special copy of the loader.elf with only these symbols (and the handful of symbols \ndiscussed in the linking section above). Finally, newt links the application, replacing the common .a libraries with the special loader.elf \nimage during the link.",
- "title": "Theory of Operation"
+ "location": "/os/modules/split/split/#boot-sequence-split",
+ "text": "The Split setup differs from the other setups mainly in that a target is not\nfully contained in a single image. Rather, the target is partitioned among two\nseparate images: the loader , and the application . Functionality is divided\namong these two images as follows: Loader: Mynewt OS. Network stack for connectivity during upgrade e.g. BLE stack. Anything else required for image upgrade. Application: Parts of Mynewt not required for image upgrade. Application-specific code. The loader image serves three purposes: Second-stage boot loader: it jumps into the application image at\n start up. Image upgrade server: the user can upgrade to a new loader + application\n combo, even if an application image is not currently running. Functionality container: the application image can directly access all the\n code present in the loader image From the perspective of the boot loader, a loader image is identical to a plain\nunified ima
ge. What makes a loader image different is a change to its start up\nsequence: rather than starting the Mynewt OS, it jumps to the application image\nin slot 1 if one is present.",
+ "title": "Boot Sequence - Split"
},
{
- "location": "/os/modules/split/split/#design",
+ "location": "/os/modules/split/split/#tutorial",
"text": "",
- "title": "Design"
- },
- {
- "location": "/os/modules/split/split/#bootloader",
- "text": "The bootloader has been modified to support \"non bootable\" images like split app images. A flag in \nthe image header denotes the image as \"non-bootable\". When this flag is set, the bootloader will \nnot boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, \nsplit app images are not.",
- "title": "Bootloader"
+ "title": "Tutorial"
},
{
- "location": "/os/modules/split/split/#newt",
- "text": "Newt builds a split image when the token loader=@apache-mynewt-core/apps/slinky is present in the target file. Newt has a Builder object that is responsible for building an image. This features a targetBuilder \nobject that contains two builders (one for the app and one for the loader). The Builder object has been expanded to include options for building as part of a split image. Ability to specify the linker file during the link Ability to specify a set of keep_symbols during the link Newt commands like download, size, create-image have been expanded to perform operations twice \n(once for loader and once for app) if the loader target is present. During normal single-image builds, the targetBuilder initializes and builds the application builder . During the split image build, the targetBuilder performs the steps outlined in the \nsection above using the two builder s for the loader and app. Special symbol and link features are designed as
follows: Newt uses objdump to parse the symbol maps in the .a and .elf files. Newt uses the --undefined= option of the linker to force the loader to keep symbols used by \nthe app (but not used by the linker) Newt uses objcopy with the -K (keep) option when building the special linker .elf . Newt uses the --just-symbols option of the linker to link against the loader .elf file.",
- "title": "Newt"
+ "location": "/os/modules/split/split/#building-a-split-image",
+ "text": "We will be referring to the nRF51dk for examples in this document. Let's take\na look at this board's flash map (defined in hw/bsp/nrf51dk/bsp.yml ): Name Offset Size (kB) Boot loader 0x00000000 16 Reboot log 0x00004000 16 Image slot 0 0x00008000 110 Image slot 1 0x00023800 110 Image scratch 0x0003f000 2 Flash file system 0x0003f800 2 The application we will be building is bleprph .\nFirst, we create a target to tie our BSP and application together. newt target create bleprph-nrf51dk\nnewt target set bleprph-nrf51dk \\\n app=@apache-mynewt-core/apps/bleprph \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 The two syscfg settings disable bluetooth security and keep the code size down. We can verify the target using the target show command: [~/tmp/myproj2]$
newt target show bleprph-nrf51dk\ntargets/bleprph-nrf51dk\n app=@apache-mynewt-core/apps/bleprph\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Next, build the target: [~/tmp/myproj2]$ newt build bleprph-nrf51dk\nBuilding target targets/bleprph-nrf51dk\n# [...]\nTarget successfully built: targets/bleprph-nrf51dk With our target built, we can view a code size breakdown using the newt size target command. In the interest of brevity, the smaller entries are excluded from the below output: [~/tmp/myproj2]$ newt size bleprph-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 2959 697 hw_drivers_nimble_nrf51.a\n 4126 108 hw_mcu_nordic_nrf51xxx.a\n 8161 4049 kernel_os.a\n
2254 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1499 44 mgmt_newtmgr_nmgr_os.a\n 23918 1930 net_nimble_controller.a\n 28537 2779 net_nimble_host.a\n 2207 205 sys_config.a\n 1074 197 sys_console_full.a\n 3268 97 sys_log.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf The full image text size is about 103kB (where 1kB = 1024 bytes). With an image slot size of 110kB,\nthis leaves only about 7kB of flash for additional application code and data.\nNot good. This is the situation we would be facing if we were using the\nUnified setup. The Split setup can go a long way in solving our problem. Our unified bleprph\nimage consists mostly of components that get used during an image upgrade. By\nusing the Split setup, we turn the unified image into tw
o separate images: the\nloader and the application. The functionality related to image upgrade can be\ndelegated to the loader image, freeing up a significant amount of flash in the\napplication image slot. Let's create a new target to use with the Split setup. We designate a target\nas a split target by setting the loader variable. In our example, we are\ngoing to use bleprph as the loader, and splitty as the application. bleprph makes sense as a loader because it contains the BLE stack and\neverything else required for an image upgrade. newt target create split-nrf51dk\nnewt target set split-nrf51dk \\\n loader=@apache-mynewt-core/apps/bleprph \\\n app=@apache-mynewt-core/apps/splitty \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Verify that the target looks correct: [~/tmp/myproj2]$ newt targe
t show split-nrf51dk\ntargets/split-nrf51dk\n app=@apache-mynewt-core/apps/splitty\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n loader=@apache-mynewt-core/apps/bleprph\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Now, let's build the new target: [~/tmp/myproj2]$ newt build split-nrf51dk\nBuilding target targets/split-nrf51dk\n# [...]\nTarget successfully built: targets/split-nrf51dk And look at the size breakdown (again, smaller entries are removed): [~/tmp/myproj2]$ newt size split-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 3064 251 sys_shell.a\n\nobjsize\n text data bss dec hex filename\n 4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf\n\nSize of Loader Image: loader\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2
390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 3168 705 hw_drivers_nimble_nrf51.a\n 4318 109 hw_mcu_nordic_nrf51xxx.a\n 8285 4049 kernel_os.a\n 2274 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1491 44 mgmt_newtmgr_nmgr_os.a\n 25169 1946 net_nimble_controller.a\n 31397 2827 net_nimble_host.a\n 2259 205 sys_config.a\n 1318 202 sys_console_full.a\n 3424 97 sys_log.a\n 1053 60 sys_stats.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf The size command shows two sets of output: one for the application, and another\nfor the loader. The addition of the split functionality did make bleprph\nslightly bigger, but notice how small the application is: 4.5 kB! Where before\nwe only had 7 kB left, now we have 105.5 kB.
Furthermore, all the\nfunctionality in the loader is available to the application at any time. For\nexample, if your application needs bluetooth functionality, it can use the BLE\nstack present in the loader instead of containing its own copy. Finally, let's deploy the split image to our nRF51dk board. The procedure here\nis the same as if we were using the Unified setup, i.e., via either the newt load or newt run command. [~/repos/mynewt/core]$ newt load split-nrf51dk 0\nLoading app image into slot 2\nLoading loader image into slot 1",
+ "title": "Building a Split Image"
},
{
- "location": "/os/modules/split/split/#newt-create-image",
- "text": "create-image uses two different methods to compute the image hash for standard and split images. \nFor split images, the hash is computed starting with the 32-byte hash of the loader, then continuing \nwith the hashing algorithm used by the standard application. This ensures that the split app can be \"validated\" against a loader image specifically.",
- "title": "newt create-image"
- },
- {
- "location": "/os/modules/split/split/#newt-errors",
- "text": "Newt has several new build errors when building split images. Linker script undefined. If the BSP for your application does not define a split image linker script \nthe build will fail. If newt finds that the same library (for example libs/os) has a different implementaiton in the loader \nand app, it will generate an error and fail to build. These differences can arise when #ifdef or features \nare included in one app and not the other. For example, it the loader includes libs/console/stubs and the \napp includes libs/console/full this may change implementations of certain functions within other packages.",
- "title": "newt errors"
- },
- {
- "location": "/os/modules/split/split/#image-manifest",
- "text": "newt builds a single manifest for split images, adding extra tags to the manifest when the image is a split image. loader : slinky.img ,\n loader_hash : 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0 ,\n loader_pkgs : [\n ...\n ] The manifest lists packages in both the loader and app. The app package list only contains those \npackages that reside in the app image itself.",
- "title": "Image manifest"
- },
- {
- "location": "/os/modules/split/split/#libsbootutil",
- "text": "Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies \nthat it matches the loader image in slot 1 and then fetches the entry information for the split app.",
- "title": "libs/bootutil"
- },
- {
- "location": "/os/modules/split/split/#libssplit",
- "text": "A small split image library was created to provide newtmgr commands for split image and to hold the \nconfiguration for split image. See newtmgr below for details. It also contains the function used by a loader to validate and boot a split image.",
- "title": "libs/split"
- },
- {
- "location": "/os/modules/split/split/#appsslinky",
- "text": "A sample app that can be built as a split image with slinky.",
- "title": "apps/slinky"
+ "location": "/os/modules/split/split/#image-management",
+ "text": "",
+ "title": "Image Management"
},
{
- "location": "/os/modules/split/split/#tips-when-building-split-images",
- "text": "To be added",
- "title": "Tips when Building Split images"
+ "location": "/os/modules/split/split/#retrieve-current-state-image-list",
+ "text": "Image management in the split setup is a bit more complicated than in the\nunified setup. You can determine a device's image management state with the newtmgr image list command. Here is how a device responds to this command\nafter our loader + application combo has been deployed: [~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags:\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching There are several interesting things about this response: Two images: This is expected; we deployed both a loader image and an\napplication image. bootable flag: Notice slot 0's bootable flag is set, while slot 1's is\nnot. This tells us that slot 0 contains a loader and slot 1 contains an\napplication. If
an image is bootable, it can be booted directly from the boot\nloader. Non-bootable images can only be started from a loader image. flags: Slot 0 is active and confirmed ; none of slot 1's flags are set.\nThe active flag indicates that the image is currently running; the confirmed flag indicates that the image will continue to be used on\nsubsequent reboots. Slot 1's lack of enabled flags indicates that the image is\nnot being used at all. Split status: The split status field tells you if the loader and\napplication are compatible. A loader + application combo is compatible only if\nboth images were built at the same time with newt . If the loader and\napplication are not compatible, the loader will not boot into the application.",
+ "title": "Retrieve Current State (image list)"
},
{
- "location": "/os/modules/split/split/#adding-bsp-support-for-split-images",
- "text": "A BSP needs additional components to be \"split image ready\". The split image requires a special linker script. The split image needs to run from the second image \npartition (since it's using the loader library that is linked to be placed in the first partition). \nIt needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it). The startup of the split image is different than a typical image. It needs to copy .data from the \nloader image, and zero the loader image bss. For this, it must reference symbols defined in the linker \nscript of the loader. It has a special entry symbol that differentiates it from the entry symbol in the \nloader application. Several of the bsp scripts need to handle additional agruments to deal with the two images produced \nby newt when building split images - mainly download and debug. Add the following components to enable your BSP for split images: A split im
age linker file A startup file for the split image A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as pkg.part2linkerscript: \"split-nrf52dk.ld for example. Modified download script Modified sbrk functionality An example can be found in the /hw/bsp/nrf52dk",
- "title": "Adding BSP support for split images"
+ "location": "/os/modules/split/split/#enabling-a-split-application",
+ "text": "By default, the application image in slot 1 is disabled. This is indicated in\nthe image list response above. When you deploy a loader / application combo\nto your device, the application image won't actually run. Instead, the loader\nwill act as though an application image is not present and remain in \"loader\nmode\". Typically, a device in loader mode simply acts as an image management\nserver, listening for an image upgrade or a request to activate the application\nimage. Use the following command sequence to enable the split application image: Tell device to \"test out\" the application image on next boot ( newtmgr image test application-image-hash ). Reboot device ( newtmgr reset ). Make above change permanent ( newtmgr image confirm ). After the above sequence, a newtmgr image list command elicits the following response: [~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags:
active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags: active confirmed\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching The active confirmed flags value on both slots indicates that both images are\npermanently running.",
+ "title": "Enabling a Split Application"
},
{
- "location": "/os/modules/split/split/#split-image-linker-script",
- "text": "The split image linker script must have the following. The split linker must be linked to run from the second flash image slot. For example: MEMORY \n{\n FLASH ( rx ) : ORIGIN = 0x00042000 , LENGTH = 0x3a000 \n RAM ( rwx ) : ORIGIN = 0x20000000 , LENGTH = 0x10000 \n} The split linker must define the entry symbol as Reset_Handler_split. For example: ENTRY ( Reset_Handler_split ) The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional \nvector entries are part of the loader and are not needed in the split image. The bootloader accesses these \nentries at the beginning of the image slot (first 2 words). For example: .text :\n {\n __split_isr_vector_start = .;\n KEEP(*(.isr_vector_split))\n __split_isr_vector_end = .;\n ... \n } The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (the
y are \nboth using RAM). Note, the two apps don't run at the same time, but the loader has global data that its \nlibraries use. This cannot be overwritten by the application. An example linker section that accomplishes \nthis can be found in /hw/bsp/nrf52dk/split-nrf52dk.ld . When linking against the loader, the loader exports \nthe following symbosl which can be used by the split app code: __HeapBase_loader __bss_start___loader __bss_end___loader __etext_loader __data_start___loader __data_end___loader The split app linker can use __HeapBase_loader to skip RAM used by the loader as follows. /* save RAM used by the split image. This assumes that * the loader uses all the RAM up to its HeapBase */ \n . loader_ram_contents :\n {\n _loader_ram_start = .;\n\n /* this symbol comes from the loader linker */ \n . = . + ( ABSOLUTE ( __HeapBase_loader ) - _loader_ram_start );\n _loader_ram_end = .;\n } RAM",
- "title": "split image linker script"
+ "location": "/os/modules/split/split/#image-upgrade",
+ "text": "First, let's review of the image upgrade process for the Unified setup. The\nuser upgrades to a new image in this setup with the following steps:",
+ "title": "Image Upgrade"
},
{
- "location": "/os/modules/split/split/#split-image-startup-code",
- "text": "The split application needs separate startup code to intialize the split image before running main. The \nsplit image is specially linked so that _start and main are included individually for the loader and split app. The split app startup code must have the following. A definition of the split image vector table (first two words). The entry point function to start the code Reset_Handler_split Code that copies the .data section for the loader from Flash to RAM Code that zeros the .bss section for the loader. Code that calls _sbrkInit to set the heap pointers for the application (see below) Code that calls the bsp_slot_init_split_application function (see below) An example can be found in the /hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s",
- "title": "split image startup code"
+ "location": "/os/modules/split/split/#image-upgrade-unified",
+ "text": "Upload new image to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new image on next boot ( newtmgr image test image-hash ). Reboot device ( newtmgr reset ). Make new image permanent ( newtmgr image confirm ).",
+ "title": "Image Upgrade - Unified"
},
{
- "location": "/os/modules/split/split/#download-script",
- "text": "The download script needs to be modified to include support for passing the image slot number in the build. \nImage slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers. See and example in /hw/bsp/bmd300eval/bmd300eval_download.sh .",
- "title": "Download script"
+ "location": "/os/modules/split/split/#image-upgrade-split",
+ "text": "The image upgrade process is a bit more complicated in the Split setup. It is\nmore complicated because two images need to be upgraded (loader and\napplication) rather than just one. The split upgrade process is described\nbelow: Disable split functionality; we need to deactivate the application image in\n slot 1 ( newtmgr image test current-loader-hash ). Reboot device ( newtmgr reset ). Make above change permanent ( newtmgr image confirm ). Upload new loader to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new loader on next boot ( newtmgr image test new-loader-hash ). Reboot device ( newtmgr reset ). Make above change of loader permanent ( newtmgr image confirm ). Upload new application to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new application on next boot ( newtmgr image test new-application-hash ). Reboot device ( newtmgr reset ). Make above change of application permanent (
newtmgr image confirm ). When performing this process manually, it may be helpful to use image list to\ncheck the image management state as you go.",
+ "title": "Image Upgrade - Split"
},
{
- "location": "/os/modules/split/split/#sbrk-functionality",
- "text": "Split image (either a loader or app) references a single set of heap managment functions. But the heap location and \nsize is different depending which image is running. Special functionality is needed to handle the dynamic \nsetting of the heap base and limit. Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk \nneeds to be dynamically initialized with these values from the startup code. See an example in /hw/bsp/bmd300eval/src/sbrk.c in the core repository. The function _sbrkInit must be \ncalled from the startup code of the split image and normal image startup code with the appropriate \nvalues of heap base and limit.",
- "title": "Sbrk functionality"
+ "location": "/os/modules/split/split/#syscfg",
+ "text": "Syscfg is Mynewt's system-wide configuration mechanism. In a split setup,\nthere is a single umbrella syscfg configuration that applies to both the loader\nand the application. Consequently, overriding a value in an application-only\npackage potentially affects the loader (and vice-versa).",
+ "title": "Syscfg"
},
{
- "location": "/os/modules/split/split/#slot-init",
- "text": "A global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as \nthe combined loader/app image. Its the responsibility of the startup code to set this global variable. See hw/bsp/bmd300eval/src/os_bsp.c for and implementation of the functionality.",
- "title": "Slot Init"
+ "location": "/os/modules/split/split/#loaders",
+ "text": "The following applications have been enabled as loaders. You may choose to\nbuild your own loader application, and these can serve as samples. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/bleprph",
+ "title": "Loaders"
},
{
- "location": "/os/modules/split/split/#newtmgr-and-split-images",
- "text": "newtmgr has support for split images. newtmgr image list lists the current images in the flash. Its clear from the output that some images are non-bootable. For example. Images:\n slot=1\n version=1.2.3\n bootable=true\n hash=55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n slot=2\n version=1.2.3\n bootable=false\n hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the boot2 \ncommand to instruct mynewt to boot slot 2. Instead, use the new split status command to see the status of split images and to set their boot status. \nThe split status command with no arguments returns status of the split image. The Split Value tells the loader \nhow to boot the split app. Options are: none Don't boot the split application. Just remain running in the loader. test Boot the split application, but re
vert back to the loader on the next reset. run Boot the split application. The split status command also verified the hash of the split application (using the hash of the loader \nas shown above) and returns the status of the check (matching or non-matching). newtmgr -c connection split status\n Split value is none\n Split status is matching When the split image application is running, the active hash in the boot2 command will match the \nhash of the split application (in slot 2). For example: prompt$ newtmgr -c foo1 image boot\n Test image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Main image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Active img: 1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe",
- "title": "newtmgr and split Images"
+ "location": "/os/modules/split/split/#split-apps",
+ "text": "The following applications have been enabled as split applications. If you\nchoose to build your own split application these can serve as samples. Note\nthat slinky can be either a loader image or an application image. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/splitty",
+ "title": "Split Apps"
},
{
- "location": "/os/modules/split/split/#upgrading-a-split-image-with-newtmgr",
- "text": "When running via newt, the newt load command will load both parts of a split image, the loader and application. When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the \nsplit app in run mode the following sequence will upgrade newtmgr split status none newtmgr reboot newtmgr image upload newtmgr image boot2 newtmgr reboot newtmgr image upload newtmgr split status test newtmgr reboot newtmgr boot2 (check status to ensure new app is running) newtmgr split status run This upgrade is robust. In all steps there is a loader image that is capable of upgrading (or reverting) images.",
- "title": "Upgrading a split image with newtmgr"
+ "location": "/os/modules/split/split/#theory-of-operation",
+ "text": "A split image is built as follows: First newt builds the application and loader images separately to ensure they\nare consistent (no errors) and to generate elf files which can inform newt of\nthe symbols used by each part. Then newt collects the symbols used by both application and loader in two ways.\nIt collects the set of symbols from the .elf files. It also collects all the\npossible symbols from the .a files for each application. Newt builds the set of packages that the two applications share. It ensures\nthat all the symbols used in those packages are matching. NOTE: because of\nfeatures and #ifdefs, its possible for the two package to have symbols that are\nnot the same. In this case newt generates an error and will not build a split\nimage. Then newt creates the list of symbols that the two applications share from\nthose packages (using the .elf files). Newt re-links the loader to ensure all of these symbols are present in the\nloader applic
ation (by forcing the linker to include them in the .elf ). Newt builds a special copy of the loader.elf with only these symbols (and the\nhandful of symbols discussed in the linking section above). Finally, newt links the application, replacing the common .a libraries with the\nspecial loader.elf image during the link.",
+ "title": "Theory of Operation"
},
{
"location": "/os/modules/bootloader/bootloader/",
@@ -5397,7 +5347,7 @@
},
{
"location": "/os/modules/fs/fs/fs/",
- "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the \nfs/fs\n package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nThe following example illustrates how file system dependencies should be managed.
In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called \nfs/nffs\n (Newtron Flash File System). The app explicitly initializes nffs via calls to \nnffs_init()\n, \nnffs_detect()\n and \nnffs_format()\n.\n\n\n# repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/nffs\n\n# [...]\n\n\n\n\n\n/* repos/apache-mynewt-core/apps/slinky/src/main.c */\n\n\n\n#include \nnffs/nffs.h\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\nNFFS_AREA_MAX\n];\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\
n) {\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n// [...]\n\n}\n\n\n\n\n\nOn the other hand, code which uses the file system after it has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to
client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfs_close\n\n\nCloses the specified file and invalidates the file handle.\n\n\n\n\n\n\nfs_closedir\n\n\nCloses the specified directory handle.\n\n\n\n\n\n\nfs_dirent_is_dir\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file.\n\n\n\n\n\n\nfs_dirent_name\n\n\nRetrieves the filename of the specified directory entry.\n\n\n\n\n\n\nfs_filelen\n\n\nRetrieves the current length of the specified open file.\n\n\n\n\n\n\nfs_getpos\n\n\nRetrieves the current read and write position of the specified open file.\n\n\n\n\n\n\nfs_mkdir\n\n\nCreates the directory represented by the specified path.\n\n\n\n\n\n\nfs
_open\n\n\nOpens a file at the specified path.\n\n\n\n\n\n\nfs_opendir\n\n\nOpens the directory at the specified path.\n\n\n\n\n\n\nfs_read\n\n\nReads data from the specified file.\n\n\n\n\n\n\nfs_readdir\n\n\nReads the next entry in an open directory.\n\n\n\n\n\n\nfs_register\n\n\nRegisters a file system with the abstraction layer.\n\n\n\n\n\n\nfs_rename\n\n\nPerforms a rename and/or move of the specified source path to the specified destination.\n\n\n\n\n\n\nfs_seek\n\n\nPositions a file's read and write pointer at the specified offset.\n\n\n\n\n\n\nfs_unlink\n\n\nUnlinks the file or directory at the specified path.\n\n\n\n\n\n\nfs_write\n\n\nWrites the supplied data to the current offset of the specified file handle.\n\n\n\n\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfsutil_read_file\n\n\nOpens a file at the specified path, retrieve data from the file starting from th
e specified offset, and close the file and invalidate the file handle.\n\n\n\n\n\n\nfsutil_write_file\n\n\nOpen a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
+ "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the\n\nfs/fs\n package.\nIn terms of the Mynewt hierarchy, an \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nApplications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.\nIn the following example, the \nNewtron Flash File System\n\nis used.\n\n\n# repos/apa
che-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/fs # include the file operations interfaces\n - fs/nffs # include the NFFS filesystem implementation\n\n\n\n\n\n# repos/apache-mynewt-core/apps/slinky/syscfg.yml\n# [...]\n # Package: apps/\nexample app\n\n# [...]\n CONFIG_NFFS: 1 # initialize and configure NFFS into the system\n# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues \n# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect\n\n# [...]\n\n\n\n\n\nConsult the documentation for \nnffs\n for a more detailed explanation of NFFS_DETECT_FAIL\n\n\nCode which uses the file system after the system has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depe
nds on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfs_close\n\n\nCloses the specified file and invalidates the file handle.\n\n\n\n\n\n\nfs_closedir\n\n\nCloses the specified directory ha
ndle.\n\n\n\n\n\n\nfs_dirent_is_dir\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file.\n\n\n\n\n\n\nfs_dirent_name\n\n\nRetrieves the filename of the specified directory entry.\n\n\n\n\n\n\nfs_filelen\n\n\nRetrieves the current length of the specified open file.\n\n\n\n\n\n\nfs_getpos\n\n\nRetrieves the current read and write position of the specified open file.\n\n\n\n\n\n\nfs_mkdir\n\n\nCreates the directory represented by the specified path.\n\n\n\n\n\n\nfs_open\n\n\nOpens a file at the specified path.\n\n\n\n\n\n\nfs_opendir\n\n\nOpens the directory at the specified path.\n\n\n\n\n\n\nfs_read\n\n\nReads data from the specified file.\n\n\n\n\n\n\nfs_readdir\n\n\nReads the next entry in an open directory.\n\n\n\n\n\n\nfs_register\n\n\nRegisters a file system with the abstraction layer.\n\n\n\n\n\n\nfs_rename\n\n\nPerforms a rename and/or move of the specified source path to the specified destination.\n\n\n\n\n\n\nfs_seek\n\n\nPositions a fil
e's read and write pointer at the specified offset.\n\n\n\n\n\n\nfs_unlink\n\n\nUnlinks the file or directory at the specified path.\n\n\n\n\n\n\nfs_write\n\n\nWrites the supplied data to the current offset of the specified file handle.\n\n\n\n\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfsutil_read_file\n\n\nOpens a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\n\n\n\n\nfsutil_write_file\n\n\nOpen a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
"title": "toc"
},
{
@@ -5407,7 +5357,7 @@
},
{
"location": "/os/modules/fs/fs/fs/#description",
- "text": "Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the fs/fs package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the app package must depend on a specific file system package, while library packages should only depend on fs/fs . The following example illustrates how file system dependencies should be managed. In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called fs/nffs (Newtron Flash File System). The app explicitly initializes nffs via calls to nffs_init() , nffs_detect() and nffs_format() . # repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/nffs\n\n# [...] /* repos/apache-mynewt-c
ore/apps/slinky/src/main.c */ #include nffs/nffs.h int main ( int argc , char **argv )\n{\n int rc ;\n int cnt ;\n struct nffs_area_desc descs [ NFFS_AREA_MAX ];\n\n rc = nffs_init ();\n assert ( rc == 0 );\n\n cnt = NFFS_AREA_MAX ;\n rc = flash_area_to_nffs_desc ( FLASH_AREA_NFFS , cnt , descs );\n assert ( rc == 0 );\n if ( nffs_detect ( descs ) == FS_ECORRUPT ) {\n rc = nffs_format ( descs );\n assert ( rc == 0 );\n }\n // [...] \n} On the other hand, code which uses the file system after it has been initialized need only depend on fs/fs . For example, the libs/imgmgr package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the fs/fs package. # repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/i
mgmgr\npkg.deps:\n - fs/fs\n\n# [...] The libs/imgmgr package uses the fs/fs API for all file system operations.",
+ "text": "Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the fs/fs package.\nIn terms of the Mynewt hierarchy, an app package must depend on a specific file system package, while library packages should only depend on fs/fs . Applications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.\nIn the following example, the Newtron Flash File System \nis used. # repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/fs # include the file operations interfaces\n - fs/nffs # include the NFFS filesystem implementation # repos/apache-mynewt-core/apps/slinky/syscfg.yml\n# [...]\n # Package: apps/ example app \n# [...]\n CONFIG_NFFS: 1 # initialize and configure NFFS into the system\n# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection is
sues \n# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect\n\n# [...] Consult the documentation for nffs for a more detailed explanation of NFFS_DETECT_FAIL Code which uses the file system after the system has been initialized need only depend on fs/fs . For example, the libs/imgmgr package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the fs/fs package. # repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...] The libs/imgmgr package uses the fs/fs API for all file system operations.",
"title": "Description"
},
{
@@ -6047,7 +5997,7 @@
},
{
"location": "/os/modules/fs/nffs/nffs/",
- "text": "Newtron Flash Filesystem (nffs)\n\n\nMynewt includes the Newtron Flash File System (nffs). This file system is designed with two priorities that makes it suitable for embedded use: \n\n\n\n\nMinimal RAM usage\n\n\nReliability\n\n\n\n\nMynewt also provides an abstraction layer API (fs) to allow you to swap out nffs with a different file system of your choice.\n\n\nDescription\n\n\nAreas\n\n\nAt the top level, an nffs disk is partitioned into \nareas\n. An area is a region of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nWriting to one area does not restrict writes to other areas.\n\n\n\n\nRegarding property 1:\n Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible.\n\n\nRegarding property 2:\n Furthermore, some flash hardware imposes a restriction with regards to writes: writes
within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.\n\n\nThus, each area must comprise a discrete number of blocks.
<TRUNCATED>
[2/5] incubator-mynewt-site git commit: Split image documentation
updated
Posted by ad...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/7eec4897/latest/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/latest/mkdocs/search_index.json b/latest/mkdocs/search_index.json
index e12bf10..8c7d2ba 100644
--- a/latest/mkdocs/search_index.json
+++ b/latest/mkdocs/search_index.json
@@ -5052,7 +5052,7 @@
},
{
"location": "/os/modules/split/split/",
- "text": "Split Images\n\n\nDescription\n\n\nSplit images allow the user to build the application content separate from the library content by \nsplitting an application into two pieces:\n\n\n\n\nA \"loader\" which contains a separate application that can perform upgrades and manage split images. \nThe \"loader\" resides in slot 1.\n\n\nA \"split app\" which contains the main application content and references the libraries in the loader \nby static linkage. The \"split app\" resides in slot 2.\n\n\n\n\nGoals\n\n\nThe goal of split images is to allow a larger application to run along with large components of \nmynewt such as \nnimble BLE stack\n and \nneutron flash file system(nffs)\n.\n\n\nConcept\n\n\nIn a typical mynewt application, an application is contained wholly within an image slot. Typically \nthere are at least two image slots since the image runs from one slot while uploading new code into \nthe second slot. Each image is capable of erasing and uploading ano
ther image. Each image is completely \nstand-alone; that is, each image contains all of the libraries and components that it needs.\n\n\nOn a typical 256 kbyte flash, a flash layout might look like this:\n\n\n\n\n\n\n\n\nName\n\n\nSize\n\n\n\n\n\n\n\n\n\n\nbootloader\n\n\n16 k\n\n\n\n\n\n\nimage slot 1\n\n\n108 k\n\n\n\n\n\n\nimage slot 2\n\n\n108 k\n\n\n\n\n\n\nscratch\n\n\n8 k\n\n\n\n\n\n\nFlash file system\n\n\n16 k\n\n\n\n\n\n\n\n\nNow, suppose the desired image contains:\n\n\n\n\n\n\n\n\nPackage\n\n\nSize\n\n\n\n\n\n\n\n\n\n\nnimble\n\n\n69 k\n\n\n\n\n\n\nos\n\n\n6 k\n\n\n\n\n\n\nlogging\n\n\n3 k\n\n\n\n\n\n\nimagemgr\n\n\n3 k\n\n\n\n\n\n\nconfig\n\n\n3 k\n\n\n\n\n\n\nnffs\n\n\n15 k\n\n\n\n\n\n\nnewtmgr\n\n\n7 k\n\n\n\n\n\n\n\n\nwhich total 106k. With an image slot size of 108k this leaves only a small amount of code space \nremaining for the application.\n\n\nHowever, we can see that these packages contain everything you need to upgrade and configure, so \nif we build a stan
d-alone loader with these components, we can build the app as a split image and \nget the entire second image slot to store application code and constant data.\n\n\nWhen do I use split images\n\n\nIf your application fits into the available image slots, there is no advantage to using split \nimages. In general, split images are harder to debug and more complicated to upload. However \nfor a larger application, there may not be enough flash space to have two copies of the entire \napplication. This is when split image becomes necessary.\n\n\nHow do I tell Newt I am building a split image?\n\n\nNewt looks for the variable \nloader\n in your target file. If it finds \nloader\n variable, it \nwill build a split image. For example,\n\n\ntargets/app\n app=@apache-mynewt-core/apps/splitty\n loader=@apache-mynewt-core/apps/slinky\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\nshows an application called splitty which uses slinky as its loader.\n\
n\nPlatforms\n\n\nSplit image requires BSP support. The following BSPs support split images:\n\n\n\n\nhw/bsp/arduino_primo_nrf52\n\n\nhw/bsp/bmd300eval\n\n\nhw/bsp/nrf51-blenano\n\n\nhw/bsp/nrf51dk\n\n\nhw/bsp/nrf51dk-16kbram\n\n\nhw/bsp/nrf52dk\n\n\n\n\nLoaders\n\n\nThe following applications have been enabled as loaders. You may choose to build your own loader \napplication, and these can serve as samples.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/bleprph\n\n\n\n\nSplit Apps\n\n\nThe following applications have been enabled as split applications. If you choose to build your own \nsplit application these can serve as samples. Note that slinky can be either a loader image or a split app image.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/splitty\n\n\n\n\nTheory of Operation\n\n\nA split image is built as follows:\n\n\nFirst newt builds the \napp\n and \nloader\n images separately to ensure they are consistent (no errors) and \n
to generate elf files which can inform newt of the symbols used by each part.\n\n\nThen newt collects the symbols used by both \napp\n and \nloader\n in two ways. It collects the set of \nsymbols from the \n.elf\n files. It also collects all the possible symbols from the \n.a\n files for \neach application.\n\n\nNewt builds the set of packages that the two applications share. It ensures that all the symbols \nused in those packages are matching. NOTE: because of features and #ifdefs, its possible for the \ntwo package to have symbols that are not the same. In this case newt generates an error and will \nnot build a split image.\n\n\nThen newt creates the list of symbols that the two applications share from those packages (using the .elf files).\n\n\nNewt re-links the loader to ensure all of these symbols are present in the loader application (by \nforcing the linker to include them in the \n.elf\n).\n\n\nNewt builds a special copy of the loader.elf with only these symbols (and t
he handful of symbols \ndiscussed in the linking section above).\n\n\nFinally, newt links the application, replacing the common .a libraries with the special loader.elf \nimage during the link.\n\n\nDesign\n\n\nBootloader\n\n\nThe \nbootloader\n has been modified to support \"non bootable\" images like split app images. A flag in \nthe image header denotes the image as \"non-bootable\". When this flag is set, the bootloader will \nnot boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, \nsplit app images are not.\n\n\nNewt\n\n\nNewt builds a split image when the token \nloader=@apache-mynewt-core/apps/slinky\n is present in the target file.\n\n\nNewt has a \nBuilder\n object that is responsible for building an image. This features a \ntargetBuilder\n \nobject that contains two builders (one for the app and one for the loader).\n\n\nThe \nBuilder\n object has been expanded to include options for building as part of a split image.\n\n Ab
ility to specify the linker file during the link\n\n Ability to specify a set of keep_symbols during the link\n\n\nNewt commands like download, size, create-image have been expanded to perform operations twice \n(once for loader and once for app) if the loader target is present.\n\n\nDuring normal single-image builds, the \ntargetBuilder\n initializes and builds the application \n\nbuilder\n. During the split image build, the \ntargetBuilder\n performs the steps outlined in the \nsection above using the two \nbuilder\ns for the loader and app.\n\n\nSpecial symbol and link features are designed as follows:\n\n\n\n\nNewt uses objdump to parse the symbol maps in the \n.a\n and \n.elf\n files.\n\n\nNewt uses the \n--undefined=\n option of the linker to force the loader to keep symbols used by \nthe app (but not used by the linker)\n\n\nNewt uses objcopy with the \n-K\n (keep) option when building the special linker \n.elf\n.\n\n\nNewt uses the \n--just-symbols\n option of the linker to
link against the loader \n.elf\n file.\n\n\n\n\nnewt create-image\n\n\ncreate-image\n uses two different methods to compute the image hash for standard and split images.\n\nFor split images, the hash is computed starting with the 32-byte hash of the loader, then continuing \nwith the hashing algorithm used by the standard application. This ensures that the split app can be \"validated\" against a loader image specifically.\n\n\nnewt errors\n\n\nNewt has several new build errors when building split images.\n\n\n\n\nLinker script undefined. If the BSP for your application does not define a split image linker script \nthe build will fail.\n\n\n\n\nIf newt finds that the same library (for example libs/os) has a different implementaiton in the loader \nand app, it will generate an error and fail to build. These differences can arise when \n#ifdef\n or features \nare included in one app and not the other. For example, it the loader includes \nlibs/console/stubs\n and the \napp include
s \nlibs/console/full\n this may change implementations of certain functions within other packages.\n\n\nImage manifest\n\n\nnewt builds a single manifest for split images, adding extra tags to the manifest when the image is a split image.\n\n\n \nloader\n: \nslinky.img\n,\n \nloader_hash\n: \n55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n,\n \nloader_pkgs\n: [\n ...\n ]\n\n\n\n\n\nThe manifest lists packages in both the loader and app. The app package list only contains those \npackages that reside in the app image itself.\n\n\nlibs/bootutil\n\n\nBootutil has been expanded to include a function that looks for a split app image in slot 2, verifies \nthat it matches the loader image in slot 1 and then fetches the entry information for the split app.\n\n\nlibs/split\n\n\nA small split image library was created to provide newtmgr commands for split image and to hold the \nconfiguration for split image. See newtmgr below for details.\n\n\nIt also
contains the function used by a loader to validate and boot a split image.\n\n\napps/slinky\n\n\nA sample app that can be built as a split image with slinky.\n\n\nTips when Building Split images\n\n\nTo be added\n\n\nAdding BSP support for split images\n\n\nA BSP needs additional components to be \"split image ready\".\n\n\nThe split image requires a special linker script. The split image needs to run from the second image \npartition (since it's using the loader library that is linked to be placed in the first partition).\n\nIt needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it).\n\n\nThe startup of the split image is different than a typical image. It needs to copy \n.data\n from the \nloader image, and zero the loader image bss. For this, it must reference symbols defined in the linker \nscript of the loader. It has a special entry symbol that differentiates it from the entry symbol in the \nloader application
.\n\n\nSeveral of the bsp scripts need to handle additional agruments to deal with the two images produced \nby newt when building split images - mainly download and debug.\n\n\nAdd the following components to enable your BSP for split images:\n\n\n\n\nA split image linker file\n\n\nA startup file for the split image\n\n\nA property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as \npkg.part2linkerscript: \"split-nrf52dk.ld\n for example.\n\n\nModified download script\n\n\nModified sbrk functionality\n\n\n\n\nAn example can be found in the \n/hw/bsp/nrf52dk\n\n\nsplit image linker script\n\n\nThe split image linker script must have the following.\n\n\nThe split linker must be linked to run from the second flash image slot. For example:\n\n\nMEMORY\n\n{\n \nFLASH\n (\nrx\n) \n:\n \nORIGIN\n \n=\n \n0x00042000\n, \nLENGTH\n \n=\n \n0x3a000\n\n \nRAM\n (\nrwx\n) \n:\n \nORIGIN\n \n=\n \n0x20000000\n, \nLENGTH\n \n=\n \n0
x10000\n\n}\n\n\n\n\n\nThe split linker must define the entry symbol as Reset_Handler_split. For example:\n\n\nENTRY\n(\nReset_Handler_split\n)\n\n\n\n\n\nThe split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional \nvector entries are part of the loader and are not needed in the split image. The bootloader accesses these \nentries at the beginning of the image slot (first 2 words). For example:\n\n\n .text :\n {\n __split_isr_vector_start = .;\n KEEP(*(.isr_vector_split))\n __split_isr_vector_end = .;\n ... \n } \n\n\n\n\n\nThe split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (they are \nboth using RAM). Note, the two apps don't run at the same time, but the loader has global data that its \nlibraries use. This cannot be overwritten by the application. An example linker section that accomplishes \nthis can be found in \n/hw/bsp/nrf52dk/split-nr
f52dk.ld\n. When linking against the loader, the loader exports \nthe following symbosl which can be used by the split app code:\n\n\n\n\n__HeapBase_loader\n\n\n__bss_start___loader\n\n\n__bss_end___loader\n\n\n__etext_loader\n\n\n__data_start___loader\n\n\n__data_end___loader\n\n\n\n\nThe split app linker can use \n__HeapBase_loader\n to skip RAM used by the loader as follows.\n\n\n \n/* save RAM used by the split image. This assumes that\n\n\n * the loader uses all the RAM up to its HeapBase */\n\n .\nloader_ram_contents\n :\n {\n \n_loader_ram_start\n \n=\n .;\n\n \n/* this symbol comes from the loader linker */\n\n . \n=\n . \n+\n (\nABSOLUTE\n(\n__HeapBase_loader\n) \n-\n \n_loader_ram_start\n);\n \n_loader_ram_end\n \n=\n .;\n } \n \nRAM\n\n\n\n\n\n\nsplit image startup code\n\n\nThe split application needs separate startup code to intialize the split image before running main. The \nsplit image is specially linked so that \n_start\n and \
nmain\n are included individually for the loader and split app.\n\n\nThe split app startup code must have the following.\n\n\n\n\nA definition of the split image vector table (first two words).\n\n\nThe entry point function to start the code \nReset_Handler_split\n\n\nCode that copies the \n.data\n section for the loader from Flash to RAM\n\n\nCode that zeros the \n.bss\n section for the loader.\n\n\nCode that calls \n_sbrkInit\n to set the heap pointers for the application (see below)\n\n\nCode that calls the \nbsp_slot_init_split_application\n function (see below)\n\n\n\n\nAn example can be found in the \n/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s\n\n\nDownload script\n\n\nThe download script needs to be modified to include support for passing the image slot number in the build.\n\nImage slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers.\n\n\nSee and example in \n/hw/bsp/bmd300eval/bmd300eval_download.sh\n.\n\n\nSbrk functionality
\n\n\nSplit image (either a loader or app) references a single set of heap managment functions. But the heap location and \nsize is different depending which image is running. Special functionality is needed to handle the dynamic \nsetting of the heap base and limit.\n\n\nInstead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk \nneeds to be dynamically initialized with these values from the startup code.\n\n\nSee an example in \n/hw/bsp/bmd300eval/src/sbrk.c\n in the core repository. The function \n_sbrkInit\n must be \ncalled from the startup code of the split image and normal image startup code with the appropriate \nvalues of heap base and limit.\n\n\nSlot Init\n\n\nA global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as \nthe combined loader/app image. Its the responsibility of the startup code to set this global variable.\n\n\nSee \nhw/bsp/bmd300eval/src/os_bsp.c\n for and imple
mentation of the functionality.\n\n\nnewtmgr and split Images\n\n\nnewtmgr has support for split images.\n\n\nnewtmgr image list\n lists the current images in the flash. Its clear from the output that some images are non-bootable. For example.\n\n\nImages:\n slot=1\n version=1.2.3\n bootable=true\n hash=55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n slot=2\n version=1.2.3\n bootable=false\n hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe\n\n\n\n\n\nThe bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the \nboot2\n \ncommand to instruct mynewt to boot slot 2.\n\n\nInstead, use the new \nsplit status\n command to see the status of split images and to set their boot status.\n\nThe split status command with no arguments returns status of the split image. The Split Value tells the loader \nhow to boot the split app. Options are:\n\n\n\n\nnone\n Don't boot the split applica
tion. Just remain running in the loader.\n\n\ntest\n Boot the split application, but revert back to the loader on the next reset.\n\n\nrun\n Boot the split application.\n\n\n\n\nThe split status command also verified the hash of the split application (using the hash of the loader \nas shown above) and returns the status of the check (matching or non-matching).\n\n\nnewtmgr -c connection split status\n Split value is none\n Split status is matching\n\n\n\n\n\nWhen the split image application is running, the active hash in the \nboot2\n command will match the \nhash of the split application (in slot 2). For example:\n\n\nprompt$ newtmgr -c foo1 image boot\n Test image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Main image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Active img: 1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe\n\n\n\n\n\nUpgrading a split image with newtmgr\n\n\nWhen running via newt, the \nnewt loa
d\n command will load both parts of a split image, the loader and application.\n\n\nWhen running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the \nsplit app in \nrun\n mode the following sequence will upgrade\n\n\n\n\nnewtmgr split status none\n\n\nnewtmgr reboot\n\n\nnewtmgr image upload \n\n\nnewtmgr image boot2 \n\n\nnewtmgr reboot\n\n\nnewtmgr image upload \n\n\nnewtmgr split status test\n\n\nnewtmgr reboot\n\n\nnewtmgr boot2 (check status to ensure new app is running)\n\n\nnewtmgr split status run\n\n\n\n\nThis upgrade is robust. In all steps there is a loader image that is capable of upgrading (or reverting) images.",
+ "text": "Split Images\n\n\nDescription\n\n\nThe split image mechanism divides a target into two separate images: one\ncapable of image upgrade; the other containing application code. By isolating\nupgrade functionality to a separate image, the application can support\nover-the-air upgrade without dedicating flash space to network stack and\nmanagement code. \n\n\nConcept\n\n\nMynewt supports three image setups:\n\n\n\n\n\n\n\n\nSetup\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nSingle\n\n\nOne large image; upgrade not supported.\n\n\n\n\n\n\nUnified\n\n\nTwo standalone images.\n\n\n\n\n\n\nSplit\n\n\nKernel in slot 0; application in slot 1.\n\n\n\n\n\n\n\n\nEach setup has its tradeoffs. The Single setup gives you the most flash space,\nbut doesn't allow you to upgrade after manufacturing. The Unified setup allows\nfor a complete failover in case a bad image gets uploaded, but requires a lot\nof redundancy in each image, limiting the amount of flash available to the\napplicat
ion. The Split setup sits somewhere between these two options.\n\n\nBefore exploring the split setup in more detail, it might be helpful to get a\nbasic understanding of the Mynewt boot sequence. The boot process is\nsummarized below.\n\n\nBoot Sequence - Single\n\n\nIn the Single setup, there is no boot loader. Instead, the image is placed at\naddress 0. The hardware boots directly into the image code. Upgrade is not\npossible because there is no boot loader to move an alternate image into place.\n\n\nBoot Sequence - Unified\n\n\nIn the Unified setup, the boot loader is placed at address 0. At startup, the\nboot loader arranges for the correct image to be in image slot 0, which may\nentail swapping the contents of the two image slots. Finally, the boot loader\njumps to the image in slot 0.\n\n\nBoot Sequence - Split\n\n\nThe Split setup differs from the other setups mainly in that a target is not\nfully contained in a single image. Rather, the target is partitioned among tw
o\nseparate images: the \nloader\n, and the \napplication\n. Functionality is divided\namong these two images as follows:\n\n\n\n\n\n\nLoader: \n\n\n\n\nMynewt OS.\n\n\nNetwork stack for connectivity during upgrade e.g. BLE stack.\n\n\nAnything else required for image upgrade.\n\n\n\n\n\n\n\n\nApplication:\n\n\n\n\nParts of Mynewt not required for image upgrade.\n\n\nApplication-specific code.\n\n\n\n\n\n\n\n\nThe loader image serves three purposes:\n\n\n\n\nSecond-stage boot loader:\n it jumps into the application image at\n start up.\n\n\nImage upgrade server:\n the user can upgrade to a new loader + application\n combo, even if an application image is not currently running.\n\n\nFunctionality container:\n the application image can directly access all the\n code present in the loader image\n\n\n\n\nFrom the perspective of the boot loader, a loader image is identical to a plain\nunified image. What makes a loader image different is a change to its start up\nsequence: rather
than starting the Mynewt OS, it jumps to the application image\nin slot 1 if one is present.\n\n\nTutorial\n\n\nBuilding a Split Image\n\n\nWe will be referring to the nRF51dk for examples in this document. Let's take\na look at this board's flash map (defined in \nhw/bsp/nrf51dk/bsp.yml\n):\n\n\n\n\n\n\n\n\nName\n\n\nOffset\n\n\nSize (kB)\n\n\n\n\n\n\n\n\n\n\nBoot loader\n\n\n0x00000000\n\n\n16\n\n\n\n\n\n\nReboot log\n\n\n0x00004000\n\n\n16\n\n\n\n\n\n\nImage slot 0\n\n\n0x00008000\n\n\n110\n\n\n\n\n\n\nImage slot 1\n\n\n0x00023800\n\n\n110\n\n\n\n\n\n\nImage scratch\n\n\n0x0003f000\n\n\n2\n\n\n\n\n\n\nFlash file system\n\n\n0x0003f800\n\n\n2\n\n\n\n\n\n\n\n\nThe application we will be building is \nbleprph\n.\nFirst, we create a target to tie our BSP and application together.\n\n\nnewt target create bleprph-nrf51dk\nnewt target set bleprph-nrf51dk \\\n app=@apache-mynewt-core/apps/bleprph \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk
\\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nThe two syscfg settings disable bluetooth security and keep the code size down.\n\n\nWe can verify the target using the \ntarget show\n command:\n\n\n[~/tmp/myproj2]$ newt target show bleprph-nrf51dk\ntargets/bleprph-nrf51dk\n app=@apache-mynewt-core/apps/bleprph\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nNext, build the target:\n\n\n[~/tmp/myproj2]$ newt build bleprph-nrf51dk\nBuilding target targets/bleprph-nrf51dk\n# [...]\nTarget successfully built: targets/bleprph-nrf51dk\n\n\n\n\n\nWith our target built, we can view a code size breakdown using the \nnewt size \ntarget\n command. In the interest of brevity, the smaller entries are excluded from the below output:\n\n\n[~/tmp/myproj2]$ newt size bleprph-nrf51dk\nSize of Application Image: app\n FLA
SH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 2959 697 hw_drivers_nimble_nrf51.a\n 4126 108 hw_mcu_nordic_nrf51xxx.a\n 8161 4049 kernel_os.a\n 2254 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1499 44 mgmt_newtmgr_nmgr_os.a\n 23918 1930 net_nimble_controller.a\n 28537 2779 net_nimble_host.a\n 2207 205 sys_config.a\n 1074 197 sys_console_full.a\n 3268 97 sys_log.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf\n\n\n\n\n\nThe full image text size is about 103kB (where 1kB = 1024 bytes). With an image slot size of 110kB,\nthis leaves only about 7kB of flash for addition
al application code and data.\nNot good. This is the situation we would be facing if we were using the\nUnified setup.\n\n\nThe Split setup can go a long way in solving our problem. Our unified bleprph\nimage consists mostly of components that get used during an image upgrade. By\nusing the Split setup, we turn the unified image into two separate images: the\nloader and the application. The functionality related to image upgrade can be\ndelegated to the loader image, freeing up a significant amount of flash in the\napplication image slot.\n\n\nLet's create a new target to use with the Split setup. We designate a target\nas a split target by setting the \nloader\n variable. In our example, we are\ngoing to use \nbleprph\n as the loader, and \nsplitty\n as the application.\n\nbleprph\n makes sense as a loader because it contains the BLE stack and\neverything else required for an image upgrade.\n\n\nnewt target create split-nrf51dk\nnewt target set split-nrf51dk
\\\n loader=@apache-mynewt-core/apps/bleprph \\\n app=@apache-mynewt-core/apps/splitty \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nVerify that the target looks correct:\n\n\n[~/tmp/myproj2]$ newt target show split-nrf51dk\ntargets/split-nrf51dk\n app=@apache-mynewt-core/apps/splitty\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n loader=@apache-mynewt-core/apps/bleprph\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nNow, let's build the new target:\n\n\n[~/tmp/myproj2]$ newt build split-nrf51dk\nBuilding target targets/split-nrf51dk\n# [...]\nTarget successfully built: targets/split-nrf51dk\n\n\n\n\n\nAnd look at the size breakdown (again, smaller entries are removed):\n\n\n[~/tmp/myproj2]$ newt size split-nrf51dk\nSize of Application Image: app\n FLASH
RAM\n 3064 251 sys_shell.a\n\nobjsize\n text data bss dec hex filename\n 4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf\n\nSize of Loader Image: loader\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 3168 705 hw_drivers_nimble_nrf51.a\n 4318 109 hw_mcu_nordic_nrf51xxx.a\n 8285 4049 kernel_os.a\n 2274 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1491 44 mgmt_newtmgr_nmgr_os.a\n 25169 1946 net_nimble_controller.a\n 31397 2827 net_nimble_host.a\n 2259 205 sys_config.a\n 1318 202 sys_console_full.a\n 3424 97 sys_log.a\n 1053 60 sys_stats.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n
112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf\n\n\n\n\n\nThe size command shows two sets of output: one for the application, and another\nfor the loader. The addition of the split functionality did make bleprph\nslightly bigger, but notice how small the application is: 4.5 kB! Where before\nwe only had 7 kB left, now we have 105.5 kB. Furthermore, all the\nfunctionality in the loader is available to the application at any time. For\nexample, if your application needs bluetooth functionality, it can use the BLE\nstack present in the loader instead of containing its own copy.\n\n\nFinally, let's deploy the split image to our nRF51dk board. The procedure here\nis the same as if we were using the Unified setup, i.e., via either the \nnewt load\n or \nnewt run\n command.\n\n\n[~/repos/mynewt/core]$ newt load split-nrf51dk 0\nLoading app image into slot 2\nLoading loader image into slot 1\n\n\n\n\n\nImage Managem
ent\n\n\nRetrieve Current State (image list)\n\n\nImage management in the split setup is a bit more complicated than in the\nunified setup. You can determine a device's image management state with the\n\nnewtmgr image list\n command. Here is how a device responds to this command\nafter our loader + application combo has been deployed:\n\n\n[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags:\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching\n\n\n\n\n\nThere are several interesting things about this response:\n\n\n\n\nTwo images:\n This is expected; we deployed both a loader image and an\napplication image.\n\n\nbootable flag:\n Notice slot 0's bootable flag is set, while slot 1's is\nnot. This tells us that slot 0
contains a loader and slot 1 contains an\napplication. If an image is bootable, it can be booted directly from the boot\nloader. Non-bootable images can only be started from a loader image.\n\n\nflags:\n Slot 0 is \nactive\n and \nconfirmed\n; none of slot 1's flags are set.\nThe \nactive\n flag indicates that the image is currently running; the\n\nconfirmed\n flag indicates that the image will continue to be used on\nsubsequent reboots. Slot 1's lack of enabled flags indicates that the image is\nnot being used at all.\n\n\nSplit status:\n The split status field tells you if the loader and\napplication are compatible. A loader + application combo is compatible only if\nboth images were built at the same time with \nnewt\n. If the loader and\napplication are not compatible, the loader will not boot into the application.\n\n\n\n\nEnabling a Split Application\n\n\nBy default, the application image in slot 1 is disabled. This is indicated in\nthe \nimage list\n response above. Wh
en you deploy a loader / application combo\nto your device, the application image won't actually run. Instead, the loader\nwill act as though an application image is not present and remain in \"loader\nmode\". Typically, a device in loader mode simply acts as an image management\nserver, listening for an image upgrade or a request to activate the application\nimage.\n\n\nUse the following command sequence to enable the split application image:\n\n\n\n\nTell device to \"test out\" the application image on next boot (\nnewtmgr image test \napplication-image-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change permanent (\nnewtmgr image confirm\n).\n\n\n\n\nAfter the above sequence, a \nnewtmgr image list\n command elicits the following response:\n\n\n[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n s
lot=1\n version: 0.0.0\n bootable: false\n flags: active confirmed\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching\n\n\n\n\n\nThe \nactive confirmed\n flags value on both slots indicates that both images are\npermanently running.\n\n\nImage Upgrade\n\n\nFirst, let's review of the image upgrade process for the Unified setup. The\nuser upgrades to a new image in this setup with the following steps:\n\n\nImage Upgrade - Unified\n\n\n\n\nUpload new image to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new image on next boot (\nnewtmgr image test \nimage-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake new image permanent (\nnewtmgr image confirm\n).\n\n\n\n\nImage Upgrade - Split\n\n\nThe image upgrade process is a bit more complicated in the Split setup. It is\nmore complicated because two images need to be upgraded (loader and\napplication) rather than just one. The split up
grade process is described\nbelow:\n\n\n\n\nDisable split functionality; we need to deactivate the application image in\n slot 1 (\nnewtmgr image test \ncurrent-loader-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change permanent (\nnewtmgr image confirm\n).\n\n\nUpload new loader to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new loader on next boot (\nnewtmgr image test \nnew-loader-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change of loader permanent (\nnewtmgr image confirm\n).\n\n\nUpload new application to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new application on next boot (\nnewtmgr image test \nnew-application-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change of application permanent (\nnewtmgr image confirm\n).\n\n\n\n\nWhen performing this process manually, it may be helpful to use \nimage list\n to\ncheck the image management
state as you go.\n\n\nSyscfg\n\n\nSyscfg is Mynewt's system-wide configuration mechanism. In a split setup,\nthere is a single umbrella syscfg configuration that applies to both the loader\nand the application. Consequently, overriding a value in an application-only\npackage potentially affects the loader (and vice-versa).\n\n\nLoaders\n\n\nThe following applications have been enabled as loaders. You may choose to\nbuild your own loader application, and these can serve as samples.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/bleprph\n\n\n\n\nSplit Apps\n\n\nThe following applications have been enabled as split applications. If you\nchoose to build your own split application these can serve as samples. Note\nthat slinky can be either a loader image or an application image.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/splitty\n\n\n\n\nTheory of Operation\n\n\nA split image is built as follows:\n\n\nFirst newt builds the applicatio
n and loader images separately to ensure they\nare consistent (no errors) and to generate elf files which can inform newt of\nthe symbols used by each part.\n\n\nThen newt collects the symbols used by both application and loader in two ways.\nIt collects the set of symbols from the \n.elf\n files. It also collects all the\npossible symbols from the \n.a\n files for each application.\n\n\nNewt builds the set of packages that the two applications share. It ensures\nthat all the symbols used in those packages are matching. NOTE: because of\nfeatures and #ifdefs, its possible for the two package to have symbols that are\nnot the same. In this case newt generates an error and will not build a split\nimage.\n\n\nThen newt creates the list of symbols that the two applications share from\nthose packages (using the .elf files).\n\n\nNewt re-links the loader to ensure all of these symbols are present in the\nloader application (by forcing the linker to include them in the \n.elf\n).\n\n\nN
ewt builds a special copy of the loader.elf with only these symbols (and the\nhandful of symbols discussed in the linking section above).\n\n\nFinally, newt links the application, replacing the common .a libraries with the\nspecial loader.elf image during the link.",
"title": "toc"
},
{
@@ -5062,138 +5062,88 @@
},
{
"location": "/os/modules/split/split/#description",
- "text": "Split images allow the user to build the application content separate from the library content by \nsplitting an application into two pieces: A \"loader\" which contains a separate application that can perform upgrades and manage split images. \nThe \"loader\" resides in slot 1. A \"split app\" which contains the main application content and references the libraries in the loader \nby static linkage. The \"split app\" resides in slot 2.",
+ "text": "The split image mechanism divides a target into two separate images: one\ncapable of image upgrade; the other containing application code. By isolating\nupgrade functionality to a separate image, the application can support\nover-the-air upgrade without dedicating flash space to network stack and\nmanagement code.",
"title": "Description"
},
{
- "location": "/os/modules/split/split/#goals",
- "text": "The goal of split images is to allow a larger application to run along with large components of \nmynewt such as nimble BLE stack and neutron flash file system(nffs) .",
- "title": "Goals"
- },
- {
"location": "/os/modules/split/split/#concept",
- "text": "In a typical mynewt application, an application is contained wholly within an image slot. Typically \nthere are at least two image slots since the image runs from one slot while uploading new code into \nthe second slot. Each image is capable of erasing and uploading another image. Each image is completely \nstand-alone; that is, each image contains all of the libraries and components that it needs. On a typical 256 kbyte flash, a flash layout might look like this: Name Size bootloader 16 k image slot 1 108 k image slot 2 108 k scratch 8 k Flash file system 16 k Now, suppose the desired image contains: Package Size nimble 69 k os 6 k logging 3 k imagemgr 3 k config 3 k nffs 15 k newtmgr 7 k which total 106k. With an image slot size of 108k this leaves only a small amount of code space \nremaining for the application. However, we can see that these packages contain everything you need to
upgrade and configure, so \nif we build a stand-alone loader with these components, we can build the app as a split image and \nget the entire second image slot to store application code and constant data.",
+ "text": "Mynewt supports three image setups: Setup Description Single One large image; upgrade not supported. Unified Two standalone images. Split Kernel in slot 0; application in slot 1. Each setup has its tradeoffs. The Single setup gives you the most flash space,\nbut doesn't allow you to upgrade after manufacturing. The Unified setup allows\nfor a complete failover in case a bad image gets uploaded, but requires a lot\nof redundancy in each image, limiting the amount of flash available to the\napplication. The Split setup sits somewhere between these two options. Before exploring the split setup in more detail, it might be helpful to get a\nbasic understanding of the Mynewt boot sequence. The boot process is\nsummarized below.",
"title": "Concept"
},
{
- "location": "/os/modules/split/split/#when-do-i-use-split-images",
- "text": "If your application fits into the available image slots, there is no advantage to using split \nimages. In general, split images are harder to debug and more complicated to upload. However \nfor a larger application, there may not be enough flash space to have two copies of the entire \napplication. This is when split image becomes necessary.",
- "title": "When do I use split images"
- },
- {
- "location": "/os/modules/split/split/#how-do-i-tell-newt-i-am-building-a-split-image",
- "text": "Newt looks for the variable loader in your target file. If it finds loader variable, it \nwill build a split image. For example, targets/app\n app=@apache-mynewt-core/apps/splitty\n loader=@apache-mynewt-core/apps/slinky\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized shows an application called splitty which uses slinky as its loader.",
- "title": "How do I tell Newt I am building a split image?"
- },
- {
- "location": "/os/modules/split/split/#platforms",
- "text": "Split image requires BSP support. The following BSPs support split images: hw/bsp/arduino_primo_nrf52 hw/bsp/bmd300eval hw/bsp/nrf51-blenano hw/bsp/nrf51dk hw/bsp/nrf51dk-16kbram hw/bsp/nrf52dk",
- "title": "Platforms"
- },
- {
- "location": "/os/modules/split/split/#loaders",
- "text": "The following applications have been enabled as loaders. You may choose to build your own loader \napplication, and these can serve as samples. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/bleprph",
- "title": "Loaders"
+ "location": "/os/modules/split/split/#boot-sequence-single",
+ "text": "In the Single setup, there is no boot loader. Instead, the image is placed at\naddress 0. The hardware boots directly into the image code. Upgrade is not\npossible because there is no boot loader to move an alternate image into place.",
+ "title": "Boot Sequence - Single"
},
{
- "location": "/os/modules/split/split/#split-apps",
- "text": "The following applications have been enabled as split applications. If you choose to build your own \nsplit application these can serve as samples. Note that slinky can be either a loader image or a split app image. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/splitty",
- "title": "Split Apps"
+ "location": "/os/modules/split/split/#boot-sequence-unified",
+ "text": "In the Unified setup, the boot loader is placed at address 0. At startup, the\nboot loader arranges for the correct image to be in image slot 0, which may\nentail swapping the contents of the two image slots. Finally, the boot loader\njumps to the image in slot 0.",
+ "title": "Boot Sequence - Unified"
},
{
- "location": "/os/modules/split/split/#theory-of-operation",
- "text": "A split image is built as follows: First newt builds the app and loader images separately to ensure they are consistent (no errors) and \nto generate elf files which can inform newt of the symbols used by each part. Then newt collects the symbols used by both app and loader in two ways. It collects the set of \nsymbols from the .elf files. It also collects all the possible symbols from the .a files for \neach application. Newt builds the set of packages that the two applications share. It ensures that all the symbols \nused in those packages are matching. NOTE: because of features and #ifdefs, its possible for the \ntwo package to have symbols that are not the same. In this case newt generates an error and will \nnot build a split image. Then newt creates the list of symbols that the two applications share from those packages (using the .elf files). Newt re-links the loader to ensure all of these symbols are present in the loader application
(by \nforcing the linker to include them in the .elf ). Newt builds a special copy of the loader.elf with only these symbols (and the handful of symbols \ndiscussed in the linking section above). Finally, newt links the application, replacing the common .a libraries with the special loader.elf \nimage during the link.",
- "title": "Theory of Operation"
+ "location": "/os/modules/split/split/#boot-sequence-split",
+ "text": "The Split setup differs from the other setups mainly in that a target is not\nfully contained in a single image. Rather, the target is partitioned among two\nseparate images: the loader , and the application . Functionality is divided\namong these two images as follows: Loader: Mynewt OS. Network stack for connectivity during upgrade e.g. BLE stack. Anything else required for image upgrade. Application: Parts of Mynewt not required for image upgrade. Application-specific code. The loader image serves three purposes: Second-stage boot loader: it jumps into the application image at\n start up. Image upgrade server: the user can upgrade to a new loader + application\n combo, even if an application image is not currently running. Functionality container: the application image can directly access all the\n code present in the loader image From the perspective of the boot loader, a loader image is identical to a plain\nunified ima
ge. What makes a loader image different is a change to its start up\nsequence: rather than starting the Mynewt OS, it jumps to the application image\nin slot 1 if one is present.",
+ "title": "Boot Sequence - Split"
},
{
- "location": "/os/modules/split/split/#design",
+ "location": "/os/modules/split/split/#tutorial",
"text": "",
- "title": "Design"
- },
- {
- "location": "/os/modules/split/split/#bootloader",
- "text": "The bootloader has been modified to support \"non bootable\" images like split app images. A flag in \nthe image header denotes the image as \"non-bootable\". When this flag is set, the bootloader will \nnot boot the split app image, nor will it copy it to the slot 1 location. Loader images are bootable, \nsplit app images are not.",
- "title": "Bootloader"
+ "title": "Tutorial"
},
{
- "location": "/os/modules/split/split/#newt",
- "text": "Newt builds a split image when the token loader=@apache-mynewt-core/apps/slinky is present in the target file. Newt has a Builder object that is responsible for building an image. This features a targetBuilder \nobject that contains two builders (one for the app and one for the loader). The Builder object has been expanded to include options for building as part of a split image. Ability to specify the linker file during the link Ability to specify a set of keep_symbols during the link Newt commands like download, size, create-image have been expanded to perform operations twice \n(once for loader and once for app) if the loader target is present. During normal single-image builds, the targetBuilder initializes and builds the application builder . During the split image build, the targetBuilder performs the steps outlined in the \nsection above using the two builder s for the loader and app. Special symbol and link features are designed as
follows: Newt uses objdump to parse the symbol maps in the .a and .elf files. Newt uses the --undefined= option of the linker to force the loader to keep symbols used by \nthe app (but not used by the linker) Newt uses objcopy with the -K (keep) option when building the special linker .elf . Newt uses the --just-symbols option of the linker to link against the loader .elf file.",
- "title": "Newt"
+ "location": "/os/modules/split/split/#building-a-split-image",
+ "text": "We will be referring to the nRF51dk for examples in this document. Let's take\na look at this board's flash map (defined in hw/bsp/nrf51dk/bsp.yml ): Name Offset Size (kB) Boot loader 0x00000000 16 Reboot log 0x00004000 16 Image slot 0 0x00008000 110 Image slot 1 0x00023800 110 Image scratch 0x0003f000 2 Flash file system 0x0003f800 2 The application we will be building is bleprph .\nFirst, we create a target to tie our BSP and application together. newt target create bleprph-nrf51dk\nnewt target set bleprph-nrf51dk \\\n app=@apache-mynewt-core/apps/bleprph \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 The two syscfg settings disable bluetooth security and keep the code size down. We can verify the target using the target show command: [~/tmp/myproj2]$
newt target show bleprph-nrf51dk\ntargets/bleprph-nrf51dk\n app=@apache-mynewt-core/apps/bleprph\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Next, build the target: [~/tmp/myproj2]$ newt build bleprph-nrf51dk\nBuilding target targets/bleprph-nrf51dk\n# [...]\nTarget successfully built: targets/bleprph-nrf51dk With our target built, we can view a code size breakdown using the newt size target command. In the interest of brevity, the smaller entries are excluded from the below output: [~/tmp/myproj2]$ newt size bleprph-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 2959 697 hw_drivers_nimble_nrf51.a\n 4126 108 hw_mcu_nordic_nrf51xxx.a\n 8161 4049 kernel_os.a\n
2254 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1499 44 mgmt_newtmgr_nmgr_os.a\n 23918 1930 net_nimble_controller.a\n 28537 2779 net_nimble_host.a\n 2207 205 sys_config.a\n 1074 197 sys_console_full.a\n 3268 97 sys_log.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf The full image text size is about 103kB (where 1kB = 1024 bytes). With an image slot size of 110kB,\nthis leaves only about 7kB of flash for additional application code and data.\nNot good. This is the situation we would be facing if we were using the\nUnified setup. The Split setup can go a long way in solving our problem. Our unified bleprph\nimage consists mostly of components that get used during an image upgrade. By\nusing the Split setup, we turn the unified image into tw
o separate images: the\nloader and the application. The functionality related to image upgrade can be\ndelegated to the loader image, freeing up a significant amount of flash in the\napplication image slot. Let's create a new target to use with the Split setup. We designate a target\nas a split target by setting the loader variable. In our example, we are\ngoing to use bleprph as the loader, and splitty as the application. bleprph makes sense as a loader because it contains the BLE stack and\neverything else required for an image upgrade. newt target create split-nrf51dk\nnewt target set split-nrf51dk \\\n loader=@apache-mynewt-core/apps/bleprph \\\n app=@apache-mynewt-core/apps/splitty \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Verify that the target looks correct: [~/tmp/myproj2]$ newt targe
t show split-nrf51dk\ntargets/split-nrf51dk\n app=@apache-mynewt-core/apps/splitty\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n loader=@apache-mynewt-core/apps/bleprph\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Now, let's build the new target: [~/tmp/myproj2]$ newt build split-nrf51dk\nBuilding target targets/split-nrf51dk\n# [...]\nTarget successfully built: targets/split-nrf51dk And look at the size breakdown (again, smaller entries are removed): [~/tmp/myproj2]$ newt size split-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 3064 251 sys_shell.a\n\nobjsize\n text data bss dec hex filename\n 4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf\n\nSize of Loader Image: loader\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2
390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 3168 705 hw_drivers_nimble_nrf51.a\n 4318 109 hw_mcu_nordic_nrf51xxx.a\n 8285 4049 kernel_os.a\n 2274 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1491 44 mgmt_newtmgr_nmgr_os.a\n 25169 1946 net_nimble_controller.a\n 31397 2827 net_nimble_host.a\n 2259 205 sys_config.a\n 1318 202 sys_console_full.a\n 3424 97 sys_log.a\n 1053 60 sys_stats.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf The size command shows two sets of output: one for the application, and another\nfor the loader. The addition of the split functionality did make bleprph\nslightly bigger, but notice how small the application is: 4.5 kB! Where before\nwe only had 7 kB left, now we have 105.5 kB.
Furthermore, all the\nfunctionality in the loader is available to the application at any time. For\nexample, if your application needs bluetooth functionality, it can use the BLE\nstack present in the loader instead of containing its own copy. Finally, let's deploy the split image to our nRF51dk board. The procedure here\nis the same as if we were using the Unified setup, i.e., via either the newt load or newt run command. [~/repos/mynewt/core]$ newt load split-nrf51dk 0\nLoading app image into slot 2\nLoading loader image into slot 1",
+ "title": "Building a Split Image"
},
{
- "location": "/os/modules/split/split/#newt-create-image",
- "text": "create-image uses two different methods to compute the image hash for standard and split images. \nFor split images, the hash is computed starting with the 32-byte hash of the loader, then continuing \nwith the hashing algorithm used by the standard application. This ensures that the split app can be \"validated\" against a loader image specifically.",
- "title": "newt create-image"
- },
- {
- "location": "/os/modules/split/split/#newt-errors",
- "text": "Newt has several new build errors when building split images. Linker script undefined. If the BSP for your application does not define a split image linker script \nthe build will fail. If newt finds that the same library (for example libs/os) has a different implementaiton in the loader \nand app, it will generate an error and fail to build. These differences can arise when #ifdef or features \nare included in one app and not the other. For example, it the loader includes libs/console/stubs and the \napp includes libs/console/full this may change implementations of certain functions within other packages.",
- "title": "newt errors"
- },
- {
- "location": "/os/modules/split/split/#image-manifest",
- "text": "newt builds a single manifest for split images, adding extra tags to the manifest when the image is a split image. loader : slinky.img ,\n loader_hash : 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0 ,\n loader_pkgs : [\n ...\n ] The manifest lists packages in both the loader and app. The app package list only contains those \npackages that reside in the app image itself.",
- "title": "Image manifest"
- },
- {
- "location": "/os/modules/split/split/#libsbootutil",
- "text": "Bootutil has been expanded to include a function that looks for a split app image in slot 2, verifies \nthat it matches the loader image in slot 1 and then fetches the entry information for the split app.",
- "title": "libs/bootutil"
- },
- {
- "location": "/os/modules/split/split/#libssplit",
- "text": "A small split image library was created to provide newtmgr commands for split image and to hold the \nconfiguration for split image. See newtmgr below for details. It also contains the function used by a loader to validate and boot a split image.",
- "title": "libs/split"
- },
- {
- "location": "/os/modules/split/split/#appsslinky",
- "text": "A sample app that can be built as a split image with slinky.",
- "title": "apps/slinky"
+ "location": "/os/modules/split/split/#image-management",
+ "text": "",
+ "title": "Image Management"
},
{
- "location": "/os/modules/split/split/#tips-when-building-split-images",
- "text": "To be added",
- "title": "Tips when Building Split images"
+ "location": "/os/modules/split/split/#retrieve-current-state-image-list",
+ "text": "Image management in the split setup is a bit more complicated than in the\nunified setup. You can determine a device's image management state with the newtmgr image list command. Here is how a device responds to this command\nafter our loader + application combo has been deployed: [~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags:\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching There are several interesting things about this response: Two images: This is expected; we deployed both a loader image and an\napplication image. bootable flag: Notice slot 0's bootable flag is set, while slot 1's is\nnot. This tells us that slot 0 contains a loader and slot 1 contains an\napplication. If
an image is bootable, it can be booted directly from the boot\nloader. Non-bootable images can only be started from a loader image. flags: Slot 0 is active and confirmed ; none of slot 1's flags are set.\nThe active flag indicates that the image is currently running; the confirmed flag indicates that the image will continue to be used on\nsubsequent reboots. Slot 1's lack of enabled flags indicates that the image is\nnot being used at all. Split status: The split status field tells you if the loader and\napplication are compatible. A loader + application combo is compatible only if\nboth images were built at the same time with newt . If the loader and\napplication are not compatible, the loader will not boot into the application.",
+ "title": "Retrieve Current State (image list)"
},
{
- "location": "/os/modules/split/split/#adding-bsp-support-for-split-images",
- "text": "A BSP needs additional components to be \"split image ready\". The split image requires a special linker script. The split image needs to run from the second image \npartition (since it's using the loader library that is linked to be placed in the first partition). \nIt needs to reserve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it). The startup of the split image is different than a typical image. It needs to copy .data from the \nloader image, and zero the loader image bss. For this, it must reference symbols defined in the linker \nscript of the loader. It has a special entry symbol that differentiates it from the entry symbol in the \nloader application. Several of the bsp scripts need to handle additional agruments to deal with the two images produced \nby newt when building split images - mainly download and debug. Add the following components to enable your BSP for split images: A split im
age linker file A startup file for the split image A property in the pkg.yml file to tell newt what linker script to use for partition 2 images. The property is defined as pkg.part2linkerscript: \"split-nrf52dk.ld for example. Modified download script Modified sbrk functionality An example can be found in the /hw/bsp/nrf52dk",
- "title": "Adding BSP support for split images"
+ "location": "/os/modules/split/split/#enabling-a-split-application",
+ "text": "By default, the application image in slot 1 is disabled. This is indicated in\nthe image list response above. When you deploy a loader / application combo\nto your device, the application image won't actually run. Instead, the loader\nwill act as though an application image is not present and remain in \"loader\nmode\". Typically, a device in loader mode simply acts as an image management\nserver, listening for an image upgrade or a request to activate the application\nimage. Use the following command sequence to enable the split application image: Tell device to \"test out\" the application image on next boot ( newtmgr image test application-image-hash ). Reboot device ( newtmgr reset ). Make above change permanent ( newtmgr image confirm ). After the above sequence, a newtmgr image list command elicits the following response: [~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags:
active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags: active confirmed\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching The active confirmed flags value on both slots indicates that both images are\npermanently running.",
+ "title": "Enabling a Split Application"
},
{
- "location": "/os/modules/split/split/#split-image-linker-script",
- "text": "The split image linker script must have the following. The split linker must be linked to run from the second flash image slot. For example: MEMORY \n{\n FLASH ( rx ) : ORIGIN = 0x00042000 , LENGTH = 0x3a000 \n RAM ( rwx ) : ORIGIN = 0x20000000 , LENGTH = 0x10000 \n} The split linker must define the entry symbol as Reset_Handler_split. For example: ENTRY ( Reset_Handler_split ) The split linker must define the first two words in the vector table (initial SP and Reset Vector). The additional \nvector entries are part of the loader and are not needed in the split image. The bootloader accesses these \nentries at the beginning of the image slot (first 2 words). For example: .text :\n {\n __split_isr_vector_start = .;\n KEEP(*(.isr_vector_split))\n __split_isr_vector_end = .;\n ... \n } The split linker must ensure that it doesn't overwrite the BSS and DATA sections of the loader (the
y are \nboth using RAM). Note, the two apps don't run at the same time, but the loader has global data that its \nlibraries use. This cannot be overwritten by the application. An example linker section that accomplishes \nthis can be found in /hw/bsp/nrf52dk/split-nrf52dk.ld . When linking against the loader, the loader exports \nthe following symbosl which can be used by the split app code: __HeapBase_loader __bss_start___loader __bss_end___loader __etext_loader __data_start___loader __data_end___loader The split app linker can use __HeapBase_loader to skip RAM used by the loader as follows. /* save RAM used by the split image. This assumes that * the loader uses all the RAM up to its HeapBase */ \n . loader_ram_contents :\n {\n _loader_ram_start = .;\n\n /* this symbol comes from the loader linker */ \n . = . + ( ABSOLUTE ( __HeapBase_loader ) - _loader_ram_start );\n _loader_ram_end = .;\n } RAM",
- "title": "split image linker script"
+ "location": "/os/modules/split/split/#image-upgrade",
+ "text": "First, let's review of the image upgrade process for the Unified setup. The\nuser upgrades to a new image in this setup with the following steps:",
+ "title": "Image Upgrade"
},
{
- "location": "/os/modules/split/split/#split-image-startup-code",
- "text": "The split application needs separate startup code to intialize the split image before running main. The \nsplit image is specially linked so that _start and main are included individually for the loader and split app. The split app startup code must have the following. A definition of the split image vector table (first two words). The entry point function to start the code Reset_Handler_split Code that copies the .data section for the loader from Flash to RAM Code that zeros the .bss section for the loader. Code that calls _sbrkInit to set the heap pointers for the application (see below) Code that calls the bsp_slot_init_split_application function (see below) An example can be found in the /hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s",
- "title": "split image startup code"
+ "location": "/os/modules/split/split/#image-upgrade-unified",
+ "text": "Upload new image to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new image on next boot ( newtmgr image test image-hash ). Reboot device ( newtmgr reset ). Make new image permanent ( newtmgr image confirm ).",
+ "title": "Image Upgrade - Unified"
},
{
- "location": "/os/modules/split/split/#download-script",
- "text": "The download script needs to be modified to include support for passing the image slot number in the build. \nImage slots are referenced as 0 and 1. Loading bootloaders ignore the image slot numbers. See and example in /hw/bsp/bmd300eval/bmd300eval_download.sh .",
- "title": "Download script"
+ "location": "/os/modules/split/split/#image-upgrade-split",
+ "text": "The image upgrade process is a bit more complicated in the Split setup. It is\nmore complicated because two images need to be upgraded (loader and\napplication) rather than just one. The split upgrade process is described\nbelow: Disable split functionality; we need to deactivate the application image in\n slot 1 ( newtmgr image test current-loader-hash ). Reboot device ( newtmgr reset ). Make above change permanent ( newtmgr image confirm ). Upload new loader to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new loader on next boot ( newtmgr image test new-loader-hash ). Reboot device ( newtmgr reset ). Make above change of loader permanent ( newtmgr image confirm ). Upload new application to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new application on next boot ( newtmgr image test new-application-hash ). Reboot device ( newtmgr reset ). Make above change of application permanent (
newtmgr image confirm ). When performing this process manually, it may be helpful to use image list to\ncheck the image management state as you go.",
+ "title": "Image Upgrade - Split"
},
{
- "location": "/os/modules/split/split/#sbrk-functionality",
- "text": "Split image (either a loader or app) references a single set of heap managment functions. But the heap location and \nsize is different depending which image is running. Special functionality is needed to handle the dynamic \nsetting of the heap base and limit. Instead of hard-coding the heap base and limit at link time (depending on the size of data and bss), sbrk \nneeds to be dynamically initialized with these values from the startup code. See an example in /hw/bsp/bmd300eval/src/sbrk.c in the core repository. The function _sbrkInit must be \ncalled from the startup code of the split image and normal image startup code with the appropriate \nvalues of heap base and limit.",
- "title": "Sbrk functionality"
+ "location": "/os/modules/split/split/#syscfg",
+ "text": "Syscfg is Mynewt's system-wide configuration mechanism. In a split setup,\nthere is a single umbrella syscfg configuration that applies to both the loader\nand the application. Consequently, overriding a value in an application-only\npackage potentially affects the loader (and vice-versa).",
+ "title": "Syscfg"
},
{
- "location": "/os/modules/split/split/#slot-init",
- "text": "A global variable tells Mynewt whether the split image is runnning as just a stand-alone loader, or as \nthe combined loader/app image. Its the responsibility of the startup code to set this global variable. See hw/bsp/bmd300eval/src/os_bsp.c for and implementation of the functionality.",
- "title": "Slot Init"
+ "location": "/os/modules/split/split/#loaders",
+ "text": "The following applications have been enabled as loaders. You may choose to\nbuild your own loader application, and these can serve as samples. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/bleprph",
+ "title": "Loaders"
},
{
- "location": "/os/modules/split/split/#newtmgr-and-split-images",
- "text": "newtmgr has support for split images. newtmgr image list lists the current images in the flash. Its clear from the output that some images are non-bootable. For example. Images:\n slot=1\n version=1.2.3\n bootable=true\n hash=55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n slot=2\n version=1.2.3\n bootable=false\n hash=1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the boot2 \ncommand to instruct mynewt to boot slot 2. Instead, use the new split status command to see the status of split images and to set their boot status. \nThe split status command with no arguments returns status of the split image. The Split Value tells the loader \nhow to boot the split app. Options are: none Don't boot the split application. Just remain running in the loader. test Boot the split application, but re
vert back to the loader on the next reset. run Boot the split application. The split status command also verified the hash of the split application (using the hash of the loader \nas shown above) and returns the status of the check (matching or non-matching). newtmgr -c connection split status\n Split value is none\n Split status is matching When the split image application is running, the active hash in the boot2 command will match the \nhash of the split application (in slot 2). For example: prompt$ newtmgr -c foo1 image boot\n Test image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Main image: 55e254f133bedf640fc7be7b5bfe3e5fb387cf5e29ecd0d4ea02b5ba617e27e0\n Active img: 1697bd1658f7e902e0191094c5f729446c9dd790c00a58e2bb37f56d6fcb72fe",
- "title": "newtmgr and split Images"
+ "location": "/os/modules/split/split/#split-apps",
+ "text": "The following applications have been enabled as split applications. If you\nchoose to build your own split application these can serve as samples. Note\nthat slinky can be either a loader image or an application image. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/splitty",
+ "title": "Split Apps"
},
{
- "location": "/os/modules/split/split/#upgrading-a-split-image-with-newtmgr",
- "text": "When running via newt, the newt load command will load both parts of a split image, the loader and application. When running via newtmgr a sequence of commands is required to upgrade. Assuming you are running the \nsplit app in run mode the following sequence will upgrade newtmgr split status none newtmgr reboot newtmgr image upload newtmgr image boot2 newtmgr reboot newtmgr image upload newtmgr split status test newtmgr reboot newtmgr boot2 (check status to ensure new app is running) newtmgr split status run This upgrade is robust. In all steps there is a loader image that is capable of upgrading (or reverting) images.",
- "title": "Upgrading a split image with newtmgr"
+ "location": "/os/modules/split/split/#theory-of-operation",
+ "text": "A split image is built as follows: First newt builds the application and loader images separately to ensure they\nare consistent (no errors) and to generate elf files which can inform newt of\nthe symbols used by each part. Then newt collects the symbols used by both application and loader in two ways.\nIt collects the set of symbols from the .elf files. It also collects all the\npossible symbols from the .a files for each application. Newt builds the set of packages that the two applications share. It ensures\nthat all the symbols used in those packages are matching. NOTE: because of\nfeatures and #ifdefs, its possible for the two package to have symbols that are\nnot the same. In this case newt generates an error and will not build a split\nimage. Then newt creates the list of symbols that the two applications share from\nthose packages (using the .elf files). Newt re-links the loader to ensure all of these symbols are present in the\nloader applic
ation (by forcing the linker to include them in the .elf ). Newt builds a special copy of the loader.elf with only these symbols (and the\nhandful of symbols discussed in the linking section above). Finally, newt links the application, replacing the common .a libraries with the\nspecial loader.elf image during the link.",
+ "title": "Theory of Operation"
},
{
"location": "/os/modules/bootloader/bootloader/",
@@ -5397,7 +5347,7 @@
},
{
"location": "/os/modules/fs/fs/fs/",
- "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the \nfs/fs\n package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nThe following example illustrates how file system dependencies should be managed.
In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called \nfs/nffs\n (Newtron Flash File System). The app explicitly initializes nffs via calls to \nnffs_init()\n, \nnffs_detect()\n and \nnffs_format()\n.\n\n\n# repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/nffs\n\n# [...]\n\n\n\n\n\n/* repos/apache-mynewt-core/apps/slinky/src/main.c */\n\n\n\n#include \nnffs/nffs.h\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\nNFFS_AREA_MAX\n];\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\
n) {\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n// [...]\n\n}\n\n\n\n\n\nOn the other hand, code which uses the file system after it has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to
client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfs_close\n\n\nCloses the specified file and invalidates the file handle.\n\n\n\n\n\n\nfs_closedir\n\n\nCloses the specified directory handle.\n\n\n\n\n\n\nfs_dirent_is_dir\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file.\n\n\n\n\n\n\nfs_dirent_name\n\n\nRetrieves the filename of the specified directory entry.\n\n\n\n\n\n\nfs_filelen\n\n\nRetrieves the current length of the specified open file.\n\n\n\n\n\n\nfs_getpos\n\n\nRetrieves the current read and write position of the specified open file.\n\n\n\n\n\n\nfs_mkdir\n\n\nCreates the directory represented by the specified path.\n\n\n\n\n\n\nfs
_open\n\n\nOpens a file at the specified path.\n\n\n\n\n\n\nfs_opendir\n\n\nOpens the directory at the specified path.\n\n\n\n\n\n\nfs_read\n\n\nReads data from the specified file.\n\n\n\n\n\n\nfs_readdir\n\n\nReads the next entry in an open directory.\n\n\n\n\n\n\nfs_register\n\n\nRegisters a file system with the abstraction layer.\n\n\n\n\n\n\nfs_rename\n\n\nPerforms a rename and/or move of the specified source path to the specified destination.\n\n\n\n\n\n\nfs_seek\n\n\nPositions a file's read and write pointer at the specified offset.\n\n\n\n\n\n\nfs_unlink\n\n\nUnlinks the file or directory at the specified path.\n\n\n\n\n\n\nfs_write\n\n\nWrites the supplied data to the current offset of the specified file handle.\n\n\n\n\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfsutil_read_file\n\n\nOpens a file at the specified path, retrieve data from the file starting from th
e specified offset, and close the file and invalidate the file handle.\n\n\n\n\n\n\nfsutil_write_file\n\n\nOpen a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
+ "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the\n\nfs/fs\n package.\nIn terms of the Mynewt hierarchy, an \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nApplications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.\nIn the following example, the \nNewtron Flash File System\n\nis used.\n\n\n# repos/apa
che-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/fs # include the file operations interfaces\n - fs/nffs # include the NFFS filesystem implementation\n\n\n\n\n\n# repos/apache-mynewt-core/apps/slinky/syscfg.yml\n# [...]\n # Package: apps/\nexample app\n\n# [...]\n CONFIG_NFFS: 1 # initialize and configure NFFS into the system\n# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues \n# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect\n\n# [...]\n\n\n\n\n\nConsult the documentation for \nnffs\n for a more detailed explanation of NFFS_DETECT_FAIL\n\n\nCode which uses the file system after the system has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depe
nds on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfs_close\n\n\nCloses the specified file and invalidates the file handle.\n\n\n\n\n\n\nfs_closedir\n\n\nCloses the specified directory ha
ndle.\n\n\n\n\n\n\nfs_dirent_is_dir\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file.\n\n\n\n\n\n\nfs_dirent_name\n\n\nRetrieves the filename of the specified directory entry.\n\n\n\n\n\n\nfs_filelen\n\n\nRetrieves the current length of the specified open file.\n\n\n\n\n\n\nfs_getpos\n\n\nRetrieves the current read and write position of the specified open file.\n\n\n\n\n\n\nfs_mkdir\n\n\nCreates the directory represented by the specified path.\n\n\n\n\n\n\nfs_open\n\n\nOpens a file at the specified path.\n\n\n\n\n\n\nfs_opendir\n\n\nOpens the directory at the specified path.\n\n\n\n\n\n\nfs_read\n\n\nReads data from the specified file.\n\n\n\n\n\n\nfs_readdir\n\n\nReads the next entry in an open directory.\n\n\n\n\n\n\nfs_register\n\n\nRegisters a file system with the abstraction layer.\n\n\n\n\n\n\nfs_rename\n\n\nPerforms a rename and/or move of the specified source path to the specified destination.\n\n\n\n\n\n\nfs_seek\n\n\nPositions a fil
e's read and write pointer at the specified offset.\n\n\n\n\n\n\nfs_unlink\n\n\nUnlinks the file or directory at the specified path.\n\n\n\n\n\n\nfs_write\n\n\nWrites the supplied data to the current offset of the specified file handle.\n\n\n\n\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfsutil_read_file\n\n\nOpens a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\n\n\n\n\nfsutil_write_file\n\n\nOpen a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
"title": "toc"
},
{
@@ -5407,7 +5357,7 @@
},
{
"location": "/os/modules/fs/fs/fs/#description",
- "text": "Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the fs/fs package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the app package must depend on a specific file system package, while library packages should only depend on fs/fs . The following example illustrates how file system dependencies should be managed. In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called fs/nffs (Newtron Flash File System). The app explicitly initializes nffs via calls to nffs_init() , nffs_detect() and nffs_format() . # repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/nffs\n\n# [...] /* repos/apache-mynewt-c
ore/apps/slinky/src/main.c */ #include nffs/nffs.h int main ( int argc , char **argv )\n{\n int rc ;\n int cnt ;\n struct nffs_area_desc descs [ NFFS_AREA_MAX ];\n\n rc = nffs_init ();\n assert ( rc == 0 );\n\n cnt = NFFS_AREA_MAX ;\n rc = flash_area_to_nffs_desc ( FLASH_AREA_NFFS , cnt , descs );\n assert ( rc == 0 );\n if ( nffs_detect ( descs ) == FS_ECORRUPT ) {\n rc = nffs_format ( descs );\n assert ( rc == 0 );\n }\n // [...] \n} On the other hand, code which uses the file system after it has been initialized need only depend on fs/fs . For example, the libs/imgmgr package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the fs/fs package. # repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/i
mgmgr\npkg.deps:\n - fs/fs\n\n# [...] The libs/imgmgr package uses the fs/fs API for all file system operations.",
+ "text": "Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the fs/fs package.\nIn terms of the Mynewt hierarchy, an app package must depend on a specific file system package, while library packages should only depend on fs/fs . Applications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.\nIn the following example, the Newtron Flash File System \nis used. # repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/fs # include the file operations interfaces\n - fs/nffs # include the NFFS filesystem implementation # repos/apache-mynewt-core/apps/slinky/syscfg.yml\n# [...]\n # Package: apps/ example app \n# [...]\n CONFIG_NFFS: 1 # initialize and configure NFFS into the system\n# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection is
sues \n# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect\n\n# [...] Consult the documentation for nffs for a more detailed explanation of NFFS_DETECT_FAIL Code which uses the file system after the system has been initialized need only depend on fs/fs . For example, the libs/imgmgr package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the fs/fs package. # repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...] The libs/imgmgr package uses the fs/fs API for all file system operations.",
"title": "Description"
},
{
@@ -6047,7 +5997,7 @@
},
{
"location": "/os/modules/fs/nffs/nffs/",
- "text": "Newtron Flash Filesystem (nffs)\n\n\nMynewt includes the Newtron Flash File System (nffs). This file system is designed with two priorities that makes it suitable for embedded use: \n\n\n\n\nMinimal RAM usage\n\n\nReliability\n\n\n\n\nMynewt also provides an abstraction layer API (fs) to allow you to swap out nffs with a different file system of your choice.\n\n\nDescription\n\n\nAreas\n\n\nAt the top level, an nffs disk is partitioned into \nareas\n. An area is a region of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nWriting to one area does not restrict writes to other areas.\n\n\n\n\nRegarding property 1:\n Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible.\n\n\nRegarding property 2:\n Furthermore, some flash hardware imposes a restriction with regards to writes: writes
within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.\n\n\nThus, each area must comprise a discrete number of blocks.\n\n\
<TRUNCATED>
[5/5] incubator-mynewt-site git commit: Split image documentation
updated
Posted by ad...@apache.org.
Split image documentation updated
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/7eec4897
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/7eec4897
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/7eec4897
Branch: refs/heads/asf-site
Commit: 7eec48971b6cb427f621680bb4706ddc1f708c16
Parents: cbe9ead
Author: aditihilbert <ad...@runtime.io>
Authored: Wed Jan 11 21:43:59 2017 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Wed Jan 11 21:43:59 2017 -0800
----------------------------------------------------------------------
develop/mkdocs/search_index.json | 161 ++---
develop/os/modules/devmgmt/newtmgr/index.html | 2 +-
develop/os/modules/fs/fs/fs/index.html | 46 +-
develop/os/modules/fs/nffs/nffs/index.html | 65 +-
develop/os/modules/split/split/index.html | 677 +++++++++++----------
develop/sitemap.xml | 24 +-
latest/mkdocs/search_index.json | 161 ++---
latest/os/modules/devmgmt/newtmgr/index.html | 2 +-
latest/os/modules/fs/fs/fs/index.html | 46 +-
latest/os/modules/fs/nffs/nffs/index.html | 65 +-
latest/os/modules/split/split/index.html | 677 +++++++++++----------
latest/sitemap.xml | 24 +-
sitemap.xml | 26 +-
v0_9_0/sitemap.xml | 26 +-
14 files changed, 934 insertions(+), 1068 deletions(-)
----------------------------------------------------------------------