blob: 573abdfe49d254620e0d03f86b43c88d05c89db1 [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
82These tools are optional:
83
Govindraj Raja2fc760e2023-05-12 14:56:42 -050084- Device Tree Compiler (DTC) >= 1.4.7
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010085
86 Needed if you want to rebuild the provided Flattened Device Tree (FDT)
87 source files (``.dts`` files). DTC is available for Linux through the package
88 repositories of most distributions.
89
Daniel Boulbydf83a832022-05-03 16:46:16 +010090- Arm `Development Studio (Arm-DS)`_
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010091
92 The standard software package used for debugging software on Arm development
93 platforms and |FVP| models.
94
Chris Kay32b292d2021-11-02 10:19:37 +000095- Node.js >= 16
Chris Kay46e17f92020-12-09 12:56:27 +000096
97 Highly recommended, and necessary in order to install and use the packaged
98 Git hooks and helper tools. Without these tools you will need to rely on the
99 CI for feedback on commit message conformance.
100
Harrison Mutaib378ad42023-02-16 10:20:48 +0000101- Poetry >= 1.3.2
102
Harrison Mutai342f4682023-04-24 09:58:17 +0100103 Required for managing Python dependencies, this will allow you to reliably
104 reproduce a Python environment to build documentation and run analysis tools.
105 Most importantly, it ensures your system environment will not be affected by
106 dependencies in the Python scripts.
Harrison Mutaib378ad42023-02-16 10:20:48 +0000107
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100108Package Installation (Linux)
109^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110
111If you are using the recommended Ubuntu distribution then you can install the
112required packages with the following command:
113
114.. code:: shell
115
Juan Pablo Conde52865522022-06-28 16:56:32 -0400116 sudo apt install build-essential git
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100117
118The optional packages can be installed using:
119
120.. code:: shell
121
122 sudo apt install device-tree-compiler
123
Chris Kayd855ae22022-10-10 14:34:23 +0100124Additionally, to install a version of Node.js compatible with TF-A's repository
125scripts, you can use the `Node Version Manager`_. To install both NVM and an
126appropriate version of Node.js, run the following **from the root directory of
127the repository**:
Chris Kay46e17f92020-12-09 12:56:27 +0000128
129.. code:: shell
130
Chris Kayd855ae22022-10-10 14:34:23 +0100131 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
132 exec "$SHELL" -ic "nvm install; exec $SHELL"
Chris Kay46e17f92020-12-09 12:56:27 +0000133
134.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script
135
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100136Supporting Files
137----------------
138
139TF-A has been tested with pre-built binaries and file systems from `Linaro
Zelalemc005fdf2021-06-01 17:05:16 -0500140Release 20.01`_. Alternatively, you can build the binaries from source using
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100141instructions in :ref:`Performing an Initial Build`.
142
143.. _prerequisites_get_source:
144
145Getting the TF-A Source
146-----------------------
147
148Source code for |TF-A| is maintained in a Git repository hosted on
149TrustedFirmware.org. To clone this repository from the server, run the following
150in your shell:
151
152.. code:: shell
153
Chris Kay46e17f92020-12-09 12:56:27 +0000154 git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100155
Chris Kay46e17f92020-12-09 12:56:27 +0000156Additional Steps for Contributors
157^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100158
Chris Kay46e17f92020-12-09 12:56:27 +0000159If you are planning on contributing back to TF-A, there are some things you'll
160want to know.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100161
Chris Kay46e17f92020-12-09 12:56:27 +0000162TF-A is hosted by a `Gerrit Code Review`_ server. Gerrit requires that all
163commits include a ``Change-Id`` footer, and this footer is typically
164automatically generated by a Git hook installed by you, the developer.
165
166If you have Node.js installed already, you can automatically install this hook,
167along with any additional hooks and Javascript-based tooling that we use, by
168running from within your newly-cloned repository:
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100169
170.. code:: shell
171
Chris Kay2ff006b2021-05-17 11:18:56 +0100172 npm install --no-save
Chris Kay46e17f92020-12-09 12:56:27 +0000173
174If you have opted **not** to install Node.js, you can install the Gerrit hook
175manually by running:
176
177.. code:: shell
178
179 curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
180 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
181
182You can read more about Git hooks in the *githooks* page of the Git
183documentation, available `here <https://git-scm.com/docs/githooks>`_.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100184
185--------------
186
Harrison Mutaib378ad42023-02-16 10:20:48 +0000187*Copyright (c) 2021-2023, Arm Limited. All rights reserved.*
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100188
Sandrine Bailleuxe356a182022-04-15 11:17:40 +0200189.. _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 +0000190.. _Gerrit Code Review: https://www.gerritcodereview.com/
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100191.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
192.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
Daniel Boulbydf83a832022-05-03 16:46:16 +0100193.. _Development Studio (Arm-DS): https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
Zelalemc005fdf2021-06-01 17:05:16 -0500194.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01