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 can be used 39to manage Realm context. 40 41Boot flow changes 42******************* 43In a typical TF-A boot flow, BL2 runs at Secure-EL1. However when RME is 44enabled, TF-A runs in the Root world at EL3. Therefore, the boot flow is 45modified to run BL2 at EL3 when RME is enabled. In addition to this, a 46Realm-world firmware (`RMM`_) is loaded by BL2 in the Realm physical address 47space. 48 49The boot flow when RME is enabled looks like the following: 50 511. BL1 loads and executes BL2 at EL3 522. BL2 loads images including RMM 533. BL2 transfers control to BL31 544. BL31 initializes SPM (if SPM is enabled) 555. BL31 initializes RMM 566. BL31 transfers control to Normal-world software 57 58Granule Protection Tables (GPT) library 59***************************************** 60Isolation between the four physical address spaces is enforced by a process 61called Granule Protection Check (GPC) performed by the MMU downstream any 62address translation. GPC makes use of Granule Protection Table (GPT) in the 63Root world that describes the physical address space assignment of every 64page (granule). A GPT library that provides APIs to initialize GPTs and to 65transition granules between different physical address spaces has been added. 66More information about the GPT library can be found in the 67:ref:`Granule Protection Tables Library` chapter. 68 69RMM Dispatcher (RMMD) 70************************ 71RMMD is a new standard runtime service that handles the switch to the Realm 72world. It initializes the `RMM`_ and handles Realm Management Interface (RMI) 73SMC calls from Non-secure. 74 75There is a contract between `RMM`_ and RMMD that defines the arguments that the 76former needs to take in order to initialize and also the possible return values. 77This contract is defined in the `RMM`_ Boot Interface, which can be found at 78:ref:`rmm_el3_boot_interface`. 79 80There is also a specification of the runtime services provided by TF-A 81to `RMM`_. This can be found at :ref:`runtime_services_and_interface`. 82 83Test Realm Payload (TRP) 84************************* 85TRP is a small test payload that runs at R-EL2 and implements a subset of 86the Realm Management Interface (RMI) commands to primarily test EL3 firmware 87and the interface between R-EL2 and EL3. When building TF-A with RME enabled, 88if the path to an RMM image is not provided, TF-A builds the TRP by default 89and uses it as the R-EL2 payload. 90 91Building and running TF-A with RME 92---------------------------------- 93 94The recommended procedure for building and running an RME enabled reference 95platform is by the use of `Shrinkwrap`_. 96 97The tool offers examples of Three-worlds and Four-worlds configurations for 98running on the *FVP_Base_RevC-2xAEMvA* model. 99 100- Three-world execution: this is the configuration to use if Secure 101 world functionality is not needed. 102 103- Four-world execution: this is the configuration to use if both Secure 104 and Realm world functionality is needed. 105 106TF-A is tested with the following software entities in each world as listed below: 107 108 - NS Host (RME capable Linux), 109 - EL3 Root (TF-A) 110 - R-EL2 (`RMM`_) 111 - S-EL2 (`SPM`_ / Hafnium) in a 4-worlds configuration 112 113Additionally, the TF-RMM project documentation has the specific `Shrinkwrap guide`_. 114 115TF-A CI pipeline includes coverage for building TF-A along with TF-RMM and SPM/Hafnium 116for running 3 worlds and 4 worlds configurations. In those cases, the normal world payload 117and test suite originates from TF-a-tests project. 118 119.. _Arm Confidential Compute Architecture (Arm CCA): https://www.arm.com/why-arm/architecture/security-features/arm-confidential-compute-architecture 120.. _SPM: https://www.trustedfirmware.org/projects/hafnium/ 121.. _RMM: https://www.trustedfirmware.org/projects/tf-rmm/ 122.. _Shrinkwrap: https://shrinkwrap.docs.arm.com/en/latest/ 123.. _Shrinkwrap guide: https://tf-rmm.readthedocs.io/en/latest/getting_started/building-with-shrinkwrap.html 124
