HiKeyUEFI

lxzh edited this page May 7, 2018 · 81 revisions

HiKey - UEFI

Table of Contents

NOTE: Throughout this document, when you see Jumper pin1-6 on J15, it refers to original HiKey boards built by CircuitCoR. If the board you have is built by LEMAKERR, then read these as "Jumper pin1-6 on J601"

The following binaries are required:

  • l-loader.bin - used to switch from aarch32 to aarch64 and boot
  • fip.bin - firmware package
  • ptable-aosp-[4g|8g].img or ptable-linux-[4g|8g].img - partition tables for respectively AOSP images or Linux images
  • kernel and dtb images - included in the boot partition

Install from prebuilt binaries

Latest UEFI snapshot builds are published here. Download the following files:

Note: Latest UEFI release build is published here, and you can go to this link to get the prebuilt binaries.

Latest Debian snapshot builds are published here. You can pick a boot partition and an eMMC rootfs:

  • boot-fat.uefi.img.gz
  • hikey-jessie_developer_YYYYMMDD-XXX-4g.emmc.img.gz or hikey-jessie_developer_YYYYMMDD-XXX-8g.emmc.img.gz

Latest Debian release build is published here.

For example, to download the latest UEFI build and Debian build:

wget https://builds.96boards.org/releases/hikey/linaro/uefi-openplatformpkg/latest/l-loader.bin
wget https://builds.96boards.org/releases/hikey/linaro/uefi-openplatformpkg/latest/fip.bin
wget https://builds.96boards.org/releases/hikey/linaro/uefi-openplatformpkg/latest/ptable-linux.img
wget https://builds.96boards.org/releases/hikey/linaro/debian/latest/boot-fat.uefi.img.gz
wget https://builds.96boards.org/releases/hikey/linaro/debian/latest/hikey-jessie_developer_YYYYMMDD-XXX-4g.emmc.img.gz (or hikey-jessie_developer_YYYYMMDD-XXX-8g.emmc.img.gz)
gunzip *.img.gz

Now skip to the Flash binaries to eMMC section.

Source code

The source code is available from:

Build instructions

Prerequisites:

  • GCC 4.8 or 4.9 - cross-toolchain for Aarch64 available in your PATH. Linaro GCC 4.9-2015.02 is used in the build instructions.
  • GCC cross-toolchain for gnueabihf available in your PATH. Linaro GCC 4.9-2015.02 is used in the build instructions.
  • GPT fdisk (gdisk package from your favorite distribution).

Install custom toolchain(s)

mkdir arm-tc arm64-tc
tar --strip-components=1 -C ${PWD}/arm-tc -xf gcc-linaro-4.9-*-x86_64_aarch64-linux-gnu.tar.xz
tar --strip-components=1 -C ${PWD}/arm64-tc -xf gcc-linaro-4.9-*-x86_64_arm-linux-gnueabihf.tar.xz
export PATH="${PWD}/arm-tc/bin:${PWD}/arm64-tc/bin:$PATH"

Get the source code

UEFI_TOOLS_GIT_URL=https://git.linaro.org/uefi/uefi-tools.git
UEFI_TOOLS_GIT_BRANCH=master
EDK2_GIT_URL=https://github.com/96boards-hikey/edk2.git
EDK2_GIT_VERSION="origin/hikey-aosp"
ATF_GIT_URL=https://github.com/96boards-hikey/arm-trusted-firmware.git
ATF_GIT_VERSION="origin/hikey"
OPEN_PLATFORM_PKG_GIT_URL=https://github.com/96boards-hikey/OpenPlatformPkg.git
OPEN_PLATFORM_PKG_GIT_BRANCH=hikey-aosp
OPTEE_OS_GIT_URL=https://github.com/OP-TEE/optee_os.git
OPTEE_GIT_VERSION=master

export AARCH64_TOOLCHAIN=GCC49

git clone https://github.com/96boards-hikey/l-loader.git
git clone -b $UEFI_TOOLS_GIT_BRANCH $UEFI_TOOLS_GIT_URL uefi-tools

git clone $EDK2_GIT_URL edk2
cd edk2
git checkout -b stable-baseline $EDK2_GIT_VERSION
cd ..

git clone -b $OPEN_PLATFORM_PKG_GIT_BRANCH $OPEN_PLATFORM_PKG_GIT_URL OpenPlatformPkg

cd edk2
rm -rf OpenPlatformPkg
ln -s ../OpenPlatformPkg
cd ..

git clone $ATF_GIT_URL arm-trusted-firmware
cd arm-trusted-firmware
git checkout -b stable-baseline $ATF_GIT_VERSION
cd ..

git clone $OPTEE_OS_GIT_URL optee_os
cd optee_os
git checkout -b stable-baseline $OPTEE_GIT_VERSION
cd ..

