1Hafnium Tests 2============= 3 4This guide explains how to build and run Hafnium tests on the Arm |FVP|, including 5all necessary other firmware images, by using `Shrinkwrap`_. 6These tests include Hafnium itself, as well as supporting components like TF-A, 7secure partitions, and test payloads such as TFTF. 8 9Overview of Shrinkwrap for Hafnium Testing 10------------------------------------------ 11 12Shrinkwrap is a tool that makes it easier to build and run firmware on Arm FVP. 13It provides a user-friendly command-line interface and, by default, uses a 14container-based backend to manage the build environment. 15It uses YAML-based configuration files to describe platform topology, firmware 16components, and runtime parameters. These configurations can be easily customized 17and extended through a built-in layering system. 18 19For further detailed information on the Shrinkwrap tool, including its design and usage, 20refer to the `Quick Start Guide`_. 21 22Shrinkwrap Integration in hftest.py 23----------------------------------- 24 25Shrinkwrap is included in the Hafnium repository as a Git submodule at 26``third_party/shrinkwrap``. 27 28For test execution, all Shrinkwrap setup is handled internally by the 29Hafnium test framework. The `hftest.py` script uses a helper class 30(``ShrinkwrapManager``) to configure paths, generate overlays, and run 31Shrinkwrap commands for each test. 32 33Manual configuration of environment variables or setup scripts is not 34required. The `hftest.py` framework handles Shrinkwrap setup automatically in all 35environments, including local development, Docker, and CI. 36 37To run Hafnium tests configured through the ``kokoro/`` test scripts, use the 38following predefined Makefile targets: 39 40.. code:: shell 41 42 make test_spmc # Runs the SPMC test suite 43 make test_el3_spmc # Runs the EL3 SPMC test suite 44 45These workflows are supported across local development, CI pipelines, and the 46Hafnium Docker container provided under ``build/docker/``. 47 48These targets invoke test scripts under `kokoro/` directory, which then invokes 49`hftest.py` with the appropriate configuration. Shrinkwrap is used under the 50hood to build the FVP package and launch tests using both static and dynamic overlays. 51 52For example: 53- ``kokoro/test_spmc.sh`` runs tests for Secure Partition Manager Component (SPMC) at S-EL1. 54- ``kokoro/test_el3_spmc.sh`` runs tests for EL3-based SPMC setups (e.g., Hafnium at EL3). 55 56 57Manual Shrinkwrap Environment Setup 58----------------------------------- 59 60If you intend to use Shrinkwrap manually, outside of `hftest.py` framework, you 61can configure the environment using the following script: 62 63.. code:: shell 64 65 source ./tools/shrinkwrap/shrinkwrap_setup_env.sh 66 67This script prepares the environment by: 68 69- Adding the Shrinkwrap CLI binary to your ``PATH`` 70- Setting ``SHRINKWRAP_CONFIG`` to point to Hafnium’s overlay configs 71- Setting ``SHRINKWRAP_BUILD`` and ``SHRINKWRAP_PACKAGE`` as the output directories for build artifacts 72 73.. note:: 74 75 By default, if ${SHRINKWRAP_BUILD} and ${SHRINKWRAP_PACKAGE} are not set, 76 Shrinkwrap uses ``${HOME}/.shrinkwrap`` as its default output directory. 77 However, the provided setup script ``shrinkwrap_setup_env.sh`` overrides that 78 and places the build/package outputs under ``out/`` folder in the Hafnium 79 repository. You can modify these paths if needed. 80 81Shrinkwrap at the Core of the hftest Framework 82---------------------------------------------- 83 84The ``hftest`` Python framework now leverages `Shrinkwrap`_ to handle model 85configuration and runtime arguments for FVP-based Hafnium tests. 86This integration replaces manual argument generation with modular and declarative 87YAML configurations, enhancing both clarity and maintainability. 88 89All Shrinkwrap-related functionality is handled internally by the 90``ShrinkwrapManager`` utility, which abstracts away the complexity of manual 91setup and execution. 92 93The ``ShrinkwrapManager`` utility is responsible for: 94 95* Setting up the Shrinkwrap environment (e.g., config paths, build directories) 96* Generating the dynamic overlay. 97* Running the Shrinkwrap build phase once, using static overlays. 98* Running the Shrinkwrap run phase individually for each test, with the appropriate dynamic overlay. 99 100Overlay Structure 101~~~~~~~~~~~~~~~~~ 102 103Overlays are an important concept in Shrinkwrap. They are configuration fragments 104(typically YAML files) that are layered on top of a base configuration—either 105during the build or run phase to compose, reuse, or override configuration logic 106without duplicating YAML files. Overlays are always applied as the topmost layer 107in the configuration stack, and can also be passed dynamically at runtime using 108the ``--overlay`` command-line flag to selectively modify or extend existing setups 109without altering the original configuration. 110 111In the context of Hafnium's ``hftest.py`` integration with Shrinkwrap, overlays 112are applied in the following way: 113 114- **Static Overlays**: 115 116 - Define reusable FVP-related configurations such as hypervisor preloading, 117 SPMC artifact addresses, debug flags, etc. 118 - Each test driver (e.g., `FvpDriverHypervisor`, `FvpDriverSPMC`, `FvpDriverEL3SPMC`) 119 contributes one or more static overlays. 120 - These are applied during the Shrinkwrap build phase and reside under: 121 ``tools/shrinkwrap/configs/kokoro/`` 122 123 - Example overlays: 124 125 - ``fvp_hf_hypervisor_preloaded.yaml`` 126 - ``fvp_hf_spmc_preloaded.yaml`` 127 - ``fvp_hf_debug.yaml`` (conditionally applied) 128 129- **Dynamic Overlay**: 130 131 - Automatically generated by ``hftest.py`` at runtime. 132 - Applied during the **Shrinkwrap run phase** using: ``fvp_hf_dynamic_overlay.yaml`` 133 134- **Overlay Layering in Practice**: 135 136 - Common FVP platform settings are defined in the base YAML: 137 ``FVP_Base_RevC-2xAEMvA-hafnium.yaml`` 138 - Static overlays provided by the test driver are layered **on top** of this 139 base during the ``shrinkwrap build`` phase. 140 - The dynamic overlay is layered **last**, during the ``shrinkwrap run`` phase, 141 and contains runtime values such as UART log paths, memory load addresses, 142 or test-specific artifacts. 143 144This overlay-based design promotes clean separation between reusable 145infrastructure setup and per-test dynamic inputs. It improves configurability, 146test maintenance, and makes it easy to add new test targets without repeating 147model configuration. 148 149Testing Hafnium with TFTF 150------------------------- 151 152Outside of the Hafnium test framework (`hftest.py`), developers can use a standalone 153Shrinkwrap configuration ``hafnium-tftf.yaml`` to build and run the full 154Hafnium software stack. This configuration is designed to support day-to-day 155integration testing of Hafnium alongside `TF-A`_ and `TF-A-Tests`_. 156 157The primary test payload from TF-A-Tests is the TFTF (Trusted Firmware Test 158Framework) binary. The test setup also deploys the Cactus and Ivy secure partitions 159to validate FF-A-based SPM functionality. 160 161In this setup: 162 163- TF-A runs at EL3 164- Hafnium runs at Secure EL2 165- Cactus and Ivy SPs (Secure Partitions) run at S-EL1 166- TFTF runs in the Normal World 167 168This configuration is ideal for validating SPMC behavior, FF-A interface support, 169and overall system integration. 170 171Hafnium provides dedicated Makefile targets to build and run the ``hafnium-tftf.yaml`` 172configuration using Shrinkwrap: 173 174.. code:: shell 175 176 make test_tftf # Builds and runs the full configuration 177 make test_tftf_build # Only performs the Shrinkwrap build phase 178 make test_tftf_run # Runs the configuration on FVP after building 179 make test_tftf_clean # Cleans previously built Shrinkwrap artifacts 180 181When ``HAFNIUM_HERMETIC_BUILD=true`` is set, the above targets are executed inside 182the Hafnium developer Docker container (``build/docker/``), with all dependencies 183and the runtime environment preconfigured. 184 185These targets invoke corresponding rules from the ``kokoro.mk`` which run 186``shrinkwrap build`` and ``shrinkwrap run`` using the ``hafnium-tftf.yaml`` 187configuration and its associated overlays. 188 189The build and run commands are also documented in detail within the corresponding 190YAML configuration file. When you run the build command, Shrinkwrap stores external 191repositories under the ``${SHRINKWRAP_BUILD}/sources/<CONFIG_NAME>`` directory. 192 193By using the ``hafnium-tftf.yaml`` custom configuration file, developers can 194easily build and run SPM-related test suites through Shrinkwrap. 195 196*Copyright (c) 2025, Arm Limited. All rights reserved.* 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.. _TF-A: https://trustedfirmware-a.readthedocs.io/en/latest/ 201.. _TF-A-Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest/index.html 202