doc: Convert rst to md and move to docs/
To avoid having multiple documentation standards, transition all
documentation files to the Markdown (md) format and move them to the
docs/ folder.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
diff --git a/docs/readme-mynewt.md b/docs/readme-mynewt.md
new file mode 100644
index 0000000..f1fbcf3
--- /dev/null
+++ b/docs/readme-mynewt.md
@@ -0,0 +1,38 @@
+# Running mynewt apps with MCUboot
+
+Due to small differences between Mynewt's bundled bootloader and MCUboot,
+when building an app that will be run with MCUboot as the bootloader and
+which at the same time requires to use `newtmgr` to manage images, MCUboot
+must be added as a new dependency for this app.
+
+First you need to add the repo to your `project.yml`:
+
+```
+ project.repositories:
+ - mcuboot
+
+ repository.mcuboot:
+ type: github
+ vers: 0-dev
+ user: runtimeco
+ repo: mcuboot
+```
+
+Then update your app's `pkg.yml` adding the extra dependency:
+
+```
+ pkg.deps:
+ - "@mcuboot/boot/bootutil"
+```
+
+Also remove any dependency on `boot/bootutil` (mynewt's bundled bootloader)
+which might exist.
+
+To configure MCUboot check all the options available in
+`boot/mynewt/mcuboot_config/syscfg.yml`.
+
+Also, MCUboot uses a different image header struct as well as slightly
+different TLV structure, so images created by `newt` have to be generated
+in this new format. That is done by passing the extra parameter `-2` as in:
+
+`newt create-image <target> <version> <pubkey> -2`
diff --git a/docs/readme-riot.md b/docs/readme-riot.md
new file mode 100644
index 0000000..9bb1b9b
--- /dev/null
+++ b/docs/readme-riot.md
@@ -0,0 +1,47 @@
+# Building and using MCUboot with RIOT
+
+MCUboot began its life as the bootloader for Mynewt. It has since
+acquired the ability to be used as a bootloader for RIOT as well.
+Currently the support is limited to the nrf52dk platform.
+
+## Building the bootloader itself
+
+In this first version, a prebuilt Mynewt binary is downloaded at
+compile time. This binary was compiled to do an integrity check, but
+not a signature check. In order to configure the bootloader for
+signature check it is necessary to re-compile it either with Mynewt
+or Zephyr, following the provided instructions.
+
+In the next version, it is planned to compile MCUboot using RIOT,
+which should be able to boot any of the supported OS images.
+
+## Building Applications for the bootloader
+
+A compatible MCUboot image can be compiled by typing: `make mcuboot`.
+
+The only variable which needs to be set is `IMAGE_VERSION` loaded
+with a valid formatted value. The format is `major.minor.patch+other`
+(e.g. `export IMAGE_VERSION= 1.1.1+1`. This variable can be either
+exported in the Makefile or manually, prior to the compilation process.
+
+The goal is to produce an ELF file which is linked to be flashed at a
+`BOOTLOADER_OFFSET` offset rather than the beginning of ROM. MCUboot
+also expects an image padded with some specific headers containing the
+version information, and trailer type-length-value records (TLVs) with
+hash and signing information. This is done through the imgtool.py
+application, which is executed automatically by the RIOT build system.
+
+### Signing the application
+
+The application will be automatically signed with the provided key.
+If no key is provided, a new key will be automatically generated. The
+default key type is RSA-2048.
+
+In order to use your provided key, you need to recompile the bootloader
+using you public key, either in Zephyr or Mynewt by following the
+provided procedure for the selected OS.
+
+### Flashing the application
+
+The application can be flashed by typing: `make flash-mcuboot`.
+This will flash both the bootloader and the application.
diff --git a/docs/readme-zephyr.md b/docs/readme-zephyr.md
new file mode 100644
index 0000000..3737f3f
--- /dev/null
+++ b/docs/readme-zephyr.md
@@ -0,0 +1,151 @@
+# Building and using MCUboot with Zephyr
+
+MCUboot began its life as the bootloader for Mynewt. It has since
+acquired the ability to be used as a bootloader for Zephyr as well.
+There are some pretty significant differences in how apps are built
+for Zephyr, and these are documented here.
+
+Please see the [design document]({% link design.md %}) for documentation on the
+design and operation of the bootloader itself. This functionality
+should be the same on all supported RTOSs.
+
+The first step required for Zephyr is making sure your board has flash
+partitions defined in its device tree. These partitions are:
+
+- `boot_partition`: for MCUboot itself
+- `slot0_partition`: the primary image slot
+- `slot1_partition`: the secondary image slot
+- `scratch_partition`: the scratch slot
+
+Currently, the two image slots must be contiguous. If you are running
+MCUboot as your stage 1 bootloader, `boot_partition` must be configured
+so your SoC runs it out of reset.
+
+The flash partitions are typically defined in the Zephyr boards folder, in a
+file named `boards/<arch>/<board>/<board>.dts`. An example `.dts` file with
+flash partitions defined is the frdm_k64f's in
+`boards/arm/frdm_k64f/frdm_k64f.dts`. Make sure the labels in your board's
+`.dts` file match the ones used there.
+
+## Building the bootloader itself
+
+The bootloader is an ordinary Zephyr application, at least from
+Zephyr's point of view. There is a bit of configuration that needs to
+be made before building it. Most of this can be done as documented in
+the `CMakeLists.txt` file in boot/zephyr. There are comments there for
+guidance. It is important to select a signature algorithm, and decide
+if slot0 should be validated on every boot.
+
+To build MCUboot, create a build directory in boot/zephyr, and build
+it as usual:
+
+```
+ cd boot/zephyr
+ mkdir build && cd build
+ cmake -GNinja -DBOARD=<board> ..
+ ninja
+```
+
+In addition to the partitions defined in DTS, some additional
+information about the flash layout is currently required to build
+MCUboot itself. All the needed configuration is collected in
+`boot/zephyr/include/target.h`. Depending on the board, this information
+may come from board-specific headers, Device Tree, or be configured by
+MCUboot on a per-SoC family basis.
+
+After building the bootloader, the binaries should reside in
+`build/zephyr/zephyr.{bin,hex,elf}`, where `build` is the build
+directory you chose when running `cmake`. Use the Zephyr build
+system `flash` target to flash these binaries, usually by running
+`make flash` (or `ninja flash`, etc.) from the build directory.
+
+## Building Applications for the bootloader
+
+In addition to flash partitions in DTS, some additional configuration
+is required to build applications for MCUboot.
+
+The directory `samples/zephyr/hello-world` in the MCUboot tree contains
+a simple application with everything you need. You can try it on your
+board and then just make a copy of it to get started on your own
+application; see samples/zephyr/README.md for a tutorial.
+
+More details:
+
+- `CONFIG_TEXT_SECTION_OFFSET` must be set to allow room for the
+ boot image header. Typically this is set in the app's prj.conf. It
+ must also be aligned to a boundary that the particular MCU requires
+ the vector table to be aligned on.
+
+- Your board must provide a DTS `zephyr,code-partition` chosen node
+ which ensures it is built and linked into the DTS `slot0_partition`. This
+ is typically achieved by creating a
+ [dts.overlay](https://github.com/runtimeco/mcuboot/blob/master/samples/zephyr/hello-world/dts.overlay)
+ file that contains the chose node description:
+
+```
+ chosen {
+ zephyr,code-partition = &slot0_partition;
+ };
+```
+
+With this, build the application as your normally would.
+
+### Signing the application
+
+In order to upgrade to an image (or even boot it, if
+`MCUBOOT_VALIDATE_SLOT0` is enabled), the images must be signed.
+To make development easier, MCUboot is distributed with some example
+keys. It is important to stress that these should never be used for
+production, since the private key is publicly available in this
+repository. See below on how to make your own signatures.
+
+There is a `sign.sh` script that gives some examples of how to make
+these signatures.
+
+### Flashing the application
+
+The application itself can flashed with regular flash tools, but will
+need to be loaded at the offset of SLOT-0 for this particular target.
+These images can also be marked for upgrade, and loaded into SLOT-1,
+at which point the bootloader should perform an upgrade. It is up to
+the image to mark slot-0 as "image ok" before the next reboot,
+otherwise the bootloader will revert the application.
+
+## Managing signing keys
+
+The signing keys used by MCUboot are represented in standard formats,
+and can be generated and processed using conventional tools. However,
+the Mynewt project has developed some tools to make this easier, and
+the `imgtool` directory contains a small program to use these tools,
+as well as some additional tools for generating and extracting public
+keys. If you will be using your own keys, it is recommended to build
+this tool following the directions within the directory.
+
+### Generating a new keypair
+
+Generating a keypair with imgtool is a matter of running the keygen
+subcommand:
+
+```
+ $ imgtool keygen -k mykey.pem -t rsa-2048
+```
+
+The argument to `-t` should be the desired key type. See the
+imgtool README.rst for more details on the possible key types.
+
+### Extracting the public key
+
+The generated keypair above contains both the public and the private
+key. It is necessary to extract the public key and insert it into the
+bootloader. The keys live in `boot/zephyr/keys.c`, and can be
+extracted using imgtool:
+
+```
+ $ imgtool getpub -k mykey.pem
+```
+
+This will output the public key as a C array that can be dropped
+directly into the `keys.c` file.
+
+Once this is done, this new keypair file (`mykey.pem` in this
+example) can be used to sign images.