1.. SPDX-License-Identifier: BSD-3-Clause 2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors. 3 4.. _using_shrinkwrap_with_rmm: 5 6Building with Shrinkwrap 7************************ 8 9This document explains how to build and run |RMM| in |FVP|, including all 10necessary firmware images, by using `Shrinkwrap`_. 11 12Introduction 13____________ 14 15`Shrinkwrap`_ is a tool that helps to simplify the process of building and 16running firmware on Arm |FVP| by providing an intuitive command line interface 17frontend and (by default) a container-based backend. 18 19Shrinkwrap works by using *configs*, which are defined in YAML and can be easily 20extended using a built-in layering system. 21 22For instructions on how to setup Shrinkwrap on your local machine as well as for 23further information, you can refer to the `Quick Start Guide`_. In particular, 24for development with RME enabled Linux in Normal World, please refer to the 25`3 world configuration`_. In case that the Secure World also needs to be 26included, please refer to the `4 world configuration`_ 27 28Setup local RMM with Shrinkwrap 29_______________________________ 30 31This section assumes that you have your local |RMM| repository cloned 32and that it is used for your development. In order to help using 33Shrinkwrap with your development workflow, the project provides some 34configs and overlays. 35 36Also, from now on, it is assumed that your current directory (pointed by 37``${PWD}``) is the root of your |RMM| development repository. 38 39In order to use the configs defined in |RMM|, it is essential to configure 40the ``${SHRINKWRAP_CONFIG}`` environment variable to point to 41``${PWD}/tools/shrinkwrap/configs`` directory so the tool can locate the 42config yaml files. 43 44 .. code-block:: shell 45 46 export SHRINKWRAP_CONFIG=${PWD}/tools/shrinkwrap/configs 47 48It is also recommended to override the default ``${SHRINKWRAP_BUILD}`` and 49``${SHRINKWRAP_PACKAGE}`` environment variables to a known workspace directory, 50as shown below: 51 52 .. code-block:: shell 53 54 export WORKSPACE=${HOME}/workspace 55 export SHRINKWRAP_BUILD=${WORKSPACE} 56 export SHRINKWRAP_PACKAGE=${SHRINKWRAP_BUILD}/package 57 58When building, Shrinkwrap will store the sources inside 59``${SHRINKWRAP_BUILD}/source/<CONFIG_NAME>`` and the build artifacts and 60packages will be stored inside ``${SHRINKWRAP_BUILD}/build/<CONFIG_NAME>`` and 61``${SHRINKWRAP_PACKAGE}/<CONFIG_NAME>`` directories respectively. 62 63.. note:: 64 65 By default, if ${SHRINKWRAP_BUILD} and ${SHRINKWRAP_PACKAGE} are not 66 specified, Shrinkwrap will use the ``${HOME}/.shrinkwrap`` as default 67 value for ${SHRINKWRAP_BUILD}. It is only necessary to overwrite the 68 environment variables in the case it is needed to build in a different 69 location. 70 71.. _3_world_testing: 72 733-World testing 74_______________ 75 76|RMM| provides a number of overlays that can be used in conjunction with some 77of the configs provided by Shrinkwrap. One of the overlays, specifically 78``rmm.yaml``, can be used along with the ``cca-3world.yaml`` to 79build a 3 World demonstrator using the ``master`` branch of |TF-A| and the 80local |RMM| repository. 81 82As an example, the following command line would build the 3-World demonstrator. 83It assumes that Shrinkwrap is called from within the ``<RMM_ROOT>`` directory: 84 85 .. code-block:: shell 86 87 shrinkwrap build cca-3world.yaml --overlay=buildroot.yaml --overlay=rmm.yaml --btvar=GUEST_ROOTFS='${artifact:BUILDROOT}' --btvar=RMM_SRC=${PWD} --no-sync=rmm 88 89You can find further instructions on how to build and package the filesystem 90and required binaries in the `3 world configuration`_ documentation. 91 92To run the demonstrator, use the following command: 93 94 .. code-block:: shell 95 96 shrinkwrap run cca-3world.yaml --rtvar=ROOTFS=${SHRINKWRAP_PACKAGE}/cca-3world/rootfs.ext2 97 98Testing RMM with TFTF 99_____________________ 100 101|RMM| provides a config that brings together a software stack to test |RMM| 102and Arm RME extension utilizing `TF-A-Tests`_. The main Test payload in 103TF-A-Tests is the |TFTF| binary. In this config, |TF-A| is in Root World, |RMM| 104is in Realm EL2 and |TFTF| is in Normal World. 105 106In order to build the config, you need to run the following command: 107 108 .. code-block:: shell 109 110 shrinkwrap build --btvar=RMM_SRC=${PWD} rmm-tftf.yaml --no-sync=rmm 111 112and you can run it through 113 114 .. code-block:: shell 115 116 shrinkwrap run rmm-tftf.yaml 117 118For further documentation about this configuration, you can check the docs through 119 120 .. code-block:: shell 121 122 shrinkwrap inspect rmm-tftf.yaml 123 124The build and run commands can also be found in the documentation of the config 125yaml file. When invoking the ``build`` command, Shrinkwrap will store the 126external repositories inside the ``${SHRINKWRAP_BUILD}/sources/<CONFIG_NAME>`` 127directory. 128 129Overlays 130________ 131 132Overlays can be used to extend the functionality of a config by overwriting 133both build and runtime settings. They can be used on any configuration and they 134can be combined in any way needed. 135 136In order to use an overlay, they need to be specified on the command line, through 137the ``--overlay`` keyword, as follows: 138 139 .. code-block:: shell 140 141 shrinkwrap build rmm-tftf.yaml --btvar=RMM_SRC=${PWD} --overlay=<OVERLAY_FILE_NAME> --no-sync=rmm 142 143The path to the overlay can be relative to where Shrinkwrap is called from and you 144can use as many ``--overlay`` statements as needed. 145 146Overlays are stored in the ``<RMM_ROOT_DIR>/tools/shrinkwrap/configs/`` directory, 147alongside with the configuration files. 148 149The available Overlays are sumarized in the next table 150 151.. csv-table:: 152 :header: "Overlay", "Description" 153 :widths: 2 8 154 155 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 156 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 157 rmm-debug.yaml,Overlay to build |RMM| (as well as |TF-A|) in debug mode 158 rmm-v1_1.yaml,Overlay to build |RMM| with v1.1 features 159 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| 160 161Example of use 162~~~~~~~~~~~~~~ 163 164Below is an example on how to use one of the available overlays with the 165existing configuration. The example specifies ``--runtime=null`` to use the 166native toolchain (without the Docker container) to build the artifacts and 167``--no-sync-all`` to prevent Shrinkwrap from updating/cleaning any of the 168repositories: 169 170 .. code-block:: shell 171 172 shrinkwrap --runtime=null build rmm-tftf.yaml --overlay=model-enable-lpa2.yaml --btvar=RMM_SRC=${PWD} --no-sync-all 173 174Similarly you can use overlay rmm-v1_1.yaml to enable RMM v1.1 features along 175with rmm-debug.yaml to enable debug build. 176 177 .. code-block:: shell 178 179 shrinkwrap --runtime=null build rmm-tftf.yaml --overlay=rmm-v1_1.yaml --overlay=rmm-debug.yaml --btvar=RMM_SRC=${PWD} --no-sync-all 180 181Then you run your tests with 182 183 .. code-block:: shell 184 185 shrinkwrap --runtime=null run rmm-tftf.yaml 186 187.. note:: 188 189 Note that ``runtime=null`` is specified for the run, as it must match 190 the same setting as used on the build stage. Also, with this setting, 191 the appropriate FVP (FVP_Base_RevC-2xAEMvA) needs to be present in the 192 system ${PATH}. 193 194 FVP version must be >= ``11.29.27`` when rmm-v1_1.yaml overlay is used. 195 196----- 197 198.. _Shrinkwrap: https://shrinkwrap.docs.arm.com 199.. _Quick Start Guide: https://shrinkwrap.docs.arm.com/en/latest/userguide/quickstart.html#quick-start-guide 200.. _3 world configuration: https://shrinkwrap.docs.arm.com/en/latest/userguide/configstore/cca-3world.html 201.. _4 world configuration: https://shrinkwrap.docs.arm.com/en/latest/userguide/configstore/cca-4world.html 202.. _TF-A-Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest/index.html 203.. _btvar: https://shrinkwrap.docs.arm.com/en/latest/userguide/configmodel.html#defined-macros 204.. _rtvar: https://shrinkwrap.docs.arm.com/en/latest/userguide/configmodel.html#defined-macros 205