From: Soby Mathew Date: Tue, 24 Jan 2023 15:39:36 +0000 (+0000) Subject: docs(rme): improve OOB instruction for RME X-Git-Tag: baikal/aarch64/sdk5.10~1^2~251^2 X-Git-Url: https://git.baikalelectronics.ru/sdk/?a=commitdiff_plain;h=d9c976b08880ba887c535ef3cfe8c57283210786;p=arm-tf.git docs(rme): improve OOB instruction for RME This patch reworks the existing OOB instructions for RME enabled TF-A. Signed-off-by: Soby Mathew Change-Id: Icaeaf48c7061feaad4b1bb92388954694705e45c --- diff --git a/docs/components/realm-management-extension.rst b/docs/components/realm-management-extension.rst index 2ea8012cc..919eea592 100644 --- a/docs/components/realm-management-extension.rst +++ b/docs/components/realm-management-extension.rst @@ -13,7 +13,7 @@ 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) +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 @@ -44,7 +44,7 @@ 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 +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: @@ -70,57 +70,85 @@ More information about the GPT library can be found in the 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. +world. It initializes the `RMM`_ and handles Realm Management Interface (RMI) +SMC calls from Non-secure. -There is a contract between RMM and RMMD that defines the arguments that the +There is a contract between `RMM`_ and RMMD that defines the arguments that the former needs to take in order to initialize and also the possible return values. -This contract is defined in the RMM Boot Interface, which can be found at +This contract is defined in the `RMM`_ Boot Interface, which can be found at :ref:`rmm_el3_boot_interface`. There is also a specification of the runtime services provided by TF-A -to RMM. This can be found at :ref:`runtime_services_and_interface`. +to `RMM`_. This can be found at :ref:`runtime_services_and_interface`. 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. +if the path to an RMM image is not provided, TF-A builds the TRP by default +and uses it as the R-EL2 payload. Building and running TF-A with RME ------------------------------------- +---------------------------------- This section describes how you can build and run TF-A with RME enabled. -We assume you have all the :ref:`Prerequisites` to build TF-A. +We assume you have read the :ref:`Prerequisites` to build TF-A. The following instructions show you how to build and run TF-A with RME -for two scenarios: +on FVP for two scenarios: -- Three-world execution: TF-A with TF-A Tests or Linux. +- Three-world execution: This is the configuration to use if Secure + world functionality is not needed. TF-A is tested with the following + software entities in each world as listed below: - - NS (TF-A Test or Linux), + - NS Host (RME capable Linux or TF-A Tests), - Root (TF-A) - - Realm (RMM or TRP) + - R-EL2 (`RMM`_ or TRP) -- Four-world execution: TF-A, Hafnium and TF-A Tests or Linux. +- Four-world execution: This is the configuration to use if both Secure + and Realm world functionality is needed. TF-A is tested with the following + software entities in each world as listed below: - - NS (TF-A Test or Linux), + - NS Host (RME capable Linux or TF-A Tests), - Root (TF-A) - - Realm (RMM or TRP) - - SPM (Hafnium) + - R-EL2 (`RMM`_ or TRP) + - S-EL2 (Hafnium SPM) To run the tests, you need an FVP model. Please use the :ref:`latest version -` of *FVP_Base_RevC-2xAEMvA* model. +` of *FVP_Base_RevC-2xAEMvA* model. If NS +Host is Linux, then the below instructions assume that a suitable RME enabled +kernel image and associated root filesystem are available. -Three World Testing with TF-A Tests -************************************* +Three-world execution +********************* -**1. Obtain and build TF-A Tests with Realm Payload** +**1. Clone and build RMM Image** -The full set of instructions to setup build host and build options for -TF-A-Tests can be found in the `TFTF Getting Started`_. +Please refer to the `RMM Getting Started`_ on how to setup +Host Environment and build `RMM`_. The build commands assume that +an AArch64 toolchain and CMake executable are available in the +shell PATH variable and CROSS_COMPILE variable has been setup +appropriately. + +To clone `RMM`_ and build using the default build options for FVP: + +.. code:: shell + + git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git + cd tf-rmm + cmake -DRMM_CONFIG=fvp_defcfg -S . -B build + cmake --build build + +This will generate **rmm.img** in **build/Release** folder. + +**2. Clone and build TF-A Tests with Realm Payload** + +This step is only needed if NS Host is TF-A Tests. The full set +of instructions to setup build host and build options for +TF-A-Tests can be found in the `TFTF Getting Started`_. TF-A Tests +can test Realm world with either `RMM`_ or TRP in R-EL2. In the TRP case, +some tests which are not applicable will be skipped. Use the following instructions to build TF-A with `TF-A Tests`_ as the non-secure payload (BL33). @@ -134,37 +162,23 @@ non-secure payload (BL33). This produces a TF-A Tests binary (**tftf.bin**) with Realm payload packaged and **sp_layout.json** in the **build/fvp/debug** directory. -**2. Obtain and build RMM Image** - -Please refer to the `RMM Getting Started`_ on how to setup -Host Environment and build RMM. - -The below command shows how to build RMM using the default build options for FVP. - -.. code:: shell - - git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git - cd tf-rmm - cmake -DRMM_CONFIG=fvp_defcfg -S . -B build - cmake --build build - -This will generate **rmm.img** in **build** folder. -**3. Build TF-A** +**3. Build RME Enabled TF-A** The `TF-A Getting Started`_ has the necessary instructions to setup Host machine and build TF-A. To build for RME, set ``ENABLE_RME`` build option to 1 and provide the path to -the RMM binary using the ``RMM`` build option. -Currently, this feature is only supported for the FVP platform. +the `RMM`_ binary ``rmm.img`` using ``RMM`` build option. .. note:: ENABLE_RME build option is currently experimental. -If the ``RMM`` option is not used, then the Test Realm Payload (TRP) in TF-A -will be built and used as the RMM. +.. note:: + + If the ``RMM`` option is not specified, TF-A builds the TRP to load and + run at R-EL2. .. code:: shell @@ -176,16 +190,42 @@ will be built and used as the RMM. RMM= \ FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ DEBUG=1 \ - BL33= \ + BL33= \ + all fip + +``BL33`` can point to a Non Secure Bootloader like UEFI/U-Boot or +the TF-A Tests binary(**tftf.bin**) from the previous step. + +This produces **bl1.bin** and **fip.bin** binaries in the **build/fvp/debug** +directory. + +TF-A can also directly boot Linux kernel on the FVP. The kernel needs to be +`preloaded` to a suitable memory location and this needs to be specified via +``PRELOADED_BL33_BASE`` build option. Also TF-A should implement the Linux +kernel register conventions for boot and this can be set using the +``ARM_LINUX_KERNEL_AS_BL33`` option. + +.. code-block:: shell + + cd trusted-firmware-a + make CROSS_COMPILE=aarch64-none-elf- \ + PLAT=fvp \ + ENABLE_RME=1 \ + RMM= \ + FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ + DEBUG=1 \ + ARM_LINUX_KERNEL_AS_BL33=1 \ + PRELOADED_BL33_BASE=0x84000000 \ all fip -This produces **bl1.bin** and **fip.bin** binaries in the **build/fvp/debug** directory. +The above command assumes that the Linux kernel will be placed in FVP +memory at 0x84000000 via suitable FVP option (see the next step). + +.. _fvp_3_world_cmd: -Running the tests for a 3 world FVP setup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**4. Running FVP for 3 world setup** -Use the following command to run the tests on FVP. TF-A Tests should boot -and run the default tests including Realm world tests. +Use the following command to run the tests on FVP. .. code:: shell @@ -239,9 +279,30 @@ and run the default tests including Realm world tests. -C cluster1.restriction_on_speculative_execution_aarch32=2 \ -C pctl.startup=0.0.0.0 \ -C bp.smsc_91c111.enabled=1 \ - -C bp.hostbridge.userNetworking=1 + -C bp.hostbridge.userNetworking=1 \ + -C bp.virtioblockdevice.image_path= -The bottom of the output from *uart0* should look something like the following. +The ``bp.virtioblockdevice.image_path`` option presents the rootfs as a +virtio block device to Linux kernel. It can be ignored if NS Host is +TF-A-Tests or rootfs is accessed by some other mechanism. + +If TF-A was built to expect a preloaded Linux kernel, then use the following +FVP argument to load the kernel image at the expected address. + +.. code-block:: shell + + --data cluster0.cpu0=@0x84000000 \ + + +.. tip:: + Tips to boot and run Linux faster on the FVP : + 1. Set the FVP option ``cache_state_modelled`` to 0. + 2. Disable the CPU Idle driver in Linux either by setting the kernel command line + parameter "cpuidle.off=1" or by disabling the ``CONFIG_CPU_IDLE`` kernel config. + +If the NS Host is TF-A-Tests, then the default test suite in TFTF +will execute on the FVP and this includes Realm world tests. The +tail of the output from *uart0* should look something like the following. .. code-block:: shell @@ -263,52 +324,19 @@ The bottom of the output from *uart0* should look something like the following. Passed ... -Building TF-A with RME enabled Linux Kernel -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If an RME enabled Linux kernel and filesystem is available for testing, -and a suitable NS boot loader is not available, then this option can be used to -launch kernel directly after BL31: - -.. code-block:: shell - - cd trusted-firmware-a - make CROSS_COMPILE=aarch64-none-elf- \ - PLAT=fvp \ - ENABLE_RME=1 \ - RMM= \ - FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ - DEBUG=1 \ - ARM_LINUX_KERNEL_AS_BL33=1 \ - PRELOADED_BL33_BASE=0x84000000 \ - all fip - -Boot and run the RME enabled Linux Kernel -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Use the following additional arguments to boot the kernel on FVP. - -.. code-block:: shell - - --data cluster0.cpu0=@0x84000000 \ - -C bp.virtioblockdevice.image_path= - -.. tip:: - - Set the FVP option `cache_state_modelled=0` to run Linux based tests much faster. - -Four-world execution with Hafnium and TF-A Tests -************************************************* +Four-world execution +******************** Four-world execution involves software components in each security state: root, secure, realm and non-secure. This section describes how to build TF-A with four-world support. -We use TF-A as the root firmware, `Hafnium SPM`_ is the reference Secure world component -and the software components for the other 2 worlds (Realm and Non-Secure) -are as described in the previous section. +We use TF-A as the root firmware, `Hafnium SPM`_ is the reference Secure world +component running at S-EL2. `RMM`_ can be built as described in previous +section. The examples below assume TF-A-Tests as the NS Host and utilize SPs +from TF-A-Tests. -**1. Obtain and build Hafnium** +**1. Obtain and build Hafnium SPM** .. code:: shell @@ -342,11 +370,12 @@ project/reference submodule The Hafnium binary should be located at *out/reference/secure_aem_v8a_fvp_clang/hafnium.bin* -**2. Build TF-A** +**2. Build RME enabled TF-A with SPM** Build TF-A with RME as well as SPM enabled. -Use sp_layout.json previously generated in tf-a-test build. +Use the ``sp_layout.json`` previously generated in TF-A Tests +build to run SP tests. .. code:: shell @@ -355,7 +384,6 @@ Use sp_layout.json previously generated in tf-a-test build. ENABLE_RME=1 \ FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ SPD=spmd \ - SPMD_SPM_AT_SEL2=1 \ BRANCH_PROTECTION=1 \ CTX_INCLUDE_PAUTH_REGS=1 \ DEBUG=1 \ @@ -365,11 +393,11 @@ Use sp_layout.json previously generated in tf-a-test build. RMM= \ all fip -Running the tests for a 4 world FVP setup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**3. Running the FVP for a 4 world setup** -Use the following arguments in addition to -`Running the tests for a 3 world FVP setup`_ to run tests for 4 world setup. +Use the following arguments in addition to the FVP options mentioned in +:ref:`4. Running FVP for 3 world setup ` to run tests for +4 world setup. .. code:: shell @@ -388,4 +416,5 @@ Use the following arguments in addition to .. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest .. _TFTF Getting Started: https://trustedfirmware-a-tests.readthedocs.io/en/latest/getting_started/index.html .. _Hafnium SPM: https://www.trustedfirmware.org/projects/hafnium -.. _RMM Getting Started: https://git.trustedfirmware.org/TF-RMM/tf-rmm.git/tree/docs/getting_started/index.rst +.. _RMM Getting Started: https://tf-rmm.readthedocs.io/en/latest/getting_started/index.html +.. _RMM: https://www.trustedfirmware.org/projects/tf-rmm/