1.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4##########################
5RMM Fake host architecture
6##########################
7
8RMM supports building and running the program natively as a regular user-space
9application on the host machine. It achieves this by emulating the ``aarch64``
10specific parts of the program on the host machine by suitable hooks in the
11program. The implementation of the hooks can differ based on the target
12employment of running the program in this mode. Some of the foreseen
13employment scenarios of this architecture includes:
14
151. Facilitate development of architecture independent parts of
16   RMM on the host machine.
172. Enable unit testing of components within RMM with the benefit of
18   not having to mock all the dependencies of the component.
193. Leverage host development environment and tools for various
20   purposes like debugging, measure code coverage, fuzz testing,
21   stress testing, runtime analysis of program etc.
224. Enable RMM compliance testing and verification of state machine
23   and locking rules on the host machine.
245. Profile RMM on the host machine and generate useful insights
25   for possible optimizations.
26
27We expect the fake host architecture to be developed over time in future to
28cover some of the employment scenarios described above. The current code
29may not reflect the full scope of this architecture as discussed in this
30document.
31
32The fake host architecture has some limitations:
33
341. The architecture is not intended to support multi-thread execution.
35   The intrisics to support critical section and atomics are emulated
36   as NOP.
372. Cannot execute AArch64 assembly code on the host due to obvious
38   reasons.
393. Cannot emulate AArch64 exceptions during RMM execution although
40   some limited form of handling exceptions occurring in Realms can
41   probably be emulated.
424. The program links against the native compiler libraries which enables
43   use of development and debug features available on the host machine.
44   This means the libc implementation in RMM cannot be verified using
45   this architecture.
46
47The fake host architecture config is selected by setting the config
48``RMM_ARCH=fake_host`` and the platform has to be set to a variant
49of `host` when building RMM. The different variants of the `host`
50platform allow to build RMM for each of the target employment
51scenarios as listed above.
52
53*****************************
54Fake host architecture design
55*****************************
56
57|Fake Host Architecture Diagram|
58
59
60The above figure shows the fake host architecture design.
61The architecture independent parts of RMM are linked against
62suitable host emulation blocks to enable the program to run
63on the host platform.
64
65The EL3 (monitor) emulation layer emulates the entry and exception
66from EL3 into Realm-EL2. This includes entry and exit from RMM
67as part of RMI handling, entry into RMM as part of warm/cold boot,
68and EL3 service invocations by RMM using SMC calls. Similarly the
69Realm entry/exit emulation block allows emulation of running
70a Realm. It would also allow to emulate exit from Realm due to
71synchronous or asynchronous exceptions like SMC calls, IRQs, etc.
72
73The hardware emulation block allows to emulate sysreg accesses,
74granule memory delegation and NS memory accesses needed for RMM. Since
75RMM is running as a user space application, it does not have the ability
76to map granule memory to a Virtual Address space. This capability is
77needed for the ``slot buffer`` component in RMM. Hence there is
78also need to emulate VA mapping for this case.
79
80The AArch64 intrinsics emulation block allows emulation of exclusives,
81assembly instructions for various architecture extensions, barriers and
82atomics, cache and TLB operations although most of them are defined
83as NOP at the moment.
84
85Within the RMM source tree, all files within the ``fake_host``
86folder of each component implement the necessary emulation on host.
87Depending on the target employment for the fake host
88architecture, it is necessary to adapt the behaviour of
89the emulation layer. This is facilitated by the APIs defined
90in ``host_harness.h`` header. The implementation of the API
91is done by the ``host`` platform and each variant of the ``host``
92can have a different implementation of the API suiting its
93target employment. The API also facilitates test and verification
94of the emulated property as needed by the employment.
95
96
97******************************************************************
98Fake host architecture employment scenarios implemented or ongoing
99******************************************************************
100
101This section describes the currently implemented scenarios utilizing
102the fake host architecture.
103
1041. Unit testing framework in RMM which allows testing public API of
105   components and generation of code coverage data.
106
107.. |Fake Host Architecture Diagram| image:: ./diagrams/fake_host_arch.drawio.png
108
109