Split Images
============

Description
-----------

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.

Concept
-------

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, 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.

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.

Boot Sequence - Single
^^^^^^^^^^^^^^^^^^^^^^

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.

Boot Sequence - Unified
^^^^^^^^^^^^^^^^^^^^^^^

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.

Boot Sequence - Split
^^^^^^^^^^^^^^^^^^^^^

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 *loader*, and the *application*.
Functionality is divided among these two images as follows:

1. Loader:

   -  Mynewt OS.
   -  Network stack for connectivity during upgrade e.g. BLE stack.
   -  Anything else required for image upgrade.

2. Application:

   -  Parts of Mynewt not required for image upgrade.
   -  Application-specific code.

The loader image serves three purposes:

1. *Second-stage boot loader:* it jumps into the application image at
   start up.
2. *Image upgrade server:* the user can upgrade to a new loader +
   application combo, even if an application image is not currently
   running.
3. *Functionality container:* the application image can directly access
   all the code present in the loader image

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.

Tutorial
--------

Building a Split Image
~~~~~~~~~~~~~~~~~~~~~~

We will be referring to the Nordic PCA10028 (nRF51 DK) for examples in
this document. Let's take a look at this board's flash map (defined in
``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 <../../tutorials/bleprph>`__. First, we create a target to tie
our BSP and application together.

::

    newt target create bleprph-nrf51dk
    newt target set bleprph-nrf51dk                     \
        app=@apache-mynewt-core/apps/bleprph            \
        bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028  \
        build_profile=optimized                         \
        syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0

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
    targets/bleprph-nrf51dk
        app=@apache-mynewt-core/apps/bleprph
        bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028
        build_profile=optimized
        syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0

Next, build the target:

::

    [~/tmp/myproj2]$ newt build bleprph-nrf51dk
    Building target targets/bleprph-nrf51dk
    # [...]
    Target 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
    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

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.

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.

Let's create a new target to use with the Split setup. We designate a
target as a split target by setting the ``loader`` variable. In our
example, we are going to use ``bleprph`` as the loader, and ``splitty``
as the application. ``bleprph`` makes sense as a loader because it
contains the BLE stack and everything else required for an image
upgrade.

::

    newt target create split-nrf51dk
    newt target set split-nrf51dk                       \
        loader=@apache-mynewt-core/apps/bleprph         \
        app=@apache-mynewt-core/apps/splitty            \
        bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028  \
        build_profile=optimized                         \
        syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0

Verify that the target looks correct:

::

    [~/tmp/myproj2]$ newt target show split-nrf51dk
    targets/split-nrf51dk
        app=@apache-mynewt-core/apps/splitty
        bsp=@apache-mynewt-core/hw/bsp/nordic_pca10028
        build_profile=optimized
        loader=@apache-mynewt-core/apps/bleprph
        syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0

Now, let's build the new target:

::

    [~/tmp/myproj2]$ newt build split-nrf51dk
    Building target targets/split-nrf51dk
    # [...]
    Target successfully built: targets/split-nrf51dk

And look at the size breakdown (again, smaller entries are removed):

::

    [~/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

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.

Finally, let's deploy the split image to our Nordic PCA10028 (nRF51 DK) board.
The procedure here is the same as if we were using the Unified setup, i.e.,
via either the ``newt load`` or ``newt run`` command.

::

    [~/repos/mynewt/core]$ newt load split-nrf51dk 0
    Loading app image into slot 2
    Loading loader image into slot 1

Image Management
~~~~~~~~~~~~~~~~

Retrieve Current State (image list)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 ``newtmgr image list`` command. Here is how a device responds
to this command after our loader + application combo has been deployed:

::

    [~/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

There are several interesting things about this response:

1. *Two images:* This is expected; we deployed both a loader image and
   an application image.
2. *bootable flag:* 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.
3. *flags:* Slot 0 is ``active`` and ``confirmed``; none of slot 1's
   flags are set. The ``active`` flag indicates that the image is
   currently running; the ``confirmed`` 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.
4. *Split status:* 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
   ``newt``. If the loader and application are not compatible, the
   loader will not boot into the application.

Enabling a Split Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the application image in slot 1 is disabled. This is
indicated in the ``image list`` 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.

Use the following command sequence to enable the split application
image:

1. Tell device to "test out" the application image on next boot
   (``newtmgr image test <application-image-hash>``).
2. Reboot device (``newtmgr reset``).
3. 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
    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

The ``active confirmed`` flags value on both slots indicates that both
images are permanently running.

Image Upgrade
~~~~~~~~~~~~~

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:

Image Upgrade - Unified
^^^^^^^^^^^^^^^^^^^^^^^

1. Upload new image to slot 1 (``newtmgr image upload <filename>``).
2. Tell device to "test out" the new image on next boot
   (``newtmgr image test <image-hash>``).
3. Reboot device (``newtmgr reset``).
4. Make new image permanent (``newtmgr image confirm``).

Image Upgrade - Split
^^^^^^^^^^^^^^^^^^^^^

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:

1.  Disable split functionality; we need to deactivate the application
    image in slot 1 (``newtmgr image test <current-loader-hash>``).
2.  Reboot device (``newtmgr reset``).
3.  Make above change permanent (``newtmgr image confirm``).
4.  Upload new loader to slot 1 (``newtmgr image upload <filename>``).
5.  Tell device to "test out" the new loader on next boot
    (``newtmgr image test <new-loader-hash>``).
6.  Reboot device (``newtmgr reset``).
7.  Make above change of loader permanent (``newtmgr image confirm``).
8.  Upload new application to slot 1
    (``newtmgr image upload <filename>``).
9.  Tell device to "test out" the new application on next boot
    (``newtmgr image test <new-application-hash>``).
10. Reboot device (``newtmgr reset``).
11. Make above change of application permanent
    (``newtmgr image confirm``).

When performing this process manually, it may be helpful to use
``image list`` to check the image management state as you go.

Syscfg
------

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).

Loaders
-------

The following applications have been enabled as loaders. You may choose
to build your own loader application, and these can serve as samples.

-  @apache-mynewt-core/apps/slinky
-  @apache-mynewt-core/apps/bleprph

Split Apps
----------

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.

-  @apache-mynewt-core/apps/slinky
-  @apache-mynewt-core/apps/splitty

Theory of Operation
-------------------

A split image is built as follows:

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.

Then newt collects the symbols used by both application and loader in
two ways. It collects the set of symbols from the ``.elf`` files. It
also collects all the possible symbols from the ``.a`` files for each
application.

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.

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 forcing 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 discussed in the linking section above).

Finally, newt links the application, replacing the common .a libraries
with the special loader.elf image during the link.