Hafnium Tests ============= This guide explains how to build and run Hafnium tests on the Arm |FVP|, including all necessary other firmware images, by using `Shrinkwrap`_. These tests include Hafnium itself, as well as supporting components like TF-A, secure partitions, and test payloads such as TFTF. Overview of Shrinkwrap for Hafnium Testing ------------------------------------------ Shrinkwrap is a tool that makes it easier to build and run firmware on Arm FVP. It provides a user-friendly command-line interface and, by default, uses a container-based backend to manage the build environment. It uses YAML-based configuration files to describe platform topology, firmware components, and runtime parameters. These configurations can be easily customized and extended through a built-in layering system. For further detailed information on the Shrinkwrap tool, including its design and usage, refer to the `Quick Start Guide`_. Shrinkwrap Integration in hftest.py ----------------------------------- Shrinkwrap is included in the Hafnium repository as a Git submodule at ``third_party/shrinkwrap``. For test execution, all Shrinkwrap setup is handled internally by the Hafnium test framework. The `hftest.py` script uses a helper class (``ShrinkwrapManager``) to configure paths, generate overlays, and run Shrinkwrap commands for each test. Manual configuration of environment variables or setup scripts is not required. The `hftest.py` framework handles Shrinkwrap setup automatically in all environments, including local development, Docker, and CI. To run Hafnium tests configured through the ``kokoro/`` test scripts, use the following predefined Makefile targets: .. code:: shell make test_spmc # Runs the SPMC test suite make test_el3_spmc # Runs the EL3 SPMC test suite These workflows are supported across local development, CI pipelines, and the Hafnium Docker container provided under ``build/docker/``. These targets invoke test scripts under `kokoro/` directory, which then invokes `hftest.py` with the appropriate configuration. Shrinkwrap is used under the hood to build the FVP package and launch tests using both static and dynamic overlays. For example: - ``kokoro/test_spmc.sh`` runs tests for Secure Partition Manager Component (SPMC) at S-EL1. - ``kokoro/test_el3_spmc.sh`` runs tests for EL3-based SPMC setups (e.g., Hafnium at EL3). Manual Shrinkwrap Environment Setup ----------------------------------- If you intend to use Shrinkwrap manually, outside of `hftest.py` framework, you can configure the environment using the following script: .. code:: shell source ./tools/shrinkwrap/shrinkwrap_setup_env.sh This script prepares the environment by: - Adding the Shrinkwrap CLI binary to your ``PATH`` - Setting ``SHRINKWRAP_CONFIG`` to point to Hafnium’s overlay configs - Setting ``SHRINKWRAP_BUILD`` and ``SHRINKWRAP_PACKAGE`` as the output directories for build artifacts .. note:: By default, if ${SHRINKWRAP_BUILD} and ${SHRINKWRAP_PACKAGE} are not set, Shrinkwrap uses ``${HOME}/.shrinkwrap`` as its default output directory. However, the provided setup script ``shrinkwrap_setup_env.sh`` overrides that and places the build/package outputs under ``out/`` folder in the Hafnium repository. You can modify these paths if needed. Shrinkwrap at the Core of the hftest Framework ---------------------------------------------- The ``hftest`` Python framework now leverages `Shrinkwrap`_ to handle model configuration and runtime arguments for FVP-based Hafnium tests. This integration replaces manual argument generation with modular and declarative YAML configurations, enhancing both clarity and maintainability. All Shrinkwrap-related functionality is handled internally by the ``ShrinkwrapManager`` utility, which abstracts away the complexity of manual setup and execution. The ``ShrinkwrapManager`` utility is responsible for: * Setting up the Shrinkwrap environment (e.g., config paths, build directories) * Generating the dynamic overlay. * Running the Shrinkwrap build phase once, using static overlays. * Running the Shrinkwrap run phase individually for each test, with the appropriate dynamic overlay. Overlay Structure ~~~~~~~~~~~~~~~~~ Overlays are an important concept in Shrinkwrap. They are configuration fragments (typically YAML files) that are layered on top of a base configuration—either during the build or run phase to compose, reuse, or override configuration logic without duplicating YAML files. Overlays are always applied as the topmost layer in the configuration stack, and can also be passed dynamically at runtime using the ``--overlay`` command-line flag to selectively modify or extend existing setups without altering the original configuration. In the context of Hafnium's ``hftest.py`` integration with Shrinkwrap, overlays are applied in the following way: - **Static Overlays**: - Define reusable FVP-related configurations such as hypervisor preloading, SPMC artifact addresses, debug flags, etc. - Each test driver (e.g., `FvpDriverHypervisor`, `FvpDriverSPMC`, `FvpDriverEL3SPMC`) contributes one or more static overlays. - These are applied during the Shrinkwrap build phase and reside under: ``tools/shrinkwrap/configs/kokoro/`` - Example overlays: - ``fvp_hf_hypervisor_preloaded.yaml`` - ``fvp_hf_spmc_preloaded.yaml`` - ``fvp_hf_debug.yaml`` (conditionally applied) - **Dynamic Overlay**: - Automatically generated by ``hftest.py`` at runtime. - Applied during the **Shrinkwrap run phase** using: ``fvp_hf_dynamic_overlay.yaml`` - **Overlay Layering in Practice**: - Common FVP platform settings are defined in the base YAML: ``FVP_Base_RevC-2xAEMvA-hafnium.yaml`` - Static overlays provided by the test driver are layered **on top** of this base during the ``shrinkwrap build`` phase. - The dynamic overlay is layered **last**, during the ``shrinkwrap run`` phase, and contains runtime values such as UART log paths, memory load addresses, or test-specific artifacts. This overlay-based design promotes clean separation between reusable infrastructure setup and per-test dynamic inputs. It improves configurability, test maintenance, and makes it easy to add new test targets without repeating model configuration. Testing Hafnium with TFTF ------------------------- Outside of the Hafnium test framework (`hftest.py`), developers can use a standalone Shrinkwrap configuration ``hafnium-tftf.yaml`` to build and run the full Hafnium software stack. This configuration is designed to support day-to-day integration testing of Hafnium alongside `TF-A`_ and `TF-A-Tests`_. The primary test payload from TF-A-Tests is the TFTF (Trusted Firmware Test Framework) binary. The test setup also deploys the Cactus and Ivy secure partitions to validate FF-A-based SPM functionality. In this setup: - TF-A runs at EL3 - Hafnium runs at Secure EL2 - Cactus and Ivy SPs (Secure Partitions) run at S-EL1 - TFTF runs in the Normal World This configuration is ideal for validating SPMC behavior, FF-A interface support, and overall system integration. Hafnium provides dedicated Makefile targets to build and run the ``hafnium-tftf.yaml`` configuration using Shrinkwrap: .. code:: shell make test_tftf # Builds and runs the full configuration make test_tftf_build # Only performs the Shrinkwrap build phase make test_tftf_run # Runs the configuration on FVP after building make test_tftf_clean # Cleans previously built Shrinkwrap artifacts When ``HAFNIUM_HERMETIC_BUILD=true`` is set, the above targets are executed inside the Hafnium developer Docker container (``build/docker/``), with all dependencies and the runtime environment preconfigured. These targets invoke corresponding rules from the ``kokoro.mk`` which run ``shrinkwrap build`` and ``shrinkwrap run`` using the ``hafnium-tftf.yaml`` configuration and its associated overlays. The build and run commands are also documented in detail within the corresponding YAML configuration file. When you run the build command, Shrinkwrap stores external repositories under the ``${SHRINKWRAP_BUILD}/sources/`` directory. By using the ``hafnium-tftf.yaml`` custom configuration file, developers can easily build and run SPM-related test suites through Shrinkwrap. *Copyright (c) 2025, Arm Limited. All rights reserved.* .. _Shrinkwrap: https://shrinkwrap.docs.arm.com .. _Quick Start Guide: https://shrinkwrap.docs.arm.com/en/latest/userguide/quickstart.html#quick-start-guide .. _TF-A: https://trustedfirmware-a.readthedocs.io/en/latest/ .. _TF-A-Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest/index.html