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 2016/08/29 22:59:06 UTC
[2/2] incubator-mynewt-site git commit: Minor edits to split.md such
as specifying image slots 1 and 2 and fixing example references
Minor edits to split.md such as specifying image slots 1 and 2 and fixing example references
This closes #112
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/468bc7f0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/468bc7f0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/468bc7f0
Branch: refs/heads/develop
Commit: 468bc7f0623476c58c95c15b68eb51f790c134c5
Parents: d8bcd01
Author: aditihilbert <ad...@runtime.io>
Authored: Mon Aug 29 15:57:48 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Mon Aug 29 15:57:59 2016 -0700
----------------------------------------------------------------------
docs/os/modules/split/split.md | 59 ++++++++++++++++++++-----------------
1 file changed, 32 insertions(+), 27 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/468bc7f0/docs/os/modules/split/split.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/split/split.md b/docs/os/modules/split/split.md
index e2df2aa..cd99def 100644
--- a/docs/os/modules/split/split.md
+++ b/docs/os/modules/split/split.md
@@ -6,18 +6,18 @@
Split images allow the user to build the application content separate from the library content by splitting an application into two pieces:
-* A "loader" which contains a separate application that can perform upgrades and manage split images
-* A "split app" which contains the main application content and references the libraries in the loader by static linkage
+* A "loader" which contains a separate application that can perform upgrades and manage split images. The "loader" resides in slot 1.
+* 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.
## Goals
-The goal of split images is to allow a larger applicaition to run along with large components of mynewt such as [nimble BLE stack](../../../network/ble/ble_intro/) and [neutron flash file system(nffs)](../fs/nffs/nffs.md).
+The goal of split images is to allow a larger application to run along with large components of mynewt such as [nimble BLE stack](../../../network/ble/ble_intro/) and [neutron flash file system(nffs)](../fs/nffs/nffs.md).
## Concept
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.
-On a typical 256 kbyte flash, there a flash layout might look like this
+On a typical 256 kbyte flash, a flash layout might look like this:
| Name | Size |
|---|---|
@@ -47,7 +47,7 @@ However, we can see that these packages contain everything you need to upgrade a
## When do I use split images
-If you 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 larger application, there may not be enough flash space to have two copies of the entire application. This is when split image becomes necessary.
+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.
## How do I tell Newt I am building a split image?
@@ -70,14 +70,14 @@ Split image requires BSP support. The following BSPs support split images:
## Loaders
-The following applications have been enabled as loaders. Of course you can build your own loader application, but these can serve as samples.
+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. Of course you can build your own split application, but these can serve as samples.
+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.
* @apache-mynewt-core/apps/slinky
* @apache-mynewt-core/apps/splitty
@@ -90,11 +90,11 @@ First newt builds the `app` and `loader` images separately to ensure they are co
Then newt collects the symbols used by both `app` 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 application 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.
+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 create the list of symbols that the two applications share from those packages (using the .elf files).
+Then newt creates the list of symbols that the two applications share from those packages (using the .elf files).
-Newt re-links the loader ensure all of these symbols are present in the loader application (by forcing the linker to include them in the `.elf`).
+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).
@@ -104,13 +104,13 @@ Finally, newt links the application, replacing the common .a libraries with the
### Bootloader
-The bootloader 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 image, nor will it copy it to the slot 0 location. Loader images are bootable, split app images are not.
+The bootloader 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.
### Newt
Newt builds a split image when the token `loader=@apache-mynewt-core/apps/slinky` is present in the target file.
-Newt has a `buider` object that is responsible for building an image. This features create a `targetBuilder` object that contains two builders (one for the app and one for the loader).
+Newt has a `Builder` object that is responsible for building an image. This features a `targetBuilder` object 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
@@ -118,7 +118,7 @@ The `Builder` object has been expanded to include options for building as part o
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.
-During normal single-image builds, the `targetBuilder` initializes and builds the application `builder`. During the split image build, the target builder performs the steps outlined in the section above using the two `builder`s for the loader and app.
+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 section above using the two `builder`s for the loader and app.
Special symbol and link features are designed as follows:
@@ -129,14 +129,13 @@ Special symbol and link features are designed as follows:
#### newt create-image
-Create image uses two different methods to compute the image has for standard and split images. For split images, the hash is computed starting with the 32-byte hash of the loader, the continuing with the hashing algorithm used by the standard application. This ensures that the split app can be "validated" against a loader image specifically.
+Create image uses two different methods to compute the image hash for standard and split images. 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.
#### newt errors
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 the build will fail.
-*
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 `#ifdef` or features are included in one app and not the other. For example, it the loader includes `libs/console/stubs` and the app includes `libs/console/full` this may change implementations of certain functions within other packages.
@@ -156,30 +155,31 @@ The manifest lists packages in both the loader and app. The app package list on
### libs/bootutil
-Bootutil has been expanded to include a function that looks for a split app image in slot one, verifies that it matches the loader image in slot 0 and then fetches the entry information for the split app.
+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.
### libs/split
-A small split image library was create to provide newtmgr commands for split image and to hold the configuration for split image. See newtmgr below for details.
+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.
It also contains the function used by a loader to validate and boot a split image.
### apps/slinky
-A sample app that can be build as a split image with slinky.
+A sample app that can be built as a split image with slinky.
-## Tips when Building SPlit images
+## Tips when Building Split images
+**To be added**
## Adding BSP support for split images
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 paritition (since its using the loader library that is linked to be placed in the first parition). It needs to reseve space for RAM used by the loader. It also does not need to include the vector table (just a bit of it).
+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). 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).
-The startup of the split image is different than a typical image. It needs to copy `.data` 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 differntiates it from the entry symbol in the loader application.
+The startup of the split image is different than a typical image. It needs to copy `.data` 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.
-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.
+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.
Add the following components to enable your BSP for split images:
@@ -194,11 +194,14 @@ An example can be found in the `/hw/bsp/nrf52dk`
The split image linker script must have the following.
-The split linker must define the entry symbol as Reset_Handler_split. For example
+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 vector entries are part of the loader. the bootloader accesses these entries at the beginning of the image slot (first 2 words). For example:
+
+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. The bootloader accesses these entries at the beginning of the image slot (first 2 words). For example:
+
```
.text :
{
@@ -207,7 +210,8 @@ The split linker must define the first two words in the vector table (initial SP
__split_isr_vector_end = .;
...
```
-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. When linking against the loader, the loader exports the following symbosl which can be used by the split app code:
+
+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 `/hw/bsp/nrf52dk/split-nrf52dk.ld`. When linking against the loader, the loader exports the following symbosl which can be used by the split app code:
* `__HeapBase_loader`
* `__bss_start___loader`
@@ -230,9 +234,10 @@ The split app linker can use `__HeapBase_loader` to skip RAM used by the loader
_loader_ram_end = .;
} > RAM
```
+
### split image startup code
-The splt application needs separate startup code to intialize the split image before running main. THe split image is specially linked so that _start and main are included individually for the loader and split app.
+The split application needs separate startup code to intialize the split image before running main. THe split 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.
@@ -264,7 +269,7 @@ Images:
The bootloader is unable to boot split app images (of course it can boot the loader images), so do not use the `boot2` command 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. 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
+Instead, use the new `split status` command to see the status of split images and to set their boot status. 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:
* `none` Don't boot the split application. Just remain running in the loader.
* `test` Boot the split application, but revert back to the loader on the next reset.