You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add configuration file for a bootloader with default RoT and internal flash firmware storage for Nucleo_F429ZI and K64F
* Application start address can be configured independently of application jump address to support cases where the vector table is not at the start of the firmware image.
* Active Metadata Header is no longer required to be directly in front of the the active application. It's location can be independently configured.
* Add configuration for new platforms: NRF52, NUCLEO_F411RE
* Upgrade to mbed-os-5.9.4
* Downgrade to sd-driver-0.1.2 to reduce binary size
* Use NVSTORE API shipped with Mbed-OS instead of SOTP API to retrieve the Root of Trust.
* Clean up configuration
* Guard sd block device instantiation so that when internal flash firmware storage is used, all sd-driver code can be linked out.
* Clean up coding style to conform to [mbed-os coding style](https://os.mbed.com/docs/latest/reference/style.html).
* Wrap ARM_UCP_FLASHIAP_BLOCKDEVICE so that it only contains the necessary read functions. This reduces binary size.
* SOTP is being replaced with NVSTORE which is shipped in Mbed-OS. As NVSTORE is binary compatible with SOTP there is no breakage. The configuration of offsets are still be the same.
* In order to keep bootloader size to a minimum, please use latest arm-none-eabi-gcc. Current version is tested with version 7.3.1 which produces binary size smaller than 32k for K64F, UBLOX_EVK_ODIN_W2 and NUCLEO_F429ZI.
1. Use this [script](https://github.com/ARMmbed/mbed-cloud-client-example/blob/master/tools/combine_bootloader_with_app.py) to combine the bootloader with application `python tools/combine_bootloader_with_app.py -a {application.bin} -b {bootloader.bin} --app-offset {firmware_metadata_header_address+firmware_metadata_header_size} --header-offset {firmware_metadata_header_address} -o {combined.bin}`.
10
+
1. Use this [script](https://github.com/ARMmbed/mbed-cloud-client-example/blob/master/tools/combine_bootloader_with_app.py) to combine the bootloader with application `python tools/combine_bootloader_with_app.py -a {application.bin} -b {bootloader.bin} --app-offset {application-start-address} --header-offset {firmware_metadata_header_address} -o {combined.bin}`.
11
11
1. Flash `{combined.bin}` to device by drag and drop.
12
12
13
13
## Metadata Header
14
14
15
15
The metadata header is the bootloader update interface. Each stage of the boot sequence leading up to and including the application (except the root bootloader) is paired with a metadata header (containing version, size, hash etc.). Information contained in the metadata header allows validation and ordering of available firmwares.
16
16
17
-
The firmware metadata header structure can be found [here](https://github.com/ARMmbed/mbed-cloud-client/blob/master/update-client-hub/modules/common/update-client-common/arm_uc_metadata_header_v2.h). There are two header formats, internal and external. The external header format is meant to be used when storing firmware on external storage which is assumed to be insecure. Hence the external header format contains extra security information prevent external tampering of the header data.
17
+
The firmware metadata header structure can be found [here](https://github.com/ARMmbed/mbed-cloud-client/blob/master/update-client-hub/modules/common/update-client-common/arm_uc_metadata_header_v2.h). There are two header formats, internal and external. The external header format is used for storing firmware on external storage which is assumed to be insecure. Hence the external header format contains extra security information to prevent external tampering of the header data.
18
18
19
19
## Configurations
20
20
21
-
User **must** set in `mbed_app.json`:
21
+
NOTE: All these configurations must be set the same in the mbed cloud client when compiling the corresponding application for successful update operation.
22
+
23
+
### Active Application and Header
24
+
22
25
1.`update-client.application-details`, Address at which the metadata header of the active firmware is written. **Must align to flash erase boundary**
23
-
1.`application-start-address`, Address at which The application starts **Must align to vector table size boundary and flash write page boundary**. It is assumed the region between `update-client.application-details` and `application-start-address` contains only the header. MUST be the same as "target.mbed_app_start" in the application.
26
+
1.`application-start-address`, Address at which the application starts **Must align to vector table size boundary and flash write page boundary**.
27
+
1.`application-jump-address`, Optional address for the application's entry point (vector table) if this is different from `application-start-address`.
28
+
29
+
If the `application-start-address` is set less than one erase sector after the `update-client.application-details`, the two regions will be erased together. Otherwise the two regions will be erased separately in which case `application-start-address` must also align to **flash erase boundary**.
30
+
31
+
If `application-jump-address` is not set, the `application-start-address` will be used as the application's entry point. The entry point MUST be the same as "target.mbed_app_start" in the application.
32
+
33
+
### Firmware Candidate Storage
34
+
35
+
1.`MBED_CLOUD_CLIENT_UPDATE_STORAGE`, This need to be set in the "macros" section of `mbed_app.json`. Choices are ARM_UCP_FLASHIAP_BLOCKDEVICE and ARM_UCP_FLASHIAP. This determines whether the firmware is stored on a blockdevice or internal flash. If blockdevice is used `ARM_UC_USE_PAL_BLOCKDEVICE=1` must also be set.
24
36
1.`update-client.storage-address`, The address in sd block device or internal flash where the firmware candidates are stored. **Must align to flash erase boundary**
25
37
1.`update-client.storage-size`, total size on the block device or internal flash reserved for firmware storage. It will be rounded up to align with flash erase sector size automatically.
26
38
1.`update-client.storage-locations`, The number of slots in the firmware storage.
27
39
1.`update-client.storage-page`, The write page size of the underlying storage.
28
40
29
-
If you are using SOTP to provide the RoT, you must set the following:
The addresses **Must align to flash erase boundary**. The sizes must be full sector sized and at least 1k large.
41
+
NOTE: See the [mbed cloud client documentation](https://cloud.mbed.com/docs/current/porting/update-k64f-port.html) for more information about storage options avaiable and porting to new platforms.
42
+
43
+
### Device Secret Key
44
+
45
+
The bootloader uses device secret key to authenticate anything that is stored on external storage. The update client must be able to obtain the same key as the bootlaoder. The key is derived from a device root of trust using the algorithm [here](https://github.com/ARMmbed/mbed-cloud-client/blob/master/update-client-hub/modules/common/source/arm_uc_crypto.c#L401).
32
46
33
-
All these configurations must be set the same in the mbed cloud client when compiling the corresponding application for successful update operation.
47
+
You may choose to use NVSTORE to store the device RoT. During first boot mbed cloud client will generate a random number from an available entropy source and storge it in NVSTORE on internal flash. On subsequent boots, the RoT will be read from NVSTORE. To enable NVSTORE RoT, you must set the following:
48
+
1. Macro `ARM_BOOTLOADER_USE_NVSTORE_ROT=1` to enable the RoT implementation [here](https://github.com/ARMmbed/mbed-bootloader/blob/master/source/nvstore_rot.cpp).
49
+
1. "nvstore.area_1_address", "nvstore.area_1_size", "nvstore.area_2_address", "nvstore.area_2_size". The addresses **Must align to flash erase boundary**. The sizes must be full sector sized and at least 1k.
50
+
1. NVSTORE and SOTP are binary compatible hence the bootloader works with any software that uses SOTP as long as the offsets are set the same.
51
+
52
+
Alternatively you can choose to use a custom device specific RoT by implementing the function `mbed_cloud_client_get_rot_128bit`. An example can be found [here](https://github.com/ARMmbed/mbed-bootloader-internal/blob/master/source/example_insecure_rot.c#L40).
53
+
54
+
### MISC
34
55
35
56
User **may** set in `mbed_app.json`:
36
57
1.`MAX_COPY_RETRIES`, The number of retries after a failed copy attempt.
@@ -39,7 +60,9 @@ User **may** set in `mbed_app.json`:
39
60
1.`SHOW_PROGRESS_BAR`, Set to 1 to print a progress bar for various processes.
40
61
41
62
## Flash Layout
63
+
42
64
### The flash layout for K64F with SOTP and firmware storage on internal flash
65
+
43
66
```
44
67
+--------------------------+
45
68
| LittleFS |
@@ -66,24 +89,25 @@ User **may** set in `mbed_app.json`:
- Internal Flash Only layout can be enabled by compiling the bootloader with the internal_flash_sotp.json configuration file `--app-config configs/internal_flash_sotp.json`. By default the firmware storage region and filesystem is on [external sd card](#external-storage).
82
105
- The default flash layout is tested with GCC_ARM compiler and tiny.json compiler profile only. If a different compiler is used, the bootloader binary size will be larger and the offsets needs to be adjusted.
83
-
- The SOTP regions require 1 flash erase sector each with at least 1k of space.
106
+
- The NVSTORE regions require 1 flash erase sector each with at least 1k of space.
84
107
- The LittleFS requires 2 flash sectors per folder and 1 sector per file as well as 2 sectors for the filesystem itself.
85
108
86
109
### Alignment
110
+
87
111
**Flash Erase Boundary**: Flash can usually only be erased in blocks of specific sizes, this is platform specific and hence many regions need to align to this boundary.
88
112
89
113
**Flash Page Boundary**: Flash can usually only be written in blocks of specific sizes, this is platform specific and hence many regions need to align to this boundary.
0 commit comments