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 76There is a contract between RMM and RMMD that defines the arguments that the 77former needs to take in order to initialize and also the possible return values. 78This contract is defined in the RMM Boot Interface, which can be found at 79:ref:`rmm_el3_boot_interface`. 80 81There is also a specification of the runtime services provided by TF-A 82to RMM. This can be found at :ref:`runtime_services_and_interface`. 83 84Test Realm Payload (TRP) 85************************* 86TRP is a small test payload that runs at R-EL2 and implements a subset of 87the Realm Management Interface (RMI) commands to primarily test EL3 firmware 88and the interface between R-EL2 and EL3. When building TF-A with RME enabled, 89if a path to an RMM image is not provided, TF-A builds the TRP by default 90and uses it as RMM image. 91 92Building and running TF-A with RME 93------------------------------------ 94 95This section describes how you can build and run TF-A with RME enabled. 96We assume you have all the :ref:`Prerequisites` to build TF-A. 97 98To enable RME, you need to set the ENABLE_RME build flag when building 99TF-A. Currently, this feature is only supported for the FVP platform. 100 101The following instructions show you how to build and run TF-A with RME 102for two scenarios: TF-A with TF-A Tests, and four-world execution with 103Hafnium and TF-A Tests. The instructions assume you have already obtained 104TF-A. You can use the following command to clone TF-A. 105 106.. code:: shell 107 108 git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 109 110To run the tests, you need an FVP model. Please use the :ref:`latest version 111<Arm Fixed Virtual Platforms (FVP)>` of *FVP_Base_RevC-2xAEMvA* model. 112 113.. note:: 114 115 ENABLE_RME build option is currently experimental. 116 117Building TF-A with TF-A Tests 118******************************************** 119Use the following instructions to build TF-A with `TF-A Tests`_ as the 120non-secure payload (BL33). 121 122**1. Obtain and build TF-A Tests** 123 124.. code:: shell 125 126 git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git 127 cd tf-a-tests 128 make CROSS_COMPILE=aarch64-none-elf- PLAT=fvp DEBUG=1 129 130This produces a TF-A Tests binary (*tftf.bin*) in the *build/fvp/debug* directory. 131 132**2. Build TF-A** 133 134.. code:: shell 135 136 cd trusted-firmware-a 137 make CROSS_COMPILE=aarch64-none-elf- \ 138 PLAT=fvp \ 139 ENABLE_RME=1 \ 140 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ 141 DEBUG=1 \ 142 BL33=<path/to/tftf.bin> \ 143 all fip 144 145This produces *bl1.bin* and *fip.bin* binaries in the *build/fvp/debug* directory. 146The above command also builds TRP. The TRP binary is packaged in *fip.bin*. 147 148Four-world execution with Hafnium and TF-A Tests 149**************************************************** 150Four-world execution involves software components at each security state: root, 151secure, realm and non-secure. This section describes how to build TF-A 152with four-world support. We use TF-A as the root firmware, `Hafnium`_ as the 153secure component, TRP as the realm-world firmware and TF-A Tests as the 154non-secure payload. 155 156Before building TF-A, you first need to build the other software components. 157You can find instructions on how to get and build TF-A Tests above. 158 159**1. Obtain and build Hafnium** 160 161.. code:: shell 162 163 git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git 164 cd hafnium 165 # Use the default prebuilt LLVM/clang toolchain 166 PATH=$PWD/prebuilts/linux-x64/clang/bin:$PWD/prebuilts/linux-x64/dtc:$PATH 167 make PROJECT=reference 168 169The Hafnium binary should be located at 170*out/reference/secure_aem_v8a_fvp_clang/hafnium.bin* 171 172**2. Build TF-A** 173 174Build TF-A with RME as well as SPM enabled. 175 176.. code:: shell 177 178 make CROSS_COMPILE=aarch64-none-elf- \ 179 PLAT=fvp \ 180 ENABLE_RME=1 \ 181 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ 182 SPD=spmd \ 183 SPMD_SPM_AT_SEL2=1 \ 184 BRANCH_PROTECTION=1 \ 185 CTX_INCLUDE_PAUTH_REGS=1 \ 186 DEBUG=1 \ 187 SP_LAYOUT_FILE=<path/to/tf-a-tests>/build/fvp/debug/sp_layout.json> \ 188 BL32=<path/to/hafnium.bin> \ 189 BL33=<path/to/tftf.bin> \ 190 all fip 191 192Running the tests 193********************* 194Use the following command to run the tests on FVP. TF-A Tests should boot 195and run the default tests including RME tests. 196 197.. code:: shell 198 199 FVP_Base_RevC-2xAEMvA \ 200 -C bp.flashloader0.fname=<path/to/fip.bin> \ 201 -C bp.secureflashloader.fname=<path/to/bl1.bin> \ 202 -C bp.refcounter.non_arch_start_at_default=1 \ 203 -C bp.refcounter.use_real_time=0 \ 204 -C bp.ve_sysregs.exit_on_shutdown=1 \ 205 -C cache_state_modelled=1 \ 206 -C cluster0.NUM_CORES=4 \ 207 -C cluster0.PA_SIZE=48 \ 208 -C cluster0.ecv_support_level=2 \ 209 -C cluster0.gicv3.cpuintf-mmap-access-level=2 \ 210 -C cluster0.gicv3.without-DS-support=1 \ 211 -C cluster0.gicv4.mask-virtual-interrupt=1 \ 212 -C cluster0.has_arm_v8-6=1 \ 213 -C cluster0.has_branch_target_exception=1 \ 214 -C cluster0.has_rme=1 \ 215 -C cluster0.has_rndr=1 \ 216 -C cluster0.has_amu=1 \ 217 -C cluster0.has_v8_7_pmu_extension=2 \ 218 -C cluster0.max_32bit_el=-1 \ 219 -C cluster0.restriction_on_speculative_execution=2 \ 220 -C cluster0.restriction_on_speculative_execution_aarch32=2 \ 221 -C cluster1.NUM_CORES=4 \ 222 -C cluster1.PA_SIZE=48 \ 223 -C cluster1.ecv_support_level=2 \ 224 -C cluster1.gicv3.cpuintf-mmap-access-level=2 \ 225 -C cluster1.gicv3.without-DS-support=1 \ 226 -C cluster1.gicv4.mask-virtual-interrupt=1 \ 227 -C cluster1.has_arm_v8-6=1 \ 228 -C cluster1.has_branch_target_exception=1 \ 229 -C cluster1.has_rme=1 \ 230 -C cluster1.has_rndr=1 \ 231 -C cluster1.has_amu=1 \ 232 -C cluster1.has_v8_7_pmu_extension=2 \ 233 -C cluster1.max_32bit_el=-1 \ 234 -C cluster1.restriction_on_speculative_execution=2 \ 235 -C cluster1.restriction_on_speculative_execution_aarch32=2 \ 236 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 \ 237 -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B \ 238 -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 \ 239 -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 \ 240 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0475 \ 241 -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 \ 242 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 \ 243 -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 \ 244 -C bp.pl011_uart0.out_file=uart0.log \ 245 -C bp.pl011_uart1.out_file=uart1.log \ 246 -C bp.pl011_uart2.out_file=uart2.log \ 247 -C pctl.startup=0.0.0.0 \ 248 -Q 1000 \ 249 "$@" 250 251The bottom of the output from *uart0* should look something like the following. 252 253.. code-block:: shell 254 255 ... 256 257 > Test suite 'FF-A Interrupt' 258 Passed 259 > Test suite 'SMMUv3 tests' 260 Passed 261 > Test suite 'PMU Leakage' 262 Passed 263 > Test suite 'DebugFS' 264 Passed 265 > Test suite 'Realm payload tests' 266 Passed 267 > Test suite 'Invalid memory access' 268 Passed 269 ... 270 271 272.. _Arm Confidential Compute Architecture (Arm CCA): https://www.arm.com/why-arm/architecture/security-features/arm-confidential-compute-architecture 273.. _Arm Architecture Models website: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models 274.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest 275.. _Hafnium: https://www.trustedfirmware.org/projects/hafnium 276
