How to install GRUB 2 on SP7021 platforms

The goal of the document is to illustrate how to install GRUB 2 (grub-uboot) on an SD card with SP7021 Linux kernel. Refer to https://sunplus-tibbo.atlassian.net/wiki/spaces/doc/pages/662569085 or https://sunplus-tibbo.atlassian.net/wiki/spaces/doc/pages/461045886 for creating an SD card with Linux kernel. After creating your SD card, your SD card should contain two partitions. One is called boot partition and the other is called rootfs partition. boot partition is formatted with FAT32 file system. Boot-loader, kernel and other related files are put here. After power-on, SP7021 loads boot-loader and starts its booting processes. Refer to screenshot of list of boot partition:

We need to create folder /efi/boot in boot partition and copy files to in step 1.

rootfs partition is formatted with ext3 or ext4 file system. Linux root and its sub-folders are put here. Refer to screenshot of list of rootfs partition:

We need to create folder /boot and /boot/grub in rootfs partition and copy files to in step 2. Please follow the following steps to install GRUB to your SD card.

1. Copy GRUB efi files

Copy efi files, bootarm.efi and bootaa64.efi, to folder /efi/boot of boot partition (FAT32). Refer to screenshot of list of folder /efi/boot of boot partition:

bootarm.efi is for ARM armhf architecture and bootaa64.efi is for ARM arm64 architecture. The second file is optional. The folder also contains grub configuration file, grub.cfg, which instructs grub what to do. It is a text file. You can use a text editor to read or edit it. File, efi-boot.7z, contains all files in folder efi/boot:

2. Copy Linux kernel and GRUB files

Copy file zImage (compressed Linux kernel) to folder /boot of rootfs partition (ext3 or ext4). Copy whole grub folder to folder /boot/grub of rootfs partition. Refer to screenshot of list of folder /boot and /boot/grub:

Folder, arm-efi, contains module files of grub, including *.mod and *.lst. Folder, fonts, contains fonts of grub. Folder, locale, contains language files of grub. File, boot-grub.7z, contains all files in folder boot/grub:

3. Modify config file of GRUB

Modify uuid of /efi/boot/grub.cfg to uuid of rootfs partition. Refer to content of file, /efi/boot/grub.cfg, below:

set btrfs_relative_path="yes"
search --fs-uuid --set=root 190b3b5a-f187-4128-ab49-bd8f3eb077ff
#search --label --set=root BPI-ROOT
#set prefix=($root)/boot/grub2
set prefix=($root)/boot/grub
normal

search command will search rootfs partition with uuid equaling to 190b3b5a-f187-4128-ab49-bd8f3eb077ff and set variable, root, to it. Please modify uuid to uuid of your rootfs partition. Variable, prefix, is set to folder of grub in rootfs. The last command is normal which means to boot in normal mode.

4. Write config file of GRUB

Write GRUB configure file in rootfs partition, /boot/grub/grub.cfg. Refer to grub.cfg in attached file, boot-grub.7z.

This configuration file defines three menu entries, “Sunplus SP7021 GNU/Linux 4.19.37”, “Sunplus SP7021 GNU/Linux 4.19.37 (recovery mode)”, and “Sunplus SP7021 GNU/Linux 4.19.37 (debug mode)”.

5. Modify u-boot environment file

Modify u-boot environment file “uEnv.txt” as shown below:

#
## uEnv.txt
#
## grub-uboot
uenvcmd=\
	echo Found EFI removable media binary /efi/boot/bootarm.efi; \
	load ${isp_if} ${isp_dev}:1 ${addr_dst_kernel} /efi/boot/bootarm.efi; \
	bootefi ${addr_dst_kernel} ${fdtcontroladdr};
#
## END
#

load command loads grub efi file, /efi/boot/bootarm.efi, to memory addressed $addr_dst_kernel.

bootefi command jumps to run grub efi file, /efi/boot/bootarm.efi loaded in memory. Address of dtb of u-boot, $fdtcontroladdr, is put as the second argument of bootefi command.

6. Boot Linux system

Boot the system. You will see GRUB menu. Use Up- or Down-key to select the entry and press Enter to boot the selected OS.

7. Appendix:

To support grub-uboot, the following feature of u-boot should be enabled.

a) Enable bootefi commands.

Move cursor to go to sub menu “Command line interface” → “Boot commands”. Enable “bootefi”. Refer to screenshot of sub menu “Boot commands” below:

b) Enable “Support running EFI Applications in U-Boot”

Move cursor to go to sub menu “Library routines” and enable “Support running EFI Applications in U-Boot”. Refer to screenshot of sub menu “Library routines” below:

c) Enable ext2, ext4 and FAT command support and filesystem commands.

Move cursor to go to sub menu “Command line interface” → “Filesystem commands”. Enable “ext2 command support”, “ext4 command support”, “FAT command support” and “filesystem commands”. Refer to screenshot of sub menu “Library routines” below:

Enabling “ext2 command support” will enable support of ext2load and ext2ls commands. Enabling “ext4 command support” will enable support of ext4load, ext4ls, and ext4size commands. Enabling “FAT command support” will enable support of fatinfo, fatload, fatls, and fatsize commands. Enabling “filesystem commands” will enable support of fstype, load, ls, save, and size commands.