1 2Realm Management Extension (RME) 3==================================== 4 5FEAT_RME (or RME for short) is an Armv9-A extension and is one component of the 6`Arm Confidential Compute Architecture (Arm CCA)`_. TF-A supports RME starting 7from version 2.6. This chapter discusses the changes to TF-A to support RME and 8provides instructions on how to build and run TF-A with RME. 9 10RME support in TF-A 11--------------------- 12 13The following diagram shows an Arm CCA software architecture with TF-A as the 14EL3 firmware. In the Arm CCA architecture there are two additional security 15states and address spaces: ``Root`` and ``Realm``. TF-A firmware runs in the 16Root world. In the realm world, a Realm Management Monitor firmware (RMM) 17manages the execution of Realm VMs and their interaction with the hypervisor. 18 19.. image:: ../resources/diagrams/arm-cca-software-arch.png 20 21RME is the hardware extension to support Arm CCA. To support RME, various 22changes have been introduced to TF-A. We discuss those changes below. 23 24Changes to translation tables library 25*************************************** 26RME adds Root and Realm Physical address spaces. To support this, two new 27memory type macros, ``MT_ROOT`` and ``MT_REALM``, have been added to the 28:ref:`Translation (XLAT) Tables Library`. These macros are used to configure 29memory regions as Root or Realm respectively. 30 31.. note:: 32 33 Only version 2 of the translation tables library supports the new memory 34 types. 35 36Changes to context management 37******************************* 38A new CPU context for the Realm world has been added. The existing 39:ref:`CPU context management API<PSCI Library Integration guide for Armv8-A 40AArch32 systems>` can be used to manage Realm context. 41 42Boot flow changes 43******************* 44In a typical TF-A boot flow, BL2 runs at Secure-EL1. However when RME is 45enabled, TF-A runs in the Root world at EL3. Therefore, the boot flow is 46modified to run BL2 at EL3 when RME is enabled. In addition to this, a 47Realm-world firmware (RMM) is loaded by BL2 in the Realm physical address 48space. 49 50The boot flow when RME is enabled looks like the following: 51 521. BL1 loads and executes BL2 at EL3 532. BL2 loads images including RMM 543. BL2 transfers control to BL31 554. BL31 initializes SPM (if SPM is enabled) 565. BL31 initializes RMM 576. BL31 transfers control to Normal-world software 58 59Granule Protection Tables (GPT) library 60***************************************** 61Isolation between the four physical address spaces is enforced by a process 62called Granule Protection Check (GPC) performed by the MMU downstream any 63address translation. GPC makes use of Granule Protection Table (GPT) in the 64Root world that describes the physical address space assignment of every 65page (granule). A GPT library that provides APIs to initialize GPTs and to 66transition granules between different physical address spaces has been added. 67More information about the GPT library can be found in the 68:ref:`Granule Protection Tables Library` chapter. 69 70RMM Dispatcher (RMMD) 71************************ 72RMMD is a new standard runtime service that handles the switch to the Realm 73world. It initializes the RMM and handles Realm Management Interface (RMI) 74SMC calls from Non-secure and Realm worlds. 75 76Test Realm Payload (TRP) 77************************* 78TRP is a small test payload that runs at R-EL2 and implements a subset of 79the Realm Management Interface (RMI) commands to primarily test EL3 firmware 80and the interface between R-EL2 and EL3. When building TF-A with RME enabled, 81if a path to an RMM image is not provided, TF-A builds the TRP by default 82and uses it as RMM image. 83 84Building and running TF-A with RME 85------------------------------------ 86 87This section describes how you can build and run TF-A with RME enabled. 88We assume you have all the :ref:`Prerequisites` to build TF-A. 89 90To enable RME, you need to set the ENABLE_RME build flag when building 91TF-A. Currently, this feature is only supported for the FVP platform. 92 93The following instructions show you how to build and run TF-A with RME 94for two scenarios: TF-A with TF-A Tests, and four-world execution with 95Hafnium and TF-A Tests. The instructions assume you have already obtained 96TF-A. You can use the following command to clone TF-A. 97 98.. code:: shell 99 100 git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 101 102To run the tests, you need an FVP model. Please use the :ref:`latest version 103<Arm Fixed Virtual Platforms (FVP)>` of *FVP_Base_RevC-2xAEMvA* model. 104 105.. note:: 106 107 ENABLE_RME build option is currently experimental. 108 109Building TF-A with TF-A Tests 110******************************************** 111Use the following instructions to build TF-A with `TF-A Tests`_ as the 112non-secure payload (BL33). 113 114**1. Obtain and build TF-A Tests** 115 116.. code:: shell 117 118 git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git 119 cd tf-a-tests 120 make CROSS_COMPILE=aarch64-none-elf- PLAT=fvp DEBUG=1 121 122This produces a TF-A Tests binary (*tftf.bin*) in the *build/fvp/debug* directory. 123 124**2. Build TF-A** 125 126.. code:: shell 127 128 cd trusted-firmware-a 129 make CROSS_COMPILE=aarch64-none-elf- \ 130 PLAT=fvp \ 131 ENABLE_RME=1 \ 132 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ 133 DEBUG=1 \ 134 BL33=<path/to/tftf.bin> \ 135 all fip 136 137This produces *bl1.bin* and *fip.bin* binaries in the *build/fvp/debug* directory. 138The above command also builds TRP. The TRP binary is packaged in *fip.bin*. 139 140Four-world execution with Hafnium and TF-A Tests 141**************************************************** 142Four-world execution involves software components at each security state: root, 143secure, realm and non-secure. This section describes how to build TF-A 144with four-world support. We use TF-A as the root firmware, `Hafnium`_ as the 145secure component, TRP as the realm-world firmware and TF-A Tests as the 146non-secure payload. 147 148Before building TF-A, you first need to build the other software components. 149You can find instructions on how to get and build TF-A Tests above. 150 151**1. Obtain and build Hafnium** 152 153.. code:: shell 154 155 git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git 156 cd hafnium 157 make PROJECT=reference 158 159The Hafnium binary should be located at 160*out/reference/secure_aem_v8a_fvp_clang/hafnium.bin* 161 162**2. Build TF-A** 163 164Build TF-A with RME as well as SPM enabled. 165 166.. code:: shell 167 168 make CROSS_COMPILE=aarch64-none-elf- \ 169 PLAT=fvp \ 170 ENABLE_RME=1 \ 171 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ 172 SPD=spmd \ 173 SPMD_SPM_AT_SEL2=1 \ 174 BRANCH_PROTECTION=1 \ 175 CTX_INCLUDE_PAUTH_REGS=1 \ 176 DEBUG=1 \ 177 SP_LAYOUT_FILE=<path/to/tf-a-tests>/build/fvp/debug/sp_layout.json> \ 178 BL32=<path/to/hafnium.bin> \ 179 BL33=<path/to/tftf.bin> \ 180 all fip 181 182Running the tests 183********************* 184Use the following command to run the tests on FVP. TF-A Tests should boot 185and run the default tests including RME tests. 186 187.. code:: shell 188 189 FVP_Base_RevC-2xAEMvA \ 190 -C bp.flashloader0.fname=<path/to/fip.bin> \ 191 -C bp.secureflashloader.fname=<path/to/bl1.bin> \ 192 -C bp.refcounter.non_arch_start_at_default=1 \ 193 -C bp.refcounter.use_real_time=0 \ 194 -C bp.ve_sysregs.exit_on_shutdown=1 \ 195 -C cache_state_modelled=1 \ 196 -C cluster0.NUM_CORES=4 \ 197 -C cluster0.PA_SIZE=48 \ 198 -C cluster0.ecv_support_level=2 \ 199 -C cluster0.gicv3.cpuintf-mmap-access-level=2 \ 200 -C cluster0.gicv3.without-DS-support=1 \ 201 -C cluster0.gicv4.mask-virtual-interrupt=1 \ 202 -C cluster0.has_arm_v8-6=1 \ 203 -C cluster0.has_branch_target_exception=1 \ 204 -C cluster0.has_rme=1 \ 205 -C cluster0.has_rndr=1 \ 206 -C cluster0.has_amu=1 \ 207 -C cluster0.has_v8_7_pmu_extension=2 \ 208 -C cluster0.max_32bit_el=-1 \ 209 -C cluster0.restriction_on_speculative_execution=2 \ 210 -C cluster0.restriction_on_speculative_execution_aarch32=2 \ 211 -C cluster1.NUM_CORES=4 \ 212 -C cluster1.PA_SIZE=48 \ 213 -C cluster1.ecv_support_level=2 \ 214 -C cluster1.gicv3.cpuintf-mmap-access-level=2 \ 215 -C cluster1.gicv3.without-DS-support=1 \ 216 -C cluster1.gicv4.mask-virtual-interrupt=1 \ 217 -C cluster1.has_arm_v8-6=1 \ 218 -C cluster1.has_branch_target_exception=1 \ 219 -C cluster1.has_rme=1 \ 220 -C cluster1.has_rndr=1 \ 221 -C cluster1.has_amu=1 \ 222 -C cluster1.has_v8_7_pmu_extension=2 \ 223 -C cluster1.max_32bit_el=-1 \ 224 -C cluster1.restriction_on_speculative_execution=2 \ 225 -C cluster1.restriction_on_speculative_execution_aarch32=2 \ 226 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 \ 227 -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B \ 228 -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 \ 229 -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 \ 230 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0475 \ 231 -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 \ 232 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 \ 233 -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 \ 234 -C bp.pl011_uart0.out_file=uart0.log \ 235 -C bp.pl011_uart1.out_file=uart1.log \ 236 -C bp.pl011_uart2.out_file=uart2.log \ 237 -C pctl.startup=0.0.0.0 \ 238 -Q 1000 \ 239 "$@" 240 241The bottom of the output from *uart0* should look something like the following. 242 243.. code-block:: shell 244 245 ... 246 247 > Test suite 'FF-A Interrupt' 248 Passed 249 > Test suite 'SMMUv3 tests' 250 Passed 251 > Test suite 'PMU Leakage' 252 Passed 253 > Test suite 'DebugFS' 254 Passed 255 > Test suite 'Realm payload tests' 256 Passed 257 ... 258 259 260.. _Arm Confidential Compute Architecture (Arm CCA): https://www.arm.com/why-arm/architecture/security-features/arm-confidential-compute-architecture 261.. _Arm Architecture Models website: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models 262.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest 263.. _Hafnium: https://www.trustedfirmware.org/projects/hafnium 264
