Djam/arm-trusted-firmware
1
0
Fork 0
mirror of https://github.com/ARM-software/arm-trusted-firmware.git synced 2025-04-16 09:34:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge changes I9e6feeee,If1cd7962 into integration

Browse source 
* changes:
  docs(rme): add description of TF-A changes for RME
  docs(gpt): add documentation page for GPT library
This commit is contained in:
Manish Pandey 2021-11-16 11:53:24 +01:00 • committed by TrustedFirmware Code Review
commit 55b2e6f0d3
9 changed files with 358 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
docs/about/maintainers.rst
View file

@ -75,7 +75,7 @@ Software Delegated Exception Interface (SDEI)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:|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 @@ Exception Handling Framework (EHF)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:|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 @@ Realm Management Extension (RME)
:|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 @@ Arm CPU libraries
^^^^^^^^^^^^^^^^^
:|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 @@ Standard C library
^^^^^^^^^^^^^^^^^^
:|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 @@ Max Power Mitigation Mechanism (MPMM)
:|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
~~~~~~~~~~~~~~

235
docs/components/granule-protection-tables-design.rst Normal file
View file

@ -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.

1
docs/components/index.rst
View file

@ -25,3 +25,4 @@ Components
xlat-tables-lib-v2-design
cot-binding
realm-management-extension
granule-protection-tables-design

89
docs/components/realm-management-extension.rst
View file

@ -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
****************************************************

10
docs/design/firmware-design.rst
View file

@ -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

8
docs/getting_started/image-terminology.rst
View file

@ -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``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

10
docs/getting_started/rt-svc-writers-guide.rst
View file

@ -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

BIN
docs/resources/diagrams/arm-cca-software-arch.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 20 KiB

7
docs/threat_model/threat_model.rst
View file

@ -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.