This document defines the communication interface between RMM and EL3.
There are two parts in this interface: the boot interface and the runtime
interface.
The Boot Interface defines the ABI between EL3 and RMM when the CPU enters
R-EL2 for the first time after boot. The cold boot interface defines the ABI
for the cold boot path and the warm boot interface defines the same for the
warm path.
The RMM-EL3 runtime interface defines the ABI for EL3 services which can be
invoked by RMM as well as the register save-restore convention when handling an
SMC call from NS.
The below sections discuss these interfaces more in detail.
.._rmm_el3_ifc_versioning:
RMM-EL3 Interface versioning
____________________________
The RMM Boot and Runtime Interface uses a version number to check
compatibility with the register arguments passed as part of Boot Interface and
RMM-EL3 runtime interface.
The Boot Manifest, discussed later in section :ref:`rmm_el3_boot_manifest`,
uses a separate version number but with the same scheme.
The version number is a 32-bit type with the following fields:
..csv-table::
:header:"Bits", "Value"
[0:15],``VERSION_MINOR``
[16:30],``VERSION_MAJOR``
[31],RES0
The version numbers are sequentially increased and the rules for updating them
are explained below:
-``VERSION_MAJOR``: This value is increased when changes break
compatibility with previous versions. If the changes
on the ABI are compatible with the previous one, ``VERSION_MAJOR``
remains unchanged.
-``VERSION_MINOR``: This value is increased on any change that is backwards
compatible with the previous version. When ``VERSION_MAJOR`` is increased,
``VERSION_MINOR`` must be set to 0.
-``RES0``: Bit 31 of the version number is reserved 0 as to maintain
consistency with the versioning schemes used in other parts of RMM.
This document specifies the 0.1 version of Boot Interface ABI and RMM-EL3
services specification and the 0.1 version of the Boot Manifest.
.._rmm_el3_boot_interface:
RMM Boot Interface
__________________
This section deals with the Boot Interface part of the specification.
One of the goals of the Boot Interface is to allow EL3 firmware to pass
down into RMM certain platform specific information dynamically. This allows
RMM to be less platform dependent and be more generic across platform
variations. It also allows RMM to be decoupled from the other boot loader
images in the boot sequence and remain agnostic of any particular format used
for configuration files.
The Boot Interface ABI defines a set of register conventions and
also a memory based manifest file to pass information from EL3 to RMM. The
boot manifest and the associated platform data in it can be dynamically created
by EL3 and there is no restriction on how the data can be obtained (e.g by DTB,
hoblist or other).
The register convention and the manifest are versioned separately to manage
future enhancements and compatibility.
RMM completes the boot by issuing the ``RMM_BOOT_COMPLETE`` SMC (0xC40001CF)
back to EL3. After the RMM has finished the boot process, it can only be
entered from EL3 as part of RMI handling.
If RMM returns an error during boot (in any CPU), then RMM must not be entered
from any CPU.
.._rmm_cold_boot_interface:
Cold Boot Interface
~~~~~~~~~~~~~~~~~~~
During cold boot RMM expects the following register values:
..csv-table::
:header:"Register", "Value"
:widths:1, 5
x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of CPUs to be supported at runtime (see x2).
x1,Version for this Boot Interface as defined in :ref:`rmm_el3_ifc_versioning`.
x2,Maximum number of CPUs to be supported at runtime. RMM should ensure that it can support this maximum number.
x3,Base address for the shared buffer used for communication between EL3 firmware and RMM. This buffer must be of 4KB size (1 page). The boot manifest must be present at the base of this shared buffer during cold boot.
During cold boot, EL3 firmware needs to allocate a 4K page that will be
passed to RMM in x3. This memory will be used as shared buffer for communication
between EL3 and RMM. It must be assigned to Realm world and must be mapped with
Normal memory attributes (IWB-OWB-ISH) at EL3. At boot, this memory will be
used to populate the Boot Manifest. Since the Boot Manifest can be accessed by
RMM prior to enabling its MMU, EL3 must ensure that proper cache maintenance
operations are performed after the Boot Manifest is populated.
EL3 should also ensure that this shared buffer is always available for use by RMM
during the lifetime of the system and that it can be used for runtime
communication between RMM and EL3. For example, when RMM invokes attestation
service commands in EL3, this buffer can be used to exchange data between RMM
and EL3. It is also allowed for RMM to invoke runtime services provided by EL3
utilizing this buffer during the boot phase, prior to return back to EL3 via
RMM_BOOT_COMPLETE SMC.
RMM should map this memory page into its Stage 1 page-tables using Normal
memory attributes.
During runtime, it is the RMM which initiates any communication with EL3. If that
communication requires the use of the shared area, it is expected that RMM needs
to do the necessary concurrency protection to prevent the use of the same buffer
by other PEs.
The following sequence diagram shows how a generic EL3 Firmware would boot RMM.
err_code,x1,[63:0],RmiCommandReturnCode,Error code returned by the RMI service invoked by NS World. See Realm Management Monitor specification for more info
Output values
-------------
This call does not return.
Failure conditions
------------------
Since this call does not return to RMM, there is no failure condition which
can be notified back to RMM.
RMM_GTSI_DELEGATE command
=========================
Delegate a memory granule by changing its PAS from Non-Secure to Realm.
As part of NS world switch, EL3 is expected to maintain a register context
specific to each world and will save and restore the registers
appropriately. This section captures the contract between EL3 and RMM on the
register set to be saved and restored.
EL3 must maintain a separate register context for the following:
#. General purpose registers (x0-x30) and ``sp_el0``, ``sp_el2`` stack pointers
#. EL2 system register context for all enabled features by EL3. These include system registers with the ``_EL2`` prefix. The EL2 physical and virtual timer registers must not be included in this.
