Rearrange docs for gh-pages
Github pages allows the documentation to be in the master branch in a
'docs' directory to be rendered as the main site (mcuboot.com). Rename
this directory, and pull in the documentation files from the old
gh-pages branch.
The main index.md page does not link to the rest of the docs yet, and
that change can be made in a future patch.
Signed-off-by: David Brown <david.brown@linaro.org>
diff --git a/docs/PORTING.md b/docs/PORTING.md
new file mode 100644
index 0000000..d40bb3d
--- /dev/null
+++ b/docs/PORTING.md
@@ -0,0 +1,126 @@
+# Porting How-To
+
+This document describes the requirements and necessary steps required to port
+`mcuboot` to a new target `OS`.
+
+# Requirements
+
+* `mcuboot` requires that the target provides a `flash` API with ability to
+ get the flash's minimum write size, and read/write/erase individual sectors.
+
+* `mcuboot` doesn't bundle a cryptographic library, which means the target
+ OS must already have it bundled. The supported libraries at the moment are
+ either `mbed TLS` or the set `tinycrypt` + `mbed TLS` (where `mbed TLS` is
+ used to provide functionality not existing in `tinycrypt`).
+
+# Steps to port
+
+## Main app and calling the bootloader
+
+From the perspective of the target OS, the bootloader can be seen as a library,
+so an entry point must be provided. This is likely a typical `app` for the
+target OS, and it must call the following function to run the bootloader:
+
+```c
+int boot_go(struct boot_rsp *rsp);
+```
+
+This function is located at `boot/bootutil/loader.c` and receives a `struct
+boot_rsp` pointer. The `struct boot_rsp` is defined as:
+
+```c
+struct boot_rsp {
+ /** A pointer to the header of the image to be executed. */
+ const struct image_header *br_hdr;
+
+ /**
+ * The flash offset of the image to execute. Indicates the position of
+ * the image header.
+ */
+ uint8_t br_flash_id;
+ uint32_t br_image_addr;
+};
+```
+
+After running the management functions of the bootloader, `boot_go` returns
+an initialized `boot_rsp` which has pointers to the location of the image
+where the target firmware is located which can be used to jump to.
+
+## Flash access and flash Map
+
+* Regarding flash access the bootloader has two requirements:
+
+### hal_flash_align
+
+`mcuboot` needs to know the write size (and alignment) of the flash. To get
+this information it calls `hal_flash_align`.
+
+`uint8_t hal_flash_align(uint8_t flash_id);`
+
+### flash_map
+
+The bootloader requires a `flash_map` to be able to know how the flash is
+partitioned. A `flash_map` consists of `struct flash_area` entries
+specifying the partitions, where a `flash_area` defined as follows:
+
+```c
+struct flash_area {
+ uint8_t fa_id; /** The slot/scratch identification */
+ uint8_t fa_device_id; /** The device id (usually there's only one) */
+ uint16_t pad16;
+ uint32_t fa_off; /** The flash offset from the beginning */
+ uint32_t fa_size; /** The size of this sector */
+};
+```
+
+`fa_id` is can be one of the following options:
+
+```c
+#define FLASH_AREA_IMAGE_0 1
+#define FLASH_AREA_IMAGE_1 2
+#define FLASH_AREA_IMAGE_SCRATCH 3
+```
+
+The functions that must be defined for working with the `flash_area`s are:
+
+```c
+/*< Opens the area for use. id is one of the `fa_id`s */
+int flash_area_open(uint8_t id, const struct flash_area **);
+void flash_area_close(const struct flash_area *);
+/*< Reads `len` bytes of flash memory at `off` to the buffer at `dst` */
+int flash_area_read(const struct flash_area *, uint32_t off, void *dst,
+ uint32_t len);
+/*< Writes `len` bytes of flash memory at `off` from the buffer at `src` */
+int flash_area_write(const struct flash_area *, uint32_t off,
+ const void *src, uint32_t len);
+/*< Erases `len` bytes of flash memory at `off` */
+int flash_area_erase(const struct flash_area *, uint32_t off, uint32_t len);
+/*< Returns this `flash_area`s alignment */
+uint8_t flash_area_align(const struct flash_area *);
+/*< Initializes an array of flash_area elements for the slot's sectors */
+int flash_area_to_sectors(int idx, int *cnt, struct flash_area *ret);
+/*< Returns the `fa_id` for slot, where slot is 0 or 1 */
+int flash_area_id_from_image_slot(int slot);
+/*< Returns the slot, for the `fa_id` supplied */
+int flash_area_id_to_image_slot(int area_id);
+```
+
+## Memory management for mbed TLS
+
+`mbed TLS` employs dynamic allocation of memory, making use of the pair
+`calloc/free`. If `mbed TLS` is to be used for crypto, your target RTOS
+needs to provide this pair of function.
+
+To configure the what functions are called when allocating/deallocating
+memory `mbed TLS` uses the following call [^cite1]:
+
+```
+int mbedtls_platform_set_calloc_free (void *(*calloc_func)(size_t, size_t),
+ void (*free_func)(void *));
+```
+
+If your system already provides functions with compatible signatures, those
+can be used directly here, otherwise create new functions that glue to
+your `calloc/free` implementations.
+
+[^cite1]```https://tls.mbed.org/api/platform_8h.html```
diff --git a/docs/SubmittingPatches.md b/docs/SubmittingPatches.md
new file mode 100644
index 0000000..da104ec
--- /dev/null
+++ b/docs/SubmittingPatches.md
@@ -0,0 +1,70 @@
+# Submitting Patches
+
+Development on mcuboot primarily takes place in github, at:
+https://github.com/runtimeco/mcuboot
+
+Changes should be submitted via github pull requests. Each commit
+should have a Signed-off-by line for the author (and the committer, if
+that is different). It is not necessary (or possible) to get a
+Signed-off-by from Github itself, even though some commits may be
+generated by that tool.
+
+The Signed-off-by line should be at the end of the commit text, in the
+last blank-line-separated section. There can be multiple lines in
+this section (the format being roughly like RFC-2822). Currently
+supported trailer lines are:
+
+ Signed-off-by: Developer Name <devname@example.com>
+
+which indicates that the signer agrees to the Developer Certificate of
+Origin below, and
+
+ JIRA: MCUB-1234
+
+which associates this commit with a particular JIRA ticket. You can
+put more than one JIRA ticket, by separating them with a comma and a
+space. JIRA is quite flexible about where the indicators go, but
+putting them in a trailer with a common format will make them easier
+to find later.
+
+# Developer Certificate of Origin
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+ have the right to submit it under the open source license
+ indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+ of my knowledge, is covered under an appropriate open source
+ license and I have the right under that license to submit that
+ work with modifications, whether created in whole or in part
+ by me, under the same open source license (unless I am
+ permitted to submit under a different license), as indicated
+ in the file; or
+
+(c) The contribution was provided directly to me by some other
+ person who certified (a), (b) or (c) and I have not modified
+ it.
+
+(d) I understand and agree that this project and the contribution
+ are public and that a record of the contribution (including all
+ personal information I submit with it, including my sign-off) is
+ maintained indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.
+```
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..277f1f2
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1 @@
+theme: jekyll-theme-cayman
diff --git a/docs/design.txt b/docs/design.txt
new file mode 100644
index 0000000..fd257d1
--- /dev/null
+++ b/docs/design.txt
@@ -0,0 +1,628 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+****** BOOT LOADER
+
+*** SUMMARY
+
+mcuboot comprises two packages:
+
+ * The bootutil library (boot/bootutil)
+ * The boot application (each port has its own at boot/<port>)
+
+The bootutil library performs most of the functions of a boot loader. In
+particular, the piece that is missing is the final step of actually jumping to
+the main image. This last step is instead implemented by the boot application.
+Boot loader functionality is separated in this manner to enable unit testing of
+the boot loader. A library can be unit tested, but an application can't.
+Therefore, functionality is delegated to the bootutil library when possible.
+
+*** LIMITATIONS
+
+The boot loader currently only supports images with the following
+characteristics:
+ * Built to run from flash.
+ * Built to run from a fixed location (i.e., not position-independent).
+
+*** IMAGE FORMAT
+
+The following definitions describe the image format.
+
+#define IMAGE_MAGIC 0x96f3b83d
+
+#define IMAGE_HEADER_SIZE 32
+
+struct image_version {
+ uint8_t iv_major;
+ uint8_t iv_minor;
+ uint16_t iv_revision;
+ uint32_t iv_build_num;
+};
+
+/** Image header. All fields are in little endian byte order. */
+struct image_header {
+ uint32_t ih_magic;
+ uint32_t ih_load_addr;
+ uint16_t ih_hdr_size; /* Size of image header (bytes). */
+ uint16_t _pad2;
+ uint32_t ih_img_size; /* Does not include header. */
+ uint32_t ih_flags; /* IMAGE_F_[...]. */
+ struct image_version ih_ver;
+ uint32_t _pad3;
+};
+
+/** Image TLV header. All fields in little endian. */
+struct image_tlv_info {
+ uint16_t it_magic;
+ uint16_t it_tlv_tot; /* size of TLV area (including tlv_info header) */
+};
+
+/** Image trailer TLV format. All fields in little endian. */
+struct image_tlv {
+ uint8_t it_type; /* IMAGE_TLV_[...]. */
+ uint8_t _pad;
+ uint16_t it_len; /* Data length (not including TLV header). */
+};
+
+/*
+ * Image header flags.
+ */
+#define IMAGE_F_PIC 0x00000001 /* Not supported. */
+#define IMAGE_F_NON_BOOTABLE 0x00000010 /* Split image app. */
+#define IMAGE_F_RAM_LOAD 0x00000020
+
+/*
+ * Image trailer TLV types.
+ */
+#define IMAGE_TLV_KEYHASH 0x01 /* hash of the public key */
+#define IMAGE_TLV_SHA256 0x10 /* SHA256 of image hdr and body */
+#define IMAGE_TLV_RSA2048_PSS 0x20 /* RSA2048 of hash output */
+#define IMAGE_TLV_ECDSA224 0x21 /* ECDSA of hash output */
+#define IMAGE_TLV_ECDSA256 0x22 /* ECDSA of hash output */
+
+Optional type-length-value records (TLVs) containing image metadata are placed
+after the end of the image.
+
+The ih_hdr_size field indicates the length of the header, and therefore the
+offset of the image itself. This field provides for backwards compatibility in
+case of changes to the format of the image header.
+
+*** FLASH MAP
+
+A device's flash is partitioned according to its _flash map_. At a high
+level, the flash map maps numeric IDs to _flash areas_. A flash area is a
+region of disk with the following properties:
+ (1) An area can be fully erased without affecting any other areas.
+ (2) A write to one area does not restrict writes to other areas.
+
+The boot loader uses the following flash area IDs:
+
+#define FLASH_AREA_BOOTLOADER 0
+#define FLASH_AREA_IMAGE_0 1
+#define FLASH_AREA_IMAGE_1 2
+#define FLASH_AREA_IMAGE_SCRATCH 3
+
+The bootloader area contains the bootloader image itself. The other areas are
+described in subsequent sections.
+
+*** IMAGE SLOTS
+
+A portion of the flash memory is partitioned into two image slots: a primary
+slot (0) and a secondary slot (1). The boot loader will only run an image from
+the primary slot, so images must be built such that they can run from that
+fixed location in flash. If the boot loader needs to run the image resident in
+the secondary slot, it must copy its contents into the primary slot before doing
+so, either by swapping the two images or by overwriting the contents of the
+primary slot. The bootloader supports either swap- or overwrite-based image
+upgrades, but must be configured at build time to choose one of these two
+strategies.
+
+In addition to the two image slots, the boot loader requires a scratch area to
+allow for reliable image swapping.
+
+The overwrite upgrade strategy is substantially simpler to implement than the
+image swapping strategy, especially since the bootloader must work properly
+even when it is reset during the middle of an image swap. For this reason, the
+rest of the document describes its behavior when configured to swap images
+during an upgrade.
+
+*** BOOT SWAP TYPES
+
+When the device first boots under normal circumstances, there is an up-to-date
+firmware image in slot 0, which mcuboot can validate and then chain-load. In
+this case, no image swaps are necessary. During device upgrades, however, new
+candidate images are present in slot 1, which mcuboot must swap into slot 0
+before booting as discussed above.
+
+Upgrading an old image with a new one by swapping can be a two-step process. In
+this process, mcuboot performs a "test" swap of image data in flash and boots
+the new image. The new image can then update the contents of flash at runtime
+to mark itself "OK", and mcuboot will then still choose to run it during the
+next boot. When this happens, the swap is made "permanent". If this doesn't
+happen, mcuboot will perform a "revert" swap during the next boot by swapping
+the images back into their original locations, and attempting to boot the old
+image.
+
+Depending on the use case, the first swap can also be made permanent directly.
+In this case, mcuboot will never attempt to revert the images on the next reset.
+
+Test swaps are supported to provide a rollback mechanism to prevent devices
+from becoming "bricked" by bad firmware. If the device crashes immediately
+upon booting a new (bad) image, mcuboot will revert to the old (working) image
+at the next device reset, rather than booting the bad image again. This allows
+device firmware to make test swaps permanent only after performing a self-test
+routine.
+
+On startup, mcuboot inspects the contents of flash to decide which of these
+"swap types" to perform; this decision determines how it proceeds.
+
+The possible swap types, and their meanings, are:
+
+- BOOT_SWAP_TYPE_NONE: The "usual" or "no upgrade" case; attempt to boot the
+ contents of slot 0.
+
+- BOOT_SWAP_TYPE_TEST: Boot the contents of slot 1 by swapping images. Unless
+ the swap is made permanent, revert back on the next boot.
+
+- BOOT_SWAP_TYPE_PERM: Permanently swap images, and boot the upgraded image
+ firmware.
+
+- BOOT_SWAP_TYPE_REVERT: A previous test swap was not made permanent; swap back
+ to the old image whose data are now in slot 1. If the old image marks itself
+ "OK" when it boots, the next boot will have swap type BOOT_SWAP_TYPE_NONE.
+
+- BOOT_SWAP_TYPE_FAIL: Swap failed because image to be run is not valid.
+
+- BOOT_SWAP_TYPE_PANIC: Swapping encountered an unrecoverable error.
+
+The "swap type" is a high-level representation of the outcome of the
+boot. Subsequent sections describe how mcuboot determines the swap type from
+the bit-level contents of flash.
+
+*** IMAGE TRAILER
+
+For the bootloader to be able to determine the current state and what actions
+should be taken during the current boot operation, it uses metadata stored in
+the image flash areas. While swapping, some of this metadata is temporarily
+copied into and out of the scratch area.
+
+This metadata is located at the end of the image flash areas, and is called an
+image trailer. An image trailer has the following structure:
+
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ ~ ~
+ ~ Swap status (128 * min-write-size * 3) ~
+ ~ ~
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Swap size |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | 0xff padding (4 octets) |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Copy done | 0xff padding (7 octets) ~
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | Image OK | 0xff padding (7 octets) ~
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ ~ MAGIC (16 octets) ~
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+The offset immediately following such a record represents the start of the next
+flash area.
+
+Note: "min-write-size" is a property of the flash hardware. If the hardware
+allows individual bytes to be written at arbitrary addresses, then
+min-write-size is 1. If the hardware only allows writes at even addresses,
+then min-write-size is 2, and so on.
+
+An image trailer contains the following fields:
+
+1. Swap status: A series of records which records the progress of an image
+swap. To swap entire images, data are swapped between the two image areas one
+or more sectors at a time, like this:
+
+ - sector data in slot 0 is copied into scratch, then erased
+ - sector data in slot 1 is copied into slot 0, then erased
+ - sector data in scratch is copied into slot 1
+
+As it swaps images, the bootloader updates the swap status field in a way that
+allows it to compute how far this swap operation has progressed for each
+sector. The swap status field can thus used to resume a swap operation if the
+bootloader is halted while a swap operation is ongoing and later reset. The
+factor of 128 is the maximum number of sectors mcuboot supports for each image;
+its value is a bootloader design decision. The factor of min-write-sz is due to
+the behavior of flash hardware. The factor of 3 is explained below.
+
+2. Swap size: When beginning a new swap operation, the total size that needs
+to be swapped (based on the slot with largest image + tlvs) is written to this
+location for easier recovery in case of a reset while performing the swap.
+
+3. Copy done: A single byte indicating whether the image in this slot is
+complete (0x01=done; 0xff=not done).
+
+4. Image OK: A single byte indicating whether the image in this slot has been
+confirmed as good by the user (0x01=confirmed; 0xff=not confirmed).
+
+5. MAGIC: The following 16 bytes, written in host-byte-order:
+
+ const uint32_t boot_img_magic[4] = {
+ 0xf395c277,
+ 0x7fefd260,
+ 0x0f505235,
+ 0x8079b62c,
+ };
+
+*** IMAGE TRAILERS
+
+At startup, the boot loader determines the boot swap type by inspecting the
+image trailers. When using the term "image trailers" what is meant is the
+aggregate information provided by both image slot's trailers.
+
+The image trailers records are structured around the limitations imposed by flash
+hardware. As a consequence, they do not have a very intuitive design, and it
+is difficult to get a sense of the state of the device just by looking at the
+image trailers. It is better to map all the possible trailer states to the swap
+types described above via a set of tables. These tables are reproduced below.
+
+Note: An important caveat about the tables described below is that they must
+be evaluated in the order presented here. Lower state numbers must have a
+higher priority when testing the image trailers.
+
+
+ State I
+ | slot-0 | slot-1 |
+ -----------------+--------+--------|
+ magic | Any | Good |
+ image-ok | Any | Unset |
+ copy-done | Any | Any |
+ -----------------+--------+--------'
+ result: BOOT_SWAP_TYPE_TEST |
+ -----------------------------------'
+
+
+ State II
+ | slot-0 | slot-1 |
+ -----------------+--------+--------|
+ magic | Any | Good |
+ image-ok | Any | 0x01 |
+ copy-done | Any | Any |
+ -----------------+--------+--------'
+ result: BOOT_SWAP_TYPE_PERM |
+ -----------------------------------'
+
+
+ State III
+ | slot-0 | slot-1 |
+ -----------------+--------+--------|
+ magic | Good | Unset |
+ image-ok | 0xff | Any |
+ copy-done | 0x01 | Any |
+ -----------------+--------+--------'
+ result: BOOT_SWAP_TYPE_REVERT |
+ -----------------------------------'
+
+Any of the above three states results in mcuboot attempting to swap images.
+
+Otherwise, mcuboot does not attempt to swap images, resulting in one of the
+other three swap types, as illustrated by State IV.
+
+
+ State IV
+ | slot-0 | slot-1 |
+ -----------------+--------+--------|
+ magic | Any | Any |
+ image-ok | Any | Any |
+ copy-done | Any | Any |
+ -----------------+--------+--------'
+ result: BOOT_SWAP_TYPE_NONE, |
+ BOOT_SWAP_TYPE_FAIL, or |
+ BOOT_SWAP_TYPE_PANIC |
+ -----------------------------------'
+
+In State IV, when no errors occur, mcuboot will attempt to boot the contents of
+slot 0 directly, and the result is BOOT_SWAP_TYPE_NONE. If the image in slot 0
+is not valid, the result is BOOT_SWAP_TYPE_FAIL. If a fatal error occurs during
+boot, the result is BOOT_SWAP_TYPE_PANIC. If the result is either
+BOOT_SWAP_TYPE_FAIL or BOOT_SWAP_TYPE_PANIC, mcuboot hangs rather than booting
+an invalid or compromised image.
+
+Note: An important caveat to the above is the result when a swap is requested
+ and the image in slot 1 fails to validate, due to a hashing or signing
+ error. This state behaves as State IV with the extra action of marking
+ the image in slot 0 as "OK", to prevent further attempts to swap.
+
+
+*** HIGH-LEVEL OPERATION
+
+With the terms defined, we can now explore the boot loader's operation. First,
+a high-level overview of the boot process is presented. Then, the following
+sections describe each step of the process in more detail.
+
+Procedure:
+
+A. Inspect swap status region; is an interrupted swap being resumed?
+ Yes: Complete the partial swap operation; skip to step C.
+ No: Proceed to step B.
+
+B. Inspect image trailers; is a swap requested?
+ Yes.
+ 1. Is the requested image valid (integrity and security check)?
+ Yes.
+ a. Perform swap operation.
+ b. Persist completion of swap procedure to image trailers.
+ c. Proceed to step C.
+ No.
+ a. Erase invalid image.
+ b. Persist failure of swap procedure to image trailers.
+ c. Proceed to step C.
+ No: Proceed to step C.
+
+C. Boot into image in slot 0.
+
+*** IMAGE SWAPPING
+
+The boot loader swaps the contents of the two image slots for two reasons:
+ * User has issued a "set pending" operation; the image in slot-1 should be
+ run once (state II) or repeatedly (state III), depending on whether a
+ permanent swap was specified.
+ * Test image rebooted without being confirmed; the boot loader should
+ revert to the original image currently in slot-1 (state IV).
+
+If the image trailers indicates that the image in the secondary slot should be
+run, the boot loader needs to copy it to the primary slot. The image currently
+in the primary slot also needs to be retained in flash so that it can be used
+later. Furthermore, both images need to be recoverable if the boot loader
+resets in the middle of the swap operation. The two images are swapped
+according to the following procedure:
+
+ 1. Determine how many flash sectors each image slot consists of. This
+ number must be the same for both slots.
+ 2. Iterate the list of sector indices in descending order (i.e., starting
+ with the greatest index); current element = "index".
+ b. Erase scratch area.
+ c. Copy slot0[index] to scratch area.
+ - If these are the last sectors (i.e., first swap being perfomed),
+ copy the full sector *except* the image trailer.
+ - Else, copy entire sector contents.
+ d. Write updated swap status (i).
+
+ e. Erase slot1[index]
+ f. Copy slot0[index] to slot1[index]
+ - If these are the last sectors (i.e., first swap being perfomed),
+ copy the full sector *except* the image trailer.
+ - Else, copy entire sector contents.
+ g. Write updated swap status (ii).
+
+ h. Erase slot0[index].
+ i. Copy scratch area slot0[index].
+ - If these are the last sectors (i.e., first swap being perfomed),
+ copy the full sector *except* the image trailer.
+ - Else, copy entire sector contents.
+ j. Write updated swap status (iii).
+
+ 3. Persist completion of swap procedure to slot 0 image trailer.
+
+The additional caveats in step 2f are necessary so that the slot 1 image
+trailer can be written by the user at a later time. With the image trailer
+unwritten, the user can test the image in slot 1 (i.e., transition to state
+II).
+
+Note1: If the sector being copied is the last sector, then swap status is
+temporarily maintained on scratch for the duration of this operation, always
+using slot0's area otherwise.
+
+Note2: The bootloader tries to copy only used sectors (based on largest image
+installed on any of the slots), minimizing the amount of sectors copied and
+reducing the amount of time required for a swap operation.
+
+The particulars of step 3 vary depending on whether an image is being tested,
+permanently used, reverted or a validation failure of slot 1 happened when a
+swap was requested:
+
+ * test:
+ o Write slot0.copy_done = 1
+ (swap caused the following values to be written:
+ slot0.magic = BOOT_MAGIC
+ slot0.image_ok = Unset)
+
+ * permanent:
+ o Write slot0.copy_done = 1
+ (swap caused the following values to be written:
+ slot0.magic = BOOT_MAGIC
+ slot0.image_ok = 0x01)
+
+ * revert:
+ o Write slot0.copy_done = 1
+ o Write slot0.image_ok = 1
+ (swap caused the following values to be written:
+ slot0.magic = BOOT_MAGIC)
+
+ * failure to validate slot 1:
+ o Write slot0.image_ok = 1
+
+After completing the operations as described above the image in slot 0 should
+be booted.
+
+*** SWAP STATUS
+
+The swap status region allows the boot loader to recover in case it restarts in
+the middle of an image swap operation. The swap status region consists of a
+series of single-byte records. These records are written independently, and
+therefore must be padded according to the minimum write size imposed by the
+flash hardware. In the below figure, a min-write-size of 1 is assumed for
+simplicity. The structure of the swap status region is illustrated below. In
+this figure, a min-write-size of 1 is assumed for simplicity.
+
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ |sec125,state 2 | |
+ +-+-+-+-+-+-+-+-+ +
+ ~ ~
+ ~ [Records for indices 124 through 1 ~
+ ~ ~
+ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ ~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+The above is probably not helpful at all; here is a description in English.
+
+Each image slot is partitioned into a sequence of flash sectors. If we were to
+enumerate the sectors in a single slot, starting at 0, we would have a list of
+sector indices. Since there are two image slots, each sector index would
+correspond to a pair of sectors. For example, sector index 0 corresponds to
+the first sector in slot 0 and the first sector in slot 1. Furthermore, we
+impose a limit of 128 indices. If an image slot consists of more than 128
+sectors, the flash layout is not compatible with this boot loader. Finally,
+reverse the list of indices such that the list starts with index 127 and ends
+with 0. The swap status region is a representation of this reversed list.
+
+During a swap operation, each sector index transitions through four separate
+states:
+ 0. slot 0: image 0, slot 1: image 1, scratch: N/A
+ 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1->s, erase 1)
+ 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0->1, erase 0)
+ 3. slot 0: image 1, slot 1: image 0, scratch: N/A (s->0)
+
+Each time a sector index transitions to a new state, the boot loader writes a
+record to the swap status region. Logically, the boot loader only needs one
+record per sector index to keep track of the current swap state. However, due
+to limitations imposed by flash hardware, a record cannot be overwritten when
+an index's state changes. To solve this problem, the boot loader uses three
+records per sector index rather than just one.
+
+Each sector-state pair is represented as a set of three records. The record
+values map to the above four states as follows
+
+ | rec0 | rec1 | rec2
+ --------+------+------+------
+ state 0 | 0xff | 0xff | 0xff
+ state 1 | 0x01 | 0xff | 0xff
+ state 2 | 0x01 | 0x02 | 0xff
+ state 3 | 0x01 | 0x02 | 0x03
+
+The swap status region can accommodate 128 sector indices. Hence, the size of
+the region, in bytes, is 128 * min-write-size * 3. The number 128 is chosen
+somewhat arbitrarily and will likely be made configurable. The only
+requirement for the index count is that is is great enough to account for a
+maximum-sized image (i.e., at least as great as the total sector count in an
+image slot). If a device's image slots use less than 128 sectors, the first
+record that gets written will be somewhere in the middle of the region. For
+example, if a slot uses 64 sectors, the first sector index that gets swapped is
+63, which corresponds to the exact halfway point within the region.
+
+Note: since the scratch area only ever needs to record swapping of the last
+sector, it uses at most min-write-size * 3 bytes for its own status area.
+
+*** RESET RECOVERY
+
+If the boot loader resets in the middle of a swap operation, the two images may
+be discontiguous in flash. Bootutil recovers from this condition by using the
+image trailers to determine how the image parts are distributed in flash.
+
+The first step is determine where the relevant swap status region is located.
+Because this region is embedded within the image slots, its location in flash
+changes during a swap operation. The below set of tables map image trailers
+contents to swap status location. In these tables, the "source" field
+indicates where the swap status region is located.
+
+ | slot-0 | scratch |
+ ----------+------------+------------|
+ magic | Good | Any |
+ copy-done | 0x01 | N/A |
+ ----------+------------+------------'
+ source: none |
+ ------------------------------------'
+
+ | slot-0 | scratch |
+ ----------+------------+------------|
+ magic | Good | Any |
+ copy-done | 0xff | N/A |
+ ----------+------------+------------'
+ source: slot 0 |
+ ------------------------------------'
+
+ | slot-0 | scratch |
+ ----------+------------+------------|
+ magic | Any | Good |
+ copy-done | Any | N/A |
+ ----------+------------+------------'
+ source: scratch |
+ ------------------------------------'
+
+ | slot-0 | scratch |
+ ----------+------------+------------|
+ magic | Unset | Any |
+ copy-done | 0xff | N/A |
+ ----------+------------+------------|
+ source: slot 0 |
+ ------------------------------------+------------------------------+
+ This represents one of two cases: |
+ o No swaps ever (no status to read, so no harm in checking). |
+ o Mid-revert; status in slot 0. |
+ For this reason we assume slot 0 as source, to trigger a check |
+ of the status area and find out if there was swapping under way. |
+ -------------------------------------------------------------------'
+
+
+If the swap status region indicates that the images are not contiguous,
+bootutil completes the swap operation that was in progress when the system was
+reset. In other words, it applies the procedure defined in the previous
+section, moving image 1 into slot 0 and image 0 into slot 1. If the boot
+status file indicates that an image part is present in the scratch area, this
+part is copied into the correct location by starting at step e or step h in the
+area-swap procedure, depending on whether the part belongs to image 0 or image
+1.
+
+After the swap operation has been completed, the boot loader proceeds as though
+it had just been started.
+
+*** INTEGRITY CHECK
+
+An image is checked for integrity immediately before it gets copied into the
+primary slot. If the boot loader doesn't perform an image swap, then it can
+perform an optional integrity check of the image in slot0 if
+MCUBOOT_VALIDATE_SLOT0 is set, otherwise it doesn't perform an integrity check.
+
+During the integrity check, the boot loader verifies the following aspects of
+an image:
+ * 32-bit magic number must be correct (0x96f3b83d).
+ * Image must contain an image_tlv_info struct, identified by its magic
+ (0x6907) exactly following the firmware (hdr_size + img_size).
+ * Image must contain a SHA256 TLV.
+ * Calculated SHA256 must match SHA256 TLV contents.
+ * Image *may* contain a signature TLV. If it does, it must also have a
+ KEYHASH TLV with the hash of the key that was used to sign. The list of
+ keys will then be iterated over looking for the matching key, which then
+ will then be used to verify the image contents.
+
+*** SECURITY
+
+As indicated above, the final step of the integrity check is signature
+verification. The boot loader can have one or more public keys embedded in it
+at build time. During signature verification, the boot loader verifies that an
+image was signed with a private key that corresponds to the embedded keyhash
+TLV.
+
+For information on embedding public keys in the boot loader, as well as
+producing signed images, see: doc/signed_images.md
diff --git a/docs/imgtool.md b/docs/imgtool.md
new file mode 100644
index 0000000..a4f5c40
--- /dev/null
+++ b/docs/imgtool.md
@@ -0,0 +1,91 @@
+## Image tool
+
+The Python program `scripts/imgtool.py` can be used to perform the
+operations that are necessary to manage keys and sign images. Using
+this script should be preferred to the manual steps described in
+`doc/signed_images.md`.
+
+This program is written for Python3, and has several dependencies on
+Python libraries. These can be installed using 'pip3' manually:
+
+ pip3 install --user pycrypto
+ pip3 install --user pyasn1
+ pip3 install --user ecdsa
+
+or, on Ubuntu, using the package manager:
+
+ sudo apt-get install python3-crypto python3-pyasn1 python3-ecdsa
+
+## Managing keys
+
+This tool currently supports rsa-2048 and ecdsa-p256 keys. You can
+generate a keypair for one of these types using the 'keygen' command:
+
+ ./scripts/imgtool.py keygen -k filename.pem -t rsa-2048
+
+or use ecdsa-p256 for the type. The key type used should match what
+mcuboot is configured to verify.
+
+This key file is what is used to sign images, this file should be
+protected, and not widely distributed.
+
+## Incorporating the public key into the code
+
+There is a development key distributed with mcuboot that can be used
+for testing. Since this private key is widely distributed, it should
+never be used for production. Once you have generated a production
+key, as described above, you should replace the public key in the
+bootloader with the generated one.
+
+For Zephyr, the keys live in the file `boot/zephyr/keys.c`. For
+mynewt, follow the instructions in `doc/signed_images.md` to generate
+the key file.
+
+ ./scripts/imgtool.py getpub -k filename.pem
+
+will extract the public key from the given private key file, and
+output it as a C data structure. You can replace or insert this code
+into the key file.
+
+## Signing images
+
+Image signing takes a binary image intended for Slot 0 and adds a
+header and trailer that the bootloader is expecting:
+
+ usage: imgtool.py sign [-h] -k filename --align ALIGN -v VERSION -H
+ HEADER_SIZE [--pad PAD] [--rsa-pkcs1-15]
+ infile outfile
+
+ positional arguments:
+ infile
+ outfile
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -k filename, --key filename
+ --align ALIGN
+ -v VERSION, --version VERSION
+ -H HEADER_SIZE, --header-size HEADER_SIZE
+ --included-header Image has gap for header
+ --pad PAD Pad image to this many bytes, adding trailer magic
+ --rsa-pkcs1-15 Use old PKCS#1 v1.5 signature algorithm
+
+The main arguments given are the key file generated above, a version
+field to place in the header (1.2.3 for example), the alignment of the
+flash device in question, and the header size.
+
+The header size depends on the operating system and the particular
+flash device. For Zephyr, it will be configured as part of the build,
+and will be a small power of two. By default, the header will be
+prepended to the image. If `--included-header` is given, the image
+must start with header-size bytes of zeros, and the header will be
+overwritten over these bytes.
+
+The optional --pad argument will place a trailer on the image that
+indicates that the image should be considered an upgrade. Writing
+this image in slot 1 will then cause the bootloader to upgrade to it.
+
+Lastly, the --rsa-pkcs1-15 will cause the tool to use the older,
+deprecated pkcs#1 v1.5 signing algorithm when using RSA. This can be
+enabled in the bootloader as wel, and may be needed if you are using
+an older version of the bootloader.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..8a2c116
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,46 @@
+# MCUboot
+
+## Overview
+
+MCUBoot is a secure bootloader for 32-bit MCUs. The goal of MCUBoot is to
+define a common infrastructure for the bootloader, system flash layout on
+microcontroller systems, and to provide a secure bootloader that enables
+easy software upgrade.
+
+MCUboot is operating system and hardware independent, and relies on
+hardware porting layers from the operating system it works with. Currently
+MCUboot works with both the Apache Mynewt, and Zephyr operating systems, but
+more ports are planned in the future. RIOT is currently supported as a boot
+target with a complete port planned.
+
+## Roadmap
+
+The issues being planned and worked on are tracked on Jira. To participate
+please visit:
+
+[MCUboot JIRA](https://runtimeco.atlassian.net/projects/MCUB/summary)
+
+## Browsing
+
+Information and documentation on the bootloader is stored within the source, and on confluence:
+
+[Confluence page](https://runtimeco.atlassian.net/wiki/discover/all-updates)
+
+For more information in the source, here are some pointers:
+
+- [boot/bootutil](https://github.com/runtimeco/mcuboot/tree/master/boot/bootutil): The core of the bootloader itself.
+- [boot/boot\_serial](https://github.com/runtimeco/mcuboot/tree/master/boot/boot_serial): Support for serial upgrade within the bootloader itself.
+- [boot/zephyr](https://github.com/runtimeco/mcuboot/tree/master/boot/zephyr): Port of the bootloader to Zephyr
+- [boot/mynewt](https://github.com/runtimeco/mcuboot/tree/master/boot/mynewt): Mynewt bootloader app
+- [imgtool](https://github.com/runtimeco/mcuboot/tree/master/imgtool): A tool to securely sign firmware images for booting by MCUboot.
+- [sim](https://github.com/runtimeco/mcuboot/tree/master/sim): A bootloader simulator for testing and regression
+
+## Joining
+
+Developers welcome!
+
+* [Our developer mailing list](http://lists.runtime.co/mailman/listinfo/dev-mcuboot_lists.runtime.co)
+* [Our Slack channel](https://mcuboot.slack.com/)<br />
+ Get your invite [here!](https://join.slack.com/t/mcuboot/shared_invite/MjE2NDcwMTQ2MTYyLTE1MDA4MTIzNTAtYzgyZTU0NjFkMg)
+* [Our IRC channel](http://irc.freenode.net), channel #mcuboot ([IRC
+ link](irc://chat.freenode.net/#mcuboot)
diff --git a/docs/signed_images.md b/docs/signed_images.md
new file mode 100644
index 0000000..80bac7b
--- /dev/null
+++ b/docs/signed_images.md
@@ -0,0 +1,103 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+-->
+
+## Image signing
+
+This signs the image by computing hash over the image, and then
+signing that hash. Signature is computed by newt tool when it's
+creating the image. This signature is placed in the image trailer.
+
+The public key of this keypair must be included in the bootloader,
+as it verifies it before allowing the image to run.
+
+This facility allows you to use multiple signing keys. This would
+be useful when you want to prevent production units from booting
+development images, but want development units to be able to boot
+both production images and development images.
+
+## Creating signing keys
+First you need a keypair to use for signing. You can create
+one with openssl command line tool.
+
+openssl genrsa -out image_sign.pem 2048
+
+This created a file which contains both the private and public key,
+and will be used when signing images.
+
+Then you need to extract the public key from this to include it
+in the bootloader. Bootloader need to keep key parsing minimal,
+so it expects simple key format.
+
+openssl rsa -in image_sign.pem -pubout -out image_sign_pub.der -outform DER -RSAPublicKey_out
+
+Now the public key is in file called image_sign_pub.der.
+
+For ECDSA224 these commands are similar.
+
+openssl ecparam -name secp224r1 -genkey -noout -out image_sign.pem
+openssl ec -in image_sign.pem -pubout -outform DER -out image_sign_pub.der
+
+And then the ECDSA256.
+openssl ecparam -name prime256v1 -genkey -noout -out image_sign.pem
+openssl ec -in image_sign.pem -pubout -outform DER -out image_sign_pub.der
+
+## Creating a key package
+
+xxd -i image_sign_pub.der image_sign_pub.c.import
+
+Then you need to create a package containing this key, or keys.
+
+## Sample pkg.yml
+This gets bootutil to turn on image signature validation.
+
+ pkg.name: libs/mykeys
+ pkg.deps:
+ - "@apache-mynewt-core/boot/bootutil"
+
+## Sample source file
+This exports the keys.
+
+ #include <bootutil/sign_key.h>
+
+ #include "image_sign_pub.c.import"
+
+ const struct bootutil_key bootutil_keys[] = {
+ [0] = {
+ .key = image_sign_pub_der,
+ .len = &image_sign_pub_der_len,
+ }
+ };
+
+ const int bootutil_key_cnt = sizeof(bootutil_keys) / sizeof(bootutil_keys[0]);
+
+## Building bootloader
+
+Enable the BOOTUTIL_SIGN_RSA syscfg setting in your app or target syscfg.yml
+file
+
+ syscfg.vals:
+ BOOTUTIL_SIGN_RSA: 1
+
+After you've created the key package, you must include it in the build
+for bootloader. So modify the pkg.yml for apps/boot to include it.
+
+The syscfg variable to enable ECDSA224 is BOOTUTIL_SIGN_EC, and
+BOOTUTIL_SIGN_EC256 for ECDS256.
diff --git a/docs/testplan-mynewt.md b/docs/testplan-mynewt.md
new file mode 100644
index 0000000..0b16fd4
--- /dev/null
+++ b/docs/testplan-mynewt.md
@@ -0,0 +1,157 @@
+## mcuboot test plan
+
+The current target for running the tests is the Freedom K64F board.
+
+### Basic sign support (RSA/EC/EC256)
+
+For each supported signing algorithm, check that non-signed, and signed
+with wrong key images are not swapped to, and image signed with correct key
+is swapped to.
+
+For the 3 algorithms supported, rsa, ec and ec256, two files are provided:
+key_<sign-algo>.pem, key_<sign-algo>_2.pem. And a keys file with the C public
+key data for key_<sign-algo>.pem.
+
+Build and load mcuboot:
+
+* `newt build k64f_boot_<sign-algo>`
+* `newt load k64f_boot_<sign-algo>`
+
+Build and load good image in slot 0:
+
+* `newt create-image k64f_blinky 1.0.1 key_<sign-algo>.pem`
+* `newt load k64f_blinky`
+
+NOTE: If testing RSA/PSS `newt create-image` needs to be passed in the extra
+flag `--rsa-pss` eg:
+
+`newt create-image k64f_blinky 1.0.1 key_rsa.pem --rsa-pss`
+
+Build and load image in slot 1 with no signing, signed with
+key_<sign-algo>_2.pem and signed with key_<sign-algo>.pem. Mark each one as
+test image and check that swap only happens for image signed with
+key_<sign-algo>.pem. Both others should be erased.
+
+* `newt create-image k64f_blinky2 1.0.2 <one-of-the-sign-keys-or-none>`
+* `newtmgr image upload k64f_blinky2`
+* `newtmgr image list`
+* `newtmgr image test <hash of slot 1>`
+
+### Image signed with more than one key
+
+FIXME: this is currently not functional, skip this section!
+
+Build and load mcuboot:
+
+* `newt build k64f_boot_rsa_ec`
+* `newt load k64f_boot_rsa_ec`
+
+Build and load good image in slot 0:
+
+* `newt create-image k64f_blinky 1.0.1 key_rsa.pem`
+* `newt load k64f_blinky`
+
+Build and load image in slot 1 with no signing, signed with
+key_<sign-algo>_2.pem and signed with key_<sign-algo>.pem. Mark each one as
+test image and check that swap only happens for image signed with
+key_<sign-algo>.pem. Both others should be erased.
+
+Use all of this options:
+
+* `newt create-image k64f_blinky2 1.0.2`
+
+And load
+
+* `newtmgr image upload k64f_blinky2`
+* `newtmgr image list`
+* `newtmgr image test <hash of slot 1>`
+
+### Overwrite only functionality
+
+Build/load mcuboot:
+
+* `newt build k64f_boot_rsa_noswap`
+* `newt load k64f_boot_rsa_noswap`
+
+Build/load blinky to slot 0:
+
+* `newt create-image k64f_blinky 1.0.1 key_rsa.pem`
+* `newt load k64f_blinky`
+
+Build/load blinky2 both with bad and good key, followed by a permanent swap
+request:
+
+* `newt create-image k64f_blinky2 1.0.2 <bad and good rsa keys>.pem`
+* `newtmgr image upload k64f_blinky2`
+* `newtmgr image list`
+* `newtmgr image confirm <hash of slot 1>`
+
+This should not swap and delete the image in slot 1 when signed with the wrong
+key, otherwise the image in slot 1 should be *moved* to slot 0 and slot 1 should
+be empty.
+
+### Validate slot 0 option
+
+Build/load mcuboot:
+
+* `newt build k64f_boot_rsa_validate0`
+* `newt load k64f_boot_rsa_validate0`
+
+Build non-signed image:
+
+* `newt create-image k64f_blinky 1.0.1`
+* `newt load k64f_blinky`
+* Reset and no image should be run
+
+Build signed image with invalid key:
+
+* `newt create-image k64f_blinky 1.0.1 key_rsa_2.pem`
+* `newt load k64f_blinky`
+* Reset and no image should be run
+
+Build signed image with *valid* key:
+
+* `newt create-image k64f_blinky 1.0.1 key_rsa.pem`
+* `newt load k64f_blinky`
+* Reset and image *should* run
+
+### Swap with random failures
+
+DISCLAIMER: be careful with copy/paste of commands, this test uses another
+target/app!
+
+Build/load mcuboot:
+
+* `newt build k64f_boot_rsa`
+* `newt load k64f_boot_rsa`
+
+Build/load slinky to slot 0:
+
+* `newt create-image k64f_slinky 1.0.1 key_rsa.pem`
+* `newt load k64f_slinky`
+
+Build/load slinky2 to slot 1:
+
+* `newt create-image k64f_slinky2 1.0.2 key_rsa.pem`
+* `newtmgr image upload k64f_slinky2`
+
+Confirm that both images are installed, request a permanent request to the
+image in slot 1 and check that it works.
+
+* `newtmgr image list`
+* `newtmgr image confirm <hash of slot 1>`
+
+If everything works, now proceed with requests for permanent swap to the image
+in slot 1 and do random swaps (as much as you like!). When the swap finishes
+confirm that the swap was finished with the previous slot 1 image now in
+slot 0 and vice-versa.
+
+### Help
+
+* Mass erase MCU
+
+ $ pyocd-flashtool -ce
+
+* Flashing image in slot 1:
+
+ $ pyocd-flashtool -se --address 0x80000 ${IMG_FILE} bin
diff --git a/docs/testplan-zephyr.rst b/docs/testplan-zephyr.rst
new file mode 100644
index 0000000..8ea5274
--- /dev/null
+++ b/docs/testplan-zephyr.rst
@@ -0,0 +1,164 @@
+Zephyr Test Plan
+================
+
+The following roughly describes how mcuboot is tested on Zephyr. The
+testing is done with the code in ``samples/zephyr``. These examples
+were written using the FRDM-K64F, but other boards should be similar.
+At this time, however, the partitions are hardcoded in the Makefile
+targets to flash.
+
+Note that at the time of release of 0.9.0-rc2, the change `MPU flash
+write`_ had not been merged. This change fixes a problem interaction
+between the MPU and the flash drivers. Without this change, if the
+MPU is enabled (the default), the bootloader will abort immediately on
+boot, generally before printing any messages.
+
+.. _MPU flash write: https://github.com/zephyrproject-rtos/zephyr/pull/654
+
+At this time, most of the test variants are done by modifying either
+the code or Makefiles. A future goal is to automate this testing.
+
+Sanity Check
+------------
+
+Begin by running make in ``samples/zephyr``::
+
+ $ make clean
+ $ make all
+
+This will result in three binaries: ``mcuboot.bin``,
+``signed-hello1.bin``, and ``signed-hello2.bin``.
+
+The second file is marked as an "upgrade" by the image tool, so
+has an appended image trailer.
+
+Begin by doing a full erase, and programming the first image::
+
+ $ pyocd-flashtool -ce
+ $ make flash_boot
+
+After it resets, look for "main: Starting bootloader", a few debug
+messages, and lastly: "main: Unable to find bootable image".
+
+Then, load hello1::
+
+ $ make flash_hello1
+
+This should print "main: Jumping to the first image slot", and you
+should get an image "Hello World number 1!".
+
+For kicks, program slot 2's image into slot one. This has to be done
+manually, and it is good to verify these addresses in the Makefile::
+
+ $ pyocd-flashtool -a 0x20000 signed-hello1.bin
+
+This should boot, printing "Upgraded hello!".
+
+Now put back image 1, and put image 2 in as the upgrade::
+
+ $ make flash_hello1
+ $ make flash_hello2
+
+This should print a message: "boot_swap_type: Swap type: test", and
+you should see "Upgraded hello!".
+
+Now reset the target::
+
+ $ pyocd-tool reset
+
+And you should see a revert and "Hello world number 1" running.
+
+Repeat this, to make sure we can mark the image as OK, and that a
+revert doesn't happen::
+
+ $ make flash_hello1
+ $ make flash_hello2
+
+We should have just booted the Upgraded hello. Mark this as OK::
+
+ $ pyocd-flashtool -a 0x7ffe8 image_ok.bin
+ $ pyocd-tool reset
+
+And make sure this stays in the "Upgraded hello" image.
+
+Other Signature Combinations
+----------------------------
+
+.. note:: Make sure you don't have changes in your tree, as the
+ following step will undo them.
+
+As part of the above sanity check, we have tested the RSA signature
+algorithm, along with the new RSA-PSS signature algorithm. To test
+other configurations, we need to make some modifications to the code.
+This is easiest to do by applying some patches (in
+``testplan/zephyr``). For each of these patches, perform something
+along the lines of::
+
+ $ cd ../..
+ $ git apply testplan/zephyr/0001-try-rsa-pkcs1-v15.patch
+ $ cd samples/zephyr
+ $ make clean
+ $ make all
+ $ pyocd-flashtool -ce
+ $ make flash_boot
+ $ make flash_hello1
+
+Make sure image one boots if it is supposed to (and doesn't if it is
+not supposed to). Then try the upgrade::
+
+ $ make flash_hello2
+
+After this, make sure that the the image does or doesn't perform the
+upgrade (see test table below).
+
+After the upgrade runs, reset to make sure the revert works (or
+doesn't for the noted cases below)::
+
+ $ pyocd-tool reset
+
+Then undo the change::
+
+ $ cd ../..
+ $ git checkout -- .
+
+and repeat the above steps for each patch.
+
+The following patches are available:
+
+.. list-table:: Test configurations
+ :header-rows: 1
+
+ * - Patch
+ - hello1 boot?
+ - Upgrade?
+ * - 0001-bad-old-rsa-in-boot-not-in-image.patch
+ - no
+ - no
+ * - 0001-bad-old-RSA-no-slot0-check.patch
+ - yes
+ - no
+ * - 0001-good-rsa-pkcs-v1.5-good.patch
+ - yes
+ - yes
+ * - 0001-bad-ECDSA-P256-bootloader-not-in-images.patch
+ - no
+ - no
+ * - 0001-partial-ECDSA-P256-bootloader-slot0-ok-slot1-bad.patch
+ - yes
+ - no
+ * - 0001-good-ECDSA-P256-bootloader-images-signed.patch
+ - yes
+ - yes
+ * - 0001-partial-ECDSA-P256-bootloader-slot-0-bad-sig.patch
+ - no
+ - yes[1]_
+ * - 0001-partial-ECDSA-P256-bootloader-slot-1-bad-sig.patch
+ - yes
+ - no
+ * - 0001-partial-ECDSA-P256-slot-0-bad-no-verification.patch
+ - no
+ - yes[1]_
+
+.. [1] These tests with hello1 bad should perform an upgrade when
+ hello2 is flashed, but they should not revert the image
+ afterwards.