# [Building and using MCUboot with Espressif's chips](#building-and-using-mcuboot-with-espressifs-chips)

The MCUBoot Espressif's port depends on HAL (Hardware Abstraction Layer) sources based on ESP-IDF
or 3rd party frameworks as such as Zephyr-RTOS (`zephyrproject-rtos/hal_espressif/`) or NuttX RTOS
(`espressif/esp-hal-3rdparty`). Building the MCUboot Espressif's port and its features is platform
dependent, therefore, the system environment including toolchains, must be set accordingly. A
standalone build version means that ESP-IDF and its toolchain are used as source. For 3rd parties
framework, HAL path and toolchain must be set.

Documentation about the MCUboot bootloader design, operation and features can be found in the
[design document](design.md).

## [SoC support availability](#soc-support-availability)

The current port is available for use in the following SoCs within the OSes:

|        | ESP32     | ESP32-S2  | ESP32-C3  | ESP32-S3  | ESP32-C2    | ESP32-C6    | ESP32-H2    |
| :----: | :-----:   | :-----:   | :-----:   | :-----:   | :---------: | :-----:     | :-----:     |
| Zephyr | Supported | Supported | Supported | Supported | In progress | In progress | In progress |
| NuttX  | Supported | Supported | Supported | Supported | In progress | In progress | In progress |

