blob: 9053e3494aa1999a3797abd0603e4f7e0a8ca917 [file] [log] [blame]
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +01001Prerequisites
2=============
3
4This document describes the software requirements for building |TF-A| for
5AArch32 and AArch64 target platforms.
6
7It may possible to build |TF-A| with combinations of software packages that are
8different from those listed below, however only the software described in this
9document can be officially supported.
Sandrine Bailleuxb386f0a2022-07-11 10:53:42 +020010
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010011Build Host
12----------
13
14|TF-A| can be built using either a Linux or a Windows machine as the build host.
15
16A relatively recent Linux distribution is recommended for building |TF-A|. We
Govindraj Raja2fc760e2023-05-12 14:56:42 -050017have performed tests using Ubuntu 22.04 LTS (64-bit) but other distributions
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010018should also work fine as a base, provided that the necessary tools and libraries
19can be installed.
20
21.. _prerequisites_toolchain:
22
23Toolchain
24---------
25
26|TF-A| can be built with any of the following *cross-compiler* toolchains that
27target the Armv7-A or Armv8-A architectures:
28
Jayanth Dodderi Chidanand334bc482023-09-07 11:14:30 +010029- TF-A has been tested with version 12.3.Rel1 (gcc 12.3) from the `Arm Developer website`_
Boyan Karatotevdaf0ef62022-10-27 14:47:18 +010030
31 You will need the targets ``arm-none-eabi`` and ``aarch64-none-elf`` for
32 AArch32 and AArch64 builds respectively.
33
Boyan Karatoteva4d03b72023-02-09 15:59:39 +000034- Clang == 14.0.0
35- Arm Compiler == 6.18
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010036
37In addition, a native compiler is required to build the supporting tools.
38
39.. note::
Boyan Karatoteva4d03b72023-02-09 15:59:39 +000040 Versions greater than the ones specified are likely but not guaranteed to
41 work. This is predominantly because TF-A carries its own copy of compiler-rt,
42 which may be older than the version expected by the compiler. Fixes and bug
43 reports are always welcome.
44
45.. note::
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010046 The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
47 Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
48
49.. note::
50 For instructions on how to select the cross compiler refer to
51 :ref:`Performing an Initial Build`.
52
53.. _prerequisites_software_and_libraries:
54
55Software and Libraries
56----------------------
57
58The following tools are required to obtain and build |TF-A|:
59
60- An appropriate toolchain (see :ref:`prerequisites_toolchain`)
61- GNU Make
62- Git
63
64The following libraries must be available to build one or more components or
65supporting tools:
66
Juan Pablo Conde3539c742022-10-25 19:41:02 -040067- OpenSSL >= 1.1.1 (v3.0.0 to v3.0.6 highly discouraged due to security issues)
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010068
Juan Pablo Conde3539c742022-10-25 19:41:02 -040069 Required to build the cert_create, encrypt_fw, and fiptool tools.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010070
Juan Pablo Conde52865522022-06-28 16:56:32 -040071 .. note::
72
Juan Pablo Conde3539c742022-10-25 19:41:02 -040073 If using OpenSSL 3, older Linux versions may require it to be built from
74 source code, as it may not be available in the default package repositories.
75 Please refer to the OpenSSL project documentation for more information.
Juan Pablo Conde52865522022-06-28 16:56:32 -040076
Sandrine Bailleux878a9982022-04-22 15:47:31 +020077The following libraries are required for Trusted Board Boot and Measured Boot
78support:
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010079
Sandrine Bailleux259fffe2023-09-11 17:02:22 +020080- mbed TLS == 3.4.1 (tag: ``mbedtls-3.4.1``)
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010081
Tamas Ban9e4a4f82023-06-06 13:58:21 +020082The following libraries are required for DICE Protection Environment support:
83
84- QCBOR == 1.2 (tag: ``v1.2``)
85
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010086These tools are optional:
87
Govindraj Raja2fc760e2023-05-12 14:56:42 -050088- Device Tree Compiler (DTC) >= 1.4.7
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010089
90 Needed if you want to rebuild the provided Flattened Device Tree (FDT)
91 source files (``.dts`` files). DTC is available for Linux through the package
92 repositories of most distributions.
93
Daniel Boulbydf83a832022-05-03 16:46:16 +010094- Arm `Development Studio (Arm-DS)`_
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010095
96 The standard software package used for debugging software on Arm development
97 platforms and |FVP| models.
98
Chris Kay32b292d2021-11-02 10:19:37 +000099- Node.js >= 16
Chris Kay46e17f92020-12-09 12:56:27 +0000100
101 Highly recommended, and necessary in order to install and use the packaged
102 Git hooks and helper tools. Without these tools you will need to rely on the
103 CI for feedback on commit message conformance.
104
Harrison Mutaib378ad42023-02-16 10:20:48 +0000105- Poetry >= 1.3.2
106
Harrison Mutai342f4682023-04-24 09:58:17 +0100107 Required for managing Python dependencies, this will allow you to reliably
108 reproduce a Python environment to build documentation and run analysis tools.
109 Most importantly, it ensures your system environment will not be affected by
110 dependencies in the Python scripts.
Harrison Mutaib378ad42023-02-16 10:20:48 +0000111
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100112Package Installation (Linux)
113^^^^^^^^^^^^^^^^^^^^^^^^^^^^
114
115If you are using the recommended Ubuntu distribution then you can install the
116required packages with the following command:
117
118.. code:: shell
119
Juan Pablo Conde52865522022-06-28 16:56:32 -0400120 sudo apt install build-essential git
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100121
122The optional packages can be installed using:
123
124.. code:: shell
125
126 sudo apt install device-tree-compiler
127
Chris Kayd855ae22022-10-10 14:34:23 +0100128Additionally, to install a version of Node.js compatible with TF-A's repository
129scripts, you can use the `Node Version Manager`_. To install both NVM and an
130appropriate version of Node.js, run the following **from the root directory of
131the repository**:
Chris Kay46e17f92020-12-09 12:56:27 +0000132
133.. code:: shell
134
Chris Kayd855ae22022-10-10 14:34:23 +0100135 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
136 exec "$SHELL" -ic "nvm install; exec $SHELL"
Chris Kay46e17f92020-12-09 12:56:27 +0000137
138.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script
139
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100140Supporting Files
141----------------
142
143TF-A has been tested with pre-built binaries and file systems from `Linaro
Zelalemc005fdf2021-06-01 17:05:16 -0500144Release 20.01`_. Alternatively, you can build the binaries from source using
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100145instructions in :ref:`Performing an Initial Build`.
146
147.. _prerequisites_get_source:
148
149Getting the TF-A Source
150-----------------------
151
152Source code for |TF-A| is maintained in a Git repository hosted on
153TrustedFirmware.org. To clone this repository from the server, run the following
154in your shell:
155
156.. code:: shell
157
Chris Kay46e17f92020-12-09 12:56:27 +0000158 git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100159
Chris Kay46e17f92020-12-09 12:56:27 +0000160Additional Steps for Contributors
161^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100162
Chris Kay46e17f92020-12-09 12:56:27 +0000163If you are planning on contributing back to TF-A, there are some things you'll
164want to know.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100165
Chris Kay46e17f92020-12-09 12:56:27 +0000166TF-A is hosted by a `Gerrit Code Review`_ server. Gerrit requires that all
167commits include a ``Change-Id`` footer, and this footer is typically
168automatically generated by a Git hook installed by you, the developer.
169
170If you have Node.js installed already, you can automatically install this hook,
171along with any additional hooks and Javascript-based tooling that we use, by
172running from within your newly-cloned repository:
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100173
174.. code:: shell
175
Chris Kay2ff006b2021-05-17 11:18:56 +0100176 npm install --no-save
Chris Kay46e17f92020-12-09 12:56:27 +0000177
178If you have opted **not** to install Node.js, you can install the Gerrit hook
179manually by running:
180
181.. code:: shell
182
183 curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
184 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
185
186You can read more about Git hooks in the *githooks* page of the Git
187documentation, available `here <https://git-scm.com/docs/githooks>`_.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100188
189--------------
190
Tamas Ban9e4a4f82023-06-06 13:58:21 +0200191*Copyright (c) 2021-2024, Arm Limited. All rights reserved.*
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100192
Sandrine Bailleuxe356a182022-04-15 11:17:40 +0200193.. _Arm Developer website: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads
Chris Kay46e17f92020-12-09 12:56:27 +0000194.. _Gerrit Code Review: https://www.gerritcodereview.com/
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100195.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
196.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
Daniel Boulbydf83a832022-05-03 16:46:16 +0100197.. _Development Studio (Arm-DS): https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
Zelalemc005fdf2021-06-01 17:05:16 -0500198.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01