1### Port of MCUboot library to be used with Cypress targets
2
3**Solution Description**
4
5Given solution demonstrates operation of MCUboot on Cypress' PSoC6 device.
6
7There are two applications implemented:
8* MCUBootApp - PSoC6 MCUboot-based bootloading application;
9* BlinkyApp - simple PSoC6 blinking LED application which is a target of BOOT/UPGRADE;
10
11Cypress boards, that can be used with this evaluation example:
12- CY8CPROTO-062-4343W - PSoC 6 2M on board
13- CY8CKIT-062-WIFI-BT - PSoC 6 1M on board
14- CY8CPROTO-062S3-4343W - PSoC 6 512K on board
15The default flash map implemented is the following:
16
17Single-image mode.
18
19`[0x10000000, 0x10018000]` - MCUBootApp (bootloader) area;
20
21`[0x10018000, 0x10028000]` - primary slot for BlinkyApp;
22
23`[0x10028000, 0x10038000]` - secondary slot for BlinkyApp;
24
25`[0x10038000, 0x10039000]` - scratch area (not used);
26
27Size of slots `0x10000` - 64kb
28
29MCUBootApp checks image integrity with SHA256, image authenticity with EC256 digital signature verification and uses completely SW implementation of cryptographic functions based on Mbed TLS Library.
30
31**Important**: make sure primary, secondary slot and bootloader app sizes are appropriate and correspond to flash area size defined in Applications' linker files.
32
33**Important**: make sure RAM areas of CM0p-based MCUBootApp bootloader and CM4-based BlinkyApp do not overlap.
34Memory (stack) corruption of CM0p application can cause failure if SystemCall-served operations invoked from CM4.
35
36### Hardware cryptography acceleration
37
38Cypress PSOC6 MCU family supports hardware acceleration of cryptography based on Mbed TLS Library via shim layer. Implementation of this layer is supplied as separate submodule `cy-mbedtls-acceleration`. HW acceleration of cryptography shortens boot time more then 4 times, comparing to software implementation (observation results).
39
40To enable hardware acceleration in `MCUBootApp` pass flag `USE_CRYPTO_HW=1` to `make` while build.
41
42Hardware acceleration of cryptography is enabled for PSOC6 devices by default.
43
44### How to modify memory map
45
46__Option 1.__
47
48Navigate to `sysflash.h` and modify the flash area(s) / slots sizes to meet your needs.
49
50__Option 2.__
51
52Navigate to `sysflash.h`, uncomment `CY_FLASH_MAP_EXT_DESC` definition.
53Now define and initialize `struct flash_area *boot_area_descs[]` with flash memory addresses and sizes you need at the beginning of application, so flash APIs from `cy_flash_map.c` will use it.
54
55__Note:__ for both options make sure you have updated `MCUBOOT_MAX_IMG_SECTORS` appropriatery with sector size assumed to be 512.
56
57**How to override the flash map values during build process:**
58
59Navigate to MCUBootApp.mk, find section `DEFINES_APP +=`
60Update this line and or add similar for flash map parameters to override.
61
62The possible list could be:
63
64* MCUBOOT_MAX_IMG_SECTORS
65* CY_FLASH_MAP_EXT_DESC
66* CY_BOOT_SCRATCH_SIZE
67* CY_BOOT_BOOTLOADER_SIZE
68* CY_BOOT_PRIMARY_1_SIZE
69* CY_BOOT_SECONDARY_1_SIZE
70* CY_BOOT_PRIMARY_2_SIZE
71* CY_BOOT_SECONDARY_2_SIZE
72
73As an example in a makefile it should look like following:
74
75`DEFINES_APP +=-DCY_FLASH_MAP_EXT_DESC`
76
77`DEFINES_APP +=-DMCUBOOT_MAX_IMG_SECTORS=512`
78
79`DEFINES_APP +=-DCY_BOOT_PRIMARY_1_SIZE=0x15000`
80
81**Multi-Image Operation**
82
83Multi-image operation considers upgrading and verification of more then one image on the device.
84
85To enable multi-image operation define `MCUBOOT_IMAGE_NUMBER` in `MCUBootApp/config/mcuboot_config.h` file should be set to 2 (only dual-image is supported at the moment). This could also be done on build time by passing `MCUBOOT_IMAGE_NUMBER=2` as parameter to `make`.
86
87Default value of `MCUBOOT_IMAGE_NUMBER` is 1, which corresponds to single image configuratios.
88
89In multi-image operation (two images are considered for simplicity) MCUboot Bootloader application operates as following:
90
91* Verifies Primary_1 and Primary_2 images;
92* Verifies Secondary_1 and Secondary_2 images;
93* Upgrades Secondary to Primary if valid images found;
94* Boots image from Primary_1 slot only;
95* Boots Primary_1 only if both - Primary_1 and Primary_2 are present and valid;
96
97This ensures two dependent applications can be accepted by device only in case both images are valid.
98
99**Default Flash map for Multi-Image operation:**
100
101`0x10000000 - 0x10018000` - MCUboot Bootloader
102
103`0x10018000 - 0x10028000` - Primary_1 (BOOT) slot of Bootloader
104
105`0x10028000 - 0x10038000` - Secondary_1 (UPGRADE) slot of Bootloader
106
107`0x10038000 - 0x10048000` - Primary_2 (BOOT) slot of Bootloader
108
109`0x10048000 - 0x10058000` - Secondary_2 (UPGRADE) slot of Bootloader
110
111`0x10058000 - 0x10059000` - Scratch of Bootloader
112
113Size of slots `0x10000` - 64kb
114
115__Note:__ It is also possible to place secondary (upgrade) slots in external memory module so resulting image size can be doubled.
116For more details about External Memory usage, please refer to separate guiding document `ExternalMemory.md`.
117
118### Hardware limitations
119
120Since this application is created to demonstrate MCUboot library features and not as reference examples some considerations are taken.
121
1221. `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.
123
1242. `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, CY8PROTO-062S3-4343W, CY8CKIT-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.
125
126
127### Downloading solution's assets
128
129There is a set assets required:
130
131* MCUBooot Library (root repository)
132* PSoC6 HAL Library
133* PSoC6 Peripheral Drivers Library (PDL)
134* Mbed TLS Cryptographic Library
135
136To get submodules - run the following command:
137
138    git submodule update --init --recursive
139
140### Building solution
141
142This folder contains make files infrastructure for building MCUBoot Bootloader. Same approach used in sample BlinkyLedApp application. Example command are provided below for couple different build configurations.
143
144* Build MCUBootApp in `Debug` for signle image use case.
145
146        make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M BUILDCFG=Debug MCUBOOT_IMAGE_NUMBER=1
147
148* Build MCUBootApp in `Release` for multi image use case.
149
150        make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M BUILDCFG=Release MCUBOOT_IMAGE_NUMBER=2
151
152* To Build MCUBootApp with external memory support - pass `USE_EXTERNAL_FLASH=1` flag to `make` command in examples above. In this case UPGRADE image will be located in external memory. Refer to ExternalMemory.md for additional details.
153
154Root directory for build is **boot/cypress.**
155
156**Encrypted Image Support**
157
158To 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 Mbed TLS as a crypto provider.
159
160To enable image encryption support use `ENC_IMG=1` build flag (BlinkyApp should also be built with this flash set 1).
161
162User 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`.
163
164After MCUBootApp is built with these settings unencrypted and encrypted images will be accepted in secondary (upgrade) slot.
165
166Example command:
167
168        make app APP_NAME=MCUBootApp PLATFORM=PSOC_062_2M BUILDCFG=Debug MCUBOOT_IMAGE_NUMBER=1 ENC_IMG=1
169
170**Programming solution**
171
172There are couple ways of programming hex of MCUBootApp and BlinkyApp. Following instructions assume one of Cypress development kits, for example `CY8CPROTO_062_4343W`.
173
1741. Direct usage of OpenOCD.
175OpenOCD package is supplied with ModuToolbox IDE and can be found in installation folder under `./tools_2.1/openocd`.
176Open terminal application -  and execute following command after substitution `PATH_TO_APPLICATION.hex` and `OPENOCD` paths.
177
178Connect a board to your computer. Switch Kitprog3 to DAP-BULK mode by pressing `SW3 MODE` button until `LED2 STATUS` constantly shines.
179
180        export OPENOCD=/Applications/ModusToolbox/tools_2.1/openocd
181
182        ${OPENOCD}/bin/openocd -s ${OPENOCD}/scripts \
183                            -f ${OPENOCD}/scripts/interface/kitprog3.cfg \
184                            -f ${OPENOCD}/scripts/target/psoc6_2m.cfg \
185                            -c "init; reset init; program PATH_TO_APPLICATION.hex" \
186                            -c "resume; reset; exit"
187
1882. Using GUI tool `Cypress Programmer` - follow [link](https://www.cypress.com/products/psoc-programming-solutions) to download.
189   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.
190
1913. Using `DAPLINK`.
192   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.
193
194
195
196**Currently supported platforms:**
197
198* PSOC_062_2M
199* PSOC_062_1M
200* PSOC_062_512K
201
202**Build environment troubleshooting:**
203
204Regular shell/terminal combination on Linux and MacOS.
205
206On Windows:
207
208* Cygwin
209* Msys2
210
211Also IDE may be used:
212* Eclipse / ModusToolbox ("makefile project from existing source")
213
214*Make* - make sure it is added to system's `PATH` variable and correct path is first in the list;
215
216*Python/Python3* - make sure you have correct path referenced in `PATH`;
217
218*Msys2* - to use systems PATH navigate to msys2 folder, open `msys2_shell.cmd`, uncomment set `MSYS2_PATH_TYPE=inherit`, restart MSYS2 shell.
219
220This will iherit system's PATH so should find `python3.7` installed in regular way as well as imgtool and its dependencies.
221
222