ArmPlatformPkg: Added Aarch64 Foundation Model

    
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Harry Liebel <Harry.Liebel@arm.com>
Signed-off-by: Olivier Martin <olivier.martin@arm.com>



git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14495 6f19259b-4bc3-4df7-8a09-765794883524

6 files changed, 564 insertions, 0 deletions

diff --git a/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/LICENSE.TXT b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/LICENSE.TXT
new file mode 100644
index 0000000000..880cbaf88b
--- /dev/null
+++ b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/LICENSE.TXT
@@ -0,0 +1,28 @@
+Copyright (c) 2011-2013 ARM Limited
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in
+      the documentation and/or other materials provided with the
+      distribution.
+    * Neither the name of ARM nor the names of its contributors may be
+      used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/Makefile b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/Makefile
new file mode 100644
index 0000000000..6aee571478
--- /dev/null
+++ b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/Makefile
@@ -0,0 +1,96 @@
+#
+# Makefile - build a UEFI boot image for booting from different exception levels.
+#
+# Copyright (C) 2011-2013 ARM Limited.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+#        notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in
+#       the documentation and/or other materials provided with the
+#       distribution.
+#     * Neither the name of ARM nor the names of its contributors may be
+#       used to endorse or promote products derived from this software
+#       without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# This license can also be found in the LICENSE.TXT file.
+
+
+# VE
+PHYS_OFFSET	:= 0x80000000
+UART_BASE	:= 0x1c090000
+GIC_DIST_BASE	:= 0x2c001000
+GIC_CPU_BASE	:= 0x2c002000
+CNTFRQ		:= 0x01800000	# 24Mhz
+
+BOOTLOADER	:= boot.S
+LD_SCRIPT	:= model.lds.S
+IMAGE_1		:= uefi-bootstrap-el1.axf
+IMAGE_2		:= uefi-bootstrap-el2.axf
+IMAGE_3		:= uefi-bootstrap-el3.axf
+IMAGE_3F	:= uefi-bootstrap-el3-foundation.axf
+
+
+CROSS_COMPILE	?= aarch64-none-elf-
+CC		:= $(CROSS_COMPILE)gcc
+LD		:= $(CROSS_COMPILE)ld
+
+all: $(IMAGE_1) $(IMAGE_2) $(IMAGE_3) $(IMAGE_3F)
+
+clean:
+	rm -f *.axf *.o *.lds
+
+$(IMAGE_1): boot1.o model1.lds
+	$(LD) -o $@ --script=model1.lds
+
+$(IMAGE_2): boot2.o model2.lds
+	$(LD) -o $@ --script=model2.lds
+
+$(IMAGE_3): boot3.o model3.lds
+	$(LD) -o $@ --script=model3.lds
+
+$(IMAGE_3F): boot3f.o model3f.lds
+	$(LD) -o $@ --script=model3f.lds
+
+boot1.o: $(BOOTLOADER) Makefile
+	$(CC) $(CPPFLAGS) -DUART_BASE=$(UART_BASE) -DCNTFRQ=$(CNTFRQ) -DGIC_DIST_BASE=$(GIC_DIST_BASE) -DGIC_CPU_BASE=$(GIC_CPU_BASE) -DSTART_EL2=1 -DSTART_EL1=1 -c -o $@ $(BOOTLOADER)
+
+boot2.o: $(BOOTLOADER) Makefile
+	$(CC) $(CPPFLAGS) -DUART_BASE=$(UART_BASE) -DCNTFRQ=$(CNTFRQ) -DGIC_DIST_BASE=$(GIC_DIST_BASE) -DGIC_CPU_BASE=$(GIC_CPU_BASE) -DSTART_EL2=1 -c -o $@ $(BOOTLOADER)
+
+boot3.o: $(BOOTLOADER) Makefile
+	$(CC) $(CPPFLAGS) -DUART_BASE=$(UART_BASE) -DCNTFRQ=$(CNTFRQ) -DGIC_DIST_BASE=$(GIC_DIST_BASE) -DGIC_CPU_BASE=$(GIC_CPU_BASE) -c -o $@ $(BOOTLOADER)
+
+boot3f.o: $(BOOTLOADER) Makefile
+	$(CC) $(CPPFLAGS) -DUART_BASE=$(UART_BASE) -DCNTFRQ=$(CNTFRQ) -DGIC_DIST_BASE=$(GIC_DIST_BASE) -DGIC_CPU_BASE=$(GIC_CPU_BASE) -DFOUNDATION_MODEL=1 -c -o $@ $(BOOTLOADER)
+
+model1.lds: $(LD_SCRIPT) Makefile boot1.o
+	$(CC) $(CPPFLAGS) -DPHYS_OFFSET=$(PHYS_OFFSET) -DBOOT1 -E -P -C -o $@ $<
+
+model2.lds: $(LD_SCRIPT) Makefile boot2.o
+	$(CC) $(CPPFLAGS) -DPHYS_OFFSET=$(PHYS_OFFSET) -DBOOT2 -E -P -C -o $@ $<
+
+model3.lds: $(LD_SCRIPT) Makefile boot3.o
+	$(CC) $(CPPFLAGS) -DPHYS_OFFSET=$(PHYS_OFFSET) -DBOOT3 -E -P -C -o $@ $<
+
+model3f.lds: $(LD_SCRIPT) Makefile boot3f.o
+	$(CC) $(CPPFLAGS) -DPHYS_OFFSET=$(PHYS_OFFSET) -DBOOT3F -E -P -C -o $@ $<
+
+.PHONY: all clean
diff --git a/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/boot.S b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/boot.S
new file mode 100644
index 0000000000..24d5bb031d
--- /dev/null
+++ b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/boot.S
@@ -0,0 +1,183 @@
+/*
+ * boot.S - simple register setup code for junping to a second stage bootloader
+ *
+ * Copyright (C) 2011-2013 ARM Limited.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ *        notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in
+ *       the documentation and/or other materials provided with the
+ *       distribution.
+ *     * Neither the name of ARM nor the names of its contributors may be
+ *       used to endorse or promote products derived from this software
+ *       without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This license can also be found in the LICENSE.TXT file.
+ */
+
+	.text
+
+	.globl	_start
+
+.set LED_ADDR, 0x1c010008
+
+_start:
+	/*
+	 * EL3 initialisation
+	 */
+
+	// Set LED to show progress.
+	ldr	x1, =LED_ADDR
+	mov	w0, #0x1
+	str	w0, [x1]
+        dsb	sy
+
+#if defined START_EL2
+
+	mrs	x0, CurrentEL
+	cmp	x0, #0xc			// EL3?
+	b.ne	start_ns			// skip EL3 initialisation
+
+	mov	x0, #0x30			// RES1
+	orr	x0, x0, #(1 << 0)		// Non-secure EL1
+	orr	x0, x0, #(1 << 8)		// HVC enable
+	orr	x0, x0, #(1 << 10)		// 64-bit EL2
+	msr	scr_el3, x0
+
+	msr	cptr_el3, xzr			// Disable copro. traps to EL3
+
+	ldr	x0, =CNTFRQ
+	msr	cntfrq_el0, x0
+
+	/*
+	 * Check for the primary CPU to avoid a race on the distributor
+	 * registers.
+	 */
+	mrs	x0, mpidr_el1
+	tst	x0, #15
+	b.ne	1f				// secondary CPU
+
+	ldr	x1, =GIC_DIST_BASE		// GICD_CTLR
+	mov	w0, #3				// EnableGrp0 | EnableGrp1
+	str	w0, [x1]
+
+1:	ldr	x1, =GIC_DIST_BASE + 0x80	// GICD_IGROUPR
+	mov	w0, #~0				// Grp1 interrupts
+	str	w0, [x1], #4
+	b.ne	2f				// Only local interrupts for secondary CPUs
+	str	w0, [x1], #4
+	str	w0, [x1], #4
+
+2:	ldr	x1, =GIC_CPU_BASE		// GICC_CTLR
+	ldr	w0, [x1]
+	mov	w0, #3				// EnableGrp0 | EnableGrp1
+	str	w0, [x1]
+
+	mov	w0, #1 << 7			// allow NS access to GICC_PMR
+	str	w0, [x1, #4]			// GICC_PMR
+
+	msr	sctlr_el2, xzr
+
+#if defined START_EL1
+
+	/* Now setup our EL1. Controlled by EL2 config on Model */
+	mrs	x0, hcr_el2			// Read EL2 Hypervisor configuration Register
+	orr	x0, x0, #(1 << 31)		// Set EL1 to be 64bit
+
+	// Send all interrupts to their respective Exception levels for EL2
+	bic	x0, x0, #(1 << 3)		// Disable virtual FIQ
+	bic	x0, x0, #(1 << 4)		// Disable virtual IRQ
+	bic	x0, x0, #(1 << 5)		// Disable virtual SError and Abort
+	msr	hcr_el2, x0			// Write back our settings
+
+	/*
+	 * Enable architected timer access
+	 */
+	mrs	x0, cnthctl_el2
+	orr	x0, x0, #3			// Enable EL1 access to timers
+	msr	cnthctl_el2, x0
+
+	mrs	x0, cntkctl_el1
+	orr	x0, x0, #3			// EL0 access to counters
+	msr	cntkctl_el1, x0
+
+	/* Set ID regs */
+	mrs	x0, midr_el1
+	mrs	x1, mpidr_el1
+	msr	vpidr_el2, x0
+	msr	vmpidr_el2, x1
+
+	/* Coprocessor traps. */
+	mov	x0, #0x33ff
+	msr	cptr_el2, x0			// Disable copro. traps to EL2
+
+	msr	hstr_el2, xzr			// Disable CP15 traps to EL2
+
+#endif // START_EL1
+
+        /* Configure UART. Primary CPU only */
+	mrs     x4, mpidr_el1
+	tst     x4, #15
+	b.ne    1f
+
+	/*
+	 * UART initialisation (38400 8N1)
+	 */
+	ldr     x4, =UART_BASE                  // UART base
+	mov     w5, #0x10                       // ibrd
+	str     w5, [x4, #0x24]
+	mov     w5, #0xc300
+	orr     w5, w5, #0x0001                 // cr
+	str     w5, [x4, #0x30]
+
+	/*
+	 * Prepare the switch to the EL2_SP2 mode from EL3
+	 */
+1:	ldr	x0, =start_ns			// Return after mode switch
+#if defined START_EL1
+	mov	x1, #0x3c5			// EL1_SP1 | D | A | I | F
+#else
+	mov	x1, #0x3c9			// EL2_SP2 | D | A | I | F
+#endif
+
+	msr	elr_el3, x0
+	msr	spsr_el3, x1
+	eret
+
+#endif // START_EL2
+
+
+start_ns:
+
+/*
+ * We do not have NOR flash on the Foundation model. So run UEFI from RAM.
+ * On the full model we use the NOR FLASH to store UEFI, so start there.
+ */
+#if defined FOUNDATION_MODEL
+	mov	x0, #0xa0000000
+#else
+	mov	x0, #0x0
+#endif
+	br	x0
+
+	.ltorg
+
+	.org	0x200
diff --git a/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/model.lds.S b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/model.lds.S
new file mode 100644
index 0000000000..f554bd5d4d
--- /dev/null
+++ b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/model.lds.S
@@ -0,0 +1,77 @@
+/*
+ * model.lds.S - simple linker script for stand-alone Linux booting
+ *
+ * Copyright (C) 2011, 2012 ARM Limited.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ *        notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in
+ *       the documentation and/or other materials provided with the
+ *       distribution.
+ *     * Neither the name of ARM nor the names of its contributors may be
+ *       used to endorse or promote products derived from this software
+ *       without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This license can also be found in the LICENSE.TXT file.
+ */
+
+OUTPUT_FORMAT("elf64-littleaarch64")
+OUTPUT_ARCH(aarch64)
+TARGET(binary)
+
+#ifdef BOOT1
+INPUT(./boot1.o)
+#endif
+
+#ifdef BOOT2
+INPUT(./boot2.o)
+#endif
+
+#ifdef BOOT3
+INPUT(./boot3.o)
+#endif
+
+#ifdef BOOT3F
+INPUT(./boot3f.o)
+#endif
+
+SECTIONS
+{
+	. = PHYS_OFFSET;
+#ifdef BOOT1
+	.text : { boot1.o }
+#endif
+
+#ifdef BOOT2
+	.text : { boot2.o }
+#endif
+
+#ifdef BOOT3
+	.text : { boot3.o }
+#endif
+
+#ifdef BOOT3F
+	.text : { boot3f.o }
+#endif
+
+	.data : { *(.data) }
+	.bss : { *(.bss) }
+}
diff --git a/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.html b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.html
new file mode 100644
index 0000000000..ecc1a51100
--- /dev/null
+++ b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.html
@@ -0,0 +1,88 @@
+<h1>AArch64 UEFI bootstraps</h1>
+
+<p>Copyright (c) 2011-2013 ARM Limited. All rights reserved.
+See the <code>LICENSE.TXT</code> file for more information.</p>
+
+<p>Contents:</p>
+
+<ul>
+<li>Introduction</li>
+<li>Build</li>
+<li>Use on ARMv8 RTSM and FVP models</li>
+<li>Use on ARMv8 Foundation model</li>
+</ul>
+
+<h2>Introduction</h2>
+
+<p>A bootstrap can be used to change the model state, like the Exception
+Level (EL), before executing the UEFI binary.</p>
+
+<p>For the ARMv8 RTSM and FVP models this can be used to show/test the UEFI binary
+starting at different exception levels. The ARMv8 models start at EL3 by
+default.</p>
+
+<p>In the case of the Foundation model a bootstrap is required to jump to the
+UEFI binary as loaded in RAM. This is required as the Foundation model cannot
+load and execute UEFI binaries directly. The Foundation model can only load and
+execute ELF binaries.</p>
+
+<h2>Build</h2>
+
+<p>Build the bootstraps using a AArch64 GCC cross-compiler. By default the
+<code>Makefile</code> is configured to assume a GCC bare-metal toolchain:</p>
+
+<pre><code>PATH=$PATH:&lt;path/to/baremetal-tools/bin/&gt; make clean
+PATH=$PATH:&lt;path/to/baremetal-tools/bin/&gt; make
+</code></pre>
+
+<p>To build the bootstraps with a Linux GCC toolchain use the following
+commands:</p>
+
+<pre><code>PATH=$PATH:&lt;path/to/aarch64-linux-gnu-tools/bin/&gt; make clean
+PATH=$PATH:&lt;path/to/aarch64-linux-gnu-tools/bin/&gt; CROSS_COMPILE=&lt;gcc-prefix&gt; make
+</code></pre>
+
+<p>The <code>gcc-prefix</code> depends on the specific toolchain distribution used. It can be
+"aarch64-linux-gnu-" for example.</p>
+
+<p>This will result in four <code>axf</code> files:</p>
+
+<ul>
+<li><p>uefi-bootstrap-el3 : The bootstrap jumps to the UEFI code in FLASH without
+                 changing anything.</p></li>
+<li><p>uefi-bootstrap-el2 : Setup EL3 and switch the model to EL2 before jumping to the
+                 UEFI code in FLASH.</p></li>
+<li><p>uefi-bootstrap-el1 : Setup EL3 and prepare to run at non-secure EL1. Switch to
+                 non-secure EL1 and run the UEFI code in FLASH.</p></li>
+<li><p>uefi-bootstrap-el3-foundation : The bootstrap jumps to the UEFI code in RAM
+                 without changing anything. Only to be used with the
+                 Foundation model. The Foundation model does not have
+                 non-secure memory at address <code>0x0</code> and thus the UEFI image
+                 should be pre-loaded into non-secure RAM at address
+                 <code>0xA0000000</code>.</p></li>
+</ul>
+
+<h2>Use on ARMv8 RTSM and FVP models</h2>
+
+<p>Add the '-a' option to the model start script and point to the required
+bootstrap:</p>
+
+<pre><code>&lt; ... model start script as described in top-level readme file ... &gt;
+ -a &lt;path/to/bootstrap-binary-file&gt;
+</code></pre>
+
+<p>NOTE: The Foundation model bootstrap should not be used with these models.</p>
+
+<h2>Use on ARMv8 Foundation model</h2>
+
+<p>The Foundation model takes an option for an ELF file to be loaded as well as an
+option to load a binary data blob into RAM. This can be used to run UEFI in the
+following manner:</p>
+
+<pre><code>&lt;PATH_TO_INSTALLED_FOUNDATION_MODEL&gt;/Foundation_v8 --cores=2 --visualization
+  --image=uefi-bootstrap-el3-foundation.axf --nsdata=RTSM_VE_FOUNDATIONV8_EFI.fd@0xA0000000
+</code></pre>
+
+<p>NOTE: The RTSM version of the bootstraps and UEFI image will not work as
+      expected on the Foundation model. Foundation model specific versions
+      should be used.</p>
diff --git a/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.txt b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.txt
new file mode 100644
index 0000000000..1d4b174557
--- /dev/null
+++ b/ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.txt
@@ -0,0 +1,92 @@
+AArch64 UEFI bootstraps
+=======================
+
+Copyright (c) 2011-2013 ARM Limited. All rights reserved.
+See the `LICENSE.TXT` file for more information.
+
+Contents:
+
+* Introduction
+* Build
+* Use on ARMv8 RTSM and FVP models
+* Use on ARMv8 Foundation model
+
+
+Introduction
+------------
+
+A bootstrap can be used to change the model state, like the Exception
+Level (EL), before executing the UEFI binary.
+
+For the ARMv8 RTSM and FVP models this can be used to show/test the UEFI binary
+starting at different exception levels. The ARMv8 models start at EL3 by
+default.
+
+In the case of the Foundation model a bootstrap is required to jump to the
+UEFI binary as loaded in RAM. This is required as the Foundation model cannot
+load and execute UEFI binaries directly. The Foundation model can only load and
+execute ELF binaries.
+
+
+Build
+-----
+
+Build the bootstraps using a AArch64 GCC cross-compiler. By default the
+`Makefile` is configured to assume a GCC bare-metal toolchain:
+
+    PATH=$PATH:<path/to/baremetal-tools/bin/> make clean
+    PATH=$PATH:<path/to/baremetal-tools/bin/> make
+
+To build the bootstraps with a Linux GCC toolchain use the following
+commands:
+
+    PATH=$PATH:<path/to/aarch64-linux-gnu-tools/bin/> make clean
+    PATH=$PATH:<path/to/aarch64-linux-gnu-tools/bin/> CROSS_COMPILE=<gcc-prefix> make
+
+The `gcc-prefix` depends on the specific toolchain distribution used. It can be
+"aarch64-linux-gnu-" for example.
+
+This will result in four `axf` files:
+
+* uefi-bootstrap-el3 : The bootstrap jumps to the UEFI code in FLASH without
+                     changing anything.
+
+* uefi-bootstrap-el2 : Setup EL3 and switch the model to EL2 before jumping to the
+                     UEFI code in FLASH.
+
+* uefi-bootstrap-el1 : Setup EL3 and prepare to run at non-secure EL1. Switch to
+                     non-secure EL1 and run the UEFI code in FLASH.
+
+* uefi-bootstrap-el3-foundation : The bootstrap jumps to the UEFI code in RAM
+                     without changing anything. Only to be used with the
+                     Foundation model. The Foundation model does not have
+                     non-secure memory at address `0x0` and thus the UEFI image
+                     should be pre-loaded into non-secure RAM at address
+                     `0xA0000000`.
+
+
+Use on ARMv8 RTSM and FVP models
+--------------------------------
+
+Add the '-a' option to the model start script and point to the required
+bootstrap:
+
+    < ... model start script as described in top-level readme file ... >
+     -a <path/to/bootstrap-binary-file>
+
+NOTE: The Foundation model bootstrap should not be used with these models.
+
+
+Use on ARMv8 Foundation model
+-----------------------------
+
+The Foundation model takes an option for an ELF file to be loaded as well as an
+option to load a binary data blob into RAM. This can be used to run UEFI in the
+following manner:
+
+    <PATH_TO_INSTALLED_FOUNDATION_MODEL>/Foundation_v8 --cores=2 --visualization
+      --image=uefi-bootstrap-el3-foundation.axf --nsdata=RTSM_VE_FOUNDATIONV8_EFI.fd@0xA0000000
+
+NOTE: The RTSM version of the bootstraps and UEFI image will not work as
+      expected on the Foundation model. Foundation model specific versions
+      should be used.