Merge "fix(spm_mm): do not compile if SVE/SME is enabled" into integration
diff --git a/docs/about/maintainers.rst b/docs/about/maintainers.rst
index 337dde6..7a48601 100644
--- a/docs/about/maintainers.rst
+++ b/docs/about/maintainers.rst
@@ -75,7 +75,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:|M|: Mark Dykes <mark.dykes@arm.com>
:|G|: `mardyk01`_
-:|M|: John Powell <John.Powell@arm.com>
+:|M|: John Powell <john.powell@arm.com>
:|G|: `john-powell-arm`_
:|F|: services/std_svc/sdei/
@@ -105,7 +105,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:|M|: Manish Badarkhe <manish.badarkhe@arm.com>
:|G|: `ManishVB-Arm`_
-:|M|: John Powell <John.Powell@arm.com>
+:|M|: John Powell <john.powell@arm.com>
:|G|: `john-powell-arm`_
:|F|: bl31/ehf.c
@@ -115,7 +115,7 @@
:|G|: `bipinravi-arm`_
:|M|: Mark Dykes <mark.dykes@arm.com>
:|G|: `mardyk01`_
-:|M|: John Powell <John.Powell@arm.com>
+:|M|: John Powell <john.powell@arm.com>
:|G|: `john-powell-arm`_
:|M|: Zelalem Aweke <Zelalem.Aweke@arm.com>
:|G|: `zelalem-aweke`_
@@ -201,7 +201,7 @@
^^^^^^^^^^^^^^^^^
:|M|: Lauren Wehrmeister <Lauren.Wehrmeister@arm.com>
:|G|: `laurenw-arm`_
-:|M|: John Powell <John.Powell@arm.com>
+:|M|: John Powell <john.powell@arm.com>
:|G|: `john-powell-arm`_
:|F|: lib/cpus/
@@ -255,7 +255,7 @@
^^^^^^^^^^^^^^^^^^
:|M|: Alexei Fedorov <Alexei.Fedorov@arm.com>
:|G|: `AlexeiFedorov`_
-:|M|: John Powell <John.Powell@arm.com>
+:|M|: John Powell <john.powell@arm.com>
:|G|: `john-powell-arm`_
:|F|: lib/libc/
@@ -335,6 +335,15 @@
:|F|: include/lib/mpmm/
:|F|: lib/mpmm/
+Granule Protection Tables Library (GPT-RME)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:|M|: Mark Dykes <mark.dykes@arm.com>
+:|G|: `mardyk01`_
+:|M|: John Powell <john.powell@arm.com>
+:|G|: `john-powell-arm`_
+:|F|: lib/gpt_rme
+:|F|: include/lib/gpt_rme
+
Platform Ports
~~~~~~~~~~~~~~
diff --git a/docs/components/granule-protection-tables-design.rst b/docs/components/granule-protection-tables-design.rst
new file mode 100644
index 0000000..07637dd
--- /dev/null
+++ b/docs/components/granule-protection-tables-design.rst
@@ -0,0 +1,235 @@
+Granule Protection Tables Library
+=================================
+
+This document describes the design of the granule protection tables (GPT)
+library used by Trusted Firmware-A (TF-A). This library provides the APIs needed
+to initialize the GPTs based on a data structure containing information about
+the systems memory layout, configure the system registers to enable granule
+protection checks based on these tables, and transition granules between
+different PAS (physical address spaces) at runtime.
+
+Arm CCA adds two new security states for a total of four: root, realm, secure, and
+non-secure. In addition to new security states, corresponding physical address
+spaces have been added to control memory access for each state. The PAS access
+allowed to each security state can be seen in the table below.
+
+.. list-table:: Security states and PAS access rights
+ :widths: 25 25 25 25 25
+ :header-rows: 1
+
+ * -
+ - Root state
+ - Realm state
+ - Secure state
+ - Non-secure state
+ * - Root PAS
+ - yes
+ - no
+ - no
+ - no
+ * - Realm PAS
+ - yes
+ - yes
+ - no
+ - no
+ * - Secure PAS
+ - yes
+ - no
+ - yes
+ - no
+ * - Non-secure PAS
+ - yes
+ - yes
+ - yes
+ - yes
+
+The GPT can function as either a 1 level or 2 level lookup depending on how a
+PAS region is configured. The first step is the level 0 table, each entry in the
+level 0 table controls access to a relatively large region in memory (block
+descriptor), and the entire region can belong to a single PAS when a one step
+mapping is used, or a level 0 entry can link to a level 1 table where relatively
+small regions (granules) of memory can be assigned to different PAS with a 2
+step mapping. The type of mapping used for each PAS is determined by the user
+when setting up the configuration structure.
+
+Design Concepts and Interfaces
+------------------------------
+
+This section covers some important concepts and data structures used in the GPT
+library.
+
+There are three main parameters that determine how the tables are organized and
+function: the PPS (protected physical space) which is the total amount of
+protected physical address space in the system, PGS (physical granule size)
+which is how large each level 1 granule is, and L0GPTSZ (level 0 GPT size) which
+determines how much physical memory is governed by each level 0 entry. A granule
+is the smallest unit of memory that can be independently assigned to a PAS.
+
+L0GPTSZ is determined by the hardware and is read from the GPCCR_EL3 register.
+PPS and PGS are passed into the APIs at runtime and can be determined in
+whatever way is best for a given platform, either through some algorithm or hard
+coded in the firmware.
+
+GPT setup is split into two parts: table creation and runtime initialization. In
+the table creation step, a data structure containing information about the
+desired PAS regions is passed into the library which validates the mappings,
+creates the tables in memory, and enables granule protection checks. In the
+runtime initialization step, the runtime firmware locates the existing tables in
+memory using the GPT register configuration and saves important data to a
+structure used by the granule transition service which will be covered more
+below.
+
+In the reference implementation for FVP models, you can find an example of PAS
+region definitions in the file ``include/plat/arm/common/arm_pas_def.h``. Table
+creation API calls can be found in ``plat/arm/common/arm_bl2_setup.c`` and
+runtime initialization API calls can be seen in
+``plat/arm/common/arm_bl31_setup.c``.
+
+Defining PAS regions
+~~~~~~~~~~~~~~~~~~~~
+
+A ``pas_region_t`` structure is a way to represent a physical address space and
+its attributes that can be used by the GPT library to initialize the tables.
+
+This structure is composed of the following:
+
+#. The base physical address
+#. The region size
+#. The desired attributes of this memory region (mapping type, PAS type)
+
+See the ``pas_region_t`` type in ``include/lib/gpt_rme/gpt_rme.h``.
+
+The programmer should provide the API with an array containing ``pas_region_t``
+structures, then the library will check the desired memory access layout for
+validity and create tables to implement it.
+
+``pas_region_t`` is a public type, however it is recommended that the macros
+``GPT_MAP_REGION_BLOCK`` and ``GPT_MAP_REGION_GRANULE`` be used to populate
+these structures instead of doing it manually to reduce the risk of future
+compatibility issues. These macros take the base physical address, region size,
+and PAS type as arguments to generate the pas_region_t structure. As the names
+imply, ``GPT_MAP_REGION_BLOCK`` creates a region using only L0 mapping while
+``GPT_MAP_REGION_GRANULE`` creates a region using L0 and L1 mappings.
+
+Level 0 and Level 1 Tables
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The GPT initialization APIs require memory to be passed in for the tables to be
+constructed, ``gpt_init_l0_tables`` takes a memory address and size for building
+the level 0 tables and ``gpt_init_pas_l1_tables`` takes an address and size for
+building the level 1 tables which are linked from level 0 descriptors. The
+tables should have PAS type ``GPT_GPI_ROOT`` and a typical system might place
+its level 0 table in SRAM and its level 1 table(s) in DRAM.
+
+Granule Transition Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Granule Transition Service allows memory mapped with GPT_MAP_REGION_GRANULE
+ownership to be changed using SMC calls. Non-secure granules can be transitioned
+to either realm or secure space, and realm and secure granules can be
+transitioned back to non-secure. This library only allows memory mapped as
+granules to be transitioned, memory mapped as blocks have their GPIs fixed after
+table creation.
+
+Library APIs
+------------
+
+The public APIs and types can be found in ``include/lib/gpt_rme/gpt_rme.h`` and this
+section is intended to provide additional details and clarifications.
+
+To create the GPTs and enable granule protection checks the APIs need to be
+called in the correct order and at the correct time during the system boot
+process.
+
+#. Firmware must enable the MMU.
+#. Firmware must call ``gpt_init_l0_tables`` to initialize the level 0 tables to
+ a default state, that is, initializing all of the L0 descriptors to allow all
+ accesses to all memory. The PPS is provided to this function as an argument.
+#. DDR discovery and initialization by the system, the discovered DDR region(s)
+ are then added to the L1 PAS regions to be initialized in the next step and
+ used by the GTSI at runtime.
+#. Firmware must call ``gpt_init_pas_l1_tables`` with a pointer to an array of
+ ``pas_region_t`` structures containing the desired memory access layout. The
+ PGS is provided to this function as an argument.
+#. Firmware must call ``gpt_enable`` to enable granule protection checks by
+ setting the correct register values.
+#. In systems that make use of the granule transition service, runtime
+ firmware must call ``gpt_runtime_init`` to set up the data structures needed
+ by the GTSI to find the tables and transition granules between PAS types.
+
+API Constraints
+~~~~~~~~~~~~~~~
+
+The values allowed by the API for PPS and PGS are enumerated types
+defined in the file ``include/lib/gpt_rme/gpt_rme.h``.
+
+Allowable values for PPS along with their corresponding size.
+
+* ``GPCCR_PPS_4GB`` (4GB protected space, 0x100000000 bytes)
+* ``GPCCR_PPS_64GB`` (64GB protected space, 0x1000000000 bytes)
+* ``GPCCR_PPS_1TB`` (1TB protected space, 0x10000000000 bytes)
+* ``GPCCR_PPS_4TB`` (4TB protected space, 0x40000000000 bytes)
+* ``GPCCR_PPS_16TB`` (16TB protected space, 0x100000000000 bytes)
+* ``GPCCR_PPS_256TB`` (256TB protected space, 0x1000000000000 bytes)
+* ``GPCCR_PPS_4PB`` (4PB protected space, 0x10000000000000 bytes)
+
+Allowable values for PGS along with their corresponding size.
+
+* ``GPCCR_PGS_4K`` (4KB granules, 0x1000 bytes)
+* ``GPCCR_PGS_16K`` (16KB granules, 0x4000 bytes)
+* ``GPCCR_PGS_64K`` (64KB granules, 0x10000 bytes)
+
+Allowable values for L0GPTSZ along with the corresponding size.
+
+* ``GPCCR_L0GPTSZ_30BITS`` (1GB regions, 0x40000000 bytes)
+* ``GPCCR_L0GPTSZ_34BITS`` (16GB regions, 0x400000000 bytes)
+* ``GPCCR_L0GPTSZ_36BITS`` (64GB regions, 0x1000000000 bytes)
+* ``GPCCR_L0GPTSZ_39BITS`` (512GB regions, 0x8000000000 bytes)
+
+Note that the value of the PPS, PGS, and L0GPTSZ definitions is an encoded value
+corresponding to the size, not the size itself. The decoded hex representations
+of the sizes have been provided for convenience.
+
+The L0 table memory has some constraints that must be taken into account.
+
+* The L0 table must be aligned to either the table size or 4096 bytes, whichever
+ is greater. L0 table size is the total protected space (PPS) divided by the
+ size of each L0 region (L0GPTSZ) multiplied by the size of each L0 descriptor
+ (8 bytes). ((PPS / L0GPTSZ) * 8)
+* The L0 memory size must be greater than or equal to the table size.
+* The L0 memory must fall within a PAS of type GPT_GPI_ROOT.
+
+The L1 memory also has some constraints.
+
+* The L1 tables must be aligned to their size. The size of each L1 table is the
+ size of each L0 region (L0GPTSZ) divided by the granule size (PGS) divided by
+ the granules controlled in each byte (2). ((L0GPTSZ / PGS) / 2)
+* There must be enough L1 memory supplied to build all requested L1 tables.
+* The L1 memory must fall within a PAS of type GPT_GPI_ROOT.
+
+If an invalid combination of parameters is supplied, the APIs will print an
+error message and return a negative value. The return values of APIs should be
+checked to ensure successful configuration.
+
+Sample Calculation for L0 memory size and alignment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let PPS=GPCCR_PPS_4GB and L0GPTSZ=GPCCR_L0GPTSZ_30BITS
+
+We can find the total L0 table size with ((PPS / L0GPTSZ) * 8)
+
+Substitute values to get this: ((0x100000000 / 0x40000000) * 8)
+
+And solve to get 32 bytes. In this case, 4096 is greater than 32, so the L0
+tables must be aligned to 4096 bytes.
+
+Sample calculation for L1 table size and alignment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let PGS=GPCCR_PGS_4K and L0GPTSZ=GPCCR_L0GPTSZ_30BITS
+
+We can find the size of each L1 table with ((L0GPTSZ / PGS) / 2).
+
+Substitute values: ((0x40000000 / 0x1000) / 2)
+
+And solve to get 0x20000 bytes per L1 table.
diff --git a/docs/components/index.rst b/docs/components/index.rst
index 754526d..95fe42c 100644
--- a/docs/components/index.rst
+++ b/docs/components/index.rst
@@ -25,3 +25,4 @@
xlat-tables-lib-v2-design
cot-binding
realm-management-extension
+ granule-protection-tables-design
diff --git a/docs/components/realm-management-extension.rst b/docs/components/realm-management-extension.rst
index 5c580f3..2c4e0b8 100644
--- a/docs/components/realm-management-extension.rst
+++ b/docs/components/realm-management-extension.rst
@@ -4,8 +4,82 @@
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 @@
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 @@
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
****************************************************
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index ef500ff..0831dc0 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -26,6 +26,13 @@
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 @@
--------------
-*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 @@
.. _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
diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst
index 5993d6e..a90ec0b 100644
--- a/docs/getting_started/image-terminology.rst
+++ b/docs/getting_started/image-terminology.rst
@@ -92,6 +92,14 @@
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``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst
index b3758b8..5a4be4d 100644
--- a/docs/getting_started/rt-svc-writers-guide.rst
+++ b/docs/getting_started/rt-svc-writers-guide.rst
@@ -200,13 +200,13 @@
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 @@
--------------
-*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
diff --git a/docs/resources/diagrams/arm-cca-software-arch.png b/docs/resources/diagrams/arm-cca-software-arch.png
new file mode 100755
index 0000000..979e083
--- /dev/null
+++ b/docs/resources/diagrams/arm-cca-software-arch.png
Binary files differ
diff --git a/docs/threat_model/threat_model.rst b/docs/threat_model/threat_model.rst
index 9f26487..4a31e79 100644
--- a/docs/threat_model/threat_model.rst
+++ b/docs/threat_model/threat_model.rst
@@ -6,6 +6,11 @@
************************
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 @@
- 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.
