[PATCH 1/2] x86/trampoline: Document how the trampoline is laid out

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

This is, to the best of my knowledge, accurate.  I am providing no comment on
how sane I believe it to be.

At the time of writing, the sizes of the regions are:

          offset  size
  AP:     0x0000  0x00b0
  S3:     0x00b0  0x0140
  Boot:   0x01f0  0x1780
  Heap:   0x1970  0xe690
  Stack:  0xf000  0x1000

and wakeup_stack overlays boot_edd_info.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
CC: Jan Beulich <JBeulich@xxxxxxxx>
CC: Roger Pau Monné <roger.pau@xxxxxxxxxx>
CC: Daniel P. Smith <dpsmith@xxxxxxxxxxxxxxxxxxxx>
CC: Frediano Ziglio <frediano.ziglio@xxxxxxxxx>
CC: Alejandro Vallejo <alejandro.vallejo@xxxxxxxxx>
---
 xen/arch/x86/include/asm/trampoline.h | 55 ++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/xen/arch/x86/include/asm/trampoline.h 
b/xen/arch/x86/include/asm/trampoline.h
index 8c1e0b48c2c9..d801bea400dc 100644
--- a/xen/arch/x86/include/asm/trampoline.h
+++ b/xen/arch/x86/include/asm/trampoline.h
@@ -37,12 +37,63 @@
  * manually as part of placement.
  */
 
+/*
+ * Layout of the trampoline.  Logical areas, in ascending order:
+ *
+ * 1) AP boot:
+ *
+ *    The INIT-SIPI-SIPI entrypoint.  This logic is stack-less so the identity
+ *    mapping (which must be executable) can at least be Read Only.
+ *
+ * 2) S3 resume:
+ *
+ *    The S3 wakeup logic may need to interact with the BIOS, so needs a
+ *    stack.  The stack pointer is set to trampoline_phys + 4k and clobbers an
+ *    undefined part of the the boot trampoline.  The stack is only used with
+ *    paging disabled.
+ *
+ * 3) Boot trampoline:
+ *
+ *    This region houses various data used by the AP/S3 paths too.  The boot
+ *    trampoline collects data from the BIOS (E820/EDD/EDID/etc), so needs a
+ *    stack.  The stack pointer is set to trampoline_phys + 64k and has 4k
+ *    space reserved.
+ *
+ * 4) Heap space:
+ *
+ *    The first 1k of heap space is statically allocated for VESA information.
+ *
+ *    The remainder of the heap is used by reloc(), logic which is otherwise
+ *    outside of the trampoline, to collect the bootloader metadata (cmdline,
+ *    module list, etc).  It does so with a bump allocator starting from the
+ *    end of the heap and allocating backwards.
+ *
+ * 5) Boot stack:
+ *
+ *    4k of space is reserved for the boot stack, at trampoline_phys + 64k.
+ *
+ * Therefore, when placed, it looks somewhat like this:
+ *
+ *    +--- trampoline_phys
+ *    v
+ *    |<-------------------------------64K------------------------------->|
+ *    |<-----4K----->|                                         |<---4K--->|
+ *    +----+----+----+-+---------------------------------------+----------+
+ *    | AP | S3 | Boot | Heap                                  |    Stack |
+ *    +----+----+------+---------------------------------------+----------+
+ *    ^           <~~^ ^                                    <~~^       <~~^
+ *    |              | +- trampoline_end[]                     |          |
+ *    |              +--- S3 Stack          reloc() allocator -+          |
+ *    +------------------ trampoline_start[]       Boot Stack ------------+
+ */
+
 #include <xen/compiler.h>
 #include <xen/types.h>
 
 /*
- * Start and end of the trampoline section, as linked into Xen.  It is within
- * the .init section and reclaimed after boot.
+ * Start and end of the trampoline section, as linked into Xen.  This covers
+ * the AP, S3 and Boot regions, but not the heap or stack.  It is within the
+ * .init section and reclaimed after boot.
  */
 /* SAF-0-safe */
 extern char trampoline_start[], trampoline_end[];

base-commit: 38febce5b35a7a4391906499b2046f01ec0129ca
-- 
2.39.5