docs(rme): add description of TF-A changes for RME

This patch expands the RME documentation with description of TF-A
changes for RME. It also modifies some other parts of TF-A documentation
to account for RME changes.

Signed-off-by: Zelalem Aweke <zelalem.aweke@arm.com>
Change-Id: I9e6feeee235f0ba4b767d239f15840f1e0c540bb

docs/components/realm-management-extension.rst

@@ -4,8 +4,82 @@ Realm Management Extension (RME)
 
 FEAT_RME (or RME for short) is an Armv9-A extension and is one component of the
 `Arm Confidential Compute Architecture (Arm CCA)`_. TF-A supports RME starting
-from version 2.6. This document provides instructions on how to build and run
-TF-A with RME.
+from version 2.6. This chapter discusses the changes to TF-A to support RME and
+provides instructions on how to build and run TF-A with RME.
+
+RME support in TF-A
+---------------------
+
+The following diagram shows an Arm CCA software architecture with TF-A as the
+EL3 firmware. In the Arm CCA architecture there are two additional security
+states and address spaces: ``Root`` and ``Realm``. TF-A firmware runs in the
+Root world. In the realm world, a Realm Management Monitor firmware (RMM)
+manages the execution of Realm VMs and their interaction with the hypervisor.
+
+.. image:: ../resources/diagrams/arm-cca-software-arch.png
+
+RME is the hardware extension to support Arm CCA. To support RME, various
+changes have been introduced to TF-A. We discuss those changes below.
+
+Changes to translation tables library
+***************************************
+RME adds Root and Realm Physical address spaces. To support this, two new
+memory type macros, ``MT_ROOT`` and ``MT_REALM``, have been added to the
+:ref:`Translation (XLAT) Tables Library`. These macros are used to configure
+memory regions as Root or Realm respectively.
+
+.. note::
+
+ Only version 2 of the translation tables library supports the new memory
+ types.
+
+Changes to context management
+*******************************
+A new CPU context for the Realm world has been added. The existing
+:ref:`CPU context management API<PSCI Library Integration guide for Armv8-A
+AArch32 systems>` can be used to manage Realm context.
+
+Boot flow changes
+*******************
+In a typical TF-A boot flow, BL2 runs at Secure-EL1. However when RME is
+enabled, TF-A runs in the Root world at EL3. Therefore, the boot flow is
+modified to run BL2 at EL3 when RME is enabled. In addition to this, a
+Realm-world firmware (RMM) is loaded by BL2 in the Realm physical address
+space.
+
+The boot flow when RME is enabled looks like the following:
+
+1. BL1 loads and executes BL2 at EL3
+2. BL2 loads images including RMM
+3. BL2 transfers control to BL31
+4. BL31 initializes SPM (if SPM is enabled)
+5. BL31 initializes RMM
+6. BL31 transfers control to Normal-world software
+
+Granule Protection Tables (GPT) library
+*****************************************
+Isolation between the four physical address spaces is enforced by a process
+called Granule Protection Check (GPC) performed by the MMU downstream any
+address translation. GPC makes use of Granule Protection Table (GPT) in the
+Root world that describes the physical address space assignment of every
+page (granule). A GPT library that provides APIs to initialize GPTs and to
+transition granules between different physical address spaces has been added.
+More information about the GPT library can be found in the
+:ref:`Granule Protection Tables Library` chapter.
+
+RMM Dispatcher (RMMD)
+************************
+RMMD is a new standard runtime service that handles the switch to the Realm
+world. It initializes the RMM and handles Realm Management Interface (RMI)
+SMC calls from Non-secure and Realm worlds.
+
+Test Realm Payload (TRP)
+*************************
+TRP is a small test payload that runs at R-EL2 and implements a subset of
+the Realm Management Interface (RMI) commands to primarily test EL3 firmware
+and the interface between R-EL2 and EL3. When building TF-A with RME enabled,
+if a path to an RMM image is not provided, TF-A builds the TRP by default
+and uses it as RMM image.
 
 Building and running TF-A with RME
 ------------------------------------
@@ -25,11 +99,8 @@ TF-A. You can use the following command to clone TF-A.
 
  git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
 
-To run the tests, you need an FVP model. You can download a model that supports
-RME from the `Arm Architecture Models website`_. Please select the
-*Base RevC AEM FVP* model. After extracting the downloaded file, you should be able to
-find the *FVP_Base_RevC-2xAEMvA* binary. The instructions below have been tested
-with model version 11.15 revision 18.
+To run the tests, you need an FVP model. Please use the :ref:`latest version
+<Arm Fixed Virtual Platforms (FVP)>` of *FVP_Base_RevC-2xAEMvA* model.
 
 .. note::
 
