[bootwrapper PATCH v3 03/15] Document entry requirements

[Mark Rutland]

Currently the boot-wrapper only supports some combinations of exception
levels, with other combinations not being supported.

While we generally expect the boot-wrapper to be entered at the highest
implemented exception level, the AArch32 boot-wrapper has a comment
implying it supports being entered with something else owning EL3. As
this would require such EL3 firmware to always be in sync with the
boot-wrapper's requirements, which change over time, we don't actually
support such a configuration.

Some CPU state (such as CNTFRQ/CNTFRQ_EL0) needs to be initialized at
the highest implemented exception level, but today the boot-wrapper only
does so when entered at EL3 / Secure-PL1. Thus, today the only
completely supported configurations are EL3 / Secure-PL1, and entering
in other configurations is not entirely supported.

The aarch64 `jump_kernel` function always writes to SCTLR_EL2, which is
UNDEFINED at EL1. Hence, the aarch64 boot-wrapper does not support being
entered at EL1.

The aarch32 code assumes that any non-hyp mode is Secure PL1, and
attempt to switch to monitor mode. If entered on a system without the
security extensions, where the highest privileged mode is Non-secure
PL1, this will not work. Hence the aarch32 boot-wrapper does not support
being entered at Non-secure PL1.

Actually supporting all of these configurations requires restructuring
much of the boot-wrapper. For now, document the supported configurations
in each architecture's boot.S, and remove the misleading comment from
arch/aarch32/boot.S. Subsequent patches will improve the support and add
support for additional configurations.

There should be no functional change as a result of this patch.

Signed-off-by: Mark Rutland <mark.rutland at arm.com>
---
 arch/aarch32/boot.S | 14 ++++++++++++++
 arch/aarch32/psci.S |  5 -----
 arch/aarch64/boot.S | 13 +++++++++++++
 3 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/arch/aarch32/boot.S b/arch/aarch32/boot.S
index 4add338..00c432d 100644
--- a/arch/aarch32/boot.S
+++ b/arch/aarch32/boot.S
@@ -16,6 +16,20 @@
 	.arch_extension virt
 
 	.section .init
+
+	/*
+	 * The boot-wrapper must be entered from the reset vector at the
+	 * highest implemented exception level. The boot-wrapper only supports
+	 * being entered in the following modes:
+	 *
+	 * - PL1 / EL3 (Secure) Supervisor mode
+	 *   Entering in this mode is strongly recommended.
+	 *   PL2 must be implemented.
+	 *
+	 * - PL2 / EL2 (Non-secure) Hypervisor mode
+	 *   Entering in this mode is partially supported.
+	 *   PSCI is not supported when entered in this mode.
+	 */
 ASM_FUNC(_start)
 	/* Stack initialisation */
 	cpuid	r0, r1
diff --git a/arch/aarch32/psci.S b/arch/aarch32/psci.S
index dc7aeb7..e0d2972 100644
--- a/arch/aarch32/psci.S
+++ b/arch/aarch32/psci.S
@@ -44,11 +44,6 @@ ASM_FUNC(start_el3)
 	/* pass through */
 
 ASM_FUNC(start_no_el3)
-	/*
-	 * For no-el3, we assume that firmware launched the boot-wrapper in
-	 * non-secure EL2 or EL1. We assume it has its own PSCI implementation
-	 * sitting at EL3, and that this path is only taken by primary CPU.
-	 */
 	cpuid	r0, r1
 	blx	find_logical_id
 	b	psci_first_spin
diff --git a/arch/aarch64/boot.S b/arch/aarch64/boot.S
index ee9ddaa..d682ba5 100644
--- a/arch/aarch64/boot.S
+++ b/arch/aarch64/boot.S
@@ -12,6 +12,19 @@
 
 	.section .init
 
+	/*
+	 * The boot-wrapper must be entered from the reset vector at the
+	 * highest implemented exception level. The boot-wrapper only supports
+	 * being entered at the following exception levels:
+	 *
+	 * - EL3 (Secure)
+	 *   Entering at EL3 is strongly recommended.
+	 *   EL2 must be implemented.
+	 *
+	 * - EL2 (Non-secure)
+	 *   Entering at EL2 is partially supported.
+	 *   PSCI is not supported when entered in this exception level.
+	 */
 ASM_FUNC(_start)
 	cpuid	x0, x1
 	bl	find_logical_id
-- 
2.30.2