aboutsummaryrefslogtreecommitdiff
path: root/docs/getting_started/tfm_build_instruction.rst
blob: fd80b037ec0e944eda6187116b6e42de046e8ad3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
##################
Build instructions
##################
Please make sure you have all required software installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.

The external dependecies are briefly listed in the
:ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.

The configuration-table
:ref:`docs/getting_started/tfm_build_instruction:Configuring the build` section
explains all the supported build parameters:

****************
TF-M build steps
****************
TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
build environment. The instructions are below.

.. Note::

    It is recommended to build each different build configurations in separate
    directories.

Getting the source-code
=======================
.. code-block:: bash

    cd <TF-M base folder>
    git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
    git clone https://github.com/ARMmbed/mbed-crypto.git -b mbedcrypto-3.0.1
    git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git

.. Note::
   For building with Armclang compiler version 6.10.0, please follow the note
   in :ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.

.. Note::
   For building with the IAR toolchain, please see the notes in
   :doc:`software requirements <tfm_build_instruction_iar>`

Build steps for the AN521 target platform:
==========================================
.. code-block:: bash

    cd <TF-M base folder>
    cd trusted-firmware-m
    mkdir cmake_build
    cd cmake_build
    cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
    cmake --build ./ -- install

Regression Tests for the AN521 target platform
==============================================
*TF-M build regression tests on Linux*

.. code-block:: bash

    cd <TF-M base folder>
    cd trusted-firmware-m
    mkdir cmake_test
    cd cmake_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

*TF-M build regression tests on Windows*

.. code-block:: bash

    cd <TF-M base folder>
    cd trusted-firmware-m
    mkdir cmake_test
    cd cmake_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

Build for PSA Developer API compliance tests
============================================
The build system provides the support for linking with prebuilt PSA Developer
API compliance NS test libraries when using the ``ConfigPsaApiTest.cmake``,
``ConfigPsaApiTestIPC.cmake`` or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config
file. The build system assumes that the PSA API compliance test suite is checked
out at the same level of the TF-M root folder and the default name for the build
folder has been used when compiling the PSA API compliance tests. Each set of
tests for the Internal Trusted Storage, Protected Storage, Crypto and Attestation
services needs to be enabled at the build configuration step by defining::

    -DPSA_API_TEST_INTERNAL_TRUSTED_STORAGE=ON
    -DPSA_API_TEST_PROTECTED_STORAGE=ON
    -DPSA_API_TEST_STORAGE=ON
    -DPSA_API_TEST_CRYPTO=ON
    -DPSA_API_TEST_INITIAL_ATTESTATION=ON

respectively for the corresponding service. For example, to enable the PSA API
tests for the Crypto service only:

.. code-block:: bash

    cd <TF-M base folder>
    cd trusted-firmware-m
    mkdir cmake_psa_test
    cd cmake_psa_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

Build for PSA FF (IPC) compliance tests
=======================================

The build system assumes that the PSA FF compliance test suite is checked out
at the same level of the TF-M root folder and the default name for the build
folder has been used when compiling the PSA FF compliance tests.

Parse the PSA FF compliance tests partition manifests using a tool script named
as ``tfm_parse_manifest_list.py``. This tool updates the TFM partitions data
structure with PSA test suite partitions detail and creates the manifest output
files that are required for the PSA test suite build. Using these manifest
output files, build the PSA FF compliance tests as per the instructions
given in the PSA FF compliance tests README.

.. code-block:: bash

    cd <TF-M base folder>
    cd trusted-firmware-m
    python tools/tfm_parse_manifest_list.py -m tools/tfm_psa_ff_test_manifest_list.yaml append

The build system provides the support for linking with prebuilt PSA FF
compliance NS and S test libraries when using the ``ConfigPsaApiTestIPC.cmake``
or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config file.  The PSA FF compliance
tests need to be enabled at the build configuration step by defining::

    -DPSA_API_TEST_IPC=ON.

For example, to enable the PSA FF tests for ConfigPsaApiTestIPCTfmLevel2.cmake
config :

