| Roman Okhrimenko | 13f79ed | 2021-03-11 19:05:41 +0200 | [diff] [blame^] | 1 | ## MCUBootApp - demo bootloading application to be used with Cypress targets |
| 2 | |
| 3 | ### Solution Description |
| 4 | |
| 5 | MCUBootApp is created to demonstrate operation of MCUBoot library on Cypress' PSoC 6 device. It supports various operation modes and features of MCUBoot library. |
| 6 | |
| 7 | * single/multi image operation modes |
| 8 | * overwrite/swap upgrade modes |
| 9 | * interrupted upgrade recovery for swap upgrades |
| 10 | * upgrade image confirmation |
| 11 | * reverting of bad upgrade images |
| 12 | * secondary slots located in external flash |
| 13 | |
| 14 | This demo supports PSoC 6 chips with 1M, 2M and 512K Flash on board. |
| 15 | Evaluation kits are: |
| 16 | * `CY8CPROTO-062-4343W` |
| 17 | * `CY8CKIT-062-WIFI-BT` |
| 18 | * `CY8CPROTO-062S3-4343W`. |
| 19 | |
| 20 | ### Memory Maps |
| 21 | |
| 22 | MCUBoot terminology assumes a slot from which **boot** is happening to be named **primary**, and a slot where **upgrade** image is placed - **secondary**. |
| 23 | |
| 24 | #### Internal Flash |
| 25 | |
| 26 | The flash map is defined at compile time. It can be configured through makefiles and `MCUBootApp/sysflash/sysflash.h` and `cypress/cy_flash_pal/cy_flash_map.c`. |
| 27 | |
| 28 | The default `MCUBootApp` flash map is defined for demonstration purpose. Sizes of slots are adjusted to be compatible with all supported device families: 1M, 2M and 512K. |
| 29 | |
| 30 | Actual addresses provided below are calculated by preprocessor in `sysflash.h` and `cy_flash_map.c` per slot sizes set. |
| 31 | |
| 32 | ##### Single Image Mode |
| 33 | |
| 34 | | Start addr | End addr | Size | Description | |
| 35 | |------------|------------|---------|-------------------------------------------| |
| 36 | | 0x10000000 | 0x10018000 | 0x18000 | MCUBootApp (bootloader) area; | |
| 37 | | 0x10018000 | 0x10028000 | 0x10000 | Primary_1 (BOOT) slot for BlinkyApp; | |
| 38 | | 0x10028000 | 0x10038000 | 0x10000 | Secondary_1 (UPGRADE) slot for BlinkyApp; | |
| 39 | |
| 40 | If upgrade type is swap using scratch: |
| 41 | |
| 42 | | Start addr | Size | Description | |
| 43 | |------------|-----------|---------------------------------| |
| 44 | | 0x10038000 | 0x1800 | Start of swap status partition; | |
| 45 | | 0x10039800 | 0x1000 | Start of scratch area partition;| |
| 46 | |
| 47 | ##### Multi Image Mode |
| 48 | |
| 49 | | Start addr | End addr | Size | Description | |
| 50 | |------------|------------|---------|-------------------------------------------| |
| 51 | | 0x10000000 | 0x10018000 | 0x18000 | MCUBootApp (bootloader) area; | |
| 52 | | 0x10018000 | 0x10028000 | 0x10000 | Primary_1 (BOOT) slot for BlinkyApp; | |
| 53 | | 0x10028000 | 0x10038000 | 0x10000 | Secondary_1 (UPGRADE) slot for BlinkyApp; | |
| 54 | | 0x10038000 | 0x10058000 | 0x20000 | Primary_2 (BOOT) slot of Bootloader | |
| 55 | | 0x10058000 | 0x10078000 | 0x20000 | Secondary_2 (UPGRADE) slot of Bootloader | |
| 56 | |
| 57 | If upgrade type swap: |
| 58 | |
| 59 | | Start addr | Size | Description | |
| 60 | |------------|-----------|---------------------------------| |
| 61 | | 0x10078000 | 0x2800 | Start of swap status partition; | |
| 62 | | 0x1007a800 | 0x1000 | Start of scratch area partition;| |
| 63 | |
| 64 | **SWAP upgrade from external memory** |
| 65 | |
| 66 | When MCUBootApp is configured to support upgrade images places in external memory following fixed addresses are predefined: |
| 67 | |
| 68 | | SMIF base address | Offset | Description | |
| 69 | |-------------------|-------------|---------------------------------| |
| 70 | | 0x18000000 | 0x0 | Start of Secondary_1 (UPGRADE) image; | |
| 71 | | 0x18000000 | 0x240000 | Start of Secondary_2 (UPGRADE) image; | |
| 72 | | 0x18000000 | 0x440000 | Start of scratch area partition;| |
| 73 | |
| 74 | ##### Single Image Mode |
| 75 | |
| 76 | | Start addr | End addr | Size | Description | |
| 77 | |------------|------------|---------|-------------------------------------------| |
| 78 | | 0x10000000 | 0x10018000 | 0x18000 | MCUBootApp (bootloader) area; | |
| 79 | | 0x10018000 | 0x10058200 | 0x40200 | Primary_1 (BOOT) slot for BlinkyApp; | |
| 80 | | 0x18000000 | 0x18040200 | 0x40200 | Secondary_1 (UPGRADE) slot for BlinkyApp; | |
| 81 | |
| 82 | If upgrade type swap: |
| 83 | |
| 84 | | Start addr | Size | Description | |
| 85 | |------------|-----------|---------------------------------| |
| 86 | | 0x10058200 | 0x3c00 | Start of swap status partition; | |
| 87 | |
| 88 | ##### Multi Image Mode |
| 89 | |
| 90 | | Start addr | End addr | Size | Description | |
| 91 | |------------|------------|---------|-------------------------------------------| |
| 92 | | 0x10000000 | 0x10018000 | 0x18000 | MCUBootApp (bootloader) area; | |
| 93 | | 0x10018000 | 0x10058200 | 0x40200 | Primary_1 (BOOT) slot for BlinkyApp; | |
| 94 | | 0x10058200 | 0x10098400 | 0x40200 | Primary_2 (BOOT) slot of Bootloader | |
| 95 | | 0x18000000 | 0x18040200 | 0x40200 | Secondary_1 (UPGRADE) slot for BlinkyApp; | |
| 96 | | 0x18240000 | 0x18280200 | 0x40200 | Secondary_2 (UPGRADE) slot of Bootloader; | |
| 97 | |
| 98 | If upgrade type is swap using scratch: |
| 99 | |
| 100 | | Start addr | Size | Description | |
| 101 | |------------|-----------|---------------------------------| |
| 102 | | 0x10098400 | 0x6400 | Start of swap status partition; | |
| 103 | |
| 104 | ##### How To Modify Flash Map |
| 105 | |
| 106 | When modifying slots sizes - make sure to align new values with linker script files for appropriate applications. |
| 107 | |
| 108 | **Option 1** |
| 109 | |
| 110 | Navigate to `sysflash.h` and modify slots sizes directly to meet your needs. |
| 111 | |
| 112 | `CY_BOOT_BOOTLOADER_SIZE` defines size of MCUBootApp. |
| 113 | `CY_BOOT_IMAGE_1_SIZE` defines slot size for single image case. |
| 114 | `CY_BOOT_IMAGE_2_SIZE` defines slot size of second image in multi image case. |
| 115 | |
| 116 | __Option 2.__ |
| 117 | |
| 118 | Navigate to `sysflash/sysflash.h` and uncomment `CY_FLASH_MAP_EXT_DESC` definition. |
| 119 | Now define and initialize `struct flash_area *boot_area_descs[]` in a code with flash memory addresses and sizes you need at the beginning of application, so flash APIs from `cy_flash_pal/cy_flash_map.c` will use it. |
| 120 | |
| 121 | __Note:__ for both options make sure to use correct `MCUBOOT_MAX_IMG_SECTORS`. This should correspond to slot size used. Maximum value of sectors can be set by passing a flag `MAX_IMG_SECTORS=__number__` to `make`. By default it is set to 256 sectors, which corresponds to `0x20000` slot size in multi image use case. Sector size assumed to be 512 bytes, so 128 sectors needed to fill `0x10000`, 256 sectors for `0x20000` and so on. |
| 122 | |
| 123 | ###### How To Override The Flash Map Values During Build Process |
| 124 | |
| 125 | It is possible to override MCUBootApp definitions from build system. Navigate to `MCUBootApp.mk`, find section `DEFINES_APP +=` |
| 126 | Using this construction macros can be defined and passed to compiler. |
| 127 | |
| 128 | The full list of macros used to configure the custom multi image case with upgrade from external memory: |
| 129 | |
| 130 | * MCUBOOT_MAX_IMG_SECTORS |
| 131 | * CY_FLASH_MAP_EXT_DESC |
| 132 | * CY_BOOT_SCRATCH_SIZE |
| 133 | * CY_BOOT_BOOTLOADER_SIZE |
| 134 | * CY_BOOT_IMAGE_1_SIZE |
| 135 | * CY_BOOT_IMAGE_2_SIZE |
| 136 | * CY_BOOT_EXTERNAL_FLASH_SECONDARY_1_OFFSET |
| 137 | * CY_BOOT_EXTERNAL_FLASH_SECONDARY_2_OFFSET |
| 138 | * CY_BOOT_EXTERNAL_FLASH_SCRATCH_OFFSET |
| 139 | |
| 140 | As an example in a makefile slots sizes redefinition should look like following: |
| 141 | |
| 142 | `DEFINES_APP +=-DCY_BOOT_EXTERNAL_FLASH_SCRATCH_OFFSET=0x18780000` |
| 143 | `DEFINES_APP +=-DMCUBOOT_MAX_IMG_SECTORS=168` |
| 144 | `DEFINES_APP +=-DCY_BOOT_IMAGE_1_SIZE=0x15000` |
| 145 | `DEFINES_APP +=-DCY_BOOT_IMAGE_2_SIZE=0x15000` |
| 146 | |
| 147 | #### External Flash |
| 148 | |
| 149 | It is also possible to place secondary (upgrade) slots in external memory module and use most of internal for primary image. |
| 150 | Details about External Memory usage are described in separate guiding document `MCUBootApp/ExternalMemory.md`. |
| 151 | |
| 152 | #### RAM |
| 153 | |
| 154 | RAM areas in CM0p-based MCUBootApp bootloading application and CM4-based BlinkyApp are defined as an example pair. If your CM4 user application requires different RAM area make sure it is not overlap with MCUBootApp ram area. Memory (stack) corruption of CM0p application can cause failure if SystemCall-served operations invoked from CM4. |
| 155 | |
| 156 | MCUBootApp linker script also contains special section `public_ram`. This section serves for shared ram area between CM0p and CM4 cores. When CM4 and CM0p cores perform operations with internal flash, this area is used for interprocessor connection data sharing. |
| 157 | |
| 158 | ### Hardware Cryptography Acceleration |
| 159 | |
| 160 | Cypress PSoC 6 MCU family supports hardware acceleration of cryptography based on mbedTLS Library via shim layer. Implementation of this layer is supplied as separate submodule `cy-mbedtls-acceleration`. HW acceleration of cryptography shortens boot time in more then 4 times, comparing to software implementation (observation results). |
| 161 | |
| 162 | To enable hardware acceleration in `MCUBootApp` pass flag `USE_CRYPTO_HW=1` to `make` while build. |
| 163 | |
| 164 | Hardware acceleration of cryptography is enabled for PSoC 6 devices by default. |
| 165 | |
| 166 | ### Multi Image Mode |
| 167 | |
| 168 | Multi image operation considers upgrading and verification of more then one image on the device. |
| 169 | |
| 170 | By default MCUBootApp is configured for single image mode. To enable multi image operation pass `MCUBOOT_IMAGE_NUMBER=2` as parameter to `make`. |
| 171 | |
| 172 | `MCUBOOT_IMAGE_NUMBER` can also be changed permanently in `MCUBootApp/config/mcuboot_config.h` file. This value can only be set to 2 (only dual-image is supported at the moment). |
| 173 | |
| 174 | In multi image operation (two images are considered for simplicity) MCUBootApp bootloading application operates as following: |
| 175 | |
| 176 | 1. Verifies Primary_1 and Primary_2 images; |
| 177 | 2. Verifies Secondary_1 and Secondary_2 images; |
| 178 | 3. Upgrades Secondary to Primary if valid images found; |
| 179 | 4. Boots image from Primary_1 slot only; |
| 180 | 5. Boots Primary_1 only if both - Primary_1 and Primary_2 are present and valid; |
| 181 | |
| 182 | This ensures two dependent applications can be accepted by device only in case both images are valid. |
| 183 | |
| 184 | ### Upgrade Modes |
| 185 | |
| 186 | There are two different types of upgrade process supported by MCUBootApp. In case of `overwrite only` type of upgrade - secondary image is simply copied to primary slot after successful validation. No way to revert upgrade in a case when secondary image is inoperable. |
| 187 | |
| 188 | In case of `swap` upgrade mode - images in primary and secondary slots are swaped. Upgrade can be reverted if secondary image did not confirm its operation. |
| 189 | |
| 190 | Upgrade mode is the same for all images in multi image mode. |
| 191 | |
| 192 | #### Overwrite Only |
| 193 | |
| 194 | To build MCUBootApp for overwrite upgrades only `MCUBootApp/config/mcuboot_config/mcuboot_config.h` should contain following define: |
| 195 | |
| 196 | `#define MCUBOOT_OVERWRITE_ONLY 1` |
| 197 | |
| 198 | This define can also be set in `MCUBootApp/MCUBootApp.mk`: |
| 199 | |
| 200 | `DEFINES_APP +=-DMCUBOOT_OVERWRITE_ONLY=1` |
| 201 | |
| 202 | In ovewrite only mode MCUBootApp first checks if any upgrade image is present in secondary slot(s), then validates digital signature of upgrade image in secondary slot(s). If validation is successful MCUBootApp starts copying secondary slot content to primary slot. After copy is done MCUBootApp starts upgrade image execution from primary slot. |
| 203 | |
| 204 | If upgraded application does not work - there is no way no revert back to previous working version. In this case only new upgrade firmware can fix previous broken upgrade. |
| 205 | |
| 206 | #### Swap Mode |
| 207 | |
| 208 | There are 2 basic types of swap modes supported in MCUBoot: |
| 209 | * scratch |
| 210 | * move |
| 211 | |
| 212 | For devices with large minimum erase size like PSoC 6 with 512 bytes and also for configurations which use external flash with even bigger minimum erase size there is an additional option in MCUBoot to use dedicated `status partition` for robust storage of swap related information. |
| 213 | |
| 214 | ##### Why use swap with status partition |
| 215 | |
| 216 | Originally MCUBoot library has been designed with a consideration, that minimum write/erase size of flash would always be 8 bytes or less. This value is critical, because swap algorithms use it to align portions of data that contain swap operation status of each flash sector in slot before writing to flash. Data alignment is also performed before writes of special purpose data to image trailer. |
| 217 | |
| 218 | Writing of flash sector status or image trailer data should be `single cycle` operation to ensure power loss and unpredicted resets robustness of bootloading applications. This requirement eliminates usage of `read-modify-write` type of operations with flash. |
| 219 | |
| 220 | `Swap with status partition` is implemented specifically to address devices with large write/erase size. It is based on existing mcuboot swap algorithms, but does not have restriction of 8 bytes alignment. Instead minimum write/erase size can be specified by user and algorithm will calculate sizes of status partition, considering this value. All write/erase operations are aligned to this minimum write/erase size as well. |
| 221 | |
| 222 | ##### Swap Status Partition Description |
| 223 | |
| 224 | The main distinction of `swap with status partition` is that separate flash area (partition) is used to store swap status values and image trailer instead of using free flash area at the end of primary/secondary image slot. |
| 225 | |
| 226 | This partition consists of separate areas: |
| 227 | * area to store swap status values |
| 228 | * swap_status_0 |
| 229 | * ... |
| 230 | * swap_status_x |
| 231 | * area to store image trailer data: |
| 232 | * Encryption key 0 |
| 233 | * Encryption key 1 |
| 234 | * Swap size |
| 235 | * Swap info |
| 236 | * Copy done value |
| 237 | * Image ok |
| 238 | * Boot image magic |
| 239 | |
| 240 | Principal diagram of status partition: |
| 241 | |
| 242 | ``` |
| 243 | +-+-+-+-+-+-+ +-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ \ |
| 244 | | | | D0 | --> | swap_status_0 | \ |
| 245 | | | +-+-+-+-+-+-+ | swap_status_1 | \ |
| 246 | | | | D1 | | swap_status_2 | \ |
| 247 | | | +-+-+-+-+-+-+ | ... | \ |
| 248 | | PRIMARY | --> | | | swap_status_max | min write/erase |
| 249 | | | | .... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ size of flash hw |
| 250 | | | +-+-+-+-+-+-+ | AREA_MAGIC | / |
| 251 | | | | Dx | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / |
| 252 | +-+-+-+-+-+-+ +-+-+-+-+-+-+ | CRC | / |
| 253 | +-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / |
| 254 | | | | CNT | / |
| 255 | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ \ |
| 256 | | | | swap_status_max+1 | \ |
| 257 | | | | swap_status_max+2 | \ |
| 258 | | SECONDARY | | swap_status_max+3 | \ |
| 259 | | | | ... | \ |
| 260 | | | | swap_status_x | min write/erase |
| 261 | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ size of flash hw |
| 262 | +-+-+-+-+-+-+ | AREA_MAGIC | / |
| 263 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / |
| 264 | | CRC | / |
| 265 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / |
| 266 | | CNT | / |
| 267 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ \ |
| 268 | | | \ |
| 269 | | Image trailer | \ |
| 270 | | | \ |
| 271 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ min write/erase |
| 272 | | AREA_MAGIC | size of flash hw |
| 273 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / |
| 274 | | CRC | / |
| 275 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / |
| 276 | | CNT | / |
| 277 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 278 | ``` |
| 279 | **Scheme legend:** |
| 280 | |
| 281 | `PRIMARY` and `SECONRADY` are areas in status partition to contain data regarding corresponding slot in mcuboot. |
| 282 | `D0`, `D1` and `Dx` are duplicates of data described on the left. At least 2 duplicates should be present in system. This duplication is used to eliminate flash wear. Each of `Dx` contains valid data for `current swap step - 1`. Each swap operation for flash sector updates status for this sector in current `Dx` and value on `CNT` inreases. Next operation checks least value of `CNT` in available `Dx`'s, copies there data from `Dx` with `CNT+1` and updates status of current sector. This continues until all sectors in slot are moved and then swaped. |
| 283 | `CRC` - 4 bytes value - checksum of data contaited in area. |
| 284 | `CNT` - 4 bytes value. |
| 285 | `swap_status_0`, `swap_status_1`- one byte values, that contain status for corresponding image sector. |
| 286 | `swap_status_x` - last sector of `BOOT_MAX_IMAGE_SECTORS`. |
| 287 | `swap_status_max` - maximum number of sectors that fits in min write/erase size for particular flash hardware. If `swap_status_max` is less then `swap_status_x` additional slice of min write/erase flash area is allocated to store swap status data. |
| 288 | `Image trailer` - should be at least 64 bytes. Code calculates how many min write/erase sizes need to be allocated to store image trailer data.m. |
| 289 | |
| 290 | **Calculation example for PSoC 6 with minimum write/erase size of 512 bytes is used.** |
| 291 | |
| 292 | Following considered: |
| 293 | * Single image case |
| 294 | * Minimum write/erase size 512 bytes |
| 295 | * PRIMARY/SECONDARY slots size `0x50000` |
| 296 | * BOOT_MAX_IMG_SECTORS 0x50000 / 512 = 640 |
| 297 | * Number of duplicates `Dx = 2` |
| 298 | |
| 299 | One slice of `min write/erase` size can store data for maximum number of 500 sectors: 512 - 4 (CRC) - 4 (CNT) - 4 (area magic) = 500. Since BOOT_MAX_IMG_SECTORS is 640 - 2 slices of `min write/erase` is allocated. Total size is 1024 bytes. |
| 300 | Image trailer data fits in 64 bytes, so one slice of `min write/erase` size is allocated. Total size is 1024 + 512 = 1536 bytes. |
| 301 | Duplicates number equals 2. Total size is 1536 * 2 = 3072 bytes. |
| 302 | 2 slots are used in particular case PRIMARY and SECONDARY, each needs 3072 bytes to store swap status data. Tolal is 3072 * 2 = 6144 bytes. |
| 303 | |
| 304 | Swap status partition occupies 6144 bytes of flash area in this case. |
| 305 | |
| 306 | **Expected lifecycle** |
| 307 | |
| 308 | Since bootloading application that uses swap using status partition upgrade mode stores system state in separate flash area following product lifecycle is expected: |
| 309 | `Empty` - Fully erased device |
| 310 | `Ready` - `Empty` device is programmed with MCUBoot based bootloading application - MCUBootApp in this case. |
| 311 | `Flashed` - Initial version v1.0 of user applicatio, BlinkyApp is this case, flashed to primary (BOOT) slot. |
| 312 | `Upgraded` - updated firmware image of user application is delivered to secondary slot (UPGRADE) and bootloading application performs upgrade. |
| 313 | |
| 314 | It is expected that product stays in `Upgraded` state ultil end of its lifecycle. |
| 315 | |
| 316 | In case there is a need to wipe out product and flash new firmware directly to primary (BOOT) slot - device should be transfered to `Empty` or `Ready` state and then walk through all states again. |
| 317 | |
| 318 | ### Hardware Limitations |
| 319 | |
| 320 | Since this application is created to demonstrate MCUBoot library features and not as reference examples some considerations are taken. |
| 321 | |
| 322 | 1. `SCB5` used to configure serial port for debug prints. This is the most commonly used Serial Communication Block number among available Cypress PSoC 6 kits. If you try to use custom hardware with this application - change definition of `CYBSP_UART_HW` in `main.c` of MCUBootApp to SCB* that correspond to your design. |
| 323 | |
| 324 | 2. `CY_SMIF_SLAVE_SELECT_0` is used as definition SMIF driver API. This configuration is used on evaluation kit for this example CY8CPROTO-062-4343W. If you try to use custom hardware with this application - change value of `smif_id` in `main.c` of MCUBootApp to value that corresponds to your design. |
| 325 | |
| 326 | ### Downloading Solution's Assets |
| 327 | |
| 328 | There is a set assets required: |
| 329 | |
| 330 | * MCUBooot Library (root repository) |
| 331 | * PSoC 6 HAL Library (submodule) |
| 332 | * PSoC 6 Peripheral Drivers Library (PDL) (submodule) |
| 333 | * mbedTLS Cryptographic Library (submodule) |
| 334 | |
| 335 | To get submodules - run the following command: |
| 336 | |
| 337 | git submodule update --init --recursive |
| 338 | |
| 339 | ### Configuring MCUBootApp Bootloading Application |
| 340 | |
| 341 | 1. Choose upgrade mode: |
| 342 | |
| 343 | `SWAP` - this mode is set by default in `MCUBootApp/config/mcuboot_config/mcuboot_config.h`. `MCUBOOT_SWAP_USING_STATUS` preprocessor symbol is defined to enable this mode. |
| 344 | |
| 345 | `Ovewrite only` - pass `USE_OVERWRITE=1` parameter to `make` for overwrite mode compilation. |
| 346 | |
| 347 | 2. Change memory map |
| 348 | |
| 349 | Check paragraph **How to modify Flash map** above. |
| 350 | |
| 351 | 3. Enable hardware acceleration of cryptography |
| 352 | |
| 353 | Pass `USE_CRYPTO_HW=1` to `make` command. This option is enabled by default. |
| 354 | |
| 355 | 4. Change number of images - single or multi image configuration |
| 356 | |
| 357 | Pass `MCUBOOT_IMAGE_NUMBER=1` for single image configuration |
| 358 | Pass `MCUBOOT_IMAGE_NUMBER=2` for multi image configuration |
| 359 | |
| 360 | ### Building Solution |
| 361 | |
| 362 | This folder `boot/cypress` contains make files infrastructure for building MCUBootApp bootloader application. Example build command are provided below for couple different build configurations. |
| 363 | |
| 364 | * Build MCUBootApp in `Debug` configuration for single image use case. |
| 365 | |
| 366 | make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M BUILDCFG=Debug MCUBOOT_IMAGE_NUMBER=1 |
| 367 | |
| 368 | * Build MCUBootApp in `Release` configuration for multi image use case. |
| 369 | |
| 370 | make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M BUILDCFG=Release MCUBOOT_IMAGE_NUMBER=2 |
| 371 | |
| 372 | Root directory for build is `boot/cypress`. |
| 373 | |
| 374 | ### Encrypted Image Support |
| 375 | |
| 376 | To protect user image from unwanted read - Upgrade Image Encryption can be applied. The ECDH/HKDF with EC256 scheme is used in a given solution as well as mbedTLS as a crypto provider. |
| 377 | |
| 378 | To enable image encryption support use `ENC_IMG=1` build flag (BlinkyApp should also be built with this flash set 1). |
| 379 | |
| 380 | User is also responsible for providing corresponding binary key data in `enc_priv_key[]` (file `\MCUBootApp\keys.c`). The public part will be used by imgtool when signing and encrypting upgrade image. Signing image with encryption is described in `\BlinkyApp\Readme.md`. |
| 381 | |
| 382 | After MCUBootApp is built with these settings unencrypted and encrypted images will be accepted in secondary (upgrade) slot. |
| 383 | |
| 384 | Example command: |
| 385 | |
| 386 | make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M BUILDCFG=Debug MCUBOOT_IMAGE_NUMBER=1 ENC_IMG=1 |
| 387 | |
| 388 | __NOTE__: Debug configuration of MCUBootApp with multi image encrypted upgrades in external flash (built with flags `BUILDCFG=Debug` `MCUBOOT_IMG_NUMBER=2 USE_EXTERNAL_FLASH=1 ENC_IMG=1`) is set to use optimization level `-O2 -g3` to fit into `0x18000` allocated for `MCUBootApp`. |
| 389 | |
| 390 | ### Programming Solution |
| 391 | |
| 392 | There are couple ways of programming MCUBootApp firmware. Following instructions assume usage of one of Cypress development kits `CY8CPROTO_062_4343W`. |
| 393 | |
| 394 | 1. Direct usage of OpenOCD. |
| 395 | |
| 396 | OpenOCD package is supplied with ModuToolbox IDE and can be found in installation folder under `./tools_2.1/openocd`. |
| 397 | |
| 398 | Open terminal application - and execute following command after substitution `PATH_TO_APPLICATION.hex` and `OPENOCD` paths. |
| 399 | |
| 400 | Connect a board to your computer. Switch Kitprog3 to DAP-BULK mode by pressing `SW3 MODE` button until `LED2 STATUS` constantly shines. |
| 401 | |
| 402 | export OPENOCD=/Applications/ModusToolbox/tools_2.1/openocd |
| 403 | |
| 404 | ${OPENOCD}/bin/openocd -s ${OPENOCD}/scripts \ |
| 405 | -f ${OPENOCD}/scripts/interface/kitprog3.cfg \ |
| 406 | -f ${OPENOCD}/scripts/target/psoc6_2m.cfg \ |
| 407 | -c "init; reset init; program PATH_TO_APPLICATION.hex" \ |
| 408 | -c "resume; reset; exit" |
| 409 | |
| 410 | 2. Using GUI tool `Cypress Programmer` |
| 411 | |
| 412 | Follow [link](https://www.cypress.com/products/psoc-programming-solutions) to download. |
| 413 | |
| 414 | Connect board to your computer. Switch Kitprog3 to DAP-BULK mode by pressing `SW3 MODE` button until `LED2 STATUS` constantly shines. Open `Cypress Programmer` and click `Connect`, then choose hex file: `MCUBootApp.hex` or `BlinkyApp.hex` and click `Program`. Check log to ensure programming success. Reset board. |
| 415 | |
| 416 | 3. Using `DAPLINK`. |
| 417 | |
| 418 | Connect board to your computer. Switch embeded Kitprog3 to `DAPLINK` mode by pressing `SW3 MODE` button until `LED2 STATUS` blinks fast and mass storage device appeared in OS. Drag and drop `hex` files you wish to program to `DAPLINK` drive in your OS. |
| 419 | |
| 420 | ### Build Environment Troubleshooting |
| 421 | |
| 422 | Regular shell/terminal combination on Linux and MacOS. |
| 423 | |
| 424 | On Windows: |
| 425 | |
| 426 | * Cygwin |
| 427 | * Msys2 |
| 428 | |
| 429 | Also IDE may be used: |
| 430 | * Eclipse / ModusToolbox ("makefile project from existing source") |
| 431 | |
| 432 | *Make* - make sure it is added to system's `PATH` variable and correct path is first in the list; |
| 433 | |
| 434 | *Python/Python3* - make sure you have correct path referenced in `PATH`; |
| 435 | |
| 436 | *Msys2* - to use systems PATH navigate to msys2 folder, open `msys2_shell.cmd`, uncomment set `MSYS2_PATH_TYPE=inherit`, restart MSYS2 shell. |
| 437 | |
| 438 | *Cygwin* - add following to build command `CURDIR=pwd | cygpath --mixed -f -` so that build command looks like that: |
| 439 | |
| 440 | make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M CURDIR=`pwd | cygpath --mixed -f -` |
| 441 | |
| 442 | This will iherit system's PATH so should find `python3.7` installed in regular way as well as imgtool and its dependencies. |
| 443 | |