blob: 6fc0c2e253ed932daf4b58349a490f96dccd23a8 [file] [log] [blame]
Zelalem Aweke1fc09802021-08-26 15:29:47 -05001
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
Zelalem Aweke023b1a42021-10-21 13:59:45 -05007from 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
39:ref:`CPU context management API<PSCI Library Integration guide for Armv8-A
40AArch32 systems>` can be used to manage Realm context.
41
42Boot flow changes
43*******************
44In a typical TF-A boot flow, BL2 runs at Secure-EL1. However when RME is
45enabled, TF-A runs in the Root world at EL3. Therefore, the boot flow is
46modified to run BL2 at EL3 when RME is enabled. In addition to this, a
47Realm-world firmware (RMM) is loaded by BL2 in the Realm physical address
48space.
49
50The boot flow when RME is enabled looks like the following:
51
521. BL1 loads and executes BL2 at EL3
532. BL2 loads images including RMM
543. BL2 transfers control to BL31
554. BL31 initializes SPM (if SPM is enabled)
565. BL31 initializes RMM
576. BL31 transfers control to Normal-world software
58
59Granule Protection Tables (GPT) library
60*****************************************
61Isolation between the four physical address spaces is enforced by a process
62called Granule Protection Check (GPC) performed by the MMU downstream any
63address translation. GPC makes use of Granule Protection Table (GPT) in the
64Root world that describes the physical address space assignment of every
65page (granule). A GPT library that provides APIs to initialize GPTs and to
66transition granules between different physical address spaces has been added.
67More information about the GPT library can be found in the
68:ref:`Granule Protection Tables Library` chapter.
69
70RMM Dispatcher (RMMD)
71************************
72RMMD is a new standard runtime service that handles the switch to the Realm
73world. It initializes the RMM and handles Realm Management Interface (RMI)
74SMC calls from Non-secure and Realm worlds.
75
Javier Almansa Sobrino37bf69c2022-04-07 18:26:49 +010076There is a contract between RMM and RMMD that defines the arguments that the
77former needs to take in order to initialize and also the possible return values.
78This contract is defined in the RMM Boot Interface, which can be found at
79:ref:`rmm_el3_boot_interface`.
80
81There is also a specification of the runtime services provided by TF-A
82to RMM. This can be found at :ref:`runtime_services_and_interface`.
83
Zelalem Aweke023b1a42021-10-21 13:59:45 -050084Test Realm Payload (TRP)
85*************************
86TRP is a small test payload that runs at R-EL2 and implements a subset of
87the Realm Management Interface (RMI) commands to primarily test EL3 firmware
88and the interface between R-EL2 and EL3. When building TF-A with RME enabled,
89if a path to an RMM image is not provided, TF-A builds the TRP by default
90and uses it as RMM image.
Zelalem Aweke1fc09802021-08-26 15:29:47 -050091
92Building and running TF-A with RME
93------------------------------------
94
95This section describes how you can build and run TF-A with RME enabled.
96We assume you have all the :ref:`Prerequisites` to build TF-A.
97
Zelalem Aweke1fc09802021-08-26 15:29:47 -050098The following instructions show you how to build and run TF-A with RME
Shruti Gupta2e5cac52022-11-02 11:33:38 +000099for two scenarios:
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500100
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000101- Three-world execution: TF-A with TF-A Tests or Linux.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500102
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000103 - NS (TF-A Test or Linux),
104 - Root (TF-A)
105 - Realm (RMM or TRP)
106
107- Four-world execution: TF-A, Hafnium and TF-A Tests or Linux.
108
109 - NS (TF-A Test or Linux),
110 - Root (TF-A)
111 - Realm (RMM or TRP)
112 - SPM (Hafnium)
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500113
Zelalem Aweke023b1a42021-10-21 13:59:45 -0500114To run the tests, you need an FVP model. Please use the :ref:`latest version
115<Arm Fixed Virtual Platforms (FVP)>` of *FVP_Base_RevC-2xAEMvA* model.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500116
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000117Three World Testing with TF-A Tests
118*************************************
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500119
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000120**1. Obtain and build TF-A Tests with Realm Payload**
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500121
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000122The full set of instructions to setup build host and build options for
123TF-A-Tests can be found in the `TFTF Getting Started`_.
124
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500125Use the following instructions to build TF-A with `TF-A Tests`_ as the
126non-secure payload (BL33).
127
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500128.. code:: shell
129
130 git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git
131 cd tf-a-tests
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000132 make CROSS_COMPILE=aarch64-none-elf- PLAT=fvp DEBUG=1 all pack_realm
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500133
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000134This produces a TF-A Tests binary (**tftf.bin**) with Realm payload packaged
135and **sp_layout.json** in the **build/fvp/debug** directory.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500136
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000137**2. Obtain and build RMM Image**
138
139Please refer to the `RMM Getting Started`_ on how to setup
140Host Environment and build RMM.
141
142The below command shows how to build RMM using the default build options for FVP.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500143
144.. code:: shell
145
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000146 git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git
147 cd tf-rmm
148 cmake -DRMM_CONFIG=fvp_defcfg -S . -B build
149 cmake --build build
150
151This will generate **rmm.img** in **build** folder.
152
153**3. Build TF-A**
154
155The `TF-A Getting Started`_ has the necessary instructions to setup Host
156machine and build TF-A.
157
158To build for RME, set ``ENABLE_RME`` build option to 1 and provide the path to
159the RMM binary using the ``RMM`` build option.
160Currently, this feature is only supported for the FVP platform.
161
162.. note::
163
164 ENABLE_RME build option is currently experimental.
165
166If the ``RMM`` option is not used, then the Test Realm Payload (TRP) in TF-A
167will be built and used as the RMM.
168
169.. code:: shell
170
171 git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500172 cd trusted-firmware-a
173 make CROSS_COMPILE=aarch64-none-elf- \
174 PLAT=fvp \
175 ENABLE_RME=1 \
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000176 RMM=<path/to/rmm.img> \
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500177 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \
178 DEBUG=1 \
179 BL33=<path/to/tftf.bin> \
180 all fip
181
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000182This produces **bl1.bin** and **fip.bin** binaries in the **build/fvp/debug** directory.
183
184Running the tests for a 3 world FVP setup
185^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
186
187Use the following command to run the tests on FVP. TF-A Tests should boot
188and run the default tests including Realm world tests.
189
190.. code:: shell
191
192 FVP_Base_RevC-2xAEMvA \
193 -C bp.refcounter.non_arch_start_at_default=1 \
194 -C bp.secureflashloader.fname=<path/to/bl1.bin> \
195 -C bp.flashloader0.fname=<path/to/fip.bin> \
196 -C bp.refcounter.use_real_time=0 \
197 -C bp.ve_sysregs.exit_on_shutdown=1 \
198 -C cache_state_modelled=1 \
199 -C bp.dram_size=2 \
200 -C bp.secure_memory=1 \
201 -C pci.pci_smmuv3.mmu.SMMU_ROOT_IDR0=3 \
202 -C pci.pci_smmuv3.mmu.SMMU_ROOT_IIDR=0x43B \
203 -C pci.pci_smmuv3.mmu.root_register_page_offset=0x20000 \
204 -C cluster0.NUM_CORES=4 \
205 -C cluster0.PA_SIZE=48 \
206 -C cluster0.ecv_support_level=2 \
207 -C cluster0.gicv3.cpuintf-mmap-access-level=2 \
208 -C cluster0.gicv3.without-DS-support=1 \
209 -C cluster0.gicv4.mask-virtual-interrupt=1 \
210 -C cluster0.has_arm_v8-6=1 \
211 -C cluster0.has_amu=1 \
212 -C cluster0.has_branch_target_exception=1 \
213 -C cluster0.rme_support_level=2 \
214 -C cluster0.has_rndr=1 \
215 -C cluster0.has_v8_7_pmu_extension=2 \
216 -C cluster0.max_32bit_el=-1 \
217 -C cluster0.stage12_tlb_size=1024 \
218 -C cluster0.check_memory_attributes=0 \
219 -C cluster0.ish_is_osh=1 \
220 -C cluster0.restriction_on_speculative_execution=2 \
221 -C cluster0.restriction_on_speculative_execution_aarch32=2 \
222 -C cluster1.NUM_CORES=4 \
223 -C cluster1.PA_SIZE=48 \
224 -C cluster1.ecv_support_level=2 \
225 -C cluster1.gicv3.cpuintf-mmap-access-level=2 \
226 -C cluster1.gicv3.without-DS-support=1 \
227 -C cluster1.gicv4.mask-virtual-interrupt=1 \
228 -C cluster1.has_arm_v8-6=1 \
229 -C cluster1.has_amu=1 \
230 -C cluster1.has_branch_target_exception=1 \
231 -C cluster1.rme_support_level=2 \
232 -C cluster1.has_rndr=1 \
233 -C cluster1.has_v8_7_pmu_extension=2 \
234 -C cluster1.max_32bit_el=-1 \
235 -C cluster1.stage12_tlb_size=1024 \
236 -C cluster1.check_memory_attributes=0 \
237 -C cluster1.ish_is_osh=1 \
238 -C cluster1.restriction_on_speculative_execution=2 \
239 -C cluster1.restriction_on_speculative_execution_aarch32=2 \
240 -C pctl.startup=0.0.0.0 \
241 -C bp.smsc_91c111.enabled=1 \
242 -C bp.hostbridge.userNetworking=1
243
244The bottom of the output from *uart0* should look something like the following.
245
246.. code-block:: shell
247
248 ...
249
250 > Test suite 'FF-A Interrupt'
251 Passed
252 > Test suite 'SMMUv3 tests'
253 Passed
254 > Test suite 'PMU Leakage'
255 Passed
256 > Test suite 'DebugFS'
257 Passed
258 > Test suite 'RMI and SPM tests'
259 Passed
260 > Test suite 'Realm payload at EL1'
261 Passed
262 > Test suite 'Invalid memory access'
263 Passed
264 ...
265
266Building TF-A with RME enabled Linux Kernel
267^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268
269If an RME enabled Linux kernel and filesystem is available for testing,
270and a suitable NS boot loader is not available, then this option can be used to
271launch kernel directly after BL31:
272
273.. code-block:: shell
274
275 cd trusted-firmware-a
276 make CROSS_COMPILE=aarch64-none-elf- \
277 PLAT=fvp \
278 ENABLE_RME=1 \
279 RMM=<path/to/rmm.img> \
280 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \
281 DEBUG=1 \
282 ARM_LINUX_KERNEL_AS_BL33=1 \
283 PRELOADED_BL33_BASE=0x84000000 \
284 all fip
285
286Boot and run the RME enabled Linux Kernel
287^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
288
289Use the following additional arguments to boot the kernel on FVP.
290
291.. code-block:: shell
292
293 --data cluster0.cpu0=<path_to_kernel_Image>@0x84000000 \
294 -C bp.virtioblockdevice.image_path=<path_to_rootfs.ext4>
295
296.. tip::
297
298 Set the FVP option `cache_state_modelled=0` to run Linux based tests much faster.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500299
300Four-world execution with Hafnium and TF-A Tests
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000301*************************************************
302
303Four-world execution involves software components in each security state: root,
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500304secure, realm and non-secure. This section describes how to build TF-A
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000305with four-world support.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500306
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000307We use TF-A as the root firmware, `Hafnium SPM`_ is the reference Secure world component
308and the software components for the other 2 worlds (Realm and Non-Secure)
309are as described in the previous section.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500310
311**1. Obtain and build Hafnium**
312
313.. code:: shell
314
315 git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git
316 cd hafnium
Manish Pandey8c041ac2022-03-02 14:02:51 +0000317 # Use the default prebuilt LLVM/clang toolchain
318 PATH=$PWD/prebuilts/linux-x64/clang/bin:$PWD/prebuilts/linux-x64/dtc:$PATH
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000319
320Feature MTE needs to be disabled in Hafnium build, apply following patch to
321project/reference submodule
322
323.. code:: diff
324
325 diff --git a/BUILD.gn b/BUILD.gn
326 index cc6a78f..234b20a 100644
327 --- a/BUILD.gn
328 +++ b/BUILD.gn
329 @@ -83,7 +83,6 @@ aarch64_toolchains("secure_aem_v8a_fvp") {
330 pl011_base_address = "0x1c090000"
331 smmu_base_address = "0x2b400000"
332 smmu_memory_size = "0x100000"
333 - enable_mte = "1"
334 plat_log_level = "LOG_LEVEL_INFO"
335 }
336 }
337
338.. code:: shell
339
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500340 make PROJECT=reference
341
342The Hafnium binary should be located at
343*out/reference/secure_aem_v8a_fvp_clang/hafnium.bin*
344
345**2. Build TF-A**
346
347Build TF-A with RME as well as SPM enabled.
348
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000349Use sp_layout.json previously generated in tf-a-test build.
350
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500351.. code:: shell
352
353 make CROSS_COMPILE=aarch64-none-elf- \
354 PLAT=fvp \
355 ENABLE_RME=1 \
356 FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \
357 SPD=spmd \
358 SPMD_SPM_AT_SEL2=1 \
359 BRANCH_PROTECTION=1 \
360 CTX_INCLUDE_PAUTH_REGS=1 \
361 DEBUG=1 \
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000362 SP_LAYOUT_FILE=<path/to/sp_layout.json> \
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500363 BL32=<path/to/hafnium.bin> \
364 BL33=<path/to/tftf.bin> \
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000365 RMM=<path/to/rmm.img> \
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500366 all fip
367
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000368Running the tests for a 4 world FVP setup
369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500370
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000371Use the following arguments in addition to
372`Running the tests for a 3 world FVP setup`_ to run tests for 4 world setup.
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500373
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000374.. code:: shell
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500375
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000376 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 \
377 -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B \
378 -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 \
379 -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 \
380 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0475 \
381 -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 \
382 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 \
383 -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500384
385.. _Arm Confidential Compute Architecture (Arm CCA): https://www.arm.com/why-arm/architecture/security-features/arm-confidential-compute-architecture
386.. _Arm Architecture Models website: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000387.. _TF-A Getting Started: https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/index.html
Zelalem Aweke1fc09802021-08-26 15:29:47 -0500388.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest
Shruti Gupta2e5cac52022-11-02 11:33:38 +0000389.. _TFTF Getting Started: https://trustedfirmware-a-tests.readthedocs.io/en/latest/getting_started/index.html
390.. _Hafnium SPM: https://www.trustedfirmware.org/projects/hafnium
391.. _RMM Getting Started: https://git.trustedfirmware.org/TF-RMM/tf-rmm.git/tree/docs/getting_started/index.rst