TF-RMM Release v0.1.0
This is the first external release of TF-RMM and provides a reference
implementation of Realm Management Monitor (RMM) as specified by the
RMM Beta0 specification[1].
The `docs/readme.rst` has more details about the project and
`docs/getting_started/getting-started.rst` has details on how to get
started with TF-RMM.
[1] https://developer.arm.com/documentation/den0137/1-0bet0/?lang=en
Signed-off-by: Soby Mathew <soby.mathew@arm.com>
Change-Id: I205ef14c015e4a37ae9ae1a64e4cd22eb8da746e
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
new file mode 100644
index 0000000..ce58ea9
--- /dev/null
+++ b/docs/getting_started/build-options.rst
@@ -0,0 +1,223 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+
+
+.. _build_options_examples:
+
+#####################
+RMM Build Examples
+#####################
+
+The |RMM| supports a wide range of build configuration options. Some of these options
+are more regularly exercised by developers, while others are for **advanced** and
+**experimental** usage only.
+
+|RMM| can be built using either GNU(GCC) or :ref:`LLVM(Clang)<llvm_build>`
+toolchain. See :ref:`this section<getting_started_toolchain>` for toolchain
+setup and the supported versions.
+
+The build is performed in 2 stages:
+
+**Configure Stage:** In this stage, a default config file can be specified which configures
+a sane config for the chosen platform. If this default config needs to be modified, it is
+recommended to first perform a default config and then modify using the cmake ncurses as
+shown in :ref:`CMake UI Example<build_config_example>`.
+
+**Build Stage:** In this stage, the source build is performed by specifying the `--build` option.
+See any of the commands below for an example.
+
+.. note::
+
+ It is recommended to clean build if any of the build options are changed from previous build.
+
+Below are some of the typical build and configuration examples frequently used in |RMM| development
+for the FVP Platform. Detailed configuration options are described :ref:`here<build_options_table>`.
+
+RMM also supports a ``fake_host`` build which can be used to build RMM for test
+and code analysis on the host machine. See
+:ref:`this section here<fake_host_build>` for more details.
+
+1. Perform an initial default build with minimum configuration options:
+
+Build using gnu toolchain
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR}
+
+Build using LLVM toolchain
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -DRMM_TOOLCHAIN=llvm -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR}
+
+.. _build_config_example:
+
+2. Perform an initial default config, then modify using ccmake ncurses UI:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ ccmake -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR}
+
+3. Perform a debug build and specify a log level:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DCMAKE_BUILD_TYPE=Debug -DLOG_LEVEL=50
+ cmake --build ${RMM_BUILD_DIR}
+
+4. Perform a documentation build:
+
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH=<install path>/bin/plantuml/plantuml.jar
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DRMM_DOCS=ON
+ cmake --build ${RMM_BUILD_DIR} -- docs
+
+5. Perform a clean verbose build:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} --clean-first --verbose
+
+6. Perform a build with Ninja Genenerator:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DCMAKE_BUILD_TYPE=${BUILD_TYPE} -G "Ninja" -DLOG_LEVEL=50
+ cmake --build ${RMM_BUILD_DIR}
+
+7. Perform a build with Ninja Multi Config Genenerator:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -G "Ninja Multi-Config" -DLOG_LEVEL=50
+ cmake --build ${RMM_BUILD_DIR} --config ${BUILD_TYPE}
+
+8. Perform a Cppcheck static analysis:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -DRMM_STATIC_ANALYSIS_CPPCHECK=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- cppcheck
+ cat ${BUILD_DIR}/tools/cppcheck/cppcheck.xml
+
+9. Perform a Cppcheck static analysis with CERT_C/MISRA/THREAD SAFETY (example with MISRA):
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -DRMM_STATIC_ANALYSIS_CPPCHECK=ON -DRMM_STATIC_ANALYSIS_CPPCHECK_CHECKER_MISRA=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- cppcheck
+ cat ${BUILD_DIR}/tools/cppcheck/cppcheck.xml
+
+10. Perform a checkpatch analysis:
+
+Run checkpatch on commits in the current branch against BASE_COMMIT (default origin/master):
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- checkpatch
+
+Run checkpatch on entire codebase:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- checkcodebase
+
+11. Perform a checkspdx analysis:
+
+Run checkspdx on commits in the current branch against BASE_COMMIT (default origin/master):
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- checkspdx-patch
+
+Run checkspdx on entire codebase:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- checkspdx-codebase
+
+13. Check header file include order:
+
+Run checkincludes-patch on commits in the current branch against BASE_COMMIT (default origin/master):
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- checkincludes-patch
+
+Run checkincludes on entire codebase:
+
+.. code-block:: bash
+
+ cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR}
+ cmake --build ${RMM_BUILD_DIR} -- checkincludes-codebase
+
+.. _build_options_table:
+
+###################
+RMM Build Options
+###################
+
+The |RMM| build system supports the following CMake build options.
+
+.. csv-table:: RMM CMake Options Table
+ :header: "Option", "Valid values", "Default", "Description"
+
+ RMM_CONFIG , , ,"Platform build configuration, eg: fvp_defcfg for the FVP"
+ RMM_ARCH ,aarch64 | fake_host ,aarch64 ,"Target Architecture for RMM build"
+ RMM_MAX_SIZE , ,0x0 ,"Maximum size for RMM image"
+ MAX_CPUS , ,16 ,"Maximum number of CPUs supported by RMM"
+ GRANULE_SIZE , ,4096 ,"Granule Size used by RMM"
+ RMM_DOCS ,ON | OFF ,OFF ,"RMM Documentation build"
+ CMAKE_BUILD_TYPE ,Debug | Release ,Release ,"CMake Build type"
+ CMAKE_CONFIGURATION_TYPES ,Debug & Release ,Debug & Release ,"Multi-generator configuration types"
+ CMAKE_DEFAULT_BUILD_TYPE ,Debug | Release ,Release ,"Default multi-generator configuration type"
+ MbedTLS_BUILD_TYPE ,Debug | Release ,Release ,"MbedTLS build type"
+ RMM_PLATFORM ,fvp | host , ,"Platform to build"
+ RMM_TOOLCHAIN ,gnu | llvm , ,"Toolchain name"
+ LOG_LEVEL , ,40 ,"Log level to apply for RMM (0 - 50)"
+ RMM_STATIC_ANALYSIS , , ,"Enable static analysis checkers"
+ RMM_STATIC_ANALYSIS_CPPCHECK ,ON | OFF ,ON ,"Enable Cppcheck static analysis"
+ RMM_STATIC_ANALYSIS_CPPCHECK_CHECKER_CERT_C ,ON | OFF ,ON ,"Enable Cppcheck's SEI CERT C checker"
+ RMM_STATIC_ANALYSIS_CPPCHECK_CHECKER_MISRA ,ON | OFF ,ON ,"Enable Cppcheck's MISRA C:2012 checker"
+ RMM_STATIC_ANALYSIS_CPPCHECK_CHECKER_THREAD_SAFETY ,ON | OFF ,ON ,"Enable Cppcheck's thread safety checker"
+ RMM_UART_ADDR , ,0x0 ,"Base addr of UART to be used for RMM logs"
+ PLAT_CMN_CTX_MAX_XLAT_TABLES , ,0 ,"Maximum number of translation tables used by the runtime context"
+ PLAT_CMN_MAX_MMAP_REGIONS , ,5 ,"Maximum number of mmap regions to be allocated for the platform"
+ RMM_NUM_PAGES_PER_STACK , ,3 ,"Number of pages to use per CPU stack"
+ MBEDTLS_ECP_MAX_OPS ,248 - ,1000 ,"Number of max operations per ECC signing iteration"
+ RMM_FPU_USE_AT_REL2 ,ON | OFF ,OFF(fake_host) ON(aarch64),"Enable FPU/SIMD usage in RMM."
+ RMM_MAX_GRANULES , ,0 ,"Maximum number of memory granules available to the system"
+
+
+
+.. _llvm_build:
+
+################
+RMM LLVM Build
+################
+
+RMM can be built using LLVM Toolchain (Clang). To build using LLVM
+toolchain, set RMM_TOOLCHAIN=llvm during configuration stage.
+
+.. _fake_host_build:
+
+#####################
+RMM Fake Host Build
+#####################
+
+RMM also provides a ``fake_host`` target architecture which allows the code to
+be built natively on the host using the host toolchain. To build for
+``fake_host`` architecture, set RMM_CONFIG=host_defcfg during the
+configuration stage.
diff --git a/docs/getting_started/getting-started.rst b/docs/getting_started/getting-started.rst
new file mode 100644
index 0000000..827c66f
--- /dev/null
+++ b/docs/getting_started/getting-started.rst
@@ -0,0 +1,256 @@
+.. 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"
+ "JRE",">=10.0","Documentation"
+ "plantuml",,"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 default-jre
+ sudo snap install cmake
+ wget https://github.com/plantuml/plantuml/releases/download/v1.2022.7/plantuml-1.2022.7.jar -P <plantuml install path>
+
+.. note::
+
+ platUML and JRE are only required for documentation build.
+
+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 and platUML path into environment:
+
+.. code-block:: bash
+
+ export PATH=<CMake path>/bin:$PATH
+ export PLANTUML_JAR_PATH=<plantuml install path>/plantuml.jar
+
+###########################
+Install python dependencies
+###########################
+
+.. note::
+
+ The installation of Python dependencies is an optional step. This is required only
+ if building documentation.
+
+RMM's ``tools/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 tools/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.
+
+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
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 0000000..b9d1cb3
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+
+Getting Started Guides
+======================
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :numbered:
+
+ getting-started
+ build-options