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