1################## 2First Things First 3################## 4 5************ 6Prerequisite 7************ 8Trusted Firmware M provides a reference implementation of the Platform Security 9Architecture (PSA) specifications, aligning with PSA Certified guidelines. 10It is assumed that the reader is familiar with the specifications that can be 11found 12`here <https://developer.arm.com/architectures/security-architectures/platform-security-architecture>`__. 13 14The current TF-M implementation on Armv8-M leverages TrustZone for Armv8-M so a 15good understanding of the v8-M architecture is also necessary. A good place to 16get started with Armv8-M is 17`developer.arm.com <https://developer.arm.com/architectures/cpu-architecture/m-profile>`__. 18 19************************** 20Build and run instructions 21************************** 22Trusted Firmware M source code is available on 23`git.trustedfirmware.org <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/>`__. 24 25To build & run TF-M: 26 27 - Follow the this guide to set up and check your environment. 28 - Follow the 29 :doc:`Build instructions </building/tfm_build_instruction>` 30 to compile and build the TF-M source. 31 - Follow the :doc:`Run TF-M examples on Arm platforms </building/run_tfm_examples_on_arm_platforms>` 32 for information on running the example. 33 34To port TF-M to a another system or OS, follow the 35:doc:`OS Integration Guide </integration_guide/index>` 36 37:doc:`Contributing Process </contributing/contributing_process>` contains guidance on how to 38contribute to this project. 39 40######################### 41Set up build environments 42######################### 43 44TF-M officially supports a limited set of build environments and setups. In 45this context, official support means that the environments listed below 46are actively used by team members and active developers, hence users should 47be able to recreate the same configurations by following the instructions 48described below. In case of problems, the TF-M team provides support 49only for these environments, but building in other environments can still be 50possible. 51 52The following environments are supported: 53 54.. tabs:: 55 56 .. group-tab:: Linux 57 58 1. version supported: 59 60 Ubuntu 18.04 x64+ 61 62 2. install dependencies: 63 64 .. code-block:: bash 65 66 sudo apt-get install -y git curl wget build-essential libssl-dev python3 \ 67 python3-pip cmake make 68 69 3. verify cmake version: 70 71 .. code-block:: bash 72 73 cmake --version 74 75 .. note:: 76 77 Please download CMake version 3.21 or later from https://cmake.org/download/. 78 79 4. add CMake path into environment: 80 81 .. code-block:: bash 82 83 export PATH=<CMake path>/bin:$PATH 84 85 .. group-tab:: Windows 86 87 1. version supported: 88 89 Windows 10 x64 90 91 2. install dependencies: 92 93 - Git client latest version (https://git-scm.com/download/win) 94 - CMake version 3.21 or later (`native Windows version <https://cmake.org/download/>`__) 95 - GNU make (http://gnuwin32.sourceforge.net/packages/make.htm) 96 - Python3 `(native Windows version) <https://www.python.org/downloads/>`__ and 97 the pip package manager (from Python 3.4 it's included) 98 99 3. add CMake path into environment: 100 101 .. code-block:: bash 102 103 set PATH=<CMake_Path>\bin;%PATH% 104 105########################### 106Install python dependencies 107########################### 108 109Clone the TF-M source code, and then install the TF-M's additional Python 110dependencies. 111 112.. tabs:: 113 114 .. group-tab:: Linux 115 116 1. get the TF-M source code: 117 118 .. code-block:: bash 119 120 git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git 121 122 2. TF-M recommends installing dependencies in a venv 123 124 .. code-block:: bash 125 126 # Setup python venv for the project 127 python3 -m venv .venv 128 129 # NOTE: If your system python install version is <3.10 you can use `uv <https://docs.astral.sh/uv/getting-started/installation/#standalone-installer>` to setup your .venv 130 uv venv --python 3.12 131 132 source .venv/bin/activate 133 # `-e` installs modules and scripts in editable/development mode 134 pip install -e . 135 136 # NOTE: If you've used `uv` to setup your `.venv`, prepend the `pip` commands with `uv` 137 # `-e` installs modules and scripts in editable/development mode 138 uv pip install -e . 139 140 141 .. group-tab:: Windows 142 143 1. get the TF-M source code: 144 145 .. code-block:: bash 146 147 git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git 148 149 2. TF-M recommends installing dependencies in a venv 150 151 .. code-block:: bash 152 153 # Setup python venv for the project 154 python3 -m venv .venv 155 156 # NOTE: If your system python install version is <3.10 you can use `uv <https://docs.astral.sh/uv/getting-started/installation/#standalone-installer>` to setup your .venv 157 uv venv --python 3.12 158 159 source .venv/bin/activate 160 # `-e` installs modules and scripts in editable/development mode 161 pip install -e . 162 163 # NOTE: If you've used `uv` to setup your `.venv`, prepend the `pip` commands with `uv` 164 # `-e` installs modules and scripts in editable/development mode 165 uv pip install -e . 166 167################### 168Install a toolchain 169################### 170 171To compile TF-M code, at least one of the supported compiler toolchains have to 172be available in the build environment. The currently supported compiler 173versions are: 174 175 - Arm Compiler minimum version v6.21 176 177 .. tabs:: 178 179 .. group-tab:: Linux 180 181 - Download the standalone packages from `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__. 182 - Add Arm Compiler into environment: 183 184 .. code-block:: bash 185 186 export PATH=<ARM_CLANG_PATH>/bin:$PATH 187 export ARM_PRODUCT_PATH=<ARM_CLANG_PATH>/sw/mappings 188 189 - Configure proper tool variant and license. 190 191 .. group-tab:: Windows 192 193 - Download the standalone packages from `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__. 194 - Add Arm Compiler into environment: 195 196 .. code-block:: bash 197 198 set PATH=<ARM_CLANG_PATH>\bin;%PATH% 199 set ARM_PRODUCT_PATH=<ARM_CLANG_PATH>\sw\mappings 200 201 - Configure proper tool variant and license. 202 203 - GNU Arm compiler version minimum 10.3.2021.10 204 205 .. tabs:: 206 207 .. group-tab:: Linux 208 209 - Download the GNU Arm compiler from `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__. 210 - Add GNU Arm into environment: 211 212 .. code-block:: bash 213 214 export PATH=<GNU_ARM_PATH>/bin:$PATH 215 216 .. group-tab:: Windows 217 218 - Download the GNU Arm compiler from `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__. 219 - Add GNU Arm into environment: 220 221 .. code-block:: bash 222 223 set PATH=<GNU_ARM_PATH>\bin;%PATH% 224 225 - IAR Arm compiler v9.30.1 226 227 .. tabs:: 228 229 .. group-tab:: Linux 230 231 - Download IAR build tools from `here <https://www.iar.com/embedded-development-tools/iar-build-tools>`__. 232 - Add IAR Arm compiler into environment: 233 234 .. code-block:: bash 235 236 export PATH=<IAR_COMPILER_PATH>/bin:$PATH 237 238 .. group-tab:: Windows 239 240 - Download IAR build tools from `here <https://www.iar.com/embedded-development-tools/iar-build-tools>`__. 241 - Add IAR Arm compiler into environment: 242 243 .. code-block:: bash 244 245 set PATH=<IAR_COMPILER_PATH>\bin;%PATH% 246 247 - LLVM Embedded Toolchain for Arm v18.1.3+ 248 249 .. tabs:: 250 251 .. group-tab:: Linux 252 253 - Download the LLVM Embedded Toolchain for Arm from `here <https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm>`__. 254 - Add LLVM Embedded into environment: 255 256 .. code-block:: bash 257 258 export PATH=<LLVM_PATH>/bin:$PATH 259 260 .. group-tab:: Windows 261 262 - Download the LLVM Embedded Toolchain for Arm from `here <https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm>`__. 263 - Add LLVM Embedded into environment: 264 265 .. code-block:: bash 266 267 set PATH=<LLVM_PATH>\bin;%PATH% 268 269 .. note:: 270 271 Not all platforms support this toolchain. Please refer to a platform documentation or check with the platform owner. 272 273############################# 274Build AN521 regression sample 275############################# 276 277Here, we take building TF-M for AN521 platform with regression tests using GCC 278as an example: 279 280.. tabs:: 281 282 .. group-tab:: Linux 283 284 Get the TF-M tests source code: 285 286 .. code-block:: bash 287 288 git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git 289 290 Build SPE and NSPE. 291 292 .. code-block:: bash 293 294 cd </tf-m-tests/tests_reg> 295 cmake -S spe -B build_spe -DTFM_PLATFORM=arm/mps2/an521 -DCONFIG_TFM_SOURCE_PATH=<TF-M source dir absolute path> \ 296 -DCMAKE_BUILD_TYPE=Debug -DTFM_TOOLCHAIN_FILE=<TF-M source dir absolute path>/toolchain_GNUARM.cmake \ 297 -DTEST_S=ON -DTEST_NS=ON \ 298 cmake --build build_spe -- install 299 300 cmake -S . -B build_test -DCONFIG_SPE_PATH=<tf-m-tests absolute path>/tests_reg/build_spe/api_ns \ 301 -DCMAKE_BUILD_TYPE=Debug -DTFM_TOOLCHAIN_FILE=<tf-m-tests absolute path>/tests_reg/build_spe/api_ns/cmake/toolchain_ns_GNUARM.cmake 302 cmake --build build_test 303 304 .. group-tab:: Windows 305 306 .. important:: 307 Use "/" instead of "\\" when assigning Windows paths to CMAKE 308 variables, for example, use "c:/build" instead of "c:\\\\build". 309 310 Get the TF-M tests source code: 311 312 .. code-block:: bash 313 314 git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git 315 316 Build SPE and NSPE. 317 318 .. code-block:: bash 319 320 cd </tf-m-tests/tests_reg> 321 cmake -G"Unix Makefiles" -S spe -B build_spe -DTFM_PLATFORM=arm/mps2/an521 -DCONFIG_TFM_SOURCE_PATH=<TF-M source dir absolute path> \ 322 -DCMAKE_BUILD_TYPE=Debug -DTFM_TOOLCHAIN_FILE=<TF-M source dir absolute path>/toolchain_GNUARM.cmake \ 323 -DTEST_S=ON -DTEST_NS=ON \ 324 cmake --build build_spe -- install 325 326 cmake -G"Unix Makefiles" -S . -B build_test -DCONFIG_SPE_PATH=<tf-m-tests absolute path>/tests_reg/build_spe/api_ns \ 327 -DCMAKE_BUILD_TYPE=Debug -DTFM_TOOLCHAIN_FILE=<tf-m-tests absolute path>/tests_reg/build_spe/api_ns/cmake/toolchain_ns_GNUARM.cmake 328 cmake --build build_test 329 330 .. note:: 331 The latest Windows support long paths, but if you are less lucky 332 then you can reduce paths by moving the build directory closer to 333 the root by changing the ``-B`` option of the commands, for example, 334 to ``C:\build_spe`` and ``C:\build_test`` folders. 335 336########################### 337Run AN521 regression sample 338########################### 339 340Run the sample code on SSE-200 Fast-Model, using FVP_MPS2_AEMv8M provided by 341Arm Development Studio. 342 343.. note:: 344 345 Arm Development Studio is not essential to develop TF-M, you can skip this 346 section if don't want to try on Arm develop boards. 347 348.. tabs:: 349 350 .. group-tab:: Linux 351 352 1. install Arm Development Studio to get the fast-model. 353 354 Download Arm Development Studio from `here <https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio#Downloads>`__. 355 356 2. Add ``bl2.axf`` and ``tfm_s_ns_signed.bin`` to symbol files in Debug 357 Configuration menu. 358 359 .. code-block:: bash 360 361 <DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \ 362 --parameter fvp_mps2.platform_type=2 \ 363 --parameter cpu0.baseline=0 \ 364 --parameter cpu0.INITVTOR_S=0x10000000 \ 365 --parameter cpu0.semihosting-enable=0 \ 366 --parameter fvp_mps2.DISABLE_GATING=0 \ 367 --parameter fvp_mps2.telnetterminal0.start_telnet=1 \ 368 --parameter fvp_mps2.telnetterminal1.start_telnet=0 \ 369 --parameter fvp_mps2.telnetterminal2.start_telnet=0 \ 370 --parameter fvp_mps2.telnetterminal0.quiet=0 \ 371 --parameter fvp_mps2.telnetterminal1.quiet=1 \ 372 --parameter fvp_mps2.telnetterminal2.quiet=1 \ 373 --application cpu0=<build_spe>/api_ns/bin/bl2.axf \ 374 --data cpu0=<build_test>/tfm_s_ns_signed.bin@0x10080000 375 376 .. note:: 377 378 The log is output to telnet by default. 379 It can be also redirected to stdout by adding the following parameter. 380 381 .. code-block:: bash 382 383 --parameter fvp_mps2.UART0.out_file=/dev/stdout 384 385 To automatically terminate the fast-model when it finishes running, 386 you can add the following parameters: 387 388 .. code-block:: bash 389 390 --parameter fvp_mps2.UART0.shutdown_on_eot=1 391 392 .. group-tab:: Windows 393 394 1. install Arm Development Studio to get the fast-model. 395 396 Download Arm Development Studio from `here <https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio#Downloads>`__. 397 398 2. Add ``bl2.axf`` and ``tfm_s_ns_signed.bin`` to symbol files in Debug 399 Configuration menu. 400 401 .. code-block:: bash 402 403 <DS_PATH>\sw\models\bin\FVP_MPS2_AEMv8M \ 404 --parameter fvp_mps2.platform_type=2 \ 405 --parameter cpu0.baseline=0 \ 406 --parameter cpu0.INITVTOR_S=0x10000000 \ 407 --parameter cpu0.semihosting-enable=0 \ 408 --parameter fvp_mps2.DISABLE_GATING=0 \ 409 --parameter fvp_mps2.telnetterminal0.start_telnet=1 \ 410 --parameter fvp_mps2.telnetterminal1.start_telnet=0 \ 411 --parameter fvp_mps2.telnetterminal2.start_telnet=0 \ 412 --parameter fvp_mps2.telnetterminal0.quiet=0 \ 413 --parameter fvp_mps2.telnetterminal1.quiet=1 \ 414 --parameter fvp_mps2.telnetterminal2.quiet=1 \ 415 --application cpu0=<build_spe>/api_ns/bin/bl2.axf \ 416 --data cpu0=<build_test>/tfm_s_ns_signed.bin@0x10080000 417 418 .. note:: 419 420 To automatically terminate the fast-model when it finishes running, 421 you can add the following parameters: 422 423 .. code-block:: bash 424 425 --parameter fvp_mps2.UART0.shutdown_on_eot=1 426 427After completing the procedure you should see the following messages on the 428DAPLink UART (baud 115200 8n1):: 429 430 ... 431 #### Execute test suites for the Secure area #### 432 Running Test Suite PSA protected storage S interface tests (TFM_S_PS_TEST_1XXX)... 433 > Executing 'TFM_S_PS_TEST_1001' 434 Description: 'Set interface' 435 TEST: TFM_S_PS_TEST_1001 - PASSED! 436 > Executing 'TFM_S_PS_TEST_1002' 437 Description: 'Set interface with create flags' 438 TEST: TFM_S_PS_TEST_1002 - PASSED! 439 > Executing 'TFM_S_PS_TEST_1003' 440 Description: 'Set interface with NULL data pointer' 441 TEST: TFM_S_PS_TEST_1003 - PASSED! 442 > Executing 'TFM_S_PS_TEST_1005' 443 Description: 'Set interface with write once UID' 444 TEST: TFM_S_PS_TEST_1005 - PASSED! 445 .... 446 447########################## 448Tool & Dependency overview 449########################## 450 451To build the TF-M firmware the following tools are needed: 452 453 - C compiler of supported toolchains 454 - CMake version 3.21 or later 455 - Git 456 - gmake, aka GNU Make 457 - Python >=v3.11 458 - [Optionally] `uv <https://docs.astral.sh/uv/getting-started/installation/#standalone-installer>` 459 460**************** 461Dependency chain 462**************** 463 464.. uml:: 465 466 @startuml 467 skinparam state { 468 BackgroundColor #92AEE0 469 FontColor black 470 FontSize 16 471 AttributeFontColor black 472 AttributeFontSize 16 473 } 474 state fw as "Firmware" : TF-M binary 475 state c_comp as "C Compiler" : C99 476 state python as "Python" : v3.x 477 478 fw --> c_comp 479 fw --> CMake 480 CMake --> gmake 481 CMake --> Ninja 482 fw --> cryptography 483 fw --> pyasn1 484 fw --> yaml 485 fw --> jinja2 486 fw --> cbor2 487 fw --> click 488 fw --> imgtool 489 c_comp --> GCC 490 c_comp --> CLANG 491 c_comp --> IAR 492 cryptography --> python 493 pyasn1 --> python 494 yaml --> python 495 jinja2 --> python 496 cbor2 --> python 497 click --> python 498 imgtool --> python 499 kconfiglib --> python 500 @enduml 501 502.. rubric:: Next steps 503 504Here are some next steps for exploring TF-M: 505 506 - Detailed :doc:`Build instructions </building/tfm_build_instruction>`. 507 - :doc:`IAR Build instructions </building/tfm_build_instruction_iar>`. 508 - Try other :doc:`Samples and Demos </building/run_tfm_examples_on_arm_platforms>`. 509 - :doc:`Documentation generation </building/documentation_generation>`. 510 511-------------- 512 513*SPDX-License-Identifier: BSD-3-Clause* 514 515*SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors* 516