.. code-block:: bash

    cd <TF-M base folder>
    cd trusted-firmware-m
    mkdir cmake_psa_test
    cd cmake_psa_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTestIPCTfmLevel2.cmake` -DPSA_API_TEST_IPC=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

Location of build artifacts
===========================
The build system defines an API which allow easy usage of build
artifacts. The ``install`` build target copies all files which might be needed
as a dependency by external tools or build systems to the
``<build_dir>/install/outputs``
directory, with the following directory hierarchy:

::

    <build_dir>/install/outputs/fvp/
    <build_dir>/install/outputs/<target_platform>/

There is one folder for FVP testing, with more elaborate naming and
there is an other for testing on target hardware platform (AN521, etc.), where
naming convention is aligned with 8.3 format. The dependency tree of
``install`` build target ensures a proper update (i.e. build) of all output
files before the actual installation step takes place. As such it is suggested
to use this build target to build TF-M.

Export dependency files for NS applications
-------------------------------------------
An NS application requires a number of files to interface with TF-M.
The build system exports these files as part of the ``install`` target and
places them in to a single directory::

    <build_dir>/install/export/tfm

Further details on how to integrate a new NS app with TF-M are available in the
:doc:`integration guide <tfm_integration_guide>`.

Building the documentation
==========================
Please ensure the dependencies for building the firmware and the
documentation are installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.

Building PDF output is optional and can be disabled by removing LaTex from the
PATH.

.. Note::
   For building the documentation all tools needed to build the firmware must
   be available.

Building the Reference Manual
-----------------------------
.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_doc
    cd cmake_doc
    cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
    cmake --build ./ -- install_doc

The documentation files will be available under the directory::

    cmake_doc/install/doc/reference_manual

Building the User Guide
-----------------------
.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_doc
    cd cmake_doc
    cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
    cmake --build ./ -- install_userguide

The documentation files will be available under the directory::

    cmake_doc/install/doc/user_guide

*********************
Configuring the build
*********************
The build configuration for TF-M is provided to the build system using command
line arguments:

.. list-table::
   :widths: 20 80

   * - -DPROJ_CONFIG=<file>
     - Specifies the way the application is built.

       | <file> is the absolute path to configurations file
         named as ``Config<APP_NAME>.cmake``.
       | i.e. On Linux:
         ``-DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake```

   * - -DTARGET_PLATFORM=<target platform name>
     - Specifies the target platform.
       Supported platforms:

          - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
            ``-DTARGET_PLATFORM=AN521``
          - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
            ``-DTARGET_PLATFORM=AN519``
          - Arm SSE-123 Example Subsystem for MPS2+ (AN539)
            ``-DTARGET_PLATFORM=AN539``
          - Cortex-M55 SSE-300 subsystem for MPS2+ FVP
            ``-DTARGET_PLATFORM=FVP_SSE300_MPS2``
          - Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
            ``-DTARGET_PLATFORM=MUSCA_A``
          - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
            ``-DTARGET_PLATFORM=MUSCA_B1``
          - Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
            ``-DTARGET_PLATFORM=MUSCA_S1``
          - Cortex-M33 SSE-200 subsystem for MPS3 (AN524)
            ``-DTARGET_PLATFORM=AN524``
          - Cypress CYS0644ABZI-S2D44 board (PSoC64 platform)
            ``-DTARGET_PLATFORM=psoc64``
            See :doc:`Cypress PSoC 64 platform specifics </platform/ext/target/cypress/psoc64/cypress_psoc64_spec>`
          - DesignStart FPGA on Cloud: Cortex-M33 based platform (SSE-200_AWS platform)
            ``-DTARGET_PLATFORM=SSE-200_AWS``
          - DISCO_L562QE board (Cortex-M33 STM32L562)
            ``-DTARGET_PLATFORM=STM_DISCO_L562QE``
            See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`
          - NUCLEO_L552ZE_Q (Cortex-M33 STM32L552)
            ``-DTARGET_PLATFORM=SSTM_NUCLEO_L552ZE_Q``
            See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`

   * - -DCOMPILER=<compiler name>
     - Specifies the compiler toolchain
       The possible values are:

         - ``ARMCLANG``
         - ``GNUARM``
   * - -DCMAKE_BUILD_TYPE=<build type>
     - Configures debugging support.
       The possible values are:

         - ``Debug``
         - ``Release``
         - ``Relwithdebinfo``
         - ``Minsizerel``
   * - -DMBEDCRYPTO_DEBUG=<ON|OFF>
     - Enables debug symbols for Mbed Crypto library. If a cryptographic
       accelerator is enabled then this will also enable debug symbols and
       logging for any accelerator libraries.
   * - -DBUILD_DWARF_VERSION=<dwarf version>
     - Configures DWARF version.
       The possible values are:

         - 2
         - 3
         - 4

.. Note::
    Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
    without BL2 bootloader.

**************
Configurations
**************
Configurations files under `configs` are TF-M provided configurations for building.
They are used by the `-DPROJ_CONFIG` argument for the build command line.
The following table describes the differences between the configurations:

+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
|     Configuration      | Model [1]_ | TF-M LVL [2]_ | Regression [3]_ | Core Test [4]_ | IPC Test [5]_ | PSA API Test [6]_ |        Comment          |
+========================+============+===============+=================+================+===============+===================+=========================+
| Default                | Library    | 1             | No              | No             | No            | No                | TF-M, no tests          |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| Regression             | Library    | 1             | Yes             | Yes            | No            | No                | TF-M & Regression tests |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| CoreIPC                | IPC        | 1             | No              | No             | No            | No                | TF-M, no tests          |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| CoreIPCTfmLevel2       | IPC        | 2             | No              | No             | No            | No                | TF-M, no tests          |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| RegressionIPC          | IPC        | 1             | Yes             | Yes            | Yes           | No                | TF-M & Regression tests |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| RegressionIPCTfmLevel2 | IPC        | 2             | Yes             | Yes            | Yes           | No                | TF-M & Regression tests |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| PsaApiTest             | Library    | 1             | No              | No             | No            | Yes               | TF-M & PSA API tests    |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| PsaApiTestIPC          | IPC        | 1             | No              | No             | No            | Yes               | TF-M & PSA API tests    |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| PsaApiTestIPCTfmLevel2 | IPC        | 2             | No              | No             | No            | Yes               | TF-M & PSA API tests    |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| DefaultProfileS        | Library    | 1             | No              | No             | No            | No                | TF-M Profile Small,     |
|                        |            |               |                 |                |               |                   | no tests [7]_           |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| RegressionProfileS     | Library    | 1             | Yes             | Yes            | No            | No                | TF-M Profile Small &    |
|                        |            |               |                 |                |               |                   | Regression tests [7]_   |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+

.. [1] Which TF-M Model is set: `CORE_IPC`. If `CORE_IPC` is set to true then the model is IPC model, otherwise it's library model.

.. [2] The TF-M isolation level `TFM_LVL`. Currently Library model supports level 1. IPC model supports level 1 and 2.

.. [3] Build regression tests or not: `REGRESSION`.

.. [4] Build core tests or not: `CORE_TEST`.

.. [5] Build IPC tests or not: `IPC_TEST`. It can be only enabled in IPC model

.. [6] Build for PSA API compliance tests or not: `PSA_API_TEST`.

.. [7] Profile Small config doesn't cover all the platforms. Please check
       Profile Small config files to find out the supported platforms.

--------------

*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*