diff --git a/docs/about/maintainers.rst b/docs/about/maintainers.rst index 337dde617..7a48601b7 100644 --- a/docs/about/maintainers.rst +++ b/docs/about/maintainers.rst @@ -75,7 +75,7 @@ Software Delegated Exception Interface (SDEI) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :|M|: Mark Dykes :|G|: `mardyk01`_ -:|M|: John Powell +:|M|: John Powell :|G|: `john-powell-arm`_ :|F|: services/std_svc/sdei/ @@ -105,7 +105,7 @@ Exception Handling Framework (EHF) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :|M|: Manish Badarkhe :|G|: `ManishVB-Arm`_ -:|M|: John Powell +:|M|: John Powell :|G|: `john-powell-arm`_ :|F|: bl31/ehf.c @@ -115,7 +115,7 @@ Realm Management Extension (RME) :|G|: `bipinravi-arm`_ :|M|: Mark Dykes :|G|: `mardyk01`_ -:|M|: John Powell +:|M|: John Powell :|G|: `john-powell-arm`_ :|M|: Zelalem Aweke :|G|: `zelalem-aweke`_ @@ -201,7 +201,7 @@ Arm CPU libraries ^^^^^^^^^^^^^^^^^ :|M|: Lauren Wehrmeister :|G|: `laurenw-arm`_ -:|M|: John Powell +:|M|: John Powell :|G|: `john-powell-arm`_ :|F|: lib/cpus/ @@ -255,7 +255,7 @@ Standard C library ^^^^^^^^^^^^^^^^^^ :|M|: Alexei Fedorov :|G|: `AlexeiFedorov`_ -:|M|: John Powell +:|M|: John Powell :|G|: `john-powell-arm`_ :|F|: lib/libc/ @@ -335,6 +335,15 @@ Max Power Mitigation Mechanism (MPMM) :|F|: include/lib/mpmm/ :|F|: lib/mpmm/ +Granule Protection Tables Library (GPT-RME) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:|M|: Mark Dykes +:|G|: `mardyk01`_ +:|M|: John Powell +:|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 000000000..07637dd58 --- /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 754526daf..95fe42cff 100644 --- a/docs/components/index.rst +++ b/docs/components/index.rst @@ -25,3 +25,4 @@ Components 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 5c580f36d..2c4e0b8a7 100644 --- a/docs/components/realm-management-extension.rst +++ b/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` 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 +` 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 **************************************************** diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index ef500ff05..0831dc056 100644 --- a/docs/design/firmware-design.rst +++ b/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 diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst index 5993d6e7a..a90ec0b3f 100644 --- a/docs/getting_started/image-terminology.rst +++ b/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``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index b3758b824..5a4be4d48 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/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 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 000000000..979e08387 Binary files /dev/null and b/docs/resources/diagrams/arm-cca-software-arch.png differ diff --git a/docs/threat_model/threat_model.rst b/docs/threat_model/threat_model.rst index 9f26487e9..4a31e7988 100644 --- a/docs/threat_model/threat_model.rst +++ b/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.