@@ -64,9 +135,7 @@ This produces a TF-A Tests binary (*tftf.bin*) in the *build/fvp/debug* director
  all fip
 
 This produces *bl1.bin* and *fip.bin* binaries in the *build/fvp/debug* directory.
-The above command also builds a Test Realm Payload (TRP), which is a small test
-payload that implements Realm Monitor Management (RMM) functionalities and runs
-in the realm world (R-EL2). The TRP binary is packaged in *fip.bin*.
+The above command also builds TRP. The TRP binary is packaged in *fip.bin*.
 
 Four-world execution with Hafnium and TF-A Tests
 ****************************************************

docs/design/firmware-design.rst

@@ -26,6 +26,13 @@ tables. The details of this library can be found in
 
 TF-A can be built to support either AArch64 or AArch32 execution state.
 
+.. note::
+
+ The descriptions in this chapter are for the Arm TrustZone architecture.
+ For changes to the firmware design for the
+ `Arm Confidential Compute Architecture (Arm CCA)`_ please refer to the
+ chapter :ref:`Realm Management Extension (RME)`.
+
 Cold boot
 ---------
 
@@ -2722,7 +2729,7 @@ kernel at boot time. These can be found in the ``fdts`` directory.
 
 --------------
 
-*Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2013-2021, Arm Limited and Contributors. All rights reserved.*
 
 .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _SMCCC: https://developer.arm.com/docs/den0028/latest
@@ -2731,5 +2738,6 @@ kernel at boot time. These can be found in the ``fdts`` directory.
 .. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest
 .. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest
 .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
+.. _Arm Confidential Compute Architecture (Arm CCA): https://www.arm.com/why-arm/architecture/security-features/arm-confidential-compute-architecture
 
 .. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png

docs/getting_started/image-terminology.rst

@@ -92,6 +92,14 @@ In systems where 3rd level images are provided by different vendors, the
 abbreviated name should identify the vendor as well as the image
 function. For example, ``AP_BL3_ARM_RAS``.
 
+Realm Monitor Management Firmware: ``RMM``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the Realm-EL2 firmware. It is required if
+:ref:`Realm Management Extension (RME)` feature is enabled. If a path to RMM
+image is not provided, TF-A builds Test Realm Payload (TRP) image by default
+and uses it as the RMM image.
+
 SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/getting_started/rt-svc-writers-guide.rst

@@ -200,13 +200,13 @@ The handler is responsible for:
        SMC_RET1(handle, SMC_UNK);
 
 #. Determining if the requested function is valid for the calling security
-   state. SMC Calls can be made from both the normal and trusted worlds and
+   state. SMC Calls can be made from Non-secure, Secure or Realm worlds and
    the framework will forward all calls to the service handler.
 
    The ``flags`` parameter to this function indicates the caller security state
-   in bit[0], where a value of ``1`` indicates a non-secure caller. The
-   ``is_caller_secure(flags)`` and ``is_caller_non_secure(flags)`` can be used to
-   test this condition.
+   in bits 0 and 5. The ``is_caller_secure(flags)``, ``is_caller_non_secure(flags)``
+   and ``is_caller_realm(flags)`` helper functions can be used to determine whether
+   the caller's security state is Secure, Non-secure or Realm respectively.
 
    If invalid, the request should be completed with:
 
@@ -314,7 +314,7 @@ provide this information....
 
 --------------
 
-*Copyright (c) 2014-2020, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2014-2021, Arm Limited and Contributors. All rights reserved.*
 
 .. _SMCCC: https://developer.arm.com/docs/den0028/latest
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf

docs/threat_model/threat_model.rst

@@ -6,6 +6,11 @@ Introduction
 ************************
 This document provides a generic threat model for TF-A firmware.
 
+.. note::
+
+ This threat model doesn't consider Root and Realm worlds introduced by
+ :ref:`Realm Management Extension (RME)`.
+
 ************************
 Target of Evaluation
 ************************
@@ -22,8 +27,10 @@ assumptions:
 - All TF-A images are run from either ROM or on-chip trusted SRAM. This means
   TF-A is not vulnerable to an attacker that can probe or tamper with off-chip
   memory.
+
 - Trusted boot is enabled. This means an attacker can't boot arbitrary images
   that are not approved by platform providers.
+
 - There is no Secure-EL2. We don't consider threats that may come with
   Secure-EL2 software.