1.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4#############################
5RMM Cold and Warm boot design
6#############################
7
8This section covers the boot design of RMM. The below
9diagram gives an overview of the boot flow.
10
11|Boot Design|
12
13Both warm and cold boot enters RMM at the same entry point
14``rmm_entry()``. This scheme simplifies the
15`RMM-EL3 communications interface`_. The boot args as specified by boot
16contract are stashed to high registers.
17
18The boot is divided into several phases as described below:
19
201. **Sysreg and C runtime initialization phase.**
21
22   The essential system registers are initialized. ``SCTLR_EL2.I``
23   is set to 1 which means instruction accesses to Normal memory are
24   Outer Shareable, Inner Write-Through cacheable, Outer Write-Through
25   cacheable. ``SCTLR_EL2.C`` is also set 1 and data accesses default
26   to Device-nGnRnE. The cpu-id, received as part of boot args, is programmed
27   to ``tpidr_el2`` and this can be retrieved using the helper function
28   ``my_cpuid()``. The per-CPU stack is also initialized using the cpu-id
29   received and this completes the C runtime initialization for warm boot.
30
31   Only the primary CPU enters RMM during cold boot and a global
32   variable is used to keep track whether it is cold or warm boot. If
33   cold boot, the Global Descriptor Table (GDT) and Relocations are fixed
34   up so that RMM can run as position independent executable (PIE). The BSS
35   is zero initialized which completes the C runtime initialization
36   for cold boot.
37
38   During this phase, and the Platform initialization phase, the RMM starts
39   with MMU disabled (and hence with data cacheability disabled). However,
40   EL3 may have cacheability enabled. The following guidelines apply to the
41   RMM, when RMM has cacheability disabled, but EL3 has cacheability enabled:
42
43   - RMM must perform invalidation on all its memory on entry on primary core,
44     prior to enabling MMU as part of cold boot.
45
46   - Any function in RMM which is invoked prior to MMU enable needs to perform
47     CMOs on any data modified which is not part of the C runtime stack in the
48     RMM. During cold boot, the primary CPU is allowed to modify global data
49     with MMU disabled. During warm boot, the secondary CPUs are only allowed
50     to modify per-cpu data with MMU disabled and reads to global data must be
51     restricted to ones which have had appropriate CMOs done by the primary.
52
53   - Runtime EL3 firmware (BL31) should not map any part of RMM except the
54     shared buffer used for comms between RMM and EL3. RMM to perform required
55     CMOs on the shared buffer when communicating with EL3 prior to enabling
56     MMU. The only exception is the Boot Manifest which needs to be flushed by
57     EL3 before RMM cold boot entry.
58
592. **Platform initialization phase**
60
61   The boot args are restored to their original registers and plat_setup()
62   and plat_warmboot_setup() are invoked for cold and warm boot respectively.
63   During cold boot, the platform is expected to consume the boot manifest
64   which is part of the `RMM-EL3 communications interface`_. The platform
65   initializes any platform specific peripherals and also intializes and
66   configures the translation table contexts for Stage 1.
67
683. **MMU enable phase**
69
70   The EL2&0 translation regime is enabled after suitable TLB and cache
71   invalidations.
72
734. **PAuth enable phase**
74
75   Disable API, APK Trap, to allow PAuth instructions access from Realm without trapping.
76   Initialize APIA Keys to random 128-bit value, Enable PAuth for R-EL2.
77
785. **RMM Main phase**
79
80   Any cold boot or warm initialization of RMM components is done in this
81   phase. This phase also involves invoking suitable EL3 services, like
82   acquiring platform attestation token for Realm attestation.
83
84After all the phases have completed successfully, RMM issues
85``RMM_BOOT_COMPLETE`` SMC. The next entry into RMM from EL3 would be for
86handling RMI calls and hence the next intruction following the SMC call
87branches to the main SMC handler routine.
88
89
90###################################
91RMM-EL3 communication specification
92###################################
93
94The communication interface between RMM and EL3 is specified in
95`RMM-EL3 communications interface`_ specification in the TF-A repository.
96
97.. |Boot Design| image:: ./diagrams/boot_design.drawio.png
98.. _`RMM-EL3 communications interface`: https://trustedfirmware-a.readthedocs.io/en/latest/components/rmm-el3-comms-spec.html
99
100