From a8f1b241f35ee3c223eef42fec42f6e6f68e4f52 Mon Sep 17 00:00:00 2001
From: Subhasish Ghosh <subhasish.ghosh@arm.com>
Date: Fri, 4 Jun 2021 13:00:05 +0100
Subject: [PATCH] docs: added RME user guide
Signed-off-by: Subhasish Ghosh <subhasish.ghosh@arm.com>
Change-Id: I57a788153ec01458b1626007ba18ae9b22cc3b72
---
docs/components/index.rst | 1 +
docs/components/rme/index.rst | 12 +++
docs/components/rme/rme-userguide.rst | 133 ++++++++++++++++++++++++++
docs/global_substitutions.txt | 2 +
docs/glossary.rst | 6 ++
5 files changed, 154 insertions(+)
create mode 100644 docs/components/rme/index.rst
create mode 100644 docs/components/rme/rme-userguide.rst
diff --git a/docs/components/index.rst b/docs/components/index.rst
index 2409f964b..0800ec33e 100644
--- a/docs/components/index.rst
+++ b/docs/components/index.rst
@@ -22,3 +22,4 @@ Components
ffa-manifest-binding
xlat-tables-lib-v2-design
cot-binding
+ rme/index
diff --git a/docs/components/rme/index.rst b/docs/components/rme/index.rst
new file mode 100644
index 000000000..25ede4ab9
--- /dev/null
+++ b/docs/components/rme/index.rst
@@ -0,0 +1,12 @@
+Realm Management Extension (RME)
+==================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ rme-userguide
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/components/rme/rme-userguide.rst b/docs/components/rme/rme-userguide.rst
new file mode 100644
index 000000000..df2e32ed4
--- /dev/null
+++ b/docs/components/rme/rme-userguide.rst
@@ -0,0 +1,133 @@
+RME Enabled TF-A userguide
+=================================
+
+Prerequisites
+--------------
+
+To evaluate |RME|, first follow the instructions as described in the |TF-A|
+:ref:`Getting Started` section to clone the repository and setup the build
+environment. This should setup the required software libraries and toolchain
+for the build. Specifically, ensure that the environment variable
+``CROSS_COMPILE`` is setup correctly.
+
+Next, similar to the |TF-A| approach, follow the instructions as described
+in the `TF-A Tests Getting Started`_ for the pre-requisites.
+
+At this point, we should be left with two directories, |TF-A| and |TF-A-Tests|.
+
+.. code:: shell
+
+ ls
+ tf-a-tests trusted-firmware-a
+
+Getting the sources
+--------------------------
+
+The source code for |RME| is currently maintained as a branch in the |TF-A| git
+repository hosted on `trustedfirmware.org`_. To checkout this branch, execute the
+following commands:
+
+.. code:: shell
+
+ cd trusted-firmware-a
+ git checkout topics/rme_prototype
+
+Similarly, checkout the appropriate branch for |TF-A-Tests|:
+
+.. code:: shell
+
+ cd tf-a-tests
+ git checkout topics/rme_prototype
+
+
+Building the sources
+---------------------
+
+To build the |TF-A-Tests| source, follow the instructions to build for the
+FVP as described in `Building TF-A Tests`_. An example command is shown below:
+
+.. code:: shell
+
+ cd tf-a-tests
+ make PLAT=fvp DEBUG=1 USE_NVM=0 SHELL_COLOR=1 tftf
+
+This should generate the tftf.bin binary which can be passed as BL33 while building |TF-A|.
+
+Finally, to build |TF-A| execute the following commands:
+
+.. code:: shell
+
+ cd trusted-firmware-a
+ make ARCH=aarch64 PLAT=fvp ARM_DISABLE_TRUSTED_WDOG=1 ENABLE_RME=1 DEBUG=1 BL33=../tf-a-tests/build/fvp/debug/tftf.bin all fip
+
+This builds |TF-A| with |TF-A-Tests| as Normal world payload (BL33) and adds the
+Test Realm payload (TRP) as BL32 image.
+
+
+Executing on ARM |FVP|
+-----------------------
+
+In order to run on the FVP, please download an RME enabled FVP model through
+`Arm FVP website`_ (expected availability by mid-July 2021). Refer
+:ref:`Arm Fixed Virtual Platforms (FVP)` for details about running the model.
+
+To launch the FVP, execute the following command:
+
+.. code:: shell
+
+ ./FVP_Base_AEMvA \
+ -C bp.dram_size=2 \
+ -C bp.pl011_uart0.uart_enable=1 \
+ -C bp.pl011_uart1.uart_enable=1 \
+ -C bp.pl011_uart2.uart_enable=1 \
+ -C bp.refcounter.non_arch_start_at_default=1 \
+ -C bp.refcounter.use_real_time=0 \
+ -C bp.secure_memory=1 \
+ -C cache_state_modelled=0 \
+ -C cluster0.ecv_support_level=1 \
+ -C cluster0.has_arm_v8-4=1 \
+ -C cluster0.has_rme=1 \
+ -C cluster0.has_rndr=1 \
+ -C cluster0.has_v8_7_pmu_extension=2 \
+ -C cluster0.max_32bit_el=-1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster0.PA_SIZE=48 \
+ -C bp.flashloader0.fname=<path to fip.bin> \
+ -C bp.secureflashloader.fname=<path to bl1.bin>
+
+Details of the |TF-A-Tests| for Realm world
+---------------------------------------------
+
+The |TF-A-Tests| adds a new testsuite "Realm payload tests". This implements
+a simple test payload which just initializes the memory and UART. The payload
+also implements a handler which can respond to few RMI calls initiated
+by the testsuite.
+
+The log for the testsuite should appear as part of the results summary:
+
+.. code-block:: shell
+
+ ******************************* Summary *******************************
+
+ > Test suite 'Realm payload tests' Passed
+
+
+Known limitations of the prototype
+-----------------------------------
+
+This is a prototype to bootstrap TF-A on an RME enabled FVP. It replaces the
+secure world payload with Realm world binary. Currently, due to prototype nature
+of the code changes, all the appropriate cache maintenance operations are not done
+and hence the cache state modelling is disabled when running on the FVP. Further,
+the Granule protection table (GPT) initialization sequence is a work in progress
+(although functional).
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+
+.. _Arm FVP website: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models
+.. _trustedfirmware.org: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io
+.. _TF-A Tests Getting Started: https://trustedfirmware-a-tests.readthedocs.io/en/latest/getting_started/index.html
+.. _Building TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest/getting_started/build.html
diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt
index 24ac8300e..dc04b9d92 100644
--- a/docs/global_substitutions.txt
+++ b/docs/global_substitutions.txt
@@ -63,3 +63,5 @@
.. |UEFI| replace:: :term:`UEFI`
.. |WDOG| replace:: :term:`WDOG`
.. |XLAT| replace:: :term:`XLAT`
+.. |RME| replace:: :term:`RME`
+.. |TF-A-Tests| replace:: :term:`TF-A Tests`
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 54820e4b6..4d757daa3 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -214,4 +214,10 @@ You can find additional definitions in the `Arm Glossary`_.
XLAT
Translation (abbr.). For example, "XLAT table".
+ RME
+ Realm Management Extension
+
+ TF-A Tests
+ Trusted Firmware-A Tests
+
.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
--
GitLab