1######################## 2Cypress PSoC64 Specifics 3######################## 4 5************* 6Prerequisites 7************* 8 9PSoC64 must first be provisioned with SecureBoot firmware and a provisioning packet 10containing policy and secure keys. Please refer to the guide at 11https://www.cypress.com/documentation/software-and-drivers/psoc-64-secure-mcu-secure-boot-sdk-user-guide 12Use the following policy file for provisioning and signing: 13policy_multi_CM0_CM4_tfm.json 14 15Please make sure you have all required software installed as explained in the 16:doc:`TF-M getting started </getting_started/tfm_getting_started>`. 17 18Please also make sure that all the source code are fetched by following 19:doc:`general building instruction </building/tfm_build_instruction>`. 20 21Install CySecureTools or update it to the newest version (2.0.0 at the time of 22writing) 23 24.. code-block:: bash 25 26 pip3 install --upgrade --force-reinstall cysecuretools 27 28PyOCD is installed by CySecureTools as a dependency. 29 30For more details please refer to 31`CySecureTools <https://pypi.org/project/cysecuretools>`_ page. 32 33Install OpenOCD with PSoC6 support. Download the latest revision 4.1.0 34or newer from: 35https://github.com/cypresssemiconductorco/openocd/releases 36 37Lastly, the PSoC64 board KitProg firmware needs to be 2.00.744 or greater. 38Please use Cypress Modus Toolbox or CyProgrammer to update it if needed. 39 40****************************************** 41Building Multi-Core TF-M on Cypress PSoC64 42****************************************** 43 44Configuring the build 45===================== 46 47The build configuration for TF-M is provided to the build system using command 48line arguments. Required arguments are noted below. 49 50 * - -DTFM_PLATFORM=cypress/psoc64 51 - Specifies target platform name ``psoc64`` 52 53 * - -DTFM_TOOLCHAIN_FILE=<path to toolchain file> 54 - Specifies the compiler toolchain 55 The possible values are: 56 57 - ``<TFM root dir>/toolchain_ARMCLANG.cmake`` 58 - ``<TFM root dir>/toolchain_GNUARM.cmake`` 59 - ``<TFM root dir>/toolchain_IARARM.cmake`` 60 61see :ref:`tfm_cmake_configuration` for 62more information. 63 64Build Instructions 65================== 66 67The following instructions build multi-core TF-M without regression test suites 68in Isolation Level 1 on Linux. 69Both the compiler and the debugging type can be changed to other configurations 70listed above. 71 72.. code-block:: bash 73 74 cd <TF-M base folder> 75 cd <trusted-firmware-m folder> 76 77 mkdir <build folder> 78 pushd <build folder> 79 cmake -DTFM_PLATFORM=cypress/psoc64 \ 80 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 81 ../ 82 popd 83 cmake --build <build folder> -- -j VERBOSE=1 84 85The following instructions build multi-core TF-M with regression test suites 86in Isolation Level 1 on Linux. 87Both the compiler and the debugging type can be changed to other configurations 88listed above. 89 90.. code-block:: bash 91 92 cd <TF-M base folder> 93 cd <trusted-firmware-m folder> 94 95 mkdir <build folder> 96 pushd <build folder> 97 cmake -DTFM_PLATFORM=cypress/psoc64 \ 98 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 99 -DTEST_S=ON -DTEST_NS=ON \ 100 ../ 101 popd 102 cmake --build <build folder> -- -j VERBOSE=1 103 104The following instructions build multi-core TF-M with PSA API test suite for 105the attestation service in Isolation Level 1 on Linux. 106Both the compiler and the debugging type can be changed to other configurations 107listed above. 108 109.. code-block:: bash 110 111 cd <TF-M base folder> 112 cd <trusted-firmware-m folder> 113 114 mkdir <build folder> 115 pushd <build folder> 116 cmake -DTFM_PLATFORM=cypress/psoc64 \ 117 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 118 -DTEST_PSA_API=INITIAL_ATTESTATION \ 119 ../ 120 popd 121 cmake --build <build folder> -- -j VERBOSE=1 122 123The following instructions build multi-core TF-M without regression test suites 124in Isolation Level 2 on Linux. 125Both the compiler and the debugging type can be changed to other configurations 126listed above. 127 128.. code-block:: bash 129 130 cd <TF-M base folder> 131 cd <trusted-firmware-m folder> 132 133 mkdir <build folder> 134 pushd <build folder> 135 cmake -DTFM_PLATFORM=cypress/psoc64 \ 136 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 137 -DTFM_ISOLATION_LEVEL=2 \ 138 ../ 139 popd 140 cmake --build <build folder> -- -j VERBOSE=1 141 142The following instructions build multi-core TF-M with regression test suites 143in Isolation Level 2 on Linux. 144Both the compiler and the debugging type can be changed to other configurations 145listed above. 146 147.. code-block:: bash 148 149 cd <TF-M base folder> 150 cd <trusted-firmware-m folder> 151 152 mkdir <build folder> 153 pushd <build folder> 154 cmake -DTFM_PLATFORM=cypress/psoc64 \ 155 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 156 -DTFM_ISOLATION_LEVEL=2 \ 157 -DTEST_S=ON -DTEST_NS=ON \ 158 ../ 159 popd 160 cmake --build <build folder> -- -j VERBOSE=1 161 162The following instructions build multi-core TF-M with PSA API test suite for 163the protected storage service in Isolation Level 2 on Linux. 164Both the compiler and the debugging type can be changed to other configurations 165listed above. 166 167.. code-block:: bash 168 169 cd <TF-M base folder> 170 cd <trusted-firmware-m folder> 171 172 mkdir <build folder> 173 pushd <build folder> 174 cmake -DTFM_PLATFORM=cypress/psoc64 \ 175 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 176 -DTFM_ISOLATION_LEVEL=2 \ 177 -DTEST_PSA_API=PROTECTED_STORAGE \ 178 ../ 179 popd 180 cmake --build <build folder> -- -j VERBOSE=1 181 182******* 183Signing 184******* 185 186Signing keys 187============ 188 189Copy secure keys used in the board provisioning process to 190platform/ext/target/cypress/psoc64/security/keys: 191 192The keys included in the repository are for reference and development only. 193DO NOT USE THESE KEYS IN ANY ACTUAL DEPLOYMENT! 194 195Note: provisioned board in SECURE state is required, otherwise refer to 196Cypress documentation for details on the provisioning process. 197https://www.cypress.com/documentation/software-and-drivers/psoc-64-secure-mcu-secure-boot-sdk-user-guide 198 199If the board was previously provisioned with signing keys and policy, copy 200secure signing keys used in the board provisioning process to 201platform/ext/target/cypress/psoc64/security/keys: 202 203TFM_S_KEY.json 204 Private OEM key for signing CM0P image 205 206TFM_S_KEY_PRIV.pem 207 Private OEM key for signing CM0P image in PEM format 208 209TFM_NS_KEY.json 210 Private OEM key for signing CM4 image 211 212TFM_NS_KEY_PRIV.pem 213 Private OEM key for signing CM4 image in PEM format 214 215Alternatively, you can generate a new set of signing keys using cysecuretools 216create-keys command and provision the keys to the board, if the previously 217provisioned policy allows board's re-provisioning. 218 219Initialize cysecuretools environment: 220 221.. code-block:: bash 222 223 cd platform/ext/target/cypress/psoc64/security 224 cysecuretools -t cy8ckit-064s0s2-4343w init 225 226Generate a new set of keys: 227 228.. code-block:: bash 229 230 cysecuretools -t cy8ckit-064s0s2-4343w -p policy/policy_multi_CM0_CM4_tfm.json create-keys 231 232Re-provision the new keys to the board: 233 234.. code-block:: bash 235 236 cysecuretools -t cy8ckit-064s0s2-4343w -p policy/policy_multi_CM0_CM4_tfm.json re-provision-device 237 238Signing the images 239================== 240 241Sign the images using CySecureTools CLI tool. 242Note: the tool overwrites unsigned file with a signed one, it also creates an 243unsigned copy <filename>_unsigned.hex. 244 245SPE image: 246 247.. code-block:: bash 248 249 cysecuretools \ 250 --policy platform/ext/target/cypress/psoc64/security/policy/policy_multi_CM0_CM4_tfm.json \ 251 --target cy8ckit-064s0s2-4343w \ 252 sign-image \ 253 --hex <build folder>/bin/tfm_s.hex \ 254 --image-type BOOT \ 255 --image-id 1 256 257NSPE image: 258 259.. code-block:: bash 260 261 cysecuretools \ 262 --policy platform/ext/target/cypress/psoc64/security/policy/policy_multi_CM0_CM4_tfm.json \ 263 --target cy8ckit-064s0s2-4343w \ 264 sign-image \ 265 --hex <build folder>/bin/tfm_ns.hex \ 266 --image-type BOOT \ 267 --image-id 16 268 269* CySecureTools sign-image overwrites unsigned file with a signed one, 270 also it creates an unsigned copy _unsigned.hex. 271 272* image-type option: "--image-type BOOT" creates a signed hex file with offsets 273 for the primary image slot. Use "--image-type UPGRADE" if you want to create 274 an image for the secondary "upgrade" slot. 275 When booting, CyBootloader will validate image in the secondary slot and copy 276 it to the primary boot slot. 277 278* image-id option: Each image has its own ID. By default, SPE image running on 279 CM0P core has ID=1, NSPE image running on CM4 core has ID=16. Refer to the 280 policy file for the actual ID's. 281 282 283********************** 284Programming the Device 285********************** 286 287After building and signing, the TFM images must be programmed into flash 288memory on the PSoC64 device. There are three methods to program it. 289 290DAPLink mode 291============ 292 293Using KitProg3 mode button, switch it to DAPLink mode. 294Mode LED should start blinking rapidly and depending on the host computer 295settings DAPLINK will be mounted as a media storage device. 296Otherwise, mount it manually. 297 298Copy tfm hex files one by one to the DAPLINK device: 299 300.. code-block:: bash 301 302 cp <build folder>/bin/tfm_ns.hex <mount point>/DAPLINK/; sync 303 cp <build folder>/bin/tfm_s.hex <mount point>/DAPLINK/; sync 304 305OpenOCD 306======= 307 308Using KitProg3 mode button, switch to KitProg3 CMSIS-DAP BULK. Status LED 309should be ON and not blinking for CMSIS-DAP BULK. 310 311Before programming the images, erase PS partition if needed. 312This will clear all data and force PS to reformat partition. 313 314.. code-block:: bash 315 316 ${OPENOCD_PATH}/bin/openocd \ 317 -s ${OPENOCD_PATH}/scripts \ 318 -f interface/kitprog3.cfg \ 319 -f target/psoc6_2m_secure.cfg \ 320 -c "init; reset init" \ 321 -c "flash erase_address 0x101c0000 0x10000" \ 322 -c "shutdown" 323 324Note that the ``0x101C0000`` in the command above must match the PS start 325address of the secure primary image specified in the file: 326 327 platform/ext/target/cypress/psoc64/partition/flash_layout.h 328 329so be sure to change it if you change that file. 330 331To program the signed tfm_s and tfm_ns images to the device with openocd 332(assuming OPENOCD_PATH is pointing at the openocd installation directory) 333run the following commands: 334 335.. code-block:: bash 336 337 OPENOCD_PATH=<cyprogrammer dir>/openocd 338 BUILD_DIR=<build folder> 339 340 ${OPENOCD_PATH}/bin/openocd \ 341 -s ${OPENOCD_PATH}/scripts \ 342 -f interface/kitprog3.cfg \ 343 -f target/psoc6_2m_secure.cfg \ 344 -c "init; reset init" \ 345 -c "flash write_image erase ${BUILD_DIR}/bin/tfm_s.hex" \ 346 -c "shutdown" 347 348 ${OPENOCD_PATH}/bin/openocd \ 349 -s ${OPENOCD_PATH}/scripts \ 350 -f interface/kitprog3.cfg \ 351 -f target/psoc6_2m_secure.cfg \ 352 -c "init; reset init" \ 353 -c "flash write_image erase ${BUILD_DIR}/bin/tfm_ns.hex" \ 354 -c "reset run" 355 356PyOCD 357===== 358 359PyOCD is installed by CySecureTools automatically. It can be used 360to program TFM images into the board. 361 362Using KitProg3 mode button, switch to KitProg3 DAPLink mode. 363Mode LED should start blinking rapidly. 364 365Optionally, erase PS partition: 366 367.. code-block:: bash 368 369 pyocd erase -b CY8CKIT-064S0S2-4343W -s 0x101c0000+0x10000 370 371To program the signed tfm_s and tfm_ns images to the device with pyocd 372run the following commands: 373 374.. code-block:: bash 375 376 pyocd flash -b CY8CKIT-064S0S2-4343W ${BUILD_DIR}/bin/tfm_s.hex 377 378 pyocd flash -b CY8CKIT-064S0S2-4343W ${BUILD_DIR}/bin/tfm_ns.hex 379 380 381******************************** 382Provisioning device certificates 383******************************** 384 3851. If not done yet, change to the psoc64 security directory and initialize 386 cysecuretools environment: 387 388.. code-block:: bash 389 390 cd platform/ext/target/cypress/psoc64/security 391 cysecuretools -t cy8ckit-064s0s2-4343w init 392 3932. Create and copy rootCA files to "certificates" directory next to the policy 394 directory (please refer to documentation of the used OS) 395 3963. Switch the board in DAPLink mode by pressing the mode button or by issuing 397 the following fw-loader command (fw-loader comes with Modus ToolBox software). 398 Mode LED should be slowly blinking: 399 400.. code-block:: bash 401 402 fw-loader --mode kp3-daplink 403 4044. Run reprov_helper.py. If running the script with default parameters, 405 the script can be run as is: 406 407.. code-block:: bash 408 409 python3 reprov_helper.py 410 411 Otherwise, run it with --help parameter to get the full list of options. 412 4135. Confirm selected options. When prompted for a serial number, enter the board 414 unique serial number (digits only, e.g. 00183). 415 4166. Script will ask if you want to create new signing keys. Answer Yes to 417 generate new signing keys in the keys directory, or No to retain and use the 418 existing keys. After re-provisioning, from now on any images for 419 this board will have to be signed with these keys. 420 4217. The script will erase user images. 422 Then the script will read device public key and create device certificates 423 based on the board serial number, root certificate and the device public key. 424 425 426************************************************************* 427Provisioning Amazon Web Services root and device certificates 428************************************************************* 429Device running Amazon FreeRTOS and using Amazon Web Services (AWS) 430requires AWS root and unique device certificate signed with the device key 431for authentication. These certificates have to be provisioned into device. 432The process is the following: 433 4341. If not done yet, change to the psoc64 security directory and initialize 435 cysecuretools environment: 436 437.. code-block:: bash 438 439 cd platform/ext/target/cypress/psoc64/security 440 cysecuretools -t cy8ckit-064s0s2-4343w init 441 4422. Obtain and copy rootCA files to "certificates" directory next to the policy 443 directory (please refer to AWS documentation) 444 4453. Switch the board in DAPLink mode by pressing the mode button or by issuing 446 the following fw-loader command (fw-loader comes with Modus ToolBox software). 447 Mode LED should be slowly blinking: 448 449.. code-block:: bash 450 451 fw-loader --mode kp3-daplink 452 4534. Run reprov_helper.py. If running the script with default parameters, 454 the script can be run as is: 455 456.. code-block:: bash 457 458 python3 reprov_helper.py 459 460 Otherwise, run it with --help parameter to get the full list of options. 461 4625. Confirm selected options. When prompted for a serial number, enter the board 463 unique serial number (digits only, e.g. 00183). 464 4656. Script will ask if you want to create new signing keys. Answer Yes to 466 generate new signing keys in the keys directory, or No to retain and use the 467 existing keys. After re-provisioning, from now on any images for 468 this board will have to be signed with these keys. 469 4707. The script will erase user images. 471 Then the script will read device public key and create device certificates 472 based on the board serial number, root certificate and the device public key. 473 474-------------- 475 476*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* 477 478*Copyright (c) 2019-2020, Cypress Semiconductor Corporation. All rights reserved.* 479
