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>
