Boot ACRN Hypervisor

Step-by-Step guide to build a custom SBL to boot ACRN and provision eMMC on UP2.

Note

This is a lengthy but rewarding process. Please expect a few hours to complete this guide.

Prerequisites

Before you start, prepare the following items:

  • Serial debug adapter for UART0 on UP2 - Required to trigger fastboot and perform firmware update
  • Micro USB cable (type A to microB)
  • USB flash drive
  • RECOMMENDED: A SPI programmer in case you brick UP2 and need to restore factory BIOS. See BIOS chip flashing for details.

For more details on setting up the hardware, see UP2 Board.

Build SBL

This section describes how to build a custom SBL with fastboot support.

Step 1: Install tool chains and clone SBL source code from GitHub

Run:

sudo apt-get install -y build-essential iasl python uuid-dev nasm openssl gcc-multilib qemu
git clone https://github.com/slimbootloader/slimbootloader.git
cd slimbootloader
git config --global user.email "email@example.com"
git config --global user.name "your name"

Compile SBL just to verify your setup is complete:

python BuildLoader.py build apl

Step 2: Download additional required images and tools

  1. Download fastboot executable fastboot.elf from here to SBL source directory
  1. Download UP2 BIOS from here and unzip as is in SBL source directory
  1. Download IAS script iasimage from here Run as root the following commands:: # apt-get install python3 python3-pip # pip3 install cryptography==2.2.2 to SBL source directory

Step 3: Generate IAS image containing fastboot.elf

Run:

mkdir -p Platform/ApollolakeBoardPkg/SpiIasBin
touch cmdline.txt
chmod 755 ./iasimage
./iasimage create -o Platform/ApollolakeBoardPkg/SpiIasBin/iasimage1.bin -d ./BootloaderCorePkg/Tools/Keys/TestSigningPrivateKey.pem -i 0x40000 cmdline.txt fastboot.elf
iasimage1.bin

The binary file will be added into SBL image during build process

See Create IAS Boot Image for additional details.

Step 4: Build and stitch

Run:

python BuildLoader.py build apl
python Platform/ApollolakeBoardPkg/Script/StitchLoader.py -i UPA1AM40.bin -s Outputs/apl/Stitch_Components.zip -o sbl_up2_ifwi.bin -p 0xAA00000E -b bios.bin
python BootloaderCorePkg/Tools/GenCapsuleFirmware.py -k ./BootloaderCorePkg/Tools/Keys/TestSigningPrivateKey.pem -o FwuImage.bin -b bios.bin
sbl_up2_ifwi.bin
The binary file to be flashed by BIOS flash tool or SPI programmer
FwuImage.bin
The binary file to be copied to USB flash drive to upgrade SBL from shell command

Flash SBL

This section describes how to update SBL for the first time from UEFI BIOS shell interface.

Step 1: BIOS flash tool is included in the same BIOS package downloaded here

BIOS flash tool is named Fpt_xxx.efi inside the BIOS package.

Step 2: Copy ALL files from the downloaded BIOS package and sbl_up2_ifwi.bin to a USB flash drive formatted in FAT32

Step 3: Insert USB flash drive and boot UP2. Press F7 during boot to enter UEFI shell

Run:

Shell> fs1:
Shell> ls
Shell> Fpt_3.1.50.2222.efi -f sbl_up2_ifwi.bin -y
...
...
FPT Operation Successful.
Shell>

The update process takes a few minutes.

Boot Up

Note

SBL uses UART0 (CN16 connector) for early boot debug messages.

Connect serial adapter between UP2 and the host. Configure host PuTTY or minicom to 115200bps, 8N1, no hardware flow control.

Power on UP2 and observe the following debug messages from serial connection:

BtGuard: VB : 0, MB : 0

============= Intel Slim Bootloader STAGE1A =============
SBID: SB_APLI
ISVN: 001
IVER: 000.005.001.000.05486
SVER: EDC112328CF3E414
FDBG: BLD(D) FSP(R)
FSPV: ID($APLFSP$) REV(01040301)
Loader global data @ 0xFEF01D54
Run  STAGE1A @ 0xFEF80000
Load STAGE1B @ 0xFEF88000
No BtGuard verification !

...

====================Os Loader====================


Press any key within 1 second(s) to enter the command shell
Boot options (in HEX):

...

Enter Fastboot Mode

Currently the only method to enter fastboot mode is by user commands from SBL shell.

Step 1: Reset UP2 and press any key in serial console to enter shell

Step 2: Type user command from shell to enter fastboot mode

Example debug messages (including user commands):

====================Os Loader====================


Press any key within 2 second(s) to enter the command shell

Shell> boot
Boot options (in HEX):

