ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/readme.txt

   1 AArch64 UEFI bootstraps
   2 =======================
   3
   4 Copyright (c) 2011-2013 ARM Limited. All rights reserved.
   5 See the `LICENSE.TXT` file for more information.
   6
   7 Contents:
   8
   9 * Introduction
  10 * Build
  11 * Use on ARMv8 RTSM and FVP models
  12 * Use on ARMv8 Foundation model
  13
  14
  15 Introduction
  16 ------------
  17
  18 A bootstrap can be used to change the model state, like the Exception
  19 Level (EL), before executing the UEFI binary.
  20
  21 For the ARMv8 RTSM and FVP models this can be used to show/test the UEFI binary
  22 starting at different exception levels. The ARMv8 models start at EL3 by
  23 default.
  24
  25 In the case of the Foundation model a bootstrap is required to jump to the
  26 UEFI binary as loaded in RAM. This is required as the Foundation model cannot
  27 load and execute UEFI binaries directly. The Foundation model can only load and
  28 execute ELF binaries.
  29
  30
  31 Build
  32 -----
  33
  34 Build the bootstraps using a AArch64 GCC cross-compiler. By default the
  35 `Makefile` is configured to assume a GCC bare-metal toolchain:
  36
  37     PATH=$PATH:<path/to/baremetal-tools/bin/> make clean
  38     PATH=$PATH:<path/to/baremetal-tools/bin/> make
  39
  40 To build the bootstraps with a Linux GCC toolchain use the following
  41 commands:
  42
  43     PATH=$PATH:<path/to/aarch64-linux-gnu-tools/bin/> make clean
  44     PATH=$PATH:<path/to/aarch64-linux-gnu-tools/bin/> CROSS_COMPILE=<gcc-prefix> make
  45
  46 The `gcc-prefix` depends on the specific toolchain distribution used. It can be
  47 "aarch64-linux-gnu-" for example.
  48
  49 This will result in four `axf` files:
  50
  51 * uefi-bootstrap-el3 : The bootstrap jumps to the UEFI code in FLASH without
  52                      changing anything.
  53
  54 * uefi-bootstrap-el2 : Setup EL3 and switch the model to EL2 before jumping to the
  55                      UEFI code in FLASH.
  56
  57 * uefi-bootstrap-el1 : Setup EL3 and prepare to run at non-secure EL1. Switch to
  58                      non-secure EL1 and run the UEFI code in FLASH.
  59
  60 * uefi-bootstrap-el3-foundation : The bootstrap jumps to the UEFI code in RAM
  61                      without changing anything. Only to be used with the
  62                      Foundation model. The Foundation model does not have
  63                      non-secure memory at address `0x0` and thus the UEFI image
  64                      should be pre-loaded into non-secure RAM at address
  65                      `0xA0000000`.
  66
  67
  68 Use on ARMv8 RTSM and FVP models
  69 --------------------------------
  70
  71 Add the '-a' option to the model start script and point to the required
  72 bootstrap:
  73
  74     < ... model start script as described in top-level readme file ... >
  75      -a <path/to/bootstrap-binary-file>
  76
  77 NOTE: The Foundation model bootstrap should not be used with these models.
  78
  79
  80 Use on ARMv8 Foundation model
  81 -----------------------------
  82
  83 The Foundation model takes an option for an ELF file to be loaded as well as an
  84 option to load a binary data blob into RAM. This can be used to run UEFI in the
  85 following manner:
  86
  87     <PATH_TO_INSTALLED_FOUNDATION_MODEL>/Foundation_v8 --cores=2 --visualization
  88       --image=uefi-bootstrap-el3-foundation.axf --nsdata=RTSM_VE_FOUNDATIONV8_EFI.fd@0xA0000000
  89
  90 NOTE: The RTSM version of the bootstraps and UEFI image will not work as
  91       expected on the Foundation model. Foundation model specific versions
  92       should be used.