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/README-RIOT.rst b/README-RIOT.rst
deleted file mode 100644
index d343210..0000000
--- a/README-RIOT.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-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: :code:`make mcuboot`.
-
-The only variable which needs to be set is :code:`IMAGE_VERSION` loaded
-with a valid formatted value. The format is :code:`major.minor.patch+other`
-(e.g. :code:`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
-:code:`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: :code:`make flash-mcuboot`.
-This will flash both the bootloader and the application.
diff --git a/README-mynewt.rst b/README-mynewt.rst
deleted file mode 100644
index 6340c05..0000000
--- a/README-mynewt.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-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``:
-
-.. code-block:: yaml
-
- 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:
-
-.. code-block:: yaml
-
- 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/README-zephyr.rst b/README-zephyr.rst
deleted file mode 100644
index e2a6186..0000000
--- a/README-zephyr.rst
+++ /dev/null
@@ -1,142 +0,0 @@
-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 ``docs/design.md`` for documentation on the
-design and operation of the bootloader itself. This functionality
-should be the same between Mynewt and Zephyr.
-
-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.
-
-An example DTS file with flash partitions defined is in the Zephyr
-file boards/arm/frdm_k64f/frdm_k64f.dts. Make sure the labels in your
-board's DTS 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 -DBOARD=<board> ..
-$ make
-
-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.
-
-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.
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.