Idx|ImgType|DevType|DevNum|Flags|HwPart|FsType|SwPart|File/Lbaoffset
  0|      0|   MMC |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  1|      0|   MMC |    0 |   0 |    0 |  RAW |    1 | 0x0       <-- ACRN boot option settings
  2|      0|  SATA |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  3|      0|   USB |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  4|      4|   MEM |    0 |   0 |    0 |  RAW |    0 | 0x0       <-- fastboot settings

SubCommand:
  s   -- swap boot order by index
  a   -- modify all boot options one by one
  q   -- quit boot option change
  idx -- modify the boot option specified by idx (0 to 0x4)
s
Enter first index to swap (0x0 to 0x4)
0
Enter second index to swap (0x0 to 0x4)
4
Updated the Boot Option List
Boot options (in HEX):

Idx|ImgType|DevType|DevNum|Flags|HwPart|FsType|SwPart|File/Lbaoffset
  0|      4|   MEM |    0 |   0 |    0 |  RAW |    0 | 0x0
  1|      0|   MMC |    0 |   0 |    0 |  RAW |    1 | 0x0
  2|      0|  SATA |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  3|      0|   USB |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  4|      0|   MMC |    0 |   0 |    0 |  FAT |    0 | iasimage.bin


Shell> exit
Boot options (in HEX):

Idx|ImgType|DevType|DevNum|Flags|HwPart|FsType|SwPart|File/Lbaoffset
  0|      4|   MEM |    0 |   0 |    0 |  RAW |    0 | 0x0
  1|      0|   MMC |    0 |   0 |    0 |  RAW |    1 | 0x0
  2|      0|  SATA |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  3|      0|   USB |    0 |   0 |    0 |  FAT |    0 | iasimage.bin
  4|      0|   MMC |    0 |   0 |    0 |  FAT |    0 | iasimage.bin

BootMediumPciBase(0x1000000)
Getting boot image from... MEM
Try to find boot partition
Part 00: 0xFF9DC000--0xFFB2C000, LBA count: 0x150000
SPI BIOS region: (1 logical partitions)
Find partition success
BootSlot = 0x0
Load image from SwPart (0x0), LbaAddr(0x0)
HASH Verification Success! Component Type (6)
RSA Verification Success!
IAS image is properly signed/verified
IAS size = 0x149404, file number: 2
IAS Image Type = 0x4
cmd Count = [0x0]
Boot image is ELF format...
and Image is Multiboot format
SetupBootImage: Status = Success

...
...
...

Starting MB Kernel ...

 abl cmd 00: console=ttyS0,115200
 abl cmd 00 length: 20
 abl cmd 01: fw_boottime=15230
 abl cmd 01 length: 17
boot target: 1
target=1
Enter fastboot mode ...
Start Send HECI Message: EndOfPost
HECI sec_mode 00000000
GetSeCMode successful
GEN_END_OF_POST size is 4
uefi_call_wrapper(SendwACK) =  0
Group    =000000FF
Command  =0000000C
IsRespone=00000001
Result   =00000000
RequestedActions   =00000000
USB for fastboot transport layer selected   <-- fastboot mode is active now!

Step 4: Verify fastboot connection

Connect USB cable between host and UP2 USB OTG port.

Run (as root):

# apt-get install fastboot

# fastboot devices
HBG4a2428525f7  fastboot

# fastboot getvar version-bootloader
version-bootloader: fastboot-NonAndroid-1.0-userdebug

ACRN How-To

Now it’s time to visit Project ACRN website to build, flash and boot a complete ACRN Hypervisor with UOS on UP2 board.

Upgrade SBL

Sometimes, you may need to update SBL firmware with newer versions on UP2.

Warning

It is highly recommended to have an SPI programmer in case UP2 is bricked after firmware update.

Step 1: Copy FwuImage.bin onto USB flash drive formatted in FAT32

Step 2: Reset UP2 and press any key to enter shell

Run:

Shell>

Shell> fwupdate
HECI SecMode 0
Group    =00000020
Command  =00000007
IsRespone=00000001
Result   =00000000
...
...

The system should start updating and reset itself a few times. If the update is successful, the system should boot into ACRN again.

To confirm the SBL is updated correctly, take notes of the version information from serial debug messages before and after the update:

BtGuard: VB : 0, MB : 0

============= Intel Slim Bootloader STAGE1A =============
SBID: SB_APLI
ISVN: 001
IVER: 000.005.001.000.05482 <-- Last part (05482) is a unique time stamp from build
SVER: C815BBFB25461C98      <-- GIT commit SHA1
FDBG: BLD(D) FSP(R)
FSPV: ID($APLFSP$) REV(01040301)
Loader global data @ 0xFEF01D54
Run  STAGE1A @ 0xFEF80000
Load STAGE1B @ 0xFEF88000
No BtGuard verification !