blob: 4e8e07b39d7407abaed3b678e46e0d3ed42b5a6a [file] [log] [blame]
Soby Mathewb4c6df42022-11-09 11:13:29 +00001.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4#############
5Prerequisite
6#############
7
Soby Mathewf572d3b2022-11-21 12:30:11 +00008This document describes the software requirements for building |RMM| for
9AArch64 target platforms.
Soby Mathewb4c6df42022-11-09 11:13:29 +000010
Soby Mathewf572d3b2022-11-21 12:30:11 +000011It may possible to build |RMM| with combinations of software packages that
12are different from those listed below, however only the software described in
13this document can be officially supported.
Soby Mathewb4c6df42022-11-09 11:13:29 +000014
15###########
16Build Host
17###########
18
19The |RMM| officially supports a limited set of build environments and setups.
20In this context, official support means that the environments listed below
21are actively used by team members and active developers, hence users should
22be able to recreate the same configurations by following the instructions
23described below. In case of problems, the |RMM| team provides support only
24for these environments, but building in other environments can still be
25possible.
26
Soby Mathewf572d3b2022-11-21 12:30:11 +000027We recommend at least Ubuntu 20.04 LTS (x64) for build environment. The
28arm64/AArch64 Ubuntu and other Linux distributions should also work fine,
29provided that the necessary tools and libraries can be installed.
Soby Mathewb4c6df42022-11-09 11:13:29 +000030
31##########################
32Tool & Dependency overview
33##########################
34
35The following tools are required to obtain and build |RMM|:
36
37.. csv-table:: Tool dependencies
38 :header: "Name", "Version", "Component"
39
40 "C compiler", see :ref:`getting_started_toolchain` ,"Firmware"
41 "CMake", ">=3.15.0", "Firmware, Documentation"
42 "GNU Make", ">4.0", "Firmware, Documentation"
43 "Python",3.x,"Firmware, Documentation"
44 "Perl",>=5.26,"Firmware, Documentation"
45 "ninja-build",,"Firmware (using Ninja Generator)"
46 "Sphinx",">=2.4,<3.0.0","Documentation"
47 "sphinxcontrib-plantuml",,"Documentation"
48 "sphinx-rtd-theme",,"Documentation"
49 "Git",, "Firmware, Documentation"
50 "Graphviz dot",">v2.38.0","Documentation"
51 "docutils",">v2.38.0","Documentation"
Soby Mathewb4c6df42022-11-09 11:13:29 +000052
53.. _getting_started_toolchain:
54
55###############
56Setup Toolchain
57###############
58
59To compile |RMM| code for an AArch64 target, at least one of the
60supported AArch64 toolchains have to be available in the
61build environment.
62
63Currently, the following compilers are supported:
64
65- GCC (aarch64-none-elf-) >= 10.2-2020.11 (from the `Arm Developer website`_)
66- Clang+LLVM >= 14.0.0 (from the `LLVM Releases website`_)
67
68The respective compiler binary must be found in the shell's search path.
69Be sure to add the bin/ directory if you have downloaded a binary version.
70The toolchain to use can be set using ``RMM_TOOLCHAIN`` parameter and can
71be set to either `llvm` or `gnu`. The default toolchain is `gnu`.
72
73For non-native AArch64 target build, the ``CROSS_COMPILE`` environment
74variable must contain the right target triplet corresponding to the AArch64
75GCC compiler. Below is an example when RMM is to be built for AArch64 target
76on a non-native host machine and using GCC as the toolchain.
77
78 .. code-block:: bash
79
80 export CROSS_COMPILE=aarch64-none-elf-
81 export PATH=<path-to-aarch64-gcc>/bin:$PATH
82
83Please note that AArch64 GCC must be included in the shell's search path
84even when using Clang as the compiler as LLVM does not include some C
85standard headers like `stdlib.h` and needs to be picked up from the
86`include` folder of the AArch64 GCC. Below is an example when RMM is
87to be built for AArch64 target on a non-native host machine and using
88LLVM as the toolchain.
89
90 .. code-block:: bash
91
92 export CROSS_COMPILE=aarch64-none-elf-
93 export PATH=<path-to-aarch64-gcc>/bin:<path-to-clang+llvm>/bin:$PATH
94
95The ``CROSS_COMPILE`` variable is ignored for ``fake_host`` build and
96the native host toolchain is used for the build.
97
98#######################################
Soby Mathewf572d3b2022-11-21 12:30:11 +000099Package Installation (Ubuntu-20.04 x64)
Soby Mathewb4c6df42022-11-09 11:13:29 +0000100#######################################
101
102If you are using the recommended Ubuntu distribution then we can install the
103required packages with the following commands:
104
1051. Install dependencies:
106
107.. code:: shell
108
Arunachalam Ganapathyf1a13aa2022-11-11 15:07:12 +0000109 sudo apt-get install -y git build-essential python3 python3-pip make ninja-build
Soby Mathewb4c6df42022-11-09 11:13:29 +0000110 sudo snap install cmake
Soby Mathewb4c6df42022-11-09 11:13:29 +0000111
1122. Verify cmake version:
113
114.. code-block:: bash
115
116 cmake --version
117
118.. note::
119
120 Please download cmake 3.19 or later version from https://cmake.org/download/.
121
Arunachalam Ganapathyf1a13aa2022-11-11 15:07:12 +00001223. Add CMake path into environment:
Soby Mathewb4c6df42022-11-09 11:13:29 +0000123
124.. code-block:: bash
125
126 export PATH=<CMake path>/bin:$PATH
Soby Mathewb4c6df42022-11-09 11:13:29 +0000127
128###########################
129Install python dependencies
130###########################
131
132.. note::
133
134 The installation of Python dependencies is an optional step. This is required only
135 if building documentation.
136
Arunachalam Ganapathyf1a13aa2022-11-11 15:07:12 +0000137RMM's ``docs/requirements.txt`` file declares additional Python dependencies.
Soby Mathewb4c6df42022-11-09 11:13:29 +0000138Install them with ``pip3``:
139
140.. code-block:: bash
141
142 pip3 install --upgrade pip
143 cd <rmm source folder>
Arunachalam Ganapathyf1a13aa2022-11-11 15:07:12 +0000144 pip3 install -r docs/requirements.txt
Soby Mathewb4c6df42022-11-09 11:13:29 +0000145
146.. _getting_started_get_source:
147
148#########################
149Getting the RMM Source
150#########################
151
152Source code for |RMM| is maintained in a Git repository hosted on TrustedFirmware.org.
153To clone this repository from the server, run the following in your shell:
154
155.. code-block:: bash
156
157 git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git
158
159Additional steps for Contributors
160*********************************
161
162If you are planning on contributing back to RMM, your commits need to
163include a ``Change-Id`` footer as explained in :ref:`mandated-trailers`.
164This footer is generated by a Git hook that needs to be installed
165inside your cloned RMM source folder.
166
167The `TF-RMM Gerrit page`_ under trustedfirmware.org contains a
168*Clone with commit-msg hook* subsection under its **Download** header where
Javier Almansa Sobrino6166c032022-11-10 14:24:03 +0000169you can copy the command to clone the repo with the required git hooks. Please
170use the **SSH** option to clone the repository on your local machine.
Soby Mathewb4c6df42022-11-09 11:13:29 +0000171
172If needed, you can also manually install the hooks separately on an existing
173repo:
174
175.. code:: shell
176
177 curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
178 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
179
180You can read more about Git hooks in the *githooks* page of the `Git hooks
181documentation`_.
182
183#################################
184Install Cppcheck and dependencies
185#################################
186
187.. note::
188
189 The installation of Cppcheck is an optional step. This is required only
190 if using the Cppcheck static analysis.
191
192Follow the public documentation to install Cppcheck either from the official
193website https://cppcheck.sourceforge.io/#download or from the official github
194https://github.com/danmar/cppcheck/
195
196If you own a valid copy of a MISRA rules file:
197
198.. code-block:: bash
199
200 sudo mkdir /usr/local/share/Cppcheck/misra
201 sudo cp -a <path to the misra rules file>/<file name> /usr/local/share/Cppcheck/misra/misra.rules
202
203###########################
204Performing an Initial Build
205###########################
206
207The |RMM| sources can be compiled using multiple CMake options.
208
209For detailed instructions on build configurations and examples
210see :ref:`build_options_examples`.
211
212A typical build command for the FVP platform using GCC toolchain
213is shown below:
214
215.. code-block:: bash
216
217 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
218 cmake --build ${RMM_BUILD_DIR}
219
220###############
221Running the RMM
222###############
223
224The |RMM| is part of the CCA software stack and relies on EL3 Firmware to load
225the binary at boot time appropriately. It needs both EL3 Firmware and
226Non-Secure Host to be present at runtime for its functionality. The EL3
227Firmware must comply to `RMM-EL3 Communication Specification`_ and is
228typically the `TF-A`_. The Non-Secure Host can be an RME aware hypervisor
229or an appropriate Test utility running in Non-Secure world which can interact
230with |RMM| via Realm Management Interface (RMI).
231
232The `TF-A`_ project includes build and run instructions for an RME enabled
233system on the FVP platform as part of `TF-A RME documentation`_.
234The ``rmm.img`` binary is provided to the TF-A bootloader to be packaged
235in FIP using ``RMM`` build option in `TF-A`_.
236
237If |RMM| is built for the `fake_host` architecture
238(see :ref:`RMM Fake Host Build`), then the generated `rmm.elf` binary can
239run natively on the Host machine. It does this by emulating parts of the system
240as described in :ref:`RMM Fake host architecture` design.
241
242-----
243
244.. _Arm Developer website: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
245.. _LLVM Releases website: https://releases.llvm.org/
246.. _RMM-EL3 Communication Specification: https://trustedfirmware-a.readthedocs.io/en/latest/components/rmm-el3-comms-spec.html
247.. _TF-A: https://www.trustedfirmware.org/projects/tf-a/
248.. _TF-A RME documentation: https://trustedfirmware-a.readthedocs.io/en/latest/components/realm-management-extension.html
249.. _TF-RMM Gerrit page: https://review.trustedfirmware.org/admin/repos/TF-RMM/tf-rmm
250.. _Git hooks documentation: https://git-scm.com/docs/githooks