1############################## 2Porting TF-M to a New Hardware 3############################## 4 5The purpose of this document is to provide a guide on how to integrate TF-M 6with another hardware platform. This document will give general guidance on 7how to port a platform on the TF-M build system and which interfaces must 8exist on the platform for TF-M (S and NS) to run on this new platform. 9 10 11************* 12Prerequisites 13************* 14 15Building environment 16==================== 17 18Make sure you have a working build environment and that you can build 19TF-M on AN521 following the 20:doc:`Build instructions </building/tfm_build_instruction>`. 21 22Toolchains and software requirements 23==================================== 24 25Please follow the :doc:`Getting started guide </getting_started/tfm_getting_started>`. 26 27CMSIS Drivers 28============= 29 30The TF-M stack requires at least two CMSIS HAL implementations: 31 32 - `USART <https://arm-software.github.io/CMSIS_6/latest/Driver/group__usart__interface__gr.html>`_ 33 - `FLASH <https://arm-software.github.io/CMSIS_6/latest/Driver/group__flash__interface__gr.html>`_ 34 35************ 36Porting flow 37************ 38 39In a nutshell, this should be a 6 iterative steps process: 40 41 #. Adding all the mandatory files and expected objects/functions declarations 42 43 #. Booting and configuring the core(s) 44 45 - startup(s) code and SystemInit 46 47 #. Adding the USART drivers 48 49 - CMSIS HAL 50 51 #. Adding the FLASH drivers 52 53 - CMSIS HAL 54 55 #. Enabling/Configuring/Disabling features including templated features 56 57 - E.G. NV Counters, attestation, crypto keys.... 58 59 #. Adding the optional platform SVC handling 60 61 Some platforms may have their own SVC requests in addition to the TF-M built-in ones. 62 63 #. Running the regression tests 64 65 - See :doc:`Running TF-M on Arm platforms </building/run_tfm_examples_on_arm_platforms>` 66 as an example 67 68 69***************** 70File architecture 71***************** 72The platform selection when building TF-M is set via the CMake 73variable TFM_PLATFORM. This variable holds part of the path to the platform. 74When using ``-DTFM_PLATFORM=arm/mps2/an521`` or ``-DTFM_PLATFORM=an521`` 75TF-M build system will look for the platform in 76<TF-M ROOT>/platform/ext/target/arm/mps2/an521. 77Therefore all hardware dependent code for your platform should go to 78<TF-M ROOT>/platform/ext/target/. 79 80platform/ext/target 81=================== 82This folder contains a first level of board vendor (such as ARM, STM, NXP, 83Cypress ....), each folder will usually contain a second level for each 84board. This second level is not mandatory. 85 86 platform/ext/target/<vendor>/[<board name>/] 87 88From now on this will be referred to as the ``platform folder``. 89 90platform/ext/common 91=================== 92This folder contains files and folder commons to the platforms, such as the 93shims to the CMSIS drivers. It also contains the scatter files that can be 94used for the bl2, tfm_s, tfm_ns partitions. 95 96This folder also contains another folder named template. The latter contains 97example implementations that are used for platforms by default, but which can be 98altered or replaced if other functionality is required. 99 100 +------------------------------+-----------------------------------------------------------------------------+ 101 | name | description | 102 +==============================+=============================================================================+ 103 |PLATFORM_DEFAULT_ATTEST_HAL |Use the default implementation of the attestation HAL (default True) | 104 +------------------------------+-----------------------------------------------------------------------------+ 105 |PLATFORM_DEFAULT_NV_COUNTERS |Use the default implementation of the counters in NV (default True) | 106 +------------------------------+-----------------------------------------------------------------------------+ 107 |PLATFORM_DEFAULT_CRYPTO_KEYS |Use the default implementation of crypto keys (default True) | 108 +------------------------------+-----------------------------------------------------------------------------+ 109 |PLATFORM_DEFAULT_ROTPK |Use the default implementation of the RoT Public Key (default True) | 110 +------------------------------+-----------------------------------------------------------------------------+ 111 |PLATFORM_DEFAULT_IAK |Use the default implementation of the initial attestation key (default True) | 112 +------------------------------+-----------------------------------------------------------------------------+ 113 |PLATFORM_DEFAULT_UART_STDOUT |Use the default implementation of the uart for stdout output (default True) | 114 +------------------------------+-----------------------------------------------------------------------------+ 115 |PLATFORM_DEFAULT_NV_SEED |Use the default implementation of the NV seed in the RNG (default True) | 116 +------------------------------+-----------------------------------------------------------------------------+ 117 |PLATFORM_DEFAULT_OTP |Use the default implementation of the OTP (default True) | 118 +------------------------------+-----------------------------------------------------------------------------+ 119 120*************** 121Platform Folder 122*************** 123 124Description 125=========== 126 127Depending on the level of integration you want with TF-M some files or 128information will be mandatory for the build system to build working firmware. 129 130Please note that platform folder provides source for building both :term:`SPE` 131and :term:`NSPE` parts. The SPE builds directly from the source tree while files 132necessary for NSPE platform support are installed to ``<Artifact folder>`` 133for building TF-M application as described in the 134:doc:`Build instructions </building/tfm_build_instruction>`. 135 136Questions to be answered: 137 - Will the platform use MCUboot as the second stage bootloader? 138 139 BL2/MCUboot provides a secure bootloader that enables simple software 140 upgrades. 141 142 This optional second stage bootloader is set-up via the bl2 target in 143 the CMakelists.txt file (see below). 144 145 - Will the platform support the Non-Secure world application? 146 147 A platform can be designed to only support the secure world, in which 148 case we would refer to it as a secure enclave. TF-M build system allows 149 the developer to strip all Non-Secure world related code out of the 150 final image. Most platforms, and especially the ones intended to be 151 generic or to have a Non-Secure application will require Non-Secure world 152 support. In that case a platform shall instruct build system on the file 153 set for exporting to Non-Secure world. 154 155 - How does the non-secure world communicate with the secure world? 156 157 TF-M supports running the non-secure world on the same CPU as the secure 158 world, communicating via TrustZone or running the non-secure world on 159 a separate CPU, communicating via a mailbox. The platform is responsible 160 for configuring toolchains with correct CPU and architecture related 161 features for secure and non-secure worlds. 162 163 The architecture for secure world is configured in the cpuarch.cmake 164 file (see below). 165 166 - How does the FLASH need to be split between worlds? 167 168 The flash split is very dependent on the support of BL2 and NS world. 169 When porting a new platform, one shall arrange enough flash size for each 170 of them. 171 172 If supporting upgrades (via MCUboot), additional flash area will be 173 required to store the updates before upgrading the whole system. 174 175 - How does the RAM need to be split between worlds? 176 177 The RAM split is very dependent on the support of the NS world. 178 179 If you're not porting the platform for a specific project but are enabling 180 the Non-Secure world, you should ensure that you leave enough RAM 181 available for it to run. 182 183.. Note:: 184 185 TF-M S world size in RAM and Flash varies greatly with different build 186 options. 187 188 TF-M project provides `metrics <https://qa-reports.linaro.org/tf/tf-m/metrics/?environment=DefaultProfileM&environment=DefaultProfileS&environment=DefaultProfileL&metric=:summary:>`_ 189 of the S world size for existing platforms, which may help to get a rough 190 guide to the sizes needed. 191 192Files 193===== 194 195CMakeLists.txt : 196---------------- 197 198 (MANDATORY) 199 200 This is the entry point for the build system to build your platform on the secure side and 201 also export files to build Non-Secure side. 202 203 it must: 204 205 - Add a folder to the target platform_region_defs. [PLATFORM_REGION_DEFS_] 206 207 This folder will contain two files flash_layout.h_ and region_defs.h_ 208 209 - Add scatter files to the bl2 and tfm_s targets. [SCATTER_] 210 211 Please note that TF-M provides a common scatter file for the bl2, tfm_s and 212 tfm_ns targets, which can be used in most cases. 213 214 - Add startup files to the bl2 and tfm_s targets. [STARTUP_] 215 - Add required sources and includes for the bl2 and tfm_s targets [SOURCES_INCLUDES_] 216 - Install all files required for building the platform in the Non-secure application [INSTALL_] 217 218 The installation section expands the common installation script with the platform specific files. 219 The following predefined variables are available to address the respective subfolders 220 of the target ``<Artifact folder>``. 221 222 +-------------------------------------+------------------------------------------------------------+ 223 | name | description | 224 +=====================================+============================================================+ 225 |INSTALL_INTERFACE_INC_DIR | interface/include - interface header files | 226 +-------------------------------------+------------------------------------------------------------+ 227 |INSTALL_INTERFACE_SRC_DIR | interface/src - interface source files | 228 +-------------------------------------+------------------------------------------------------------+ 229 |INSTALL_INTERFACE_LIB_DIR | interface/lib - interface libraries | 230 +-------------------------------------+------------------------------------------------------------+ 231 |INSTALL_IMAGE_SIGNING_DIR | image_signing tools and files | 232 +-------------------------------------+------------------------------------------------------------+ 233 |INSTALL_CMAKE_DIR | CMake modules for Non-secure app build | 234 +-------------------------------------+------------------------------------------------------------+ 235 |INSTALL_PLATFORM_NS_DIR | NS platform source files | 236 +-------------------------------------+------------------------------------------------------------+ 237 238config.cmake: 239------------- 240 241 (MANDATORY) 242 243 This file is used to setup default build configurations for TF-M and platform configurations 244 which have fixed values depending on hardware and software supportness. 245 These configurations should be set as normal CMake variables while others are cache variables. 246 247 The platform configurations in the below table are required. 248 249 +------------------------------+-------------------------------------------------------------------+ 250 | name | description | 251 +==============================+===================================================================+ 252 |CONFIG_TFM_USE_TRUSTZONE | Use TrustZone to transition between NSPE and SPE on the same CPU | 253 +------------------------------+-------------------------------------------------------------------+ 254 |TFM_MULTI_CORE_TOPOLOGY | NSPE runs on a separate CPU to SPE | 255 +------------------------------+-------------------------------------------------------------------+ 256 257 The platform configurations in the below table control optional features which rely on platform 258 specific implementation. 259 These features are disabled by default. 260 Platforms shall implement corresponding functionalities and explicitly set the configuration to 261 enable the feature. 262 263 +-------------------------------------+------------------------------------------------------------+ 264 | name | description | 265 +=====================================+============================================================+ 266 |PLATFORM_HAS_ISOLATION_L3_SUPPORT | Whether the platform has isolation level 3 support | 267 +-------------------------------------+------------------------------------------------------------+ 268 |PLATFORM_HAS_FIRMWARE_UPDATE_SUPPORT | Whether the platform has firmware update support | 269 +-------------------------------------+------------------------------------------------------------+ 270 |PSA_API_TEST_TARGET | The target platform name of PSA API test | 271 +-------------------------------------+------------------------------------------------------------+ 272 |PLATFORM_SVC_HANDLERS | Whether the platform has specific SVC handling | 273 +-------------------------------------+------------------------------------------------------------+ 274 275 For build configurations, please refer to ``config_base.cmake``. 276 277 [config_cmake_] 278 279cpuarch.cmake: 280-------------- 281 282 (MANDATORY) 283 284 This file contains hardware information such as the main processor and architecture of the SPE 285 CPU. 286 On single-core platforms, it should be installed to ``<Artifact folder>`` for NSPE build. 287 On multi-core platforms, two cpuarch.cmake files should be added. 288 289 - a SPE specific ``cpuarch.cmake`` used in SPE build 290 - an NSPE one which should be installed to ``<Artifact folder>`` with filename ``cpuarch.cmake`` 291 for NSPE build. See `ns/cpuarch_ns.cmake`_. 292 293 +-------------------------+------------------------------------------------------------+ 294 | name | description | 295 +=========================+============================================================+ 296 |TFM_SYSTEM_PROCESSOR | The SPE Processor the platform is using | 297 +-------------------------+------------------------------------------------------------+ 298 |TFM_SYSTEM_ARCHITECTURE | The architecture of the processor | 299 +-------------------------+------------------------------------------------------------+ 300 |CONFIG_TFM_FP_ARCH | The Float Point architecture flag for toolchain | 301 +-------------------------+------------------------------------------------------------+ 302 |CONFIG_TFM_FP_ARCH_ASM | The Float Point architecture flag for assembly code | 303 +-------------------------+------------------------------------------------------------+ 304 305tests/tfm_tests_config.cmake: 306----------------------------- 307 308 (OPTIONAL) 309 310 This file contains platform-specific config options for TF-M regression tests. 311 The ``tests`` folder should installed to <Artifact folder>/platform for NSPE build. 312 Here are some examples. 313 314 +--------------------------------+------------------------------------------------------------+ 315 | name | description | 316 +================================+============================================================+ 317 |PLATFORM_SLIH_IRQ_TEST_SUPPORT | Whether the platform has SLIH test support | 318 +-------------------------+-------------------------------------------------------------------+ 319 |PLATFORM_FLIH_IRQ_TEST_SUPPORT | Whether the platform has FLIH test support | 320 +--------------------------------+------------------------------------------------------------+ 321 322tests/psa_arch_tests_config.cmake: 323---------------------------------- 324 325 (OPTIONAL) 326 327 This file contains platform-specific config options for PSA API tests. 328 Here are some examples. 329 330 +--------------------------------+------------------------------------------------------------+ 331 | name | description | 332 +================================+============================================================+ 333 |PSA_API_TEST_TARGET | The target platform name of PSA API test | 334 +--------------------------------+------------------------------------------------------------+ 335 336startup files: 337--------------- 338 339 (MANDATORY) 340 341 These files (one for BL2, one for S, one for NS) are the expected startup 342 files. The reset handler should call SystemInit and then should end up 343 calling __START which should be defined as _start if not defined elsewhere. 344 345.. _flash_layout.h: 346 347flash_layout.h: 348--------------- 349 350 (MANDATORY) 351 352 This file can be anywhere in the platform folder, usually in a sub folder 353 named ``partition``. 354 TF-M doesn't provide a template for this file, common practice is to copy it 355 from another platform (e.g. arm/mps2/an521) and update the following entries. 356 357 Note: all size are in bytes 358 359 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 360 | name | description | Requisiteness | 361 +==============================+===================================================================+===========================================+ 362 |FLASH_S_PARTITION_SIZE | Size of the Secure partition in flash | Yes | 363 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 364 |FLASH_NS_PARTITION_SIZE | Size of the Non-Secure partition in flash | if tfm_ns is built | 365 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 366 |FLASH_AREA_IMAGE_SECTOR_SIZE | Size of the flash sector | if bl2 is built | 367 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 368 |FLASH_TOTAL_SIZE | Flash total size | Yes | 369 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 370 |FLASH_BASE_ADDRESS | Flash base memory address | if bl2 is built | 371 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 372 |FLASH_AREA_BL2_OFFSET | BL2 offset in flash | if bl2 is built | 373 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 374 |FLASH_AREA_BL2_SIZE | BL2 flash size | if bl2 is built | 375 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 376 |FLASH_PS_AREA_SIZE | Allocated size for the protected storage data in flash | Yes | 377 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 378 |FLASH_ITS_AREA_SIZE | Allocated size for the internal trusted storage data in flash | Yes | 379 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 380 |SECURE_IMAGE_OFFSET | Offset of the secure image data in flash | if bl2 is built | 381 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 382 |FLASH_DEV_NAME | Name as defined in the CMSIS flash drivers | Yes | 383 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 384 |TFM_HAL_PS_FLASH_DRIVER | Name as defined in the CMSIS flash drivers | used by protected storage partition | 385 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 386 |TFM_HAL_PS_SECTORS_PER_BLOCK | Number of physical erase sectors per logical FS block | used by protected storage partition | 387 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 388 |TFM_HAL_PS_PROGRAM_UNIT | Smallest flash programmable unit in bytes | used by protected storage partition | 389 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 390 |TFM_HAL_ITS_FLASH_DRIVER | Name as defined in the CMSIS flash drivers | used by internal trusted storage partition| 391 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 392 |TFM_HAL_ITS_SECTORS_PER_BLOCK | Number of physical erase sectors per logical ITS block | used by internal trusted storage partition| 393 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 394 |TFM_HAL_ITS_PROGRAM_UNIT | Smallest flash programmable unit in bytes | used by internal trusted storage partition| 395 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 396 |TFM_NV_COUNTERS_AREA_SIZE | Allocated size for the NV counters data in flash | if using TF-M templates | 397 +------------------------------+-------------------------------------------------------------------+-------------------------------------------+ 398 399.. _region_defs.h: 400 401region_defs.h: 402-------------- 403 404 (MANDATORY) 405 406 This file can be anywhere in the platform folder, usually in a sub folder 407 named ``partition``. 408 TF-M doesn't provide a template for this file, common practice is to copy it 409 from another platform (e.g. arm/mps2/an521) and update the following entries. 410 411 General advice: if you don't know beforehand the size you will want for 412 these elements you will have to make it iterative from an arbitrary value 413 taken from another platform (e.g. arm/mps2/an521) 414 415 Note: all size are in bytes 416 417 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 418 | name | description | Requisiteness | 419 +==================================+===================================================================+===============================================+ 420 |BL2_HEAP_SIZE | Size of the Bootloader (MCUboot) heap | if bl2 is built | 421 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 422 |BL2_MSP_STACK_SIZE | (if bl2 is built) Size of the Bootloader (MCUboot) Main stack | if bl2 is built | 423 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 424 |S_HEAP_SIZE | Size of the Secure (S) world Heap | yes | 425 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 426 |S_MSP_STACK_SIZE | Size of the Secure (S) world Main stack | yes | 427 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 428 |S_PSP_STACK_SIZE | Size of the Secure (S) world Process stack | no for IPC model | 429 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 430 |NS_HEAP_SIZE | Size of the Non-Secure (NS) world Heap | if tfm_ns is built | 431 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 432 |NS_STACK_SIZE | Size of the Non-Secure (NS) world stack | if tfm_ns is built | 433 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 434 |PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE | Size of the buffer that will store the initial attestation | used by initial attestation partition | 435 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 436 |TFM_ATTEST_BOOT_RECORDS_MAX_SIZE | Size of buffer that can store the encoded list of boot records | used by delegated attestation partition | 437 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 438 |BL2_HEADER_SIZE | Size of the Header for the Bootloader (MCUboot) | if bl2 is built | 439 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 440 |BL2_TRAILER_SIZE | Size of the Trailer for the Bootloader (MCUboot) | if bl2 is built | 441 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 442 |SHARED_SYMBOL_AREA_SIZE | Size of shared common code between bl2 and tfm_s | if bl2 is built and want to reduce image size | 443 +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+ 444 445 (OPTIONAL) 446 447 If the TF-M common linker script is used then: 448 449 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 450 | name | description | Requisiteness | 451 +==================================+=======================================================================+===================================+ 452 |S_CODE_START | Start address for the S code | Yes | 453 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 454 |S_CODE_SIZE | Size of the S code | Yes | 455 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 456 |S_DATA_START | Start address for the S data | Yes | 457 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 458 |S_DATA_SIZE | Size of the S data | Yes | 459 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 460 |S_RAM_CODE_START | Start address for the S code | if no XIP on flash | 461 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 462 |S_RAM_CODE_SIZE | Size of the S code | if no XIP on flash | 463 +----------------------------------+-----------------------------------------------------------------------+-----------------------------------+ 464 465CMSIS_Driver/Config/cmsis_driver_config.h: 466------------------------------------------ 467 468 (location as defined in CMakeLists.txt) 469 470 This file should include the CMSIS drivers implementation headers. 471 472CMSIS_Driver/Config/RTE_Device.h: 473--------------------------------- 474 475 (location as defined in CMakeLists.txt) 476 477 This is the Run-Time Environment file from CMSIS, which is there to allow 478 enabling or disabling drivers prior to building. If your platform is 479 designed as a general use platform, this file should contain all the 480 available CMSIS drivers, and you should provide a recommended configuration. 481 If your platform is designed for a specific use-case then you should 482 reference and enable only the mandatory drivers. 483 484CMSIS_Driver/Driver_Flash.c: 485---------------------------- 486 487 (location as defined in CMakeLists.txt) 488 489 TF-M relies on CMSIS Drivers, as such it requires the CMSIS functions to 490 be implemented. As a platform owner you can decide to either implement the 491 drivers in the CMSIS functions or to use the CMSIS functions as a shim to 492 your native drivers. 493 494 Refer to the CMSIS `FLASH <https://arm-software.github.io/CMSIS_6/latest/Driver/group__flash__interface__gr.html>`_ 495 documentation. 496 497CMSIS_Driver/Driver_USART.c: 498---------------------------- 499 500 (location as defined in CMakeLists.txt) 501 502 TF-M relies on CMSIS Drivers, as such it requires the CMSIS functions to 503 be implemented. As a platform owner you can decide to either implement the 504 drivers in the CMSIS functions or to use the CMSIS functions as a shim to 505 your native drivers. 506 507 Refer to the CMSIS `USART <https://arm-software.github.io/CMSIS_6/latest/Driver/group__usart__interface__gr.html>`_ 508 documentation. 509 510target_cfg.[ch]: 511---------------- 512 513 (location as defined in CMakeLists.txt) 514 515 It is expected that these files contain all platform specific code related 516 to memory protection (e.g. SAU/PPC/MPC). These functions will not be called 517 by TF-M directly, but are expected to be called from the function 518 tfm_hal_set_up_static_boundaries() in tfm_hal_isolation.c. 519 520tfm_hal_platform.c: 521------------------- 522 523 (location as defined in CMakeLists.txt) 524 525 Each platform is expected to implement the following API declared in 526 platform/include/tfm_hal_platform.h 527 528.. code-block:: c 529 530 enum tfm_hal_status_t tfm_hal_platform_init(void); 531 532 The function will be called before SPM initialization. 533 534tfm_hal_isolation.c: 535-------------------- 536 537 (location as defined in CMakeLists.txt) 538 539 Each platform is expected to implement all the functions declared in 540 platform/include/tfm_hal_isolation.h. 541 542 A reference implementation for Armv8-M platforms is provided in 543 platform/ext/common/tfm_hal_isolation_v8m.c. Platforms using the common TF-M 544 linker scripts and scatter files can use it to implement standard TF-M 545 isolation with Armv8-M MPU regions. Platform-specific MPU regions can be 546 appended by defining PLATFORM_STATIC_MPU_REGIONS in the platform's 547 tfm_peripherals_def.h header. 548 549 These functions will be called from TF-M. 550 551tfm_platform_system.c: 552---------------------- 553 554 (location as defined in CMakeLists.txt) 555 556 Each platform is expected to implement all the functions declared in 557 platform/include/tfm_platform_system.h. 558 559check_config.cmake: 560------------------- 561 562 As a platform owner you may want to enforce some configuration or to prevent 563 the use of unsupported configurations. 564 565 This file (CMake format) allows you to do so by allowing you to check for 566 invalid configuration values. 567 568 This file is optional. 569 570 TF-M build system already provides a generic configuration checker that will 571 be called on top of one provided by the platform owner. The generic checker 572 is located in <TF-M ROOT>/config/. 573 574 [check_config.cmake_] 575 576platform_svc_numbers.h 577---------------------- 578 579 (OPTIONAL) 580 581 If your platform has its own SVC handling, then you need to 582 583 - create the ``platform_svc_numbers.h`` which defines the platform SVC numbers. 584 585 The bit [7] of the number must be set to 1 to reflect that it is a platform SVC number. 586 The bit [6] indicates whether this SVC should be called from Handler mode or Thread mode. 587 For more details of the bit assignments, please check the ``svc_num.h``. 588 TF-M provides two Macros ``TFM_SVC_NUM_PLATFORM_THREAD(index)`` and 589 ``TFM_SVC_NUM_PLATFORM_HANDLER(index)`` to easily construct a valid number. 590 591 - implement the `platform_svc_handlers`_ function which handles SVC. 592 - enable ``PLATFORM_SVC_HANDLERS`` config option. 593 594ns/CMakeLists.txt 595----------------- 596 597 (MANDATORY) 598 599 This is CMake script for building the platform support on NSPE side. It's 600 copied to ``<Artifact folder>`` in the installation phase and instructs on 601 how to build **platform_ns** target. The default NSPE build script expects 602 this target definition and extends it with files, common for all TF-M platforms. 603 604 Note:: 605 This file shall define and use paths of installed directories in ``<Artifact folder>``, 606 instead of paths in TF-M platform folder. 607 608 [NSCMakeLists.txt_] 609 610ns/cpuarch_ns.cmake 611------------------- 612 613 (MANDATORY for multi-core platforms) 614 615 This file contains the hardware information for the NSPE CPU. 616 It should be installed to ``<Artifact folder>/platform`` for NSPE build, 617 ranamed to ``ns/cpuarch_ns.cmake``. 618 619 [`ns/cpuarch_ns.cmake`_] 620 621.. _Functions: 622 623Functions 624========= 625 626 There are a few functions that need to be declared and properly 627 initialized for TF-M to work. The function declarations can be found in 628 ``platform/include/tfm_platform_system.h`` and ``platform/include/tfm_hal_*.h``. 629 630tfm_platform_hal_system_reset: 631------------------------------ 632 633 This function will in most cases end up calling the NVIC System Reset. 634 635 The platform can uninitialize or store some resources before reset. 636 637.. code-block:: c 638 639 void tfm_platform_hal_system_reset(void); 640 641 642tfm_platform_hal_ioctl: 643----------------------- 644 645 A single entry point to platform-specific code across the HAL is provided by the 646 IOCTL service. 647 648.. code-block:: c 649 650 enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request, psa_invec *in_vec, psa_outvec *out_vec); 651 652tfm_hal_set_up_static_boundaries: 653--------------------------------- 654 655 Sets up the static isolation boundaries which are constant throughout the 656 runtime of the system, including the SPE/NSPE and partition boundaries. 657 658.. code-block:: c 659 660 enum tfm_hal_status_t tfm_hal_set_up_static_boundaries(uintptr_t *p_spm_boundary); 661 662tfm_hal_activate_boundary: 663-------------------------- 664 665 Activates one Secure Partition boundary. 666 667.. code-block:: c 668 669 enum tfm_hal_status_t tfm_hal_activate_boundary(const struct partition_load_info_t *p_ldinf, uintptr_t boundary); 670 671tfm_hal_memory_check: 672--------------------- 673 674 Checks if a given range of memory can be accessed with specified access 675 types in boundary. The boundary belongs to a partition which contains all 676 asset info. 677 678 A default implementation for Armv8-M platforms with TrustZone is provided in 679 ``platform/ext/common/tfm_hal_isolation_v8m.c``. Multi-core topology 680 platforms without TrustZone may use the 681 :doc:`Memory Check APIs </design_docs/dual-cpu/tfm_multi_core_access_check>` 682 to implement this HAL. 683 684.. code-block:: c 685 686 enum tfm_hal_status_t tfm_hal_memory_check(uintptr_t boundary, uintptr_t base, size_t size, uint32_t access_type); 687 688tfm_hal_bind_boundary: 689---------------------- 690 691 Binds partition boundaries with the platform. The platform maintains the 692 platform-specific settings for SPM further usage, such as update partition 693 boundaries or check resource accessibility. The platform needs to manage the 694 settings with internal mechanism, and return a value to SPM. SPM delivers 695 this value back to platform when necessary. And SPM checks this value to 696 decide if the platform-specific settings need to be updated. Hence multiple 697 partitions can have the same value if they have the same platform-specific 698 settings, depending on isolation level. 699 700.. code-block:: c 701 702 enum tfm_hal_status_t tfm_hal_bind_boundary(const struct partition_load_info_t *p_ldinf, uintptr_t *p_boundary); 703 704tfm_hal_boundary_need_switch: 705----------------------------- 706 707 Lets the platform decide if a boundary switch is needed. 708 709.. code-block:: c 710 711 bool tfm_hal_boundary_need_switch(uintptr_t boundary_from, uintptr_t boundary_to); 712 713tfm_hal_irq_clear_pending: 714-------------------------- 715 716 This function clears any pending IRQ. 717 718.. code-block:: c 719 720 void tfm_hal_irq_clear_pending(uint32_t irq_num); 721 722tfm_hal_irq_enable: 723------------------- 724 725 This function enable an IRQ. 726 727.. code-block:: c 728 729 void tfm_hal_irq_enable(uint32_t irq_num); 730 731tfm_hal_irq_disable: 732-------------------- 733 734 This function disable an IRQ. 735 736.. code-block:: c 737 738 void tfm_hal_irq_disable(uint32_t irq_num); 739 740platform_svc_handlers 741--------------------- 742 743 This function is the platform's SVC handler. 744 It should return the result for callers and the SPM will then return it to the caller. 745 746.. code-block:: c 747 748 int32_t platform_svc_handlers(uint8_t svc_num, uint32_t *svc_args, uint32_t exc_return); 749 750Annex 751===== 752 753CMake build system snippets examples 754 755.. _PLATFORM_REGION_DEFS: 756 757CMakeLists.txt: Defining regions for Secure world platform and all linked to it. 758 759.. code-block:: CMake 760 761 target_include_directories(platform_region_defs 762 INTERFACE 763 <folder name under the platform folder - usually named platform> 764 ) 765 766.. _SCATTER: 767 768CMakeLists.txt: Scatter files for SPE platform and bootloader 769 770.. code-block:: CMake 771 772 target_add_scatter_file(bl2 773 $<$<C_COMPILER_ID:ARMClang>:${PLATFORM_DIR}/ext/common/armclang/tfm_common_bl2.sct> 774 $<$<C_COMPILER_ID:GNU>:${PLATFORM_DIR}/ext/common/gcc/tfm_common_bl2.ld> 775 $<$<C_COMPILER_ID:IAR>:${PLATFORM_DIR}/ext/common/iar/tfm_common_bl2.icf> 776 ) 777 target_add_scatter_file(tfm_s 778 $<$<C_COMPILER_ID:ARMClang>:${PLATFORM_DIR}/ext/common/armclang/tfm_isolation_s.sct> 779 $<$<C_COMPILER_ID:GNU>:${PLATFORM_DIR}/ext/common/gcc/tfm_isolation_s.ld> 780 $<$<C_COMPILER_ID:IAR>:${PLATFORM_DIR}/ext/common/iar/tfm_isolation_s.icf> 781 ) 782 783.. _STARTUP: 784 785CMakeLists.txt: Startup files for SPE platform and bootloader 786 787.. code-block:: CMake 788 789 target_sources(bl2 790 PRIVATE 791 ${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target/<folder to platform>/device/source/startup_<platform name>.c 792 ) 793 target_sources(tfm_s 794 PRIVATE 795 ${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target/<folder to platform>/device/source/startup_<platform name>.c 796 ) 797 798.. _SOURCES_INCLUDES: 799 800CMakeLists.txt: The Secure world platform sources 801 802.. code-block:: CMake 803 804 target_include_directories(platform_bl2 805 PUBLIC 806 ) 807 target_include_directories(platform_s 808 PUBLIC 809 ) 810 811 target_sources(platform_bl2 812 PRIVATE 813 ) 814 target_sources(platform_s 815 PRIVATE 816 ) 817 target_sources(tfm_spm 818 PRIVATE 819 target_cfg.c 820 tfm_hal_isolation.c 821 tfm_hal_platform.c 822 ) 823 824.. _INSTALL: 825 826CMakeLists.txt: installation for the Non-Secure world platform build 827 828.. code-block:: CMake 829 830 install(FILES ${PLATFORM_DIR}/ext/common/uart_stdout.c 831 native_drivers/arm_uart_drv.c 832 native_drivers/timer_cmsdk/timer_cmsdk.c 833 cmsis_drivers/Driver_USART.c 834 retarget/platform_retarget_dev.c 835 cmsis_core/an521_ns_init.c 836 DESTINATION ${INSTALL_PLATFORM_NS_DIR}) 837 838 install(DIRECTORY ${PLATFORM_DIR}/ext/common 839 DESTINATION ${INSTALL_PLATFORM_NS_DIR}/ext) 840 841.. _config_cmake: 842 843config.cmake 844 845.. code-block:: CMake 846 847 set(CONFIG_TFM_USE_TRUSTZONE ON) 848 set(TFM_MULTI_CORE_TOPOLOGY OFF) 849 set(BL2 OFF CACHE BOOL "Whether to build BL2") 850 set(NS FALSE CACHE BOOL "Whether to build NS app" FORCE) 851 852.. _check_config.cmake: 853 854check_config.cmake 855 856.. code-block:: CMake 857 858 function(tfm_invalid_config) 859 if (${ARGV}) 860 string (REPLACE ";" " " ARGV_STRING "${ARGV}") 861 string (REPLACE "STREQUAL" "=" ARGV_STRING "${ARGV_STRING}") 862 string (REPLACE "GREATER" ">" ARGV_STRING "${ARGV_STRING}") 863 string (REPLACE "LESS" "<" ARGV_STRING "${ARGV_STRING}") 864 string (REPLACE "VERSION_LESS" "<" ARGV_STRING "${ARGV_STRING}") 865 string (REPLACE "EQUAL" "=" ARGV_STRING "${ARGV_STRING}") 866 string (REPLACE "IN_LIST" "in" ARGV_STRING "${ARGV_STRING}") 867 868 message(FATAL_ERROR "INVALID CONFIG: ${ARGV_STRING}") 869 endif() 870 endfunction() 871 872 # Requires armclang >= 6.10.1 873 tfm_invalid_config((CMAKE_C_COMPILER_ID STREQUAL "ARMClang") AND (CMAKE_C_COMPILER_VERSION VERSION_LESS "6.10.1")) 874 875.. _NSCMakeLists.txt: 876 877/ns/CMakeLists.txt: 878 879.. code-block:: CMake 880 881 add_library(platform_ns) 882 883 target_sources(platform_ns 884 PRIVATE 885 arm_uart_drv.c 886 timer_cmsdk.c 887 uart_stdout.c 888 Driver_USART.c 889 PUBLIC 890 cmsis_core/startup_an521.c 891 ) 892 893 target_include_directories(platform_ns 894 PUBLIC 895 include 896 cmsis 897 cmsis_core 898 ) 899 900 target_compile_definitions(platform_ns 901 PUBLIC 902 $<$<BOOL:${PLATFORM_DEFAULT_CRYPTO_KEYS}>:PLATFORM_DEFAULT_CRYPTO_KEYS> 903 ) 904 905*Copyright (c) 2021-2024, Arm Limited. All rights reserved.* 906 907*Copyright (c) 2022 Cypress Semiconductor Corporation (an Infineon company) 908or an affiliate of Cypress Semiconductor Corporation. All rights reserved.* 909