feat(tools/shrinkwrap): add shrinkwrap configs for RMM
This patch adds a shrinkwrap configuration to build and run RMM TFTF
tests using the current local (or, alternatively, a different one)
RMM repository. The configuration included in this patch can be
found at:
- <RMM_ROOT>/shrinkwrap/configs/rmm-tftf.yaml
In addition to the above configuration, this patch includes the
following overlays, that can be used in any needed combination:
- rmm.yaml
- rmm-debug.yaml
- model-enable-lpa2.yaml
- model-wait-debugger.yaml
- clean.yaml
Of all the above overlays, which are stored on the same directory as
the configuration, the first one is already used by the former
whereas the rest of overlays can be used as needed to test any
particular functionality.
In addition to the presented configuration and overlays, this patch
also adds instructions to the Getting Started guide to build
and run the 3-world CCA demonstrator. This is done by using
the `rmm.yaml` overlay provided in the patch,
so it can be used to test RMM during development.
Signed-off-by: Javier Almansa Sobrino <javier.almansasobrino@arm.com>
Change-Id: I8ccd243d8580ad6ddb4b146674f55c8d6b5b1df9
diff --git a/docs/getting_started/building-with-shrinkwrap.rst b/docs/getting_started/building-with-shrinkwrap.rst
new file mode 100644
index 0000000..6045289
--- /dev/null
+++ b/docs/getting_started/building-with-shrinkwrap.rst
@@ -0,0 +1,194 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+
+.. _using_shrinkwrap_with_rmm:
+
+Building with Shrinkwrap
+************************
+
+This document explains how to build and run |RMM| in |FVP|, including all
+necessary firmware images, by using `Shrinkwrap`_.
+
+Introduction
+____________
+
+`Shrinkwrap`_ is a tool that helps to simplify the process of building and
+running firmware on Arm |FVP| by providing an intuitive command line interface
+frontend and (by default) a container-based backend.
+
+Shrinkwrap works by using *configs*, which are defined in YAML and can be easily
+extended using a built-in layering system.
+
+For instructions on how to setup Shrinkwrap on your local machine as well as for
+further information, you can refer to the `Quick Start Guide`_. In particular,
+for development with RME enabled Linux in Normal World, please refer to the
+`3 world configuration`_. In case that the Secure World also needs to be
+included, please refer to the `4 world configuration`_
+
+Setup local RMM with Shrinkwrap
+_______________________________
+
+This section assumes that you have your local |RMM| repository cloned
+and that it is used for your development. In order to help using
+Shrinkwrap with your development workflow, the project provides some
+configs and overlays.
+
+Also, from now on, it is assumed that your current directory (pointed by
+``${PWD}``) is the root of your |RMM| development repository.
+
+In order to use the configs defined in |RMM|, it is essential to configure
+the ``${SHRINKWRAP_CONFIG}`` environment variable to point to
+``${PWD}/tools/shrinkwrap/configs`` directory so the tool can locate the
+config yaml files.
+
+ .. code-block:: shell
+
+ export SHRINKWRAP_CONFIG=${PWD}/tools/shrinkwrap/configs
+
+It is also recommended to override the default ``${SHRINKWRAP_BUILD}`` and
+``${SHRINKWRAP_PACKAGE}`` environment variables to a known workspace directory,
+as shown below:
+
+ .. code-block:: shell
+
+ export WORKSPACE=${HOME}/workspace
+ export SHRINKWRAP_BUILD=${WORKSPACE}
+ export SHRINKWRAP_PACKAGE=${SHRINKWRAP_BUILD}/package
+
+When building, Shrinkwrap will store the sources inside
+``${SHRINKWRAP_BUILD}/source/<CONFIG_NAME>`` and the build artifacts and
+packages will be stored inside ``${SHRINKWRAP_BUILD}/build/<CONFIG_NAME>`` and
+``${SHRINKWRAP_PACKAGE}/<CONFIG_NAME>`` directories respectively.
+
+.. note::
+
+ By default, if ${SHRINKWRAP_BUILD} and ${SHRINKWRAP_PACKAGE} are not
+ specified, Shrinkwrap will use the ``${HOME}/.shrinkwrap`` as default
+ value for ${SHRINKWRAP_BUILD}. It is only necessary to overwrite the
+ environment variables in the case it is needed to build in a different
+ location.
+
+.. _3_world_testing:
+
+3-World testing
+_______________
+
+|RMM| provides a number of overlays that can be used in conjunction with some
+of the configs provided by Shrinkwrap. One of the overlays, specifically
+``rmm.yaml``, can be used along with the ``cca-3world.yaml`` to
+build a 3 World demonstrator using the ``master`` branch of |TF-A| and the
+local |RMM| repository.
+
+As an example, the following command line would build the 3-World demonstrator.
+It assumes that Shrinkwrap is called from within the ``<RMM_ROOT>`` directory:
+
+ .. code-block:: shell
+
+ shrinkwrap build cca-3world.yaml --overlay=buildroot.yaml --overlay=rmm.yaml --btvar=GUEST_ROOTFS='${artifact:BUILDROOT}' --btvar=RMM_SRC=${PWD} --no-sync=rmm
+
+You can find further instructions on how to build and package the filesystem
+and required binaries in the `3 world configuration`_ documentation.
+
+To run the demonstrator, use the following command:
+
+ .. code-block:: shell
+
+ shrinkwrap run cca-3world.yaml -rtvar=ROOTFS=${SHRINKWRAP_PACKAGE}/cca-3world/rootfs.ext2
+
+Testing RMM with TFTF
+_____________________
+
+|RMM| provides a config that brings together a software stack to test |RMM|
+and Arm RME extension utilizing `TF-A-Tests`_. The main Test payload in
+TF-A-Tests is the |TFTF| binary. In this config, |TF-A| is in Root World, |RMM|
+is in Realm EL2 and |TFTF| is in Normal World.
+
+In order to build the config, you need to run the following command:
+
+ .. code-block:: shell
+
+ shrinkwrap build --btvar=RMM_SRC=${PWD} rmm-tftf.yaml --no-sync=rmm
+
+and you can run it through
+
+ .. code-block:: shell
+
+ shrinkwrap run rmm-tftf.yaml
+
+For further documentation about this configuration, you can check the docs through
+
+ .. code-block:: shell
+
+ shrinkwrap inspect rmm-tftf.yaml
+
+The build and run commands can also be found in the documentation of the config
+yaml file. When invoking the ``build`` command, Shrinkwrap will store the
+external repositories inside the ``${SHRINKWRAP_BUILD}/sources/<CONFIG_NAME>``
+directory.
+
+Overlays
+________
+
+Overlays can be used to extend the functionality of a config by overwriting
+both build and runtime settings. They can be used on any configuration and they
+can be combined in any way needed.
+
+In order to use an overlay, they need to be specified on the command line, through
+the ``--overlay`` keyword, as follows:
+
+ .. code-block:: shell
+
+ shrinkwrap build rmm-tftf.yaml --btvar=RMM_SRC=${PWD} --overlay=<OVERLAY_FILE_NAME> --no-sync=rmm
+
+The path to the overlay can be relative to where Shrinkwrap is called from and you
+can use as many ``--overlay`` statements as needed.
+
+Overlays are stored in the ``<RMM_ROOT_DIR>/tools/shrinkwrap/configs/`` directory,
+alongside with the configuration files.
+
+The available Overlays are sumarized in the next table
+
+.. csv-table::
+ :header: "Overlay", "Description"
+ :widths: 2 8
+
+ model-enable-lpa2.yaml,Overlay used to enable ``FEAT_LPA2`` on the |FVP| model at run time. In addition this overlay also sets the ``PA_SIZE`` on the model to 52
+ model-wait-debugger.yaml,Overlay to configure the |FVP| model to listen for Iris connections on port 7100 and make it wait until a debugger is connected before starting execution
+ rmm-debug.yaml,Overlay to build |RMM| (as well as |TF-A|) in debug mode
+ clean.yaml,Overlay used to avoid an exception with ``Shrinkwrap clean`` in which a path with a valid format needs to be specified for |RMM|
+
+Example of use
+~~~~~~~~~~~~~~
+
+Below is an example on how to use one of the available overlays with the
+existing configuration. The example specifies ``--runtime=null`` to use the
+native toolchain (without the Docker container) to build the artifacts and
+``--no-sync-all`` to prevent Shrinkwrap from updating/cleaning any of the
+repositories:
+
+ .. code-block:: shell
+
+ shrinkwrap --runtime=null build rmm-tftf.yaml --overlay=model-enable-lpa2.yaml --btvar=RMM_SRC=${PWD} --no-sync-all
+
+Then you run your tests with
+
+ .. code-block:: shell
+
+ shrinkwrap --runtime=null run rmm-tftf.yaml
+
+.. note::
+
+ Note that ``runtime=null`` is specified for the run, as it must match
+ the same setting as used on the build stage. Also, with this setting,
+ the appropriate FVP (FVP_Base_RevC-2xAEMvA) needs to be present in the
+ system ${PATH}.
+
+-----
+
+.. _Shrinkwrap: https://shrinkwrap.docs.arm.com
+.. _Quick Start Guide: https://shrinkwrap.docs.arm.com/en/latest/userguide/quickstart.html#quick-start-guide
+.. _3 world configuration: https://shrinkwrap.docs.arm.com/en/latest/userguide/configstore/cca-3world.html
+.. _4 world configuration: https://shrinkwrap.docs.arm.com/en/latest/userguide/configstore/cca-4world.html
+.. _TF-A-Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest/index.html
+.. _btvar: https://shrinkwrap.docs.arm.com/en/latest/userguide/configmodel.html#defined-macros
+.. _rtvar: https://shrinkwrap.docs.arm.com/en/latest/userguide/configmodel.html#defined-macros
diff --git a/docs/getting_started/getting-started.rst b/docs/getting_started/getting-started.rst
index 367b1d6..4b8bfbc 100644
--- a/docs/getting_started/getting-started.rst
+++ b/docs/getting_started/getting-started.rst
@@ -286,10 +286,16 @@
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`_.
+Building all of the involved stack is complicated. We recommend using the
+`Shrinkwrap`_ tooling to bootstrap the stack. For more details on `Shrinkwrap`_
+and utilizing configs and overlays included in |RMM| please refer to
+:ref:`using_shrinkwrap_with_rmm` and, specially for building a demonstrator
+for 3-world, you can refer to :ref:`3_world_testing`.
+
+The |TF-A| documentation also provides some documentation to build |TF-A| and
+other pieces of firmware for RME in `TF-A RME documentation`_. The |RMM| build
+option in |TF-A| should point to the ``rmm.img`` binary generated by building
+|RMM|.
If |RMM| is built for the `fake_host` architecture
(see :ref:`RMM Fake Host Build`), then the generated `rmm.elf` binary can
@@ -305,3 +311,4 @@
.. _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
+.. _Shrinkwrap: https://shrinkwrap.docs.arm.com
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index b9d1cb3..4e808ff 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -10,3 +10,4 @@
getting-started
build-options
+ building-with-shrinkwrap
diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt
index aeac5a3..8e3e344 100644
--- a/docs/global_substitutions.txt
+++ b/docs/global_substitutions.txt
@@ -5,3 +5,5 @@
.. |RD| replace:: :term:`RD`
.. |PAR| replace:: :term:`PAR`
.. |PAS| replace:: :term:`PAS`
+.. |TFTF| replace:: :term:`TFTF`
+.. |FVP| replace:: :term:`FVP`
diff --git a/docs/glossary.rst b/docs/glossary.rst
index ef679b3..38a985d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -51,4 +51,10 @@
VHE
Virtualization Host Extensions
+ TFTF
+ Trusted Firmware Test Framework
+
+ FVP
+ Fixed Virtual Platforms
+
.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
diff --git a/tools/shrinkwrap/configs/clean.yaml b/tools/shrinkwrap/configs/clean.yaml
new file mode 100644
index 0000000..53acfb7
--- /dev/null
+++ b/tools/shrinkwrap/configs/clean.yaml
@@ -0,0 +1,21 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+
+%YAML 1.2
+---
+description: >-
+ Currently, Shrinkwrap has the limitation that it needs to have a non-null path
+ for all repositories in order to be able to clean a given configuration, even
+ if such path is incorrect and/or not needed for the cleaning process.
+
+ rmm.yaml provides a null path for ``RMM_SRC`` btvar, but the clean command
+ does not accept any btvar. Hence, Shrinkwrap clean will fail when invoked for
+ the rmm-tftf.yaml config. This overlay is therefore meant to be used to
+ overwrite the RMM sourcedir path with a dummy path so shrinkwrap clean will
+ pass.
+
+build:
+ rmm:
+ sourcedir: /dev/null
diff --git a/tools/shrinkwrap/configs/model-enable-lpa2.yaml b/tools/shrinkwrap/configs/model-enable-lpa2.yaml
new file mode 100644
index 0000000..90ad0aa
--- /dev/null
+++ b/tools/shrinkwrap/configs/model-enable-lpa2.yaml
@@ -0,0 +1,20 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+
+%YAML 1.2
+---
+description: >-
+ Overlay to enable FEAT_LPA2 on FVP at run time. This overlay also
+ sets the PA_SIZE to 52 bits for all the clusters.
+
+run:
+ params:
+ -C cluster0.has_52bit_address_with_4k: 2
+ -C cluster0.has_large_va: 2
+ -C cluster0.PA_SIZE: 52
+
+ -C cluster1.has_52bit_address_with_4k: 2
+ -C cluster1.has_large_va: 2
+ -C cluster1.PA_SIZE: 52
diff --git a/tools/shrinkwrap/configs/model-wait-debugger.yaml b/tools/shrinkwrap/configs/model-wait-debugger.yaml
new file mode 100644
index 0000000..d16fa80
--- /dev/null
+++ b/tools/shrinkwrap/configs/model-wait-debugger.yaml
@@ -0,0 +1,17 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+
+%YAML 1.2
+---
+description: >-
+ Configures the FVP model to listen for Iris connections on port 7100
+ and makes it wait until a debugger is connected before starting the
+ execution.
+
+run:
+ params:
+ -I :
+ -A :
+ -p :
diff --git a/tools/shrinkwrap/configs/rmm-debug.yaml b/tools/shrinkwrap/configs/rmm-debug.yaml
new file mode 100644
index 0000000..8cc3476
--- /dev/null
+++ b/tools/shrinkwrap/configs/rmm-debug.yaml
@@ -0,0 +1,13 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+
+%YAML 1.2
+---
+description: >-
+ Overlay to build images in Debug mode
+
+layers:
+ - debug/rmm.yaml
+ - debug/tfa.yaml
diff --git a/tools/shrinkwrap/configs/rmm-tftf.yaml b/tools/shrinkwrap/configs/rmm-tftf.yaml
new file mode 100644
index 0000000..1604d16
--- /dev/null
+++ b/tools/shrinkwrap/configs/rmm-tftf.yaml
@@ -0,0 +1,147 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+
+%YAML 1.2
+---
+description: >-
+ This Config Brings together a software stack to test RMM and Arm RME extension
+ utilizing TF-A-Tests. The main Test payload in TF-A-Tests is the TFTF
+ binary. In this config, TF-A is in Root World, TF-RMM is in Realm EL2 and
+ TFTF is in Normal World.
+
+ The Config pulls TF-A and TFTF repositories to the Shrinkwrap working
+ directory (defined through the environment variable ${SHRINKWRAP_BUILD})
+ whilst using the local RMM repository to build specified through the
+ btvar ${RMM_SRC}.
+
+ In order to build TF-RMM with TF-A and TFTF you can invoke the following
+ command:
+
+ .. code-block:: shell
+
+ shrinkwrap build --btvar=RMM_SRC=${PWD} rmm-tftf.yaml --no-sync=rmm
+
+ The command above assumes that shrinkwrap is called from the root directory
+ of your local TF-RMM installation and that ${SHRINKWRAP_CONFIG} has been setup
+ to point to the configs directory in TF-RMM:
+
+ .. code-block:: shell
+
+ export SHRINKWRAP_CONFIG=${PWD}/tools/shrinkwrap/configs
+
+ Note that when building, shrinkwrap will, by default, reset all your repositories,
+ including your local copy of TF-RMM, to their master/main branches, which
+ will cause you to lose any uncommited changes. It is therefore recommended,
+ specially for incremental builds, to always use the ``--no-sync=rmm`` or
+ ``no-sync-all`` options when building to avoid reseting the repositories.
+
+ Once built, you can run your configuration as follows:
+
+ .. code-block:: shell
+
+ shrinkwrap run rmm-tftf.yaml
+
+ If you need to build and run your software stack using your installed native
+ toolchain and model in your host machine, you can do it so by passing
+ --runtime=null to the command line when building and running. Otherwise,
+ Shrinkwrap will download and use the default Docker image containing the
+ the toolchain and FVP. Ensure that the relevant toolchains and FVP are
+ present in the PATH variable.
+
+ In order to clean your workspace, which is recommended when trying to test
+ different configurations, you need to invoke the clean command on Shrinkwrap:
+
+ .. code-block:: shell
+
+ shrinkwrap clean rmm-tftf.yaml --overlay=${PWD}/tools/shrinkwrap/common/layers/clean.yaml
+
+ Note that currently, Shrinkwrap has the limitation that it needs to have a
+ non-null path for all repositories in order to be able to clean a given
+ configuration, even if such path is incorrect and/or not needed for the
+ cleaning process.
+
+ This config allows to tune some of the build and run options by the use of
+ btvar and rtvars respectively. Specifically, it can define the SHA/Branch of
+ the TFTF repository used for the tests by specifying the ``TFTF_REVISION``
+ btvar, which by default points to the ``master`` branch. It also allows
+ to enable Cache Modelling on the FVP model by setting the
+ ``CACHE_MODEL_ENABLED`` rtvar, which by default is ``0`` (disabled).
+
+layers:
+ - tftf-base.yaml
+ - tfa-base.yaml
+ - FVP_Base_RevC-2xAEMvA-base.yaml
+ - rmm.yaml
+
+concrete: true
+
+buildex:
+ btvars:
+ # Determines the branch or SHA to pull for TFTF
+ TFTF_REVISION:
+ type: string
+ value: master
+
+build:
+ tftf:
+ repo:
+ revision: ${btvar:TFTF_REVISION}
+ artifacts:
+ TFTF_BIN: ${param:builddir}/fvp/release/tftf.bin
+ params:
+ TESTS: realm-payload # Include only relevant tests for RMM/RME
+ ENABLE_REALM_PAYLOAD_TESTS: 1
+
+ tfa:
+ params:
+ ENABLE_RME: 1
+ RMM: ${artifact:RMM}
+ BL33: ${artifact:TFTF_BIN}
+
+run:
+ rtvars:
+ BL1:
+ type: path
+ value: ${artifact:BL1}
+
+ FIP:
+ type: path
+ value: ${artifact:FIP}
+
+ CACHE_MODEL_ENABLED:
+ type: string
+ value: 0
+
+ params:
+ # Suppress "WARNING: MPAM_NS is deprecated when RME is in use. Should use MPAM_SP"
+ -C cluster0.output_attributes: ExtendedID[62:55]=MPAM_PMG,ExtendedID[54:39]=MPAM_PARTID,ExtendedID[38:37]=MPAM_SP
+ -C cluster1.output_attributes: ExtendedID[62:55]=MPAM_PMG,ExtendedID[54:39]=MPAM_PARTID,ExtendedID[38:37]=MPAM_SP
+
+ # CCA-specific SMMU settings.
+ -C pci.pci_smmuv3.mmu.SMMU_ROOT_IDR0: 3
+ -C pci.pci_smmuv3.mmu.SMMU_ROOT_IIDR: 0x43B
+ -C pci.pci_smmuv3.mmu.root_register_page_offset: 0x20000
+
+ # Enable FEAT_CSV2_2, which is optional. But TFA 2.10 force-enables it when
+ # ENABLE_RME=1 so if it's not there we see an exception.
+ -C cluster0.restriction_on_speculative_execution: 2
+ -C cluster1.restriction_on_speculative_execution: 2
+ -C cluster0.restriction_on_speculative_execution_aarch32: 2
+ -C cluster1.restriction_on_speculative_execution_aarch32: 2
+
+ # Cache modelling settings
+ -C cache_state_modelled: ${rtvar:CACHE_MODEL_ENABLED}
+
+ -C bp.secureflashloader.fname: ${rtvar:BL1}
+ -C bp.flashloader0.fname: ${rtvar:FIP}
+
+ -C cluster0.rme_support_level: 2
+ -C cluster1.rme_support_level: 2
+
+ terminals:
+ bp.terminal_0:
+ friendly: TF-A
+ bp.terminal_3:
+ friendly: RMM
diff --git a/tools/shrinkwrap/configs/rmm.yaml b/tools/shrinkwrap/configs/rmm.yaml
new file mode 100644
index 0000000..c0ddc4f
--- /dev/null
+++ b/tools/shrinkwrap/configs/rmm.yaml
@@ -0,0 +1,55 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+
+%YAML 1.2
+---
+description: >-
+ Overlay to build TF-RMM with standard build settings.
+ In order to use this overlay, the RMM_SRC btvar must be defined containing
+ the absolute path for the local TF-RMM repository.
+
+ The overlay allows to overwrite the default log level for TF-RMM, by
+ using ``RMM_LOG_LEVEL`` btvar as well as to define the SHA/Branch of TF-A
+ to be used for the particular instance of RMM to build through the
+ ``TFA_REVISION`` btvar. It also allows to define the host platform through
+ the ``RMM_CONFIG`` btvar.
+
+layers:
+ - rmm-base.yaml
+ - arch/v9.2.yaml
+
+buildex:
+ btvars:
+ # Determines where the TF-RMM source root directory is
+ RMM_SRC:
+ type: path
+ value: null
+
+ # Determines the RMM Log level
+ RMM_LOG_LEVEL:
+ type: string
+ value: '40'
+
+ # Determines the RMM Configuration (a.k.a. platform) to build
+ RMM_CONFIG:
+ type: string
+ value: 'fvp_defcfg'
+
+ # Determines the branch or SHA to pull for TF-A which is suitable
+ # for the current RMM
+ TFA_REVISION:
+ type: string
+ value: master
+
+build:
+ rmm:
+ sourcedir: ${btvar:RMM_SRC}
+ params:
+ -DLOG_LEVEL: ${btvar:RMM_LOG_LEVEL}
+ -DRMM_CONFIG: ${btvar:RMM_CONFIG}
+
+ tfa:
+ repo:
+ revision: ${btvar:TFA_REVISION}