1### Blinking LED test application for MCUBoot Bootloader 2 3### Description 4 5Implements simple Blinky LED CM4 application to demonstrate MCUBoot Application operation in terms of BOOT and UPGRADE process. 6 7It is started by MCUBoot Application which is running on CM0p. 8 9Functionality: 10 11* Blinks RED led with 2 different rates, depending on type of image - BOOT or UPGRADE. 12* Prints debug info and version of itself to terminal at 115200 baud. 13* Can be built for BOOT slot or UPGRADE slot of bootloader. 14 15Currently supported platforms 16 17* PSOC_062_2M 18* PSOC_062_1M 19* PSOC_062_512K 20 21### Hardware limitations 22 23Since this application is created to demonstrate MCUBoot library features and not as reference examples some considerations are taken. 24 251. Port/pin `P5_0` and `P5_1` used to configure serial port for debug prints. These pins are the most commonly used for serial port connection among available Cypress PSoC 6 kits. If you try to use custom hardware with this application - change definitions of `CY_DEBUG_UART_TX` and `CY_DEBUG_UART_RX` in `main.c` of BlinkyApp to port/pin pairs corresponding to your design. 262. Port `GPIO_PRT13` pin `7U` used to define user connection LED. This pin is the most commonly used for USER_LED connection among available Cypress PSoC 6 kits. If you try to use custom hardware with this application - change definitions of `LED_PORT` and `LED_PIN` in `main.c` of BlinkyApp to port/pin pairs corresponding to your design. 27 28### Pre-build action 29 30Pre-build action is implemented for defining start address and size of flash, as well as RAM start address and size for BlinkyApp. 31These values are set by specifing following macros: `-DUSER_APP_SIZE`, `-DUSER_APP_START`, `-DRAM_SIZE`, `-DRAM_START` in makefile. 32 33Pre-build action calls GCC preprocessor which intantiates defines for particular values in `BlinkyApp_template.ld`. 34 35Default values set for currently supported targets: 36* `BlinkyApp.mk` to `-DUSER_APP_START=0x10018000` 37 38**Important**: make sure RAM areas of CM4-based BlinkyApp and CM0p-based MCUBootApp bootloader do not overlap. 39Memory (stack) corruption of CM0p application can cause failure if SystemCall-served operations invoked from CM4. 40 41### Building an application 42 43Root directory for build is **boot/cypress.** 44 45The following command will build regular HEX file of a BlinkyApp for BOOT slot. Substitute `PLATFORM=` to a paltform name you use in all following commands. 46 47 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=BOOT 48 49This have following defaults suggested: 50 51 BUILDCFG=Debug 52 IMG_TYPE=BOOT 53 54To build UPGRADE image use following command: 55 56 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=UPGRADE HEADER_OFFSET=0x10000 57 58 Note: HEADER_OFFSET=%SLOT_SIZE% 59 60Example command-line for single-image: 61 62 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=BOOT 63 64**Building Multi-Image** 65 66`BlinkyApp` can be built to use in multi-image bootloader configuration. 67 68To get appropriate artifacts to use with multi image MCUBootApp, makefile flag `HEADER_OFFSET=` can be used. 69 70Example usage: 71 72Considering default config: 73 74* first image BOOT (PRIMARY) slot start `0x10018000` 75* slot size `0x10000` 76* second image BOOT (PRIMARY) slot start `0x10038000` 77 78To get appropriate artifact for second image PRIMARY slot run this command: 79 80 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=BOOT HEADER_OFFSET=0x20000 81 82*Note:* only 2 images are supported at the moment. 83 84**How to build upgrade image for external memory:** 85 86To prepare MCUBootApp for work with external memory please refer to `MCUBootApp/ExternalMemory.md`. 87 88For build BlinkyApp upgrade image for external memory use command: 89 90 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=UPGRADE HEADER_OFFSET=0x7FE8000 ERASED_VALUE=0xff 91 92`HEADER_OFFSET` defines the offset from original boot image address. This one in line above suggests secondary slot will start from `0x18000000`. 93 94`ERASED_VALUE` defines the memory cell contents in erased state. It is `0x00` for PSoC6's internal Flash and `0xff` for S25FL512S. 95 96In case of using muti-image configuration, upgrade image for second application can be built using next command: 97 98 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=UPGRADE HEADER_OFFSET=0x8028000 ERASED_VALUE=0xff 99 100 Note: for S25FL512S block address shuld be mutiple by 0x40000 101 102**How to build encrypted upgrade image :** 103 104To prepare MCUBootApp for work with encrypted upgrade image please refer to `MCUBootApp/Readme.md`. 105 106To obtain encrypted upgrade image of BlinkyApp extra flag `ENC_IMG=1` should be passed in command line, for example: 107 108 make app APP_NAME=BlinkyApp PLATFORM=PSOC_062_2M IMG_TYPE=UPGRADE HEADER_OFFSET=0x20000 ENC_IMG=1 109 110This also suggests user already placed corresponing `*.pem` key in `\keys` folder. The key variables are defined in root `Makefile` as `SIGN_KEY_FILE` and `ENC_KEY_FILE` 111 112### Post-Build 113 114Post build action is executed at compile time for `BlinkyApp`. In case of build for `PSOC_062_2M` platform it calls `imgtool` from `MCUBoot` scripts and adds signature to compiled image. 115 116Flags passed to `imgtool` for signature are defined in `SIGN_ARGS` variable in BlinkyApp.mk. 117 118### How to program an application 119 120Use any preferred tool for programming hex files. 121 122Hex file names to use for programming: 123 124`BlinkyApp` always produce build artifacts in 2 separate folders - `boot` and `upgrade`. 125 126`BlinkyApp` built to run with `MCUBootApp` produces files with name BlinkyApp.hex in `boot` directory and `BlinkyApp_upgrade.hex` in `upgrade` folder. These files are ready to be flashed to the board. 127 128`BlinkyApp_unsigned.hex` hex file is also preserved in both cases for possible troubleshooting. 129 130Files to use for programming are: 131 132`BOOT` - boot/BlinkyApp.hex 133`UPGRADE` - upgrade/BlinkyApp_upgrade.hex 134 135**Flags:** 136- `BUILDCFG` - configuration **Release** or **Debug** 137- `MAKEINFO` - 0 (default) - less build info, 1 - verbose output of compilation. 138- `HEADER_OFFSET` - 0 (default) - no offset of output hex file, 0x%VALUE% - offset for output hex file. Value 0x10000 is slot size MCUBoot Bootloader in this example. 139- `IMG_TYPE` - `BOOT` (default) - build image for BOOT slot of MCUBoot Bootloader, `UPGRADE` - build image for UPGRADE slot of MCUBoot Bootloader. 140- `ENC_IMG` - 0 (default) - build regular upgrade image, `1` - build encrypted upgrade image (MCUBootApp should also be built with this flash set 1) 141 142**NOTE**: In case of `UPGRADE` image `HEADER_OFFSET` should be set to MCUBoot Bootloader slot size. 143 144### Example terminal output 145 146When user application programmed in BOOT slot: 147 148 =========================== 149 [BlinkyApp] BlinkyApp v1.0 [CM4] 150 =========================== 151 [BlinkyApp] GPIO initialized 152 [BlinkyApp] UART initialized 153 [BlinkyApp] Retarget I/O set to 115200 baudrate 154 [BlinkyApp] Red led blinks with 1 sec period 155 156When user application programmed in UPRADE slot and upgrade procedure was successful: 157 158 =========================== 159 [BlinkyApp] BlinkyApp v2.0 [+] 160 =========================== 161 162 [BlinkyApp] GPIO initialized 163 [BlinkyApp] UART initialized 164 [BlinkyApp] Retarget I/O set to 115200 baudrate 165 [BlinkyApp] Red led blinks with 0.25 sec period 166