Build UEFI for HiKey

export EDK2_DIR=${PWD}/edk2
export ATF_DIR=${PWD}/arm-trusted-firmware
export OPTEE_OS_DIR=${PWD}/optee_os
export UEFI_TOOLS_DIR=${PWD}/uefi-tools

cd ${EDK2_DIR}
bash -x ${UEFI_TOOLS_DIR}/uefi-build.sh -T GCC49 -b RELEASE -a ${ATF_DIR} -s ${OPTEE_OS_DIR} hikey

# To use UART0 instead of UART3 as the console, uncomment the appropriate line(s) in
# ${UEFI_TOOLS_DIR}/platforms.config before running the command above.

cd ../l-loader
ln -s ${EDK2_DIR}/Build/HiKey/RELEASE_GCC49/FV/bl1.bin
ln -s ${EDK2_DIR}/Build/HiKey/RELEASE_GCC49/FV/fip.bin
make # requires sudo for creating the partition tables

The files fip.bin, l-loader.bin and ptable-linux.img are now built. All the image files are in $BUILD/l-loader directory. The Fastboot App is at $EDK2_DIR/Build/HiKey/RELEASE_GCC49/AARCH64/AndroidFastbootApp.efi

Create or modify menu entry in GRUB

GRUB is the loader to OS. Now both debian and AOSP are booted by GRUB on HiKey. If user wants to create his own kernel, creating a new menu entry is preferred.

grub.cfg is stored in /EFI/BOOT directory of boot partition (boot-fat.uefi.img). Append new entry in grub.cfg. In this case, only custom kernel and dtb file are stored in rootfs. And still use the initrd that are installed in rootfs.

menuentry 'Custom Kernel' {
    search.fs_label rootfs root
    search.fs_label boot esp
    linux ($esp)/Image console=tty0 console=ttyAMA3,115200 root=/dev/disk/by-partlabel/system rootwait rw efi=noruntime
    initrd ($root)/boot/initrd.img
    devicetree ($esp)/hi6220-hikey.dtb
}

User can also store custom kernel & dtb file into rootfs. Just update grub.cfg according to the change.

Since boot partition could be mounted after system boot, user could edit grub.cfg directly. Or user could unpack boot-fat.uefi.img, edit it and pack again.

EFI boot partition (boot-fat.uefi.img)

The boot partition is a 64MB FAT partition. In prebuilt boot partition, there are grubaa64.efi, grub.cfg and fastboot.efi. Kernel, initrd and dtb files are stored in rootfs (partition 9 in eMMC).

If user wants to create his own boot partition, it's better to be based on prebuilt boot-fat.uefi.img. See Getting Started instructions for more information on building the kernel. See GRUB section for more information on creating new entry in grub.cfg.

$ mkdir -p boot-fat
$ sudo mount -o loop,rw,sync boot-fat.uefi.img boot-fat
# command to copy custom kernel & dtb file into boot-fat
$ sync
$ sudo umount boot-fat.uefi.img

Flash binaries to eMMC

The flashing process requires to be in recovery mode if user wants to update l-loader.bin.

  • turn off HiKey board
  • connect debug UART on HiKey to PC (used to monitor debug status)
  • make sure pin1-pin2 and pin3-pin4 on J15 are linked (recovery mode)
