blob: 62ef8263ebfb2c48aceb3024778fdd1e57360269 [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
17have performed tests using Ubuntu 16.04 LTS (64-bit) but other distributions
18should 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 Chidanand8b957ed2022-09-12 14:50:12 +010029- GCC >= 11.3.Rel1 (from the `Arm Developer website`_)
Harrison Mutai38a293a2022-02-23 11:37:12 +000030- Clang >= 14.0.0
31- Arm Compiler >= 6.18
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010032
33In addition, a native compiler is required to build the supporting tools.
34
35.. note::
36 The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
37 Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
38
39.. note::
40 For instructions on how to select the cross compiler refer to
41 :ref:`Performing an Initial Build`.
42
43.. _prerequisites_software_and_libraries:
44
45Software and Libraries
46----------------------
47
48The following tools are required to obtain and build |TF-A|:
49
50- An appropriate toolchain (see :ref:`prerequisites_toolchain`)
51- GNU Make
52- Git
53
54The following libraries must be available to build one or more components or
55supporting tools:
56
Juan Pablo Conde3539c742022-10-25 19:41:02 -040057- OpenSSL >= 1.1.1 (v3.0.0 to v3.0.6 highly discouraged due to security issues)
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010058
Juan Pablo Conde3539c742022-10-25 19:41:02 -040059 Required to build the cert_create, encrypt_fw, and fiptool tools.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010060
Juan Pablo Conde52865522022-06-28 16:56:32 -040061 .. note::
62
Juan Pablo Conde3539c742022-10-25 19:41:02 -040063 If using OpenSSL 3, older Linux versions may require it to be built from
64 source code, as it may not be available in the default package repositories.
65 Please refer to the OpenSSL project documentation for more information.
Juan Pablo Conde52865522022-06-28 16:56:32 -040066
Sandrine Bailleux878a9982022-04-22 15:47:31 +020067The following libraries are required for Trusted Board Boot and Measured Boot
68support:
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010069
Daniel Boulby831e4bc2022-09-23 09:37:20 +010070- mbed TLS == 2.28.1 (tag: ``mbedtls-2.28.1``)
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010071
72These tools are optional:
73
74- Device Tree Compiler (DTC) >= 1.4.6
75
76 Needed if you want to rebuild the provided Flattened Device Tree (FDT)
77 source files (``.dts`` files). DTC is available for Linux through the package
78 repositories of most distributions.
79
Daniel Boulbydf83a832022-05-03 16:46:16 +010080- Arm `Development Studio (Arm-DS)`_
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010081
82 The standard software package used for debugging software on Arm development
83 platforms and |FVP| models.
84
Chris Kay32b292d2021-11-02 10:19:37 +000085- Node.js >= 16
Chris Kay46e17f92020-12-09 12:56:27 +000086
87 Highly recommended, and necessary in order to install and use the packaged
88 Git hooks and helper tools. Without these tools you will need to rely on the
89 CI for feedback on commit message conformance.
90
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010091Package Installation (Linux)
92^^^^^^^^^^^^^^^^^^^^^^^^^^^^
93
94If you are using the recommended Ubuntu distribution then you can install the
95required packages with the following command:
96
97.. code:: shell
98
Juan Pablo Conde52865522022-06-28 16:56:32 -040099 sudo apt install build-essential git
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100100
101The optional packages can be installed using:
102
103.. code:: shell
104
105 sudo apt install device-tree-compiler
106
Chris Kayd855ae22022-10-10 14:34:23 +0100107Additionally, to install a version of Node.js compatible with TF-A's repository
108scripts, you can use the `Node Version Manager`_. To install both NVM and an
109appropriate version of Node.js, run the following **from the root directory of
110the repository**:
Chris Kay46e17f92020-12-09 12:56:27 +0000111
112.. code:: shell
113
Chris Kayd855ae22022-10-10 14:34:23 +0100114 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
115 exec "$SHELL" -ic "nvm install; exec $SHELL"
Chris Kay46e17f92020-12-09 12:56:27 +0000116
117.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script
118
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100119Supporting Files
120----------------
121
122TF-A has been tested with pre-built binaries and file systems from `Linaro
Zelalemc005fdf2021-06-01 17:05:16 -0500123Release 20.01`_. Alternatively, you can build the binaries from source using
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100124instructions in :ref:`Performing an Initial Build`.
125
126.. _prerequisites_get_source:
127
128Getting the TF-A Source
129-----------------------
130
131Source code for |TF-A| is maintained in a Git repository hosted on
132TrustedFirmware.org. To clone this repository from the server, run the following
133in your shell:
134
135.. code:: shell
136
Chris Kay46e17f92020-12-09 12:56:27 +0000137 git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100138
Chris Kay46e17f92020-12-09 12:56:27 +0000139Additional Steps for Contributors
140^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100141
Chris Kay46e17f92020-12-09 12:56:27 +0000142If you are planning on contributing back to TF-A, there are some things you'll
143want to know.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100144
Chris Kay46e17f92020-12-09 12:56:27 +0000145TF-A is hosted by a `Gerrit Code Review`_ server. Gerrit requires that all
146commits include a ``Change-Id`` footer, and this footer is typically
147automatically generated by a Git hook installed by you, the developer.
148
149If you have Node.js installed already, you can automatically install this hook,
150along with any additional hooks and Javascript-based tooling that we use, by
151running from within your newly-cloned repository:
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100152
153.. code:: shell
154
Chris Kay2ff006b2021-05-17 11:18:56 +0100155 npm install --no-save
Chris Kay46e17f92020-12-09 12:56:27 +0000156
157If you have opted **not** to install Node.js, you can install the Gerrit hook
158manually by running:
159
160.. code:: shell
161
162 curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
163 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
164
165You can read more about Git hooks in the *githooks* page of the Git
166documentation, available `here <https://git-scm.com/docs/githooks>`_.
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100167
168--------------
169
Harrison Mutai38a293a2022-02-23 11:37:12 +0000170*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100171
Sandrine Bailleuxe356a182022-04-15 11:17:40 +0200172.. _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 +0000173.. _Gerrit Code Review: https://www.gerritcodereview.com/
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100174.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
175.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
Daniel Boulbydf83a832022-05-03 16:46:16 +0100176.. _Development Studio (Arm-DS): https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
Zelalemc005fdf2021-06-01 17:05:16 -0500177.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01