docs/getting_started/getting-started.rst - TF-RMM/tf-rmm - TrustedFirmware Git Browser

 .. SPDX-License-Identifier: BSD-3-Clause
 .. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.

 #############
 Prerequisite
 #############

 This document describes the software requirements for building |RMM| for AArch64 target platforms.

 It may possible to build |RMM| with combinations of software packages that are different from
 those listed below, however only the software described in this document can be officially supported.

 ###########
 Build Host
 ###########

 The |RMM| officially supports a limited set of build environments and setups.
 In this context, official support means that the environments listed below
 are actively used by team members and active developers, hence users should
 be able to recreate the same configurations by following the instructions
 described below. In case of problems, the |RMM| team provides support only
 for these environments, but building in other environments can still be
 possible.

 A relatively recent Linux distribution is recommended for building RMM. We
 have performed tests using Ubuntu 18.04 LTS (64-bit) but other distributions
 should also work fine as a base, provided that the necessary tools and
 libraries can be installed.

 ##########################
 Tool & Dependency overview
 ##########################

 The following tools are required to obtain and build |RMM|:

 .. csv-table:: Tool dependencies
    :header: "Name", "Version", "Component"

    "C compiler", see :ref:`getting_started_toolchain` ,"Firmware"
    "CMake", ">=3.15.0", "Firmware, Documentation"
    "GNU Make", ">4.0", "Firmware, Documentation"
    "Python",3.x,"Firmware, Documentation"
    "Perl",>=5.26,"Firmware, Documentation"
    "ninja-build",,"Firmware (using Ninja Generator)"
    "Sphinx",">=2.4,<3.0.0","Documentation"
    "sphinxcontrib-plantuml",,"Documentation"
    "sphinx-rtd-theme",,"Documentation"
    "Git",, "Firmware, Documentation"
    "Graphviz dot",">v2.38.0","Documentation"
    "docutils",">v2.38.0","Documentation"

 .. _getting_started_toolchain:

 ###############
 Setup Toolchain
 ###############

 To compile |RMM| code for an AArch64 target, at least one of the
 supported AArch64 toolchains have to be available in the
 build environment.

 Currently, the following compilers are supported:

 - GCC (aarch64-none-elf-) >= 10.2-2020.11 (from the `Arm Developer website`_)
 - Clang+LLVM >= 14.0.0 (from the `LLVM Releases website`_)

 The respective compiler binary must be found in the shell's search path.
 Be sure to add the bin/ directory if you have downloaded a binary version.
 The toolchain to use can be set using ``RMM_TOOLCHAIN`` parameter and can
 be set to either `llvm` or `gnu`. The default toolchain is `gnu`.

 For non-native AArch64 target build, the ``CROSS_COMPILE`` environment
 variable must contain the right target triplet corresponding to the AArch64
 GCC compiler. Below is an example when RMM is to be built for AArch64 target
 on a non-native host machine and using GCC as the toolchain.

     .. code-block:: bash

       export CROSS_COMPILE=aarch64-none-elf-
       export PATH=<path-to-aarch64-gcc>/bin:$PATH

 Please note that AArch64 GCC must be included in the shell's search path
 even when using Clang as the compiler as LLVM does not include some C
 standard headers like `stdlib.h` and needs to be picked up from the
 `include` folder of the AArch64 GCC. Below is an example when RMM is
 to be built for AArch64 target on a non-native host machine and using
 LLVM as the toolchain.

     .. code-block:: bash

       export CROSS_COMPILE=aarch64-none-elf-
       export PATH=<path-to-aarch64-gcc>/bin:<path-to-clang+llvm>/bin:$PATH

 The ``CROSS_COMPILE`` variable is ignored for ``fake_host`` build and
 the native host toolchain is used for the build.

 #######################################
 Package Installation (Ubuntu-18.04 x64)
 #######################################

 If you are using the recommended Ubuntu distribution then we can install the
 required packages with the following commands:

 1. Install dependencies:

 .. code:: shell

     sudo apt-get install -y git build-essential python3 python3-pip make ninja-build
     sudo snap install cmake

 2. Verify cmake version:

 .. code-block:: bash

     cmake --version

 .. note::

     Please download cmake 3.19 or later version from https://cmake.org/download/.

 3. Add CMake path into environment:

 .. code-block:: bash

     export PATH=<CMake path>/bin:$PATH

 ###########################
 Install python dependencies
 ###########################

 .. note::

     The installation of Python dependencies is an optional step. This is required only
     if building documentation.

 RMM's ``docs/requirements.txt`` file declares additional Python dependencies.
 Install them with ``pip3``:

 .. code-block:: bash

     pip3 install --upgrade pip
     cd <rmm source folder>
     pip3 install -r docs/requirements.txt

 .. _getting_started_get_source:

 #########################
 Getting the RMM Source
 #########################

 Source code for |RMM| is maintained in a Git repository hosted on TrustedFirmware.org.
 To clone this repository from the server, run the following in your shell:

 .. code-block:: bash

     git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git

 Additional steps for Contributors
 *********************************

 If you are planning on contributing back to RMM, your commits need to
 include a ``Change-Id`` footer as explained in :ref:`mandated-trailers`.
 This footer is generated by a Git hook that needs to be installed
 inside your cloned RMM source folder.

 The `TF-RMM Gerrit page`_ under trustedfirmware.org contains a
 *Clone with commit-msg hook* subsection under its **Download** header where
 you can copy the command to clone the repo with the required git hooks. Please
 use the **SSH** option to clone the repository on your local machine.

 If needed, you can also manually install the hooks separately on an existing
 repo:

 .. code:: shell

     curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
     chmod +x $(git rev-parse --git-dir)/hooks/commit-msg

 You can read more about Git hooks in the *githooks* page of the `Git hooks
 documentation`_.

 #################################
 Install Cppcheck and dependencies
 #################################

 .. note::

     The installation of Cppcheck is an optional step. This is required only
     if using the Cppcheck static analysis.

 Follow the public documentation to install Cppcheck either from the official
 website https://cppcheck.sourceforge.io/#download or from the official github
 https://github.com/danmar/cppcheck/

 If you own a valid copy of a MISRA rules file:

 .. code-block:: bash

     sudo mkdir /usr/local/share/Cppcheck/misra
     sudo cp -a <path to the misra rules file>/<file name> /usr/local/share/Cppcheck/misra/misra.rules

 ###########################
 Performing an Initial Build
 ###########################

 The |RMM| sources can be compiled using multiple CMake options.

 For detailed instructions on build configurations and examples
 see :ref:`build_options_examples`.

 A typical build command for the FVP platform using GCC toolchain
 is shown below:

 .. code-block:: bash

     cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
     cmake --build ${RMM_BUILD_DIR}

 ###############
 Running the RMM
 ###############

 The |RMM| is part of the CCA software stack and relies on EL3 Firmware to load
 the binary at boot time appropriately. It needs both EL3 Firmware and
 Non-Secure Host to be present at runtime for its functionality. The EL3
 Firmware must comply to `RMM-EL3 Communication Specification`_ and is
 typically the `TF-A`_. The Non-Secure Host can be an RME aware hypervisor
 or an appropriate Test utility running in Non-Secure world which can interact
 with |RMM| via Realm Management Interface (RMI).

 The `TF-A`_ project includes build and run instructions for an RME enabled
 system on the FVP platform as part of `TF-A RME documentation`_.
 The ``rmm.img`` binary is provided to the TF-A bootloader to be packaged
 in FIP using ``RMM`` build option in `TF-A`_.

 If |RMM| is built for the `fake_host` architecture
 (see :ref:`RMM Fake Host Build`), then the generated `rmm.elf` binary can
 run natively on the Host machine. It does this by emulating parts of the system
 as described in :ref:`RMM Fake host architecture` design.

 -----

 .. _Arm Developer website: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
 .. _LLVM Releases website: https://releases.llvm.org/
 .. _RMM-EL3 Communication Specification: https://trustedfirmware-a.readthedocs.io/en/latest/components/rmm-el3-comms-spec.html
 .. _TF-A: https://www.trustedfirmware.org/projects/tf-a/
 .. _TF-A RME documentation: https://trustedfirmware-a.readthedocs.io/en/latest/components/realm-management-extension.html
 .. _TF-RMM Gerrit page: https://review.trustedfirmware.org/admin/repos/TF-RMM/tf-rmm
 .. _Git hooks documentation:  https://git-scm.com/docs/githooks
	.. SPDX-License-Identifier: BSD-3-Clause
	.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.

	#############
	Prerequisite
	#############

	This document describes the software requirements for building \|RMM\| for AArch64 target platforms.

	It may possible to build \|RMM\| with combinations of software packages that are different from
	those listed below, however only the software described in this document can be officially supported.

	###########
	Build Host
	###########

	The \|RMM\| officially supports a limited set of build environments and setups.
	In this context, official support means that the environments listed below
	are actively used by team members and active developers, hence users should
	be able to recreate the same configurations by following the instructions
	described below. In case of problems, the \|RMM\| team provides support only
	for these environments, but building in other environments can still be
	possible.

	A relatively recent Linux distribution is recommended for building RMM. We
	have performed tests using Ubuntu 18.04 LTS (64-bit) but other distributions
	should also work fine as a base, provided that the necessary tools and
	libraries can be installed.

	##########################
	Tool & Dependency overview
	##########################

	The following tools are required to obtain and build \|RMM\|:

	.. csv-table:: Tool dependencies
	:header: "Name", "Version", "Component"

	"C compiler", see :ref:`getting_started_toolchain` ,"Firmware"
	"CMake", ">=3.15.0", "Firmware, Documentation"
	"GNU Make", ">4.0", "Firmware, Documentation"
	"Python",3.x,"Firmware, Documentation"
	"Perl",>=5.26,"Firmware, Documentation"
	"ninja-build",,"Firmware (using Ninja Generator)"
	"Sphinx",">=2.4,<3.0.0","Documentation"
	"sphinxcontrib-plantuml",,"Documentation"
	"sphinx-rtd-theme",,"Documentation"
	"Git",, "Firmware, Documentation"
	"Graphviz dot",">v2.38.0","Documentation"
	"docutils",">v2.38.0","Documentation"

	.. _getting_started_toolchain:

	###############
	Setup Toolchain
	###############

	To compile \|RMM\| code for an AArch64 target, at least one of the
	supported AArch64 toolchains have to be available in the
	build environment.

	Currently, the following compilers are supported:

	- GCC (aarch64-none-elf-) >= 10.2-2020.11 (from the `Arm Developer website`_)
	- Clang+LLVM >= 14.0.0 (from the `LLVM Releases website`_)

	The respective compiler binary must be found in the shell's search path.
	Be sure to add the bin/ directory if you have downloaded a binary version.
	The toolchain to use can be set using ``RMM_TOOLCHAIN`` parameter and can
	be set to either `llvm` or `gnu`. The default toolchain is `gnu`.

	For non-native AArch64 target build, the ``CROSS_COMPILE`` environment
	variable must contain the right target triplet corresponding to the AArch64
	GCC compiler. Below is an example when RMM is to be built for AArch64 target
	on a non-native host machine and using GCC as the toolchain.

	.. code-block:: bash

	export CROSS_COMPILE=aarch64-none-elf-
	export PATH=<path-to-aarch64-gcc>/bin:$PATH

	Please note that AArch64 GCC must be included in the shell's search path
	even when using Clang as the compiler as LLVM does not include some C
	standard headers like `stdlib.h` and needs to be picked up from the
	`include` folder of the AArch64 GCC. Below is an example when RMM is
	to be built for AArch64 target on a non-native host machine and using
	LLVM as the toolchain.

	.. code-block:: bash

	export CROSS_COMPILE=aarch64-none-elf-
	export PATH=<path-to-aarch64-gcc>/bin:<path-to-clang+llvm>/bin:$PATH

	The ``CROSS_COMPILE`` variable is ignored for ``fake_host`` build and
	the native host toolchain is used for the build.

	#######################################
	Package Installation (Ubuntu-18.04 x64)
	#######################################

	If you are using the recommended Ubuntu distribution then we can install the
	required packages with the following commands:

	1. Install dependencies:

	.. code:: shell

	sudo apt-get install -y git build-essential python3 python3-pip make ninja-build
	sudo snap install cmake

	2. Verify cmake version:

	.. code-block:: bash

	cmake --version

	.. note::

	Please download cmake 3.19 or later version from https://cmake.org/download/.

	3. Add CMake path into environment:

	.. code-block:: bash

	export PATH=<CMake path>/bin:$PATH

	###########################
	Install python dependencies
	###########################

	.. note::

	The installation of Python dependencies is an optional step. This is required only
	if building documentation.

	RMM's ``docs/requirements.txt`` file declares additional Python dependencies.
	Install them with ``pip3``:

	.. code-block:: bash

	pip3 install --upgrade pip
	cd <rmm source folder>
	pip3 install -r docs/requirements.txt

	.. _getting_started_get_source:

	#########################
	Getting the RMM Source
	#########################

	Source code for \|RMM\| is maintained in a Git repository hosted on TrustedFirmware.org.
	To clone this repository from the server, run the following in your shell:

	.. code-block:: bash

	git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git

	Additional steps for Contributors
	*********************************

	If you are planning on contributing back to RMM, your commits need to
	include a ``Change-Id`` footer as explained in :ref:`mandated-trailers`.
	This footer is generated by a Git hook that needs to be installed
	inside your cloned RMM source folder.

	The `TF-RMM Gerrit page`_ under trustedfirmware.org contains a
	Clone with commit-msg hook subsection under its Download header where
	you can copy the command to clone the repo with the required git hooks. Please
	use the SSH option to clone the repository on your local machine.

	If needed, you can also manually install the hooks separately on an existing
	repo:

	.. code:: shell

	curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
	chmod +x $(git rev-parse --git-dir)/hooks/commit-msg

	You can read more about Git hooks in the githooks page of the `Git hooks
	documentation`_.

	#################################
	Install Cppcheck and dependencies
	#################################

	.. note::

	The installation of Cppcheck is an optional step. This is required only
	if using the Cppcheck static analysis.

	Follow the public documentation to install Cppcheck either from the official
	website https://cppcheck.sourceforge.io/#download or from the official github
	https://github.com/danmar/cppcheck/

	If you own a valid copy of a MISRA rules file:

	.. code-block:: bash

	sudo mkdir /usr/local/share/Cppcheck/misra
	sudo cp -a <path to the misra rules file>/<file name> /usr/local/share/Cppcheck/misra/misra.rules

	###########################
	Performing an Initial Build
	###########################

	The \|RMM\| sources can be compiled using multiple CMake options.

	For detailed instructions on build configurations and examples
	see :ref:`build_options_examples`.

	A typical build command for the FVP platform using GCC toolchain
	is shown below:

	.. code-block:: bash

	cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
	cmake --build ${RMM_BUILD_DIR}

	###############
	Running the RMM
	###############

	The \|RMM\| is part of the CCA software stack and relies on EL3 Firmware to load
	the binary at boot time appropriately. It needs both EL3 Firmware and
	Non-Secure Host to be present at runtime for its functionality. The EL3
	Firmware must comply to `RMM-EL3 Communication Specification`_ and is
	typically the `TF-A`_. The Non-Secure Host can be an RME aware hypervisor
	or an appropriate Test utility running in Non-Secure world which can interact
	with \|RMM\| via Realm Management Interface (RMI).

	The `TF-A`_ project includes build and run instructions for an RME enabled
	system on the FVP platform as part of `TF-A RME documentation`_.
	The ``rmm.img`` binary is provided to the TF-A bootloader to be packaged
	in FIP using ``RMM`` build option in `TF-A`_.

	If \|RMM\| is built for the `fake_host` architecture
	(see :ref:`RMM Fake Host Build`), then the generated `rmm.elf` binary can
	run natively on the Host machine. It does this by emulating parts of the system
	as described in :ref:`RMM Fake host architecture` design.

	-----

	.. _Arm Developer website: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
	.. _LLVM Releases website: https://releases.llvm.org/
	.. _RMM-EL3 Communication Specification: https://trustedfirmware-a.readthedocs.io/en/latest/components/rmm-el3-comms-spec.html
	.. _TF-A: https://www.trustedfirmware.org/projects/tf-a/
	.. _TF-A RME documentation: https://trustedfirmware-a.readthedocs.io/en/latest/components/realm-management-extension.html
	.. _TF-RMM Gerrit page: https://review.trustedfirmware.org/admin/repos/TF-RMM/tf-rmm
	.. _Git hooks documentation: https://git-scm.com/docs/githooks