Name Link State
Auto Power up Link 1-2 closed
Boot Select Link 3-4 closed
GPIO3-1 Link 5-6 open
  • connect HiKey Micro-USB to PC with USB cable
  • turn on HiKey board
  • on serial console, you should see some debug message (NULL packet)
  • run HiKey recovery tool to flash l-loader.bin (Note: if the serial port recorded in hisi-idt.py isn't available, adjust the command line below by manually setting the serial port with "-d /dev/ttyUSBx" where x is usually the last serial port reported by "dmesg" command)
$ sudo python hisi-idt.py --img1=l-loader.bin

do not reboot yet

  • run fastboot commands to flash the images (order must be respected)
$ wget https://builds.96boards.org/releases/hikey/linaro/binaries/latest/nvme.img
$ sudo fastboot flash ptable ptable-linux.img
$ sudo fastboot flash fastboot fip.bin
$ sudo fastboot flash nvme nvme.img
$ sudo fastboot flash boot boot-fat.uefi.img
$ sudo fastboot flash system hikey-jessie_alip_2015MMDD-nnn.emmc.img
  • turn off HiKey board
  • remove the jumper of pin3-pin4 on J15
Name Link State
Auto Power up Link 1-2 closed
Boot Select Link 3-4 open
GPIO3-1 Link 5-6 open
  • turn on HiKey board

Note: UEFI may report "Fail to start BootNext" if you have an SD card installed, see Boot Sequence for more information.

Run Fastboot from UEFI

  • make sure that jumper of pin5-pin6 on J15 are connected
Name Link State
Auto Power up Link 1-2 closed
Boot Select Link 3-4 open
GPIO3-1 Link 5-6 closed
  • Or Interrupt the boot by pressing any select
The default boot selection will start in 10 seconds
[1] fastboot
[2] boot from eMMC
[3] boot from SD card
[4] Shell
[5] Boot Manager
Start:
  • At the "Shell>" prompt, type: fastboot
Shell> fastboot
Android Fastboot mode - version 0.4. Press any key to quit
  • fastboot configuration in host
sudo apt-get install android-tools-fastboot
  • host use:
$ sudo fastboot flash ptable ptable-linux.img
$ sudo fastboot flash fastboot fip.bin  
$ sudo fastboot flash nvme nvme.img  
$ sudo fastboot flash boot boot-fat.uefi.img  
$ sudo fastboot flash system system.img  
$ sudo fastboot flash cache cache.img  
$ sudo fastboot flash userdata userdata.img  
# l-loader.bin should be flashed in recovery mode only
  • Run Fastboot automatically:

Connect jumper on pin5-6 of J15. Then UEFI will run Fastboot app directly.

Name Link State
Auto Power up Link 1-2 closed
Boot Select Link 3-4 open
GPIO3-1 Link 5-6 closed

If user input "enter" key directly, bootmenu will be displayed.

  • Control Auto Boot
By default, auto boot feature is enabled.

Command to disable auto boot:
$sudo fastboot oem autoboot 0
Command to enable auto boot:
$sudo fastboot oem autoboot 1

HiKey supports booting from both eMMC and microSD card.

Boot Sequence

If auto boot feature is enabled, a predefined boot entry will be selected by default.

Boot entries:
1 -- Android Fastboot App
2 -- grub on eMMC
3 -- SD

If SD card is in slot, booting from SD (entry #3) is the highest priority. Otherwise, system will boot from eMMC (entry #2) instead.

If jumper on pin5-6 of J15 is connected, entry #1 is the highest priority instead.

Although booting from SD is higher priority than booting from eMMC (without jumper on pin5-6), user still can change the priority.

$sudo fastboot oem bootdevice [emmc|sd]
By default, SD card is the boot device. The boot flow is in below.
    a. If boot device is SD card.
         1) If SD card is present, boot from SD card.
         2) If SD card is _not_ present, boot from eMMC.
    b. If boot device is eMMC.
         Always boot from eMMC whether SD card is present or not. It's used when SD card is just mass storage device. For this case, people always leave SD card in slot.

Set Serial Number in recovery mode

  • make sure pin1-pin2 and pin3-pin4 on J15 are linked (recovery mode)
Name Link State
Auto Power up Link 1-2 closed
Boot Select Link 3-4 closed
GPIO3-1 Link 5-6 open
  • Generate new serial number
# In recovery mode, we need to input this command to run initial program with fastboot protocol.
$sudo python hisi-idt.py --img1=l-loader.bin
# Change serial number by custom fastboot command.
$sudo fastboot oem serialno

By default, random serial number is generated in recovery mode. If user wants to generate new serial number, run the above command when hikey is in recovery mode. Then power off. In the next time, fastboot will use the new generated serial number for transmission.

  • Set specified serial number
$sudo fastboot oem serialno set {serialno string, 16 characters long}

Control user led

  • Operate user led
$sudo fastboot oem led1 on
$sudo fastboot oem led1 off

All four leds could be controlled by fastboot command. They are from led1 to led4.

How to Use UART0 as console

By default, UART3 is used as serial console. There's UART3 port on LS connector on HiKey. If user wants to use UART0 instead, he has to change a few things below.

  • Use UART0 as console in ARM Trust Firmware
# Update $CROSS_COMPILE in uefi-tools/atf-build.sh
CROSS_COMPILE="$CROSS_COMPILE" make -j$NUM_THREADS PLAT="$ATF_PLATFORM" $SPD_OPTION DEBUG=$DEBUG CONSOLE=PL011_UART0_BASE CRASH_CONSOLE_BASE=PL011_UART0_BASE

# Rebuild ARM Trust Firmware
  • Use UART0 as console in OP-TEE
# Rerun make with CFG_CONSOLE_UART=0 option
  • Use UART0 as console in UEFI
# Update SERIAL_BASE in HisiPkg/HiKeyPkg/HiKey.dsc file.
DEFINE SERIAL_BASE = 0xF8015000

# Rebuild UEFI
  • Use UART0 as console in kernel
# Update kernel command line in grub.cfg
linux ($root)/boot/Image console=tty0 console=ttyAMA0,115200 console=ttyAMA3,115200 root=/dev/disk/by-partlabel/system rootwait rw quiet efi=noruntime

# Don't need to build kernel again.

Known Issues

  • flashing l-loader.bin to the pseudopartitions is not enabled