Skip to content

Commit

Permalink
v3.4.0 (#5)
Browse files Browse the repository at this point in the history
* 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.
  • Loading branch information
LiyouZhou committed Aug 22, 2018
1 parent d953689 commit 1003366
Show file tree
Hide file tree
Showing 31 changed files with 595 additions and 578 deletions.
2 changes: 2 additions & 0 deletions .astyleignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
BUILD
scripts
59 changes: 59 additions & 0 deletions .astylerc
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Mbed OS code style definition file for astyle

# Don't create backup files, let git handle it
suffix=none

# K&R style
style=kr

# 1 TBS addition to k&r, add braces to one liners
# Use -j as it was changed in astyle from brackets to braces, this way it is compatible with older astyle versions
-j

# 4 spaces, convert tabs to spaces
indent=spaces=4
convert-tabs

# Indent switches and cases
indent-switches

# Remove spaces in and around parentheses
unpad-paren

# Insert a space after if, while, for, and around operators
pad-header
pad-oper

# Pointer/reference operators go next to the name (on the right)
align-pointer=name
align-reference=name

# Attach { for classes and namespaces
attach-namespaces
attach-classes

# Extend longer lines, define maximum 120 value. This results in aligned code,
# otherwise the lines are broken and not consistent
max-continuation-indent=120


# Style formatting options for Update Client codebase.

# Each line no greater than 120 characters.
--max-code-length=120

# Display only files that have been formatted.
-Q

# Keep one-line blocks, especially for union initialization of error structs.
--keep-one-line-blocks

# Indent pre-processor block
# --indent-preproc-block

# Delete empty lines
# --delete-empty-lines

# Attach the return type to a function definition or declaration.
--attach-return-type # Definition
--attach-return-type-decl # Declaration
55 changes: 16 additions & 39 deletions .mbedignore
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,24 @@ mbed-os/features/FEATURE_COMMON_PAL/mbed-trace/test/*
mbed-os/features/FEATURE_COMMON_PAL/nanostack-libservice/source/*
mbed-os/features/FEATURE_COMMON_PAL/nanostack-libservice/test/*
mbed-os/features/FEATURE_UVISOR/*
mbed-os/features/unsupported/*
mbed-os/features/cellular/*
mbed-os/features/lorawan/*
mbed-os/features/nanostack/*
mbed-os/features/netsocket/*
mbed-os/features/storage/*
mbed-os/features/filesystem/littlefs/*
mbed-os/features/filesystem/fat/*
mbed-os/features/unsupported/*
mbed-os/features/device_key/*
mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F437xG/TARGET_UBLOX_C030/onboard_modem_api.c
mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F437xG/TARGET_UBLOX_C030/onboard_modem_api.h
mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F437xG/TARGET_UBLOX_C030/min_battery_voltage.c
mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F437xG/TARGET_UBLOX_C030/min_battery_voltage.h
mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F439xI/TARGET_MODULE_UBLOX_ODIN_W2/sdk/ublox-odin-w2-drivers/default_wifi_interface.cpp
mbed-os/features/frameworks/mbed-client-randlib/*
mbed-os/features/frameworks/mbed-coap/*
mbed-os/features/frameworks/mbed-trace/*
mbed-os/features/frameworks/nanostack-libservice/*
mbed-cloud-client/update-client-hub/source/*
mbed-cloud-client/update-client-hub/modules/atomic-queue/*
mbed-cloud-client/update-client-hub/modules/control-center/*
Expand All @@ -33,52 +45,17 @@ mbed-cloud-client/update-client-hub/modules/pal-filesystem/*
mbed-cloud-client/update-client-hub/modules/pal-target-specific/*
mbed-cloud-client/update-client-hub/modules/source-http/*
mbed-cloud-client/update-client-hub/modules/source-manager/*
mbed-cloud-client/update-client-hub/modules/resume-engine/*
mbed-cloud-client/update-client-hub/modules/common/source/arm_uc_scheduler.c
mbed-cloud-client/mbed-client-pal/Test/*
mbed-cloud-client/mbed-client-pal/Utils/*
mbed-cloud-client/mbed-client-pal/Examples/*
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/pal_init.c
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Modules/Crypto/*
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Modules/Networking/*
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Modules/RTOS/*
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Modules/TLS/*
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Modules/Update/*
mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Modules/Storage/FileSystem/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/Lib_Specific/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/OS_Specific/FreeRTOS/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/OS_Specific/Linux/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/OS_Specific/mbedOS/Networking/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/OS_Specific/mbedOS/RTOS/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/OS_Specific/mbedOS/Update/*
mbed-cloud-client/mbed-client-pal/Source/Port/Reference-Impl/OS_Specific/mbedOS/Storage/FileSystem/*
mbed-cloud-client/mbed-client-pal/*
mbed-cloud-client/CMakeLists.txt
mbed-cloud-client/DOXYGEN_FRONTPAGE.md
mbed-cloud-client/Jenkinsfile
mbed-cloud-client/LICENSE
mbed-cloud-client/README.md
mbed-cloud-client/contributions.md
mbed-cloud-client/doxygen/*
mbed-cloud-client/factory-configurator-client/CMakeLists.txt
mbed-cloud-client/factory-configurator-client/DOXYGEN_FRONTPAGE.md
mbed-cloud-client/factory-configurator-client/common_includes.cmake
mbed-cloud-client/factory-configurator-client/crypto-service/*
mbed-cloud-client/factory-configurator-client/factory-configurator-client/*
mbed-cloud-client/factory-configurator-client/fcc-bundle-handler/*
mbed-cloud-client/factory-configurator-client/fcc-output-info-handler/*
mbed-cloud-client/factory-configurator-client/ftcd-comm-base/*
mbed-cloud-client/factory-configurator-client/ftcd-comm-serial/*
mbed-cloud-client/factory-configurator-client/ftcd-comm-socket/*
mbed-cloud-client/factory-configurator-client/key-config-manager/*
mbed-cloud-client/factory-configurator-client/logger/*
mbed-cloud-client/factory-configurator-client/mbed-trace-helper/*
mbed-cloud-client/factory-configurator-client/secsrv-cbor/*
mbed-cloud-client/factory-configurator-client/storage/*
mbed-cloud-client/factory-configurator-client/utils/*
mbed-cloud-client/factory-configurator-client/mbed-client-esfs/Test/*
mbed-cloud-client/factory-configurator-client/mbed-client-esfs/Tools/*
mbed-cloud-client/factory-configurator-client/mbed-client-esfs/source/esfs.c
mbed-cloud-client/factory-configurator-client/mbed-client-esfs/source/esfs_file_name.c
mbed-cloud-client/factory-configurator-client/mbed-client-esfs/source/esfs_performance.c
mbed-cloud-client/factory-configurator-client/*
mbed-cloud-client/mbed-client/*
mbed-cloud-client/mbed-client-randlib/*
mbed-cloud-client/mbed-cloud-client/*
Expand Down
52 changes: 38 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,30 +7,51 @@ Generic bootloader to be used in conjunction with [mbed-cloud-client](https://gi
1. Install `mbed-cli` https://github.com/ARMmbed/mbed-cli
1. Run `mbed deploy` to pull in dependencies
1. Compile by running `mbed compile -t GCC_ARM -m (K64F|NUCLEO_F429ZI|UBLOX_EVK_ODIN_W2) --profile=tiny.json`
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}`.
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}`.
1. Flash `{combined.bin}` to device by drag and drop.

## Metadata Header

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.

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

## Configurations

User **must** set in `mbed_app.json`:
NOTE: All these configurations must be set the same in the mbed cloud client when compiling the corresponding application for successful update operation.

### Active Application and Header

1. `update-client.application-details`, Address at which the metadata header of the active firmware is written. **Must align to flash erase boundary**
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.
1. `application-start-address`, Address at which the application starts **Must align to vector table size boundary and flash write page boundary**.
1. `application-jump-address`, Optional address for the application's entry point (vector table) if this is different from `application-start-address`.

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

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.

### Firmware Candidate Storage

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.
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**
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.
1. `update-client.storage-locations`, The number of slots in the firmware storage.
1. `update-client.storage-page`, The write page size of the underlying storage.

If you are using SOTP to provide the RoT, you must set the following:
- "sotp-section-1-address", "sotp-section-1-size", "sotp-section-2-address", "sotp-section-2-size"
The addresses **Must align to flash erase boundary**. The sizes must be full sector sized and at least 1k large.
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.

### Device Secret Key

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

All these configurations must be set the same in the mbed cloud client when compiling the corresponding application for successful update operation.
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:
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).
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.
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.

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

### MISC

User **may** set in `mbed_app.json`:
1. `MAX_COPY_RETRIES`, The number of retries after a failed copy attempt.
Expand All @@ -39,7 +60,9 @@ User **may** set in `mbed_app.json`:
1. `SHOW_PROGRESS_BAR`, Set to 1 to print a progress bar for various processes.

## Flash Layout

### The flash layout for K64F with SOTP and firmware storage on internal flash

```
+--------------------------+
| LittleFS |
Expand All @@ -66,24 +89,25 @@ User **may** set in `mbed_app.json`:
|Active App Metadata Header|
| |
+--------------------------+ <-+ update-client.application-details
| SOTP_2 |
+--------------------------+ <-+ sotp-section-2-address
| SOTP_1 |
+--------------------------+ <-+ sotp-section-1-address
| NVSTORE_2 |
+--------------------------+ <-+ nvstore.area_2_address
| NVSTORE_1 |
+--------------------------+ <-+ nvstore.area_1_address
| |
| Bootloader |
| |
| |
+--------------------------+ <-+ 0
```

### Notes on Flash Layout

- 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).
- 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.
- The SOTP regions require 1 flash erase sector each with at least 1k of space.
- The NVSTORE regions require 1 flash erase sector each with at least 1k of space.
- The LittleFS requires 2 flash sectors per folder and 1 sector per file as well as 2 sectors for the filesystem itself.

### Alignment

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

**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.
Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
{
"macros": [
"MBEDTLS_USER_CONFIG_FILE=\"mbedtls_mbed_client_config.h\"",
"MBEDTLS_USER_CONFIG_FILE=\"bootloader_mbedtls_user_config.h\"",
"PAL_USER_DEFINED_CONFIGURATION=\"bootloader_pal_user_config.h\"",
"MAX_COPY_RETRIES=1",
"SHOW_PROGRESS_BAR=1",
"MAX_BOOT_RETRIES=3",
"ARM_UC_USE_PAL_CRYPTO=0",
"Mutex=PlatformMutex",
"PAL_USE_INTERNAL_FLASH=1",
"PAL_THREAD_SAFETY=0",
"ARM_UC_USE_SOTP=1",
"MBED_CLOUD_CLIENT_UPDATE_STORAGE=ARM_UCP_FLASHIAP"
"ARM_BOOTLOADER_USE_NVSTORE_ROT=0",
"MBED_CLOUD_CLIENT_UPDATE_STORAGE=ARM_UCP_FLASHIAP",
"Mutex=PlatformMutex"
],
"config": {
"application-start-address": {
Expand All @@ -19,26 +18,6 @@
"max-application-size": {
"help": "Maximum size of the active application",
"value": null
},
"sotp-section-1-address": {
"help": "Flash sector address for SOTP sector 1",
"macro_name": "PAL_INTERNAL_FLASH_SECTION_1_ADDRESS",
"value": null
},
"sotp-section-1-size": {
"help": "Flash sector size for SOTP sector 1",
"macro_name": "PAL_INTERNAL_FLASH_SECTION_1_SIZE",
"value": null
},
"sotp-section-2-address": {
"help": "Flash sector address for SOTP sector 2",
"macro_name": "PAL_INTERNAL_FLASH_SECTION_2_ADDRESS",
"value": null
},
"sotp-section-2-size": {
"help": "Flash sector size for SOTP sector 2",
"macro_name": "PAL_INTERNAL_FLASH_SECTION_2_SIZE",
"value": null
}
},
"target_overrides": {
Expand All @@ -50,17 +29,22 @@
"update-client.firmware-header-version": "2"
},
"K64F": {
"sotp-section-1-address" : "( 32*1024)",
"sotp-section-1-size" : "( 4*1024)",
"sotp-section-2-address" : "( 36*1024)",
"sotp-section-2-size" : "( 4*1024)",
"update-client.application-details": "( 40*1024)",
"application-start-address" : "( 41*1024)",
"max-application-size" : "(MBED_CONF_UPDATE_CLIENT_STORAGE_ADDRESS-MBED_CONF_APP_APPLICATION_START_ADDRESS)",
"update-client.storage-address" : "(436*1024)",
"update-client.storage-size" : "(388*1024)",
"update-client.storage-locations" : 1,
"update-client.storage-page" : 8
},
"NUCLEO_F429ZI": {
"update-client.application-details": "(0x08000000+64*1024)",
"application-start-address" : "(0x08000000+65*1024)",
"max-application-size" : "(MBED_CONF_UPDATE_CLIENT_STORAGE_ADDRESS-MBED_CONF_APP_APPLICATION_START_ADDRESS)",
"update-client.storage-address" : "(0x08000000+1024*1024)",
"update-client.storage-size" : "(512*1024)",
"update-client.storage-locations" : 1,
"update-client.storage-page" : 1
}
}
}
Loading

0 comments on commit 1003366

Please sign in to comment.