Notice that any customization in the memory layout from the OS application must be done aware of
the bootloader own memory layout to avoid overlapping. More information on the section
[Memory map organization for OS compatibility](#memory-map-organization-for-os-compatibility).

## [Installing requirements and dependencies](#installing-requirements-and-dependencies)

The following instructions considers a MCUboot Espressif port standalone build.

1. Install additional packages required for development with MCUboot:

    ```bash
    cd ~/mcuboot  # or to your directory where MCUboot is cloned
    ```

    ```bash
    pip3 install --user -r scripts/requirements.txt
    ```

2. Update the Mbed TLS submodule required by MCUboot:

    ```bash
    git submodule update --init --recursive ext/mbedtls
    ```

3. If ESP-IDF is the chosen option for use as HAL layer and the system already have ESP-IDF
   installed, ensure that the environment is set:

    ```bash
    <IDF_PATH>/install.sh
    ```

    ```bash
    . <IDF_PATH>/export.sh
    ```

    ---
    ***Note***

    *If desirable, instructions for ESP-IDF installation can be found
    [here](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#manual-installation)*

    ---

    ---
    ***Note***

    *The other HALs mentioned above like `hal_espressif` from Zephyr RTOS or `esp-hal-3rdparty`
    from NuttX RTOS environments also can be used for the bootloader standalone build, however as
    eventually code revision may differ from what is currently expected, it is recommended using
    them only within their RTOS build system.*

    ---

4. If ESP-IDF is not installed and will not be used, install `esptool`:

    ```bash
    pip3 install esptool
    ```

## [Building the bootloader itself](#building-the-bootloader-itself)

The MCUboot Espressif port bootloader is built using the toolchain and tools provided by Espressif.
Additional configuration related to MCUboot features and slot partitioning may be made using the
`port/<TARGET>/bootloader.conf` file or passing a custom config file using the
`-DMCUBOOT_CONFIG_FILE` argument on the first step below.

---
***Note***

*Replace `<TARGET>` with the target ESP32 family (like `esp32`, `esp32s2` and others).*

---

1. Compile and generate the BIN:

    ```bash
    cmake -DCMAKE_TOOLCHAIN_FILE=tools/toolchain-<TARGET>.cmake -DMCUBOOT_TARGET=<TARGET> -DESP_HAL_PATH=<ESP_HAL_PATH> -DMCUBOOT_FLASH_PORT=<PORT> -B build -GNinja
    ```

    ```bash
    ninja -C build/
    ```

    ---
    ***Note***

    *If using ESP-IDF as HAL layer source, `ESP_HAL_PATH` can be ommited.*

    ---

2. Flash MCUboot in your device:

    ```bash
    ninja -C build/ flash
    ```

    If `MCUBOOT_FLASH_PORT` arg was not passed to `cmake`, the default `PORT` for flashing will be
    `/dev/ttyUSB0`.

    Alternatively:

    ```bash
    esptool.py -p <PORT> -b <BAUD> --before default_reset --after no_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> build/mcuboot_<TARGET>.bin
    ```

    ---
    ***Note***

    You may adjust the port `<PORT>` (like `/dev/ttyUSB0`) and baud rate `<BAUD>` (like `2000000`)
    according to the connection with your board. You can also skip `<PORT>` and `<BAUD>` parameters
    so that esptool tries to automatically detect it.

    *`<FLASH_SIZE>` can be found using the command below:*

    ```bash
    esptool.py -p <PORT> -b <BAUD> flash_id
    ```

    The output contains device information and its flash size:

    ```
    Detected flash size: 4MB
    ```

    *`<BOOTLOADER_FLASH_OFFSET>` value must follow one of the addresses below:*

    | ESP32   | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C2 | ESP32-C6 | ESP32-H2 |
    | :-----: | :-----:  | :-----:  | :-----:  | :-----:  | :-----:  | :-----:  |
    | 0x1000  | 0x1000   | 0x0000   | 0x0000   | 0x0000   | 0x0000   | 0x0000   |

    ---

3. Reset your device

## [Signing and flashing an application](#signing-and-flashing-an-application)

1. Images can be regularly signed with the `scripts/imgtool.py` script:

    ```bash
    imgtool.py sign --align 4 -v 0 -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <SIGNED_BIN>
    ```

    ---

    ***Note***

    `<SLOT_SIZE>` is the size of the slot to be used.
    Default slot0 size is `0x100000`, but it can change as per application flash partitions.

    For Zephyr images, `--pad-header` is not needed as it already has the padding for MCUboot
    header.

    ---

    :warning: ***ATTENTION***

    *This is the basic signing needed for adding MCUboot headers and trailers.
    For signing with a crypto key and guarantee the authenticity of the image being booted, see the
    section [MCUboot image signature verification](#mcuboot-image-signature-verification) below.*

    ---

2. Flash the signed application:

    ```bash
    esptool.py -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <TARGET>  write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <SLOT_OFFSET> <SIGNED_BIN>
    ```

# [Downgrade prevention](#downgrade-prevention)

Downgrade prevention (avoid updating of images to an older version) can be enabled using the
following configuration:

```
CONFIG_ESP_DOWNGRADE_PREVENTION=y
```

MCUboot will then verify and compare the new image version number with the current one before
perform an update swap.

Version number is added to the image when signing it with `imgtool` (`-v` parameter, e.g.
`-v 1.0.0`).

### [Downgrade prevention with security counter](#downgrade-prevention-with-security-counter)

It is also possible to rely on a security counter, also added to the image when signing with
`imgtool` (`-s` parameter), apart from version number. This allows image downgrade at some extent,
since any update must have greater or equal security counter value. Enable using the following
configuration:

```
CONFIG_ESP_DOWNGRADE_PREVENTION_SECURITY_COUNTER=y
```

E.g.: if the current image was signed using `-s 1` parameter, an eventual update image must have
been signed using security counter `-s 1` or greater.

# [Security Chain on Espressif port](#security-chain-on-espressif-port)

[MCUboot encrypted images](encrypted_images.md) do not provide full code confidentiality when only
external storage is available (see [Threat model](encrypted_images.md#threat-model)) since by
MCUboot design the image in Primary Slot, from where the image is executed, is stored plaintext.
Espressif chips have off-chip flash memory, so to ensure a security chain along with MCUboot image
signature verification, the hardware-assisted Secure Boot and Flash Encryption were made available
on the MCUboot Espressif port.

## [MCUboot image signature verification](#mcuboot-image-signature-verification)

The image that MCUboot is booting can be signed with 4 types of keys: RSA-2048, RSA-3072, EC256 and
ED25519. In order to enable the feature, the **bootloader** must be compiled with the following
configurations:

---
***Note***

*It is strongly recommended to generate a new signing key using `imgtool` instead of use the
existent samples.*

---

#### For EC256 algorithm use

```
CONFIG_ESP_SIGN_EC256=y

# Use Tinycrypt lib for EC256 or ED25519 signing
CONFIG_ESP_USE_TINYCRYPT=y

CONFIG_ESP_SIGN_KEY_FILE=<YOUR_SIGNING_KEY.pem>
```

#### For ED25519 algorithm use

```
CONFIG_ESP_SIGN_ED25519=y

# Use Tinycrypt lib for EC256 or ED25519 signing
CONFIG_ESP_USE_TINYCRYPT=y

CONFIG_ESP_SIGN_KEY_FILE=<YOUR_SIGNING_KEY.pem>
```

#### For RSA (2048 or 3072) algorithm use

```
CONFIG_ESP_SIGN_RSA=y
# RSA_LEN is 2048 or 3072
CONFIG_ESP_SIGN_RSA_LEN=<RSA_LEN>

# Use Mbed TLS lib for RSA image signing
CONFIG_ESP_USE_MBEDTLS=y

CONFIG_ESP_SIGN_KEY_FILE=<YOUR_SIGNING_KEY.pem>
```

Notice that the public key will be embedded in the bootloader code, since the hardware key storage
is not supported by Espressif port.

### [Signing the image](#signing-the-image)

Now you need to sign the **image binary**, use the `imgtool` with `-k` parameter:

```bash
imgtool.py sign -k <YOUR_SIGNING_KEY.pem> --pad --pad-sig --align 4 -v 0 -H 32 --pad-header -S 0x00100000 <BIN_IN> <BIN_OUT>
```

If signing a Zephyr image, the `--pad-header` is not needed, as it already have the padding for
MCUboot header.


## [Secure Boot](#secure-boot)

The Secure Boot implementation is based on
[IDF's Secure Boot V2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html),
is hardware-assisted and RSA based - except ESP32-C2 that uses ECDSA signing scheme - and has the
role for ensuring that only authorized code will be executed on the device. This is done through
bootloader signature checking by the ROM bootloader.

***Note***: ROM bootloader is the First Stage Bootloader, while the Espressif MCUboot port is the
Second Stage Bootloader.

### [Building bootloader with Secure Boot](#building-bootloader-with-secure-boot)

In order to build the bootloader with the feature on, the following configurations must be enabled:

```
CONFIG_SECURE_BOOT=1
CONFIG_SECURE_BOOT_V2_ENABLED=1
CONFIG_SECURE_SIGNED_ON_BOOT=1
```

For the currently supported chips, with exception of ESP32-C2, enable RSA signing scheme:

```
CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME=1
CONFIG_SECURE_BOOT_SUPPORTS_RSA=1
```

For ESP32-C2, enable ECDSA signing scheme and, if working with Flash Encryption too, enable the
configuration to burn keys to efuse together:

```
CONFIG_SECURE_SIGNED_APPS_ECDSA_V2_SCHEME=1

CONFIG_SECURE_BOOT_FLASH_ENC_KEYS_BURN_TOGETHER=1
```

---
:warning: ***ATTENTION***

*On development phase is recommended add the following configuration in order to keep the debugging
enabled and also to avoid any unrecoverable/permanent state change:*

```
CONFIG_SECURE_BOOT_ALLOW_JTAG=1
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=1

# Options for enabling eFuse emulation in Flash
CONFIG_EFUSE_VIRTUAL=1
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
```
---

---
:warning: ***ATTENTION***

*You can disable UART Download Mode by adding the following configuration:*

```
CONFIG_SECURE_DISABLE_ROM_DL_MODE=1
```

*This may be suitable for __production__ builds. __After disabling UART Download Mode you will not
be able to flash other images through UART.__*

*Otherwise, you can switch the UART ROM Download Mode to the Secure Download Mode. It will limit
the use of Download Mode functions to simple flash read, write and erase operations.*

```
CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE=1
```

*Once the device makes its first full boot, these configurations cannot be reverted*

---

Once the **bootloader image** is built, the resulting binary file is required to be signed with
`espsecure.py` tool.

First create a signing key:

```bash
espsecure.py generate_signing_key --version 2 <BOOTLOADER_SIGNING_KEY.pem>
```

Then sign the bootloader image:

```bash
espsecure.py sign_data --version 2 --keyfile <BOOTLOADER_SIGNING_KEY.pem> -o <BOOTLOADER_BIN_OUT> <BOOTLOADER_BIN_IN>
```

---
:warning: ***ATTENTION***

*Once the bootloader is flashed and the device resets, the **first boot will enable Secure Boot**
and the bootloader and key **no longer can be modified**. So **ENSURE** that both bootloader and
key are correct and you did not forget anything before flashing.*

---

Flash the bootloader as following, with `--after no_reset` flag, so you can reset the device only
when assured:

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <SIGNED_BOOTLOADER_BIN>
```

### [Secure Boot Process](#secure-boot-process)

Secure boot uses a signature block appended to the bootloader image in order to verify the
authenticity. The signature block contains the RSA-3072 signature of that image and the RSA-3072
public key.

On its **first boot** the Secure Boot is not enabled on the device eFuses yet, neither the key nor
digests. So the first boot will have the following process:

1. On startup, since it is the first boot, the ROM bootloader will not verify the bootloader image
   (the Secure Boot bit in the eFuse is disabled) yet, so it proceeds to execute it (our MCUboot
   bootloader port).
2. Bootloader calculates the SHA-256 hash digest of the public key and writes the result to eFuse.
3. Bootloader validates the application images and prepare the booting process (MCUboot phase).
4. Bootloader burns eFuse to enable Secure Boot V2.
5. Bootloader proceeds to load the Primary image.

After that the Secure Boot feature is permanently enabled and on every next boot the ROM bootloader
will verify the MCUboot bootloader image. The process of an usual boot:

1. On startup, the ROM bootloader checks the Secure Boot enable bit in the eFuse. If it is enabled,
   the boot will proceed as following.
2. ROM bootloader verifies the bootloader's signature block integrity (magic number and CRC).
   Interrupt boot if it fails.
3. ROM bootloader verifies the bootloader image, interrupt boot if any step fails:
    1. Compare the SHA-256 hash digest of the public key embedded in the bootloader’s signature
       block with the digest saved in the eFuses.
    2. Generate the application image digest and match it with the image digest in the signature
       block.
    3. Use the public key to verify the signature of the bootloader image, using RSA-PSS with the
       image digest calculated from previous step for comparison.
4. ROM bootloader executes the bootloader image.
5. Bootloader does the usual verification (MCUboot phase).
6. Proceeds to boot the Primary image.

## [Flash Encryption](#flash-encryption)

The Espressif Flash Encryption is hardware-assisted, transparent to the MCUboot process and is an
additional security measure beyond MCUboot existent features.
The Flash Encryption implementation is also based on
[IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html)
and is intended for encrypting off-chip flash memory contents, so it is protected against physical
reading.

When enabling the Flash Encryption, the user can encrypt the content either using a **device
generated key** (remains unknown and unreadable) or a **host generated key** (owner is responsible
for keeping the key private and safe). After the flash encryption gets enabled through eFuse
burning on the device, all read and write operations are decrypted/encrypted in runtime.

### [Building bootloader with Flash Encryption](#building-bootloader-with-flash-encryption)

In order to build the bootloader with the feature on, the following configurations must be enabled:

For **release mode**:

```
CONFIG_SECURE_FLASH_ENC_ENABLED=1
CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=1
```

For **development mode**:

```
CONFIG_SECURE_FLASH_ENC_ENABLED=1
CONFIG_SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT=1
```

---
:warning: ***ATTENTION***

*On development phase is strongly recommended adding the following configuration in order to keep
the debugging enabled and also to avoid any unrecoverable/permanent state change:*

```
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=1
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=1
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=1
CONFIG_SECURE_BOOT_ALLOW_JTAG=1

# Options for enabling eFuse emulation in Flash
CONFIG_EFUSE_VIRTUAL=1
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
```
---

---
:warning: ***ATTENTION***

*Unless the recommended flags for __DEVELOPMENT MODE__ were enabled, the actions made by Flash
Encryption process are __PERMANENT__.* \
*Once the bootloader is flashed and the device resets, the __first boot will enable Flash
Encryption, encrypt the flash content including bootloader and image slots, burn the eFuses that no
longer can be modified__ and if device generated the key __it will not be recoverable__.* \
*When on __RELEASE MODE__, __ENSURE__ that the application with an update agent is flashed before
reset the device.*

*In the same way as Secure Boot feature, you can disable UART Download Mode by adding the following
configuration:*

```
CONFIG_SECURE_DISABLE_ROM_DL_MODE=1
```

*This may be suitable for __production__ builds. __After disabling UART Download Mode you will not
be able to flash other images through UART.__*

*Otherwise, you can switch the UART Download Mode to the Secure Download Mode. It will limit the
use of Download Mode functions to simple flash read, write and erase operations.*

```
CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE=1
```

*These configurations cannot be reverted after the device's first boot*

---

### [Signing the image when working with Flash Encryption](#signing-the-image-when-working-with-flash-encryption)

When enabling flash encryption, it is required to signed the image using 32-byte alignment:
`--align 32 --max-align 32`.

Command example:

```bash
imgtool.py sign -k <YOUR_SIGNING_KEY.pem> --pad --pad-sig --align 32 --max-align 32 -v 0 -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <BIN_OUT>
```

### [Device generated key](#device-generated-key)

First ensure that the application image is able to perform encrypted read and write operations to
the SPI Flash. Flash the bootloader and application normally:

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>
```

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>
```

On the **first boot**, the bootloader will:

1. Generate Flash Encryption key and write to eFuse.
2. Encrypt flash in-place including bootloader, image primary/secondary slot and scratch.
3. Burn eFuse to enable Flash Encryption.
4. Reset system to ensure Flash Encryption cache resets properly.

### [Host generated key](#host-generated-key)

First ensure that the application image is able to perform encrypted read and write operations to
the SPI Flash. Also ensure that the **UART ROM Download Mode is not disabled** - or that the
**Secure Download Mode is enabled**. Before flashing, generate the encryption key using
`espsecure.py` tool:

```bash
espsecure.py generate_flash_encryption_key <FLASH_ENCRYPTION_KEY.bin>
```

Burn the key into the device's eFuse (keep a copy on the host), this action can be done **only
once**:

---
:warning: ***ATTENTION***

*eFuse emulation in Flash configuration options do not have any effect, so if the key burning
command below is used, it will actually burn the physical eFuse.*

---

- ESP32

```bash
espefuse.py --port PORT burn_key flash_encryption <FLASH_ENCRYPTION_KEY.bin>
```

- ESP32S2, ESP32C3 and ESP32S3

```bash
espefuse.py --port PORT burn_key BLOCK <FLASH_ENCRYPTION_KEY.bin> <KEYPURPOSE>
```

`BLOCK` is a free keyblock between `BLOCK_KEY0` and `BLOCK_KEY5`. And `KEYPURPOSE` is either
`XTS_AES_128_KEY`, `XTS_AES_256_KEY_1`, `XTS_AES_256_KEY_2` (AES XTS 256 is available only in
ESP32S2).

Now, similar as the Device generated key, the bootloader and application can be flashed plaintext.
The **first boot** will encrypt the flash content using the host key burned in the eFuse instead
of generate a new one.

Flashing the bootloader and application:

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>
```

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>
```

On the **first boot**, the bootloader will:

1. Encrypt flash in-place including bootloader, image primary/secondary slot and scratch using the
   written key.
2. Burn eFuse to enable Flash Encryption.
3. Reset system to ensure Flash Encryption cache resets properly.

Encrypting data on the host:

- ESP32

```bash
espsecure.py encrypt_flash_data --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFFSET> --output <OUTPUT_DATA> <INPUT_DATA>
```

- ESP32-S2, ESP32-C3 and ESP32-S3

```bash
espsecure.py encrypt_flash_data --aes_xts --keyfile <FLASH_ENCRYPTION_KEY.bin> --address <FLASH_OFFSET> --output <OUTPUT_DATA> <INPUT_DATA>
```

---
***Note***

OTA updates are required to be sent plaintext. The reason is that, as said before, after the Flash
Encryption is enabled all read/write operations are decrypted/encrypted in runtime, so as e.g. if
pre-encrypted data is sent for an OTA update, it would be wrongly double-encrypted when the update
agent writes to the flash.

For updating with an image encrypted on the host, flash it through serial using `esptool.py` as
above. **UART ROM Download Mode must not be disabled**.

---

## [Security Chain scheme](#security-chain-scheme)

Using the 3 features, Secure Boot, Image signature verification and Flash Encryption, a Security
Chain can be established so only trusted code is executed, and also the code and content residing
in the off-chip flash are protected against undesirable reading.

The overall final process when all features are enabled:

1. ROM bootloader validates the MCUboot bootloader using RSA signature verification.
2. MCUboot bootloader validates the image using the chosen algorithm EC256/RSA/ED25519. It also
   validates an upcoming image when updating.
3. Flash Encryption guarantees that code and data are not exposed.

### [Size Limitation](#size-limitation)

When all 3 features are enable at same time, the bootloader size may exceed the fixed limit for
the ROM bootloader checking on the Espressif chips **depending on which algorithm** was chosen for
MCUboot image signing. The issue <https://github.com/mcu-tools/mcuboot/issues/1262> was created to
track this limitation.

## [Multi image](#multi-image)

The multi image feature (currently limited to 2 images) allows the images to be updated separately
(each one has its own primary and secondary slot) by MCUboot.

The Espressif port bootloader handles the boot in two different approaches:

### [Host OS boots second image](#host-os-boots-second-image)

Host OS from the *first image* is responsible for booting the *second image*, therefore the
bootloader is aware of the second image regions and can update it, however it does not load
neither boots it.

Configuration example (`bootloader.conf`):

```
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y

# Enables multi image, if it is not defined, its assumed
# only one updatable image
CONFIG_ESP_IMAGE_NUMBER=2

# Example of values to be used when multi image is enabled
# Notice that the OS layer and update agent must be aware
# of these regions
CONFIG_ESP_APPLICATION_SIZE=0x50000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x60000
CONFIG_ESP_IMAGE1_PRIMARY_START_ADDRESS=0xB0000
CONFIG_ESP_IMAGE1_SECONDARY_START_ADDRESS=0x100000
CONFIG_ESP_SCRATCH_OFFSET=0x150000
CONFIG_ESP_SCRATCH_SIZE=0x40000
```

### [Multi boot](#multi-boot)

In the multi boot approach the bootloader is responsible for booting two different images in two
different CPUs, firstly the *second image* on the APP CPU and then the *first image* on the PRO
CPU (current CPU), it is also responsible for update both images as well. Thus multi boot will be
only supported by Espressif multi core chips - currently only ESP32 is implemented.

---
***Note***

*The host OSes in each CPU must handle how the resources are divided/controlled between then.*

---

Configuration example:

```
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y

# Enables multi image, if it is not defined, its assumed
# only one updatable image
CONFIG_ESP_IMAGE_NUMBER=2

# Enables multi image boot on independent processors
# (main host OS is not responsible for booting the second image)
# Use only with CONFIG_ESP_IMAGE_NUMBER=2
CONFIG_ESP_MULTI_PROCESSOR_BOOT=y

# Example of values to be used when multi image is enabled
# Notice that the OS layer and update agent must be aware
# of these regions
CONFIG_ESP_APPLICATION_SIZE=0x50000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x60000
CONFIG_ESP_IMAGE1_PRIMARY_START_ADDRESS=0xB0000
CONFIG_ESP_IMAGE1_SECONDARY_START_ADDRESS=0x100000
CONFIG_ESP_SCRATCH_OFFSET=0x150000
CONFIG_ESP_SCRATCH_SIZE=0x40000
```

### [Image version dependency](#image-version-dependency)

MCUboot allows version dependency check between the images when updating them. As `imgtool.py`
allows a version assigment when signing an image, it is also possible to add the version
dependency constraint:

```bash
imgtool.py sign --align 4 -v <VERSION> -d "(<IMAGE_INDEX>, <VERSION_DEPENDENCY>)" -H 32 --pad-header -S <SLOT_SIZE> <BIN_IN> <SIGNED_BIN>
```

- `<VERSION>` defines the version of the image being signed.
- `"(<IMAGE_INDEX>, <VERSION_DEPENDENCY>)"` defines the minimum version and from which image is
  needed to satisfy the dependency.

---
Example:

```bash
imgtool.py sign --align 4 -v 1.0.0 -d "(1, 0.0.1+0)" -H 32 --pad-header -S 0x100000 image0.bin image0-signed.bin
```

Supposing that the image 0 is being signed, its version is 1.0.0 and it depends on image 1 with
version at least 0.0.1+0.

---

## [Serial recovery mode](#serial-recovery-mode)

Serial recovery mode allows management through MCUMGR (more information and how to install it:
<https://github.com/apache/mynewt-mcumgr-cli>) for communicating and uploading a firmware to the
device.

Configuration example:

```
# Enables the MCUboot Serial Recovery, that allows the use of
# MCUMGR to upload a firmware through the serial port
CONFIG_ESP_MCUBOOT_SERIAL=y
# GPIO used to boot on Serial Recovery
CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT=32
# GPIO input type (0 for Pull-down, 1 for Pull-up)
CONFIG_ESP_SERIAL_BOOT_GPIO_INPUT_TYPE=0
# GPIO signal value
CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL=1
# Delay time for identify the GPIO signal
CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S=5
# UART port used for serial communication
CONFIG_ESP_SERIAL_BOOT_UART_NUM=1
# GPIO for Serial RX signal
CONFIG_ESP_SERIAL_BOOT_GPIO_RX=25
# GPIO for Serial TX signal
CONFIG_ESP_SERIAL_BOOT_GPIO_TX=26
```

When enabled, the bootloader checks the if the GPIO `<CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT>`
configured has the signal value `<CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL>` for approximately
`<CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S>` seconds for entering the Serial recovery mode. Example:
a button configured on GPIO 32 pressed for 5 seconds.

Serial mode then uses the UART port configured for communication
(`<CONFIG_ESP_SERIAL_BOOT_UART_NUM>`, pins `<CONFIG_ESP_SERIAL_BOOT_GPIO_RX>`,
`<CONFIG_ESP_SERIAL_BOOT_GPIO_RX>`).

### [Serial Recovery through USB JTAG Serial port](#serial-recovery-through-usb-jtag-serial-port)

Some chips, like ESP32-C3 and ESP32-S3 have an integrated USB JTAG Serial Controller that
implements a serial port (CDC) that can also be used for handling MCUboot Serial Recovery.
More information about the USB pins and hardware configuration:

- ESP32-C3: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/usb-serial-jtag-console.html>
- ESP32-S3: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/usb-serial-jtag-console.html>
- ESP32-C6: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-guides/usb-serial-jtag-console.html>
- ESP32-H2: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-guides/usb-serial-jtag-console.html>

Configuration example:

```
# Use Serial through USB JTAG Serial port for Serial Recovery
CONFIG_ESP_MCUBOOT_SERIAL_USB_SERIAL_JTAG=y
# Use sector erasing (recommended) instead of entire image size
# erasing when uploading through Serial Recovery
CONFIG_ESP_MCUBOOT_ERASE_PROGRESSIVELY=y
# GPIO used to boot on Serial Recovery
CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT=5
# GPIO input type (0 for Pull-down, 1 for Pull-up)
CONFIG_ESP_SERIAL_BOOT_GPIO_INPUT_TYPE=0
# GPIO signal value
CONFIG_ESP_SERIAL_BOOT_GPIO_DETECT_VAL=1
# Delay time for identify the GPIO signal
CONFIG_ESP_SERIAL_BOOT_DETECT_DELAY_S=5
```

---
:warning: ***ATTENTION***

*When working with Flash Encryption enabled, `CONFIG_ESP_MCUBOOT_ERASE_PROGRESSIVELY` must be
__disabled__, although it is recommended for common Serial Recovery usage*

---

### [MCUMGR image upload example](#mcumgr-image-upload-example)

After entering the Serial recovery mode on the device, MCUMGR can be used as following:

Configure the connection:
```bash
mcumgr conn add esp type="serial" connstring="dev=<PORT>,baud=115200,mtu=256"
```

Upload the image (the process may take some time):
```bash
mcumgr -c esp image upload <IMAGE_BIN>
```

Reset the device:
```bash
mcumgr -c esp reset
```

---
:warning: ***ATTENTION***

*Serial recovery mode uploads the image to the PRIMARY_SLOT, therefore if the upload process gets
interrupted the image may be corrupted and unable to boot*

---

## [Memory map organization for OS compatibility](#memory-map-organization-for-os-compatibility)

When adding support for this MCUboot port to an OS or even customizing an already supported
application memory layout, it is mandatory for the OS linker script to avoid overlaping on
`iram_loader_seg` and `dram_seg` bootloader RAM regions. Although part of the RAM becomes initially
unavailable, it is reclaimable by the OS after boot as heap.

Therefore, the application must be designed aware of the bootloader memory usage.

---
***Note***

*Mostly of the Espressif chips have a separation on the address space for the same physical memory
ammount: IRAM (accessed by the instruction bus) and DRAM (accessed by the data bus), which means
that they need to be accessed by different addresses ranges depending on type, but refer to the
same region. More information on the
[Espressif TRMs](https://www.espressif.com/en/support/documents/technical-documents?keys=&field_download_document_type_tid%5B%5D=963).*

---

The following diagrams illustrate a memory organization from the bootloader point of view (notice
that the addresses and sizes may vary depending on the chip), they reflect the linker script
`boot/espressif/port/<TARGET>/ld/bootloader.ld`:

### ESP32

#### ESP32 standard

```
  SRAM0
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40070000 / --------- - SRAM0 START
 *  |        ^                    |
 *  |        | PRO CPU Cache      |  *NOT CLAIMABLE BY OS RAM
 *  |        v                    |
 *  +--------+--------------+------+ 0x40078000 / ----------
 *  |        ^                    |
 *  |        |                    |  *NOT CLAIMABLE BY OS RAM
 *  |        | iram_loader_seg    |  *Region usable as iram_loader_seg during boot
 *  |        | (APP CPU Cache)    |   as APP CPU is not initialized yet
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x40080000 / ----------
 *  |        ^                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        v                    |
 *  +------------------------------+ 0x40090000 / ----------
 *  |        ^                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x40099000 / ----------
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +------------------------------+ 0x4009FFFF / ---------- - SRAM0 END

  SRAM1
                                     IRAM ADDR  / DRAM ADDR
 *  +------------------------------+ 0x400A0000 / 0x3FFFFFFF - SRAM1 START
 *  |        ^                    |
 *  |        |                    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        | dram_seg           |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x400AB900 / 0x3FFF4700
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x400BFFFF / 0x3FFE0000 - SRAM1 END
 Note: On ESP32 the SRAM1 addresses are accessed in reverse order comparing Instruction
 bus (IRAM) and Data bus (DRAM), but refer to the same location. See the TRM for more
 information.

  SRAM2
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ ---------- / 0x3FFAE000 - SRAM2 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ ---------- / 0x3FFDFFFF - SRAM2 END
```

#### ESP32 Multi Processor Boot

This is the linker script mapping when the `CONFIG_ESP_MULTI_PROCESSOR_BOOT` is enabled
([Multi boot](#multi-boot)) since APP CPU Cache region cannot be used for `iram_loader_seg` region
as there would be conflict when the bootloader starts the APP CPU before jump to the main
application.

```
  SRAM0
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40070000 / --------- - SRAM0 START
 *  |        ^                    |
 *  |        |                    |
 *  |        | Cache              |  *Used by PRO CPU and APP CPU as Cache
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x40080000 / ----------
 *  |        ^                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        v                    |
 *  +------------------------------+ 0x40090000 / ----------
 *  |        ^                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x40099000 / ----------
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +------------------------------+ 0x4009FFFF / ---------- - SRAM0 END

  SRAM1
                                     IRAM ADDR  / DRAM ADDR
 *  +------------------------------+ 0x400A0000 / 0x3FFFFFFF - SRAM1 START
 *  |        ^                    |
 *  |        |                    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        | dram_seg           |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x400AB900 / 0x3FFF4700
 *  |        ^                    |
 *  |        |                    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        | iram_loader_seg    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x400B1E00 / 0x3FFEE200
 *  |        ^                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x400BFFFF / 0x3FFE0000 - SRAM1 END
 Note: On ESP32 the SRAM1 addresses are accessed in reverse order comparing Instruction
 bus (IRAM) and Data bus (DRAM), but refer to the same location. See the TRM for more
 information.

  SRAM2
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ ---------- / 0x3FFAE000 - SRAM2 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ ---------- / 0x3FFDFFFF - SRAM2 END
```

### ESP32-S2

```
  SRAM0
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40020000 / 0x3FFB0000 - SRAM0 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ 0x40027FFF / 0x3FFB7FFF - SRAM0 END

  SRAM1
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40028000 / 0x3FFB8000 - SRAM1 START
 *  |        ^                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x40047000 / 0x3FFD7000
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x40050000 / 0x3FFE0000
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_loader_seg    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x40056000 / 0x3FFE6000
 *  |        ^                    |
 *  |        |                    |
 *  |        | dram_seg           |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x4006FFFF / 0x3FFFFFFF - SRAM1 END
```

### ESP32-S3

```
  SRAM0
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40370000 / ---------- - SRAM0 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ 0x40377FFF / ---------- - SRAM0 END

  SRAM1
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40378000 / 0x3FC88000 - SRAM1 START
 *  |        ^                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x403B0000 / 0x3FCC0000
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x403BA000 / 0x3FCCA000
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_loader_seg    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x403C0000 / 0x3FCD0000
 *  |        ^                    |
 *  |        |                    |
 *  |        | dram_seg           |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x403DFFFF / 0x3FCEFFFF - SRAM1 END

  SRAM2
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ ---------- / 0x3FCF0000 - SRAM2 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ ---------- / 0x3FCFFFFF - SRAM2 END
```

### ESP32-C2

```
  SRAM0
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x4037C000 / ---------- - SRAM0 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ 0x4037FFFF / ---------- - SRAM0 END

  SRAM1
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40380000 / 0x3FCA0000 - SRAM1 START
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x403A1370 / 0x3FCC1370
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x403A9B70 / 0x3FCC9B70
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_loader_seg    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x403B0B70 / 0x3FCD0B70
 *  |        ^                    |
 *  |        |                    |
 *  |        | dram_seg           |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x403BFFFF / 0x3FCDFFFF - SRAM1 END
```

### ESP32-C3

```
  SRAM0
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x4037C000 / ---------- - SRAM0 START
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  +--------+--------------+------+ 0x4037FFFF / ---------- - SRAM0 END

  SRAM1
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40380000 / 0x3FC80000 - SRAM1 START
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x403C7000 / 0x3FCC7000
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x403D0000 / 0x3FCD0000
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_loader_seg    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x403D5400 / 0x3FCD5400
 *  |        ^                    |
 *  |        |                    |
 *  |        | dram_seg           |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x403DFFFF / 0x3FCDFFFF - SRAM1 END
```

### ESP32-C6

```
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40800000 / 0x40800000 - HP SRAM START
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x40860610 / 0x40860610
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x40869610 / 0x40869610
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_loader_seg    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x40870610 / 0x40870610
 *  |        ^                    |
 *  |        |                    |
 *  |        | dram_seg           |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x4087FFFF / 0x4087FFFF - HP SRAM END
```

### ESP32-H2

```
                                     IRAM ADDR  / DRAM ADDR
 *  +--------+--------------+------+ 0x40800000 / 0x40800000 - HP SRAM START
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | FREE               |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +--------+--------------+------+ 0x408317D0 / 0x408317D0
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_seg           |  *CLAIMABLE BY OS RAM
 *  |        |                    |
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x40839FD0 / 0x40839FD0
 *  |        ^                    |
 *  |        |                    |
 *  |        |                    |
 *  |        | iram_loader_seg    |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        |                    |
 *  |        v                    |
 *  +------------------------------+ 0x40840FD0 / 0x40840FD0
 *  |        ^                    |
 *  |        |                    |
 *  |        | dram_seg           |  *** SHOULD NOT BE OVERLAPPED ***
 *  |        |                    |  *** OS CAN RECLAIM IT AFTER BOOT LATER AS HEAP ***
 *  |        v                    |
 *  +--------+--------------+------+ 0x4084FFFF / 0x4084FFFF - HP SRAM END
```

# MCUboot port for Mbed OS

This is an MCUboot port for Mbed OS.

## Using MCUboot

Note: The following is a general overview. It does not cover MCUboot or Mbed OS basics.

See https://github.com/AGlass0fMilk/mbed-mcuboot-demo as a detailed example.

### Basic configurations

To use MCUboot, you need to create an Mbed OS project with the following configurations:
* `"mcuboot.primary-slot-address"`: address of the primary slot in the internal flash
* `"mcuboot.slot-size"`: size of an image slot (only one image, two slots are currently supported)
* `"mcuboot.max-img-sectors"`: maximum number of sectors, should be at least the number of sectors in each slot
* `"target.restrict_size"`: the maximum size of the bootloader, such that it does not overlap with the primary slot

More configurations such as signing algorithm, slot swapping, etc. can be found in [mbed_lib.json](https://github.com/mcu-tools/mcuboot/tree/main/boot/mbed/mbed_lib.json). Please note that certain features are not currently supported.

### Providing a secondary slot

You need to provide an instance of `mbed::BlockDevice` as the secondary slot. It can be any types of internal or external storage provided that:
* Its size equals the `"mcuboot.slot-size"` you have set
* Its minimum supported read and write sizes (granularities) are _no larger than_ 16 byte, which MCUboot's read/write operations are aligned to. If the read size is larger than _one byte_, you need to set `"mcuboot.read-granularity"` to the read size of the storage - this buffers smaller read operations.

In order for MCUboot to access your secondary slot, the interface to implement is
```cpp
mbed::BlockDevice* get_secondary_bd(void);
```
which should return an uninitialized instance of BlockDevice.

### Building the bootloader

To build a bootloader based on MCUboot, make sure `"mcuboot.bootloader-build"` is `true` (already the default) and you have provided configurations and a secondary slot BlockDevice as explained above.

### Building a user application

To build a user application, set `"mcuboot.bootloader-build"` to `false` so MCUboot is built as a _library only_ without a bootloader application. This is useful if your user application needs to confirm the current image with `boot_set_confirmed()` after an update, or set a new image in the secondary slot as pending with `boot_set_pending()` in order to trigger an update upon reboot.

As your application starts in the primary slots (instead of the beginning of the whole flash), you need to set the start address (`"target.mbed_app_start"`) to be equal to `"mcuboot.primary-slot-address"` + `"mcuboot.header-size"` of your bootloader. And its size (`"target.mbed_app_size"`) must be no larger than `"mcuboot.slot-size"` - `"mcuboot.header-size"`, and some space must be left for the image trailer too (see [this](design.md#image-trailer)).

# 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: mcu-tools
        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`

# Boot serial functionality with Mynewt

Building with `BOOT_SERIAL: 1` enables some basic management functionality
like listing images and uploading a new image to `slot0`. The serial bootloader
requires that `mtu` is set to a value that is less than or equal to `256`.
This can be done either by editing `~/.newtmgr.cp.json` and setting the `mtu`
for the connection profile, or specifying you connection string manually as in:

```
newtmgr --conntype serial --connstring "dev=/dev/ttyUSB0,mtu=256" image upload -e blinky.img
```

where `/dev/ttyUSB0` is your serial port.

# MCUboot port for NuttX

## Description

The NuttX port of MCUboot secure boot library expects that the platform provides a Flash storage with the following partitions:
- `CONFIG_MCUBOOT_PRIMARY_SLOT_PATH`: MTD partition for the application firmware image PRIMARY slot;
- `CONFIG_MCUBOOT_SECONDARY_SLOT_PATH`: MTD partition for the application firmware image SECONDARY slot;
- `CONFIG_MCUBOOT_SCRATCH_PATH`: MTD partition for the Scratch area;

Also, these are optional features that may be enabled:

- `CONFIG_MCUBOOT_WATCHDOG`: If `CONFIG_WATCHDOG` is enabled, MCUboot shall reset the watchdog timer indicated by `CONFIG_MCUBOOT_WATCHDOG_DEVPATH` to the current timeout value, preventing any imminent watchdog timeouts.

The porting layer of MCUboot library consists of the following interfaces:
- `<flash_map_backend/flash_map_backend.h>`, for enabling MCUboot to manage the application firmware image slots in the device storage.
- `<mcuboot_config/mcuboot_config.h>`, for configuration of MCUboot's features.
- `<mcuboot_config/mcuboot_logging.h>`, for providing logging capabilities.
- `<os/os_malloc.h>`, for providing MCUboot access to the OS memory management interfaces.
- `<sysflash/sysflash.h>`, for configuration of the system's flash area organization.

The NuttX port of MCUboot is implemented at application-level and requires minimal knowledge about characteristics of the underlying storage device. This is achieved by means of the `BCH` and `FTL` subsystems, which enable MCUboot to manage MTD partitions via character device drivers using standard POSIX filesystem operations (e.g. `open()` / `close()` / `read()` / `write()`).

## Creating MCUboot-compatible application firmware images

One common use case for MCUboot is to integrate it to a firmware update agent, which is an important component of a secure firmware update subsystem. Through MCUboot APIs an application is able to install a newly received application firmware image and, once this application firmware image is assured to be valid, the application may confirm it as a stable image. In case that application firmware image is deemed bogus, MCUboot provides an API for invalidating that update, which will induce a rollback procedure to the most recent stable application firmware image.

The `CONFIG_MCUBOOT_UPDATE_AGENT_EXAMPLE` example demonstrates this workflow by downloading an application firmware image from a webserver, installing it and triggering the firmware update process for the next boot after a system reset. There is also the `CONFIG_MCUBOOT_SLOT_CONFIRM_EXAMPLE`, which is a fairly simple example that just calls an MCUboot API for confirming the executing application firmware image as stable.

## Using MCUboot on NuttX as a secure boot solution

NuttX port for MCUboot also enables the creation of a secure bootloader application requiring minimal platform-specific implementation. The logical implementation for the secure boot is performed at application-level by the MCUboot library. Once MCUboot validates the application firmware image, it delegates the loading and execution of the application firmware image to a platform-specific routine, which is accessed via `boardctl(BOARDIOC_BOOT_IMAGE)` call. Each platform must then provide an implementation for the `board_boot_image()` for executing the required actions in order to boot a new application firmware image (e.g. deinitialize peripherals, load the Program Counter register with the application firmware image entry point address).

The MCUboot bootloader application may be enabled by selecting the `CONFIG_MCUBOOT_BOOTLOADER` option.

## Assumptions

### IOCTL MTD commands

The implementation of `<flash_map_backend/flash_map_backend.h>` expects that the MTD driver for a given image partition handles the following `ioctl` commands:
- `MTDIOC_GEOMETRY`, for retrieving information about the geometry of the MTD, required for the configuration of the size of each flash area.
- `MTDIOC_ERASESTATE`, for retrieving the byte value of an erased cell of the MTD, required for the implementation of `flash_area_erased_val()` interface.

### Write access alignment

Through `flash_area_align()` interface MCUboot expects that the implementation provides the shortest data length that may be written via `flash_area_write()` interface. The NuttX implementation passes through the `BCH` and `FTL` layers, which appropriately handle the write alignment restrictions of the underlying MTD. So The NuttX implementation of `flash_area_align()` is able to return a fixed value of 1 byte, even if the MTD does not support byte operations.

## Limitations

### `<flash_map_backend/flash_map_backend.h>` functions are not multitasking-safe

MCUboot's documentation imposes no restrictions regarding the usage of its public interfaces, which doesn't mean they are thread-safe.
But, regarding NuttX implementation of the `<flash_map_backend/flash_map_backend.h>`, it is safe to state that they are **not** multitasking-safe. NuttX implementation manages the MTD partitions via character device drivers. As file-descriptors cannot be shared between different tasks, if one task calls `flash_area_open` and another task calls `flash_area_<read/write/close>` passing the same `struct flash_area` instance, it will result in failure.

# 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.

# 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](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 slot of Image 0
- `slot1_partition`: the secondary slot of Image 0

It is not recommended to use the swap-using-scratch algorithm of MCUboot, but
if this operating mode is desired then the following flash partition is also
needed (see end of this help file for details on creating a scratch partition
and how to use the swap-using-scratch algorithm):

- `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. If there are multiple updateable images
then the corresponding primary and secondary partitions must be defined for
the rest of the images too (for example, `slot2_partition` and
`slot3_partition` for Image 1).

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 DT node labels in your board's
`.dts` file match the ones used there.

## Installing requirements and dependencies

Install additional packages required for development with MCUboot:

```
  cd ~/mcuboot  # or to your directory where MCUboot is cloned
  pip3 install --user -r scripts/requirements.txt
```

## 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 the primary slot should be validated on every boot.

To build MCUboot, create a build directory in boot/zephyr, and build
it as usual:

```
  cd boot/zephyr
  west build -b <board>
```

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 `west build`. Use `west flash`
to flash these binaries from the build directory. Depending
on the target and flash tool used, this might erase the whole of the flash
memory (mass erase) or only the sectors where the bootloader resides prior to
programming the bootloader image itself.

## Building applications for the bootloader

In addition to flash partitions in DTS, some additional configuration
is required to build applications for MCUboot.

This is handled internally by the Zephyr configuration system and is wrapped
in the `CONFIG_BOOTLOADER_MCUBOOT` Kconfig variable, which must be enabled in
the application's `prj.conf` file.

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.

The Zephyr `CONFIG_BOOTLOADER_MCUBOOT` configuration option
[documentation](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_BOOTLOADER_MCUBOOT)
provides additional details regarding the changes it makes to the image
placement and generation in order for an application to be bootable by MCUboot.

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_PRIMARY_SLOT` 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.

Images can be signed with the `scripts/imgtool.py` script.  It is best
to look at `samples/zephyr/Makefile` for examples on how to use this.

### Flashing the application

The application itself can flashed with regular flash tools, but will
need to be programmed at the offset of the primary slot for this particular
target. Depending on the platform and flash tool you might need to manually
specify a flash offset corresponding to the primary slot starting address. This
is usually not relevant for flash tools that use Intel Hex images (.hex) instead
of raw binary images (.bin) since the former include destination address
information. Additionally you will need to make sure that the flash tool does
not perform a mass erase (erasing the whole of the flash) or else you would be
deleting MCUboot.
These images can also be marked for upgrade, and loaded into the secondary slot,
at which point the bootloader should perform an upgrade.  It is up to
the image to mark the primary slot 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,
`scripts/imgtool.py` is able to generate key pairs in all of the
supported formats.  See [the docs](imgtool.md) for more details on
this tool.

### Generating a new keypair

Generating a keypair with imgtool is a matter of running the keygen
subcommand:

```
    $ ./scripts/imgtool.py keygen -k mykey.pem -t rsa-2048
```

The argument to `-t` should be the desired key type.  See the
[the docs](imgtool.md) 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.  Use the ``CONFIG_BOOT_SIGNATURE_KEY_FILE`` Kconfig option to
provide the path to the key file so the build system can extract
the public key in a format usable by the C compiler.
The generated public key is saved in `build/zephyr/autogen-pubkey.h`, which is included
by the `boot/zephyr/keys.c`.

Currently, the Zephyr RTOS port limits its support to one keypair at the time,
although MCUboot's key management infrastructure supports multiple keypairs.

Once MCUboot is built, this new keypair file (`mykey.pem` in this
example) can be used to sign images.

## Using swap-using-scratch flash algorithm

To use the swap-using-scratch flash algorithm, a scratch partition needs to be
present for the target board which is used for holding the data being swapped
from both slots, this section must be at least as big as the largest sector
size of the 2 partitions (e.g. if a device has a primary slot in main flash
with a sector size of 512 bytes and secondar slot in external off-chip flash
with a sector size of 4KB then the scratch area must be at least 4KB in size).
The number of sectors must also be evenly divisable by this sector size, e.g.
4KB, 8KB, 12KB, 16KB are allowed, 7KB, 7.5KB are not. This scratch partition
needs adding to the .dts file for the board, e.g. for the nrf52dk_nrf52832
board thus would involve updating
`<zephyr>/boards/arm/nrf52dk_nrf52832/nrf52dk_nrf52832.dts` with:

```
    boot_partition: partition@0 {
        label = "mcuboot";
        reg = <0x00000000 0xc000>;
    };
    slot0_partition: partition@c000 {
        label = "image-0";
        reg = <0x0000C000 0x37000>;
    };
    slot1_partition: partition@43000 {
        label = "image-1";
        reg = <0x00043000 0x37000>;
    };
    storage_partition: partition@7a000 {
        label = "storage";
        reg = <0x0007a000 0x00006000>;
    };
```

Which would make the application size 220KB and scratch size 24KB (the nRF52832
has a 4KB sector size so the size of the scratch partition can be reduced at
the cost of vastly reducing flash lifespan, e.g. for a 32KB firmware update
with an 8KB scratch area, the scratch area would be erased and programmed 8
times per image upgrade/revert). To configure MCUboot to work in
swap-using-scratch mode, the Kconfig value must be set when building it:
`CONFIG_BOOT_SWAP_USING_SCRATCH=y`.

Note that it is possible for an application to get into a stuck state when
swap-using-scratch is used whereby an application has loaded a firmware update
and marked it as test/confirmed but MCUboot will not swap the images and
erasing the secondary slot from the zephyr application returns an error
because the slot is marked for upgrade.

## Serial recovery

### Interface selection

A serial recovery protocol is available over either a hardware serial port or a USB CDC ACM virtual serial port.
The SMP server implementation can be enabled by the ``CONFIG_MCUBOOT_SERIAL=y`` Kconfig option.
To set a type of an interface, use the ``BOOT_SERIAL_DEVICE`` Kconfig choice, and select either the ``CONFIG_BOOT_SERIAL_UART`` or the ``CONFIG_BOOT_SERIAL_CDC_ACM`` value.
Which interface belongs to the protocol shall be set by the devicetree-chosen node:
- `zephyr,console` - If a hardware serial port is used.
- `zephyr,cdc-acm-uart` - If a virtual serial port is used.

### Entering the serial recovery mode

To enter the serial recovery mode, the device has to initiate rebooting, and a triggering event has to occur (for example, pressing a button).

By default, the serial recovery GPIO pin active state enters the serial recovery mode.
Use the ``mcuboot_button0`` devicetree button alias to assign the GPIO pin to the MCUboot.

Alternatively, MCUboot can wait for a limited time to check if DFU is invoked by receiving an MCUmgr command.
Select ``CONFIG_BOOT_SERIAL_WAIT_FOR_DFU=y`` to use this mode. ``CONFIG_BOOT_SERIAL_WAIT_FOR_DFU_TIMEOUT`` option defines
the amount of time in milliseconds the device will wait for the trigger.

### Direct image upload

By default, the SMP server implementation will only use the first slot.
To change it, invoke the `image upload` MCUmgr command with a selected image number, and make sure the ``CONFIG_MCUBOOT_SERIAL_DIRECT_IMAGE_UPLOAD=y`` Kconfig option is enabled.
Note that the ``CONFIG_UPDATEABLE_IMAGE_NUMBER`` Kconfig option adjusts the number of image-pairs supported by the MCUboot.

The mapping of image number to partition is as follows:
* 0 and 1 - image-0, the primary slot of the first image.
* 2 - image-1, the secondary slot of the first image.
* 3 - image-2.
* 4 - image-3.

0 is a default upload target when no explicit selection is done.

### System-specific commands

Use the ``CONFIG_ENABLE_MGMT_PERUSER=y`` Kconfig option to enable the following additional commands:
* Storage erase - This command allows erasing the storage partition (enable with ``CONFIG_BOOT_MGMT_CUSTOM_STORAGE_ERASE=y``).
* Custom image list - This command allows fetching version and installation status (custom properties) for all images (enable with ``CONFIG_BOOT_MGMT_CUSTOM_IMG_LIST=y``).

### More configuration

For details on other available configuration options for the serial recovery protocol, check the Kconfig options  (for example by using ``menuconfig``).