119 lines
4.9 KiB
ReStructuredText
119 lines
4.9 KiB
ReStructuredText
Building and using mcuboot with Zephyr
|
|
######################################
|
|
|
|
*mcuboot* began its life as the bootloader for Mynewt. It has since
|
|
aquired 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 ``boot/bootutil/design.txt`` for documentation on the
|
|
design and operation of the bootloader itself. This functionality
|
|
should be the same between Mynewt and Zephyr
|
|
|
|
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 is done in the top-level
|
|
``Makefile`` in the source tree. There are comments there for
|
|
guidance. It is important to select a signature algorithm, and decide
|
|
if slot0 should be validated on every boot.
|
|
|
|
There is a ``build_boot.sh`` script at the top level that can make
|
|
building a bit easier. It assumes that the mcuboot tree is next to,
|
|
at the same level, as the zephyr source tree. It takes a single
|
|
argument, which is the target to build. This must match one of the
|
|
targets in ``boot/zephyr/targets`` to be a supported board. Additionally,
|
|
the Zephyr Device Tree board definition in ``dts/<arch>/<board>.dts`` must
|
|
contain the flash partitions description.
|
|
|
|
Once this is finished building, the bootloader should reside in
|
|
``outdir/targname/zephyr.[bin|hex]``. Use the flashing tools you have to
|
|
install this image at the beginning of the flash.
|
|
|
|
Building Applications for the bootloader
|
|
========================================
|
|
|
|
In order build an application to be used within the bootloader, there
|
|
are a few configuration changes that need to be made to it (typically
|
|
in the app's prj.conf).
|
|
|
|
- ``CONFIG_TEXT_SECTION_OFFSET`` must be set to allow room for the
|
|
boot image header. It must also be aligned to a boundary that the
|
|
particular MCU requires the vector table to be aligned on. This is
|
|
dependent upon the particular board you have chosen. Starting with
|
|
0x200 is a good way to start, since all of the boards will work with
|
|
this alignment.
|
|
|
|
- ``CONFIG_FLASH_BASE_ADDRESS`` must be set to the base address in
|
|
flash where the SLOT0 lives. This should match the value found in
|
|
``boot/zephyr/target/*.h`` for your target, for
|
|
``FLASH_AREA_IMAGE_0_OFFSET``. Note that some targets build for a
|
|
higher-than-zero flash address, and this should be compensated for
|
|
when setting this value. It should generally be set to a small
|
|
amount larger than its initial value.
|
|
|
|
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 publically 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 keytypes.
|
|
|
|
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.
|