docs: added RME user guide

Signed-off-by: Subhasish Ghosh <subhasish.ghosh@arm.com>
Change-Id: I57a788153ec01458b1626007ba18ae9b22cc3b72

docs/components/index.rst

@@ -22,3 +22,4 @@ Components
    ffa-manifest-binding
    xlat-tables-lib-v2-design
    cot-binding
+   rme/index

docs/components/rme/index.rst

+Realm Management Extension (RME)
+==================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   rme-userguide
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*

docs/components/rme/rme-userguide.rst

+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

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`

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