How to build and install SP7021 Linux image to run Raspbian on SD card

The goal of the document is to illustrate how to build and install SP7021 (Plus 1) image to run Raspbian on SD card. Raspbian is a famous and popular Linux distribution. It is based Debian and for running on Raspberry Pi boards. Raspbian is released in form of SD card image. Raspbian image file of SD card can be downloaded from web of Raspbian foundation. Users can then write the image file into an SD card. The SD card image consists of two partitions. One is boot partition which is formatted to DOS/Windows FAT32 file-system and the other is rootfs partition which is formatted to Linux Ext4 file-system. boot partition contains files, including boot-loader, Linux kernel image, and etc, for booting from Raspberry Pi boards. rootfs partition contains files of whole root file-system of Linux. You need to copy SP7021 boot-loader and Linux kernel image, and etc files to boot partition. Also, you need to copy some module files of Linux kernel to rootfs partition. Since SP7021 files have different file name, original files of Raspbian will not be overwritten. The new-made SD card can be boot either from Raspberry Pi boards or SP7021 boards. Please follow the following steps to build and install Plus 1 image to run Raspbian.

1. Download source files

Source files of SP7021 can be downloaded from GitHub or Yocto server of SP7021. Refer to GitHub - sunplus-plus1/SP7021 or 2. HOW TO GET SOURCE FILE AND PACKAGE. Refer to report of ll command for the contents of top folder of source of SP7021:

wellslu@scdiu3:~/q628/sdc$ ll
total 52
drwxr-xr-x 12 wellslu sp 4096 Oct 15 12:08 ./
drwxr-xr-x 19 wellslu sp 4096 Oct 15 12:03 ../
drwxr-xr-x  8 wellslu sp 4096 May 26 17:29 boot/
drwxr-xr-x  4 wellslu sp 4096 Aug 25 17:17 build/
drwxr-xr-x  7 wellslu sp 4096 Aug 19 11:45 crossgcc/
drwxr-xr-x  6 wellslu sp 4096 Sep  9  2019 eCos/
drwxr-xr-x  9 wellslu sp 4096 Jun  5 19:10 freertos/
drwxr-xr-x  8 wellslu sp 4096 Aug 19 11:45 ipack/
drwxr-xr-x  7 wellslu sp 4096 Sep  9  2019 linux/
-r--r--r--  1 wellslu sp   23 Sep  9  2019 Makefile
drwxr-xr-x  4 wellslu sp 4096 Sep  9  2019 nonos/
drwxr-xr-x  7 wellslu sp 4096 Sep  9  2019 .repo/
drwxr-xr-x  3 wellslu sp 4096 Jun 29 10:43 yocto/

2. Configure environment

Run make config command on top folder. After configuration menu pops up, first, choose board you want to build image for. For example, press 4 for SP7021 Demo Board (V3)https://sunplus-tibbo.atlassian.net/browse/SP7021-679. Second, press 2 and then enter to start to configure building environment. Refer to screenshot below,

Wait for ‘make config’ completing.

3. Modify device-tree source file

Modify display-format (frame-buffer format) in node sp_display (which is a label to sp_display@0x9c005c80) in device-tree source file "linux/kernel/arch/arm/boot/dts/sp7021-demov3.dts" as shown below:

&sp_display {
	ui_width = <1280>;
	ui_height = <720>;
	ui_format = <0x8>;
		/* 0x2 = 8bpp (ARGB)
		 * 0x4 = YUY2
		 * 0x8 = RGB565
		 * 0x9 = ARGB1555
		 * 0xa = RGBA4444
		 * 0xb = ARGB4444
		 * 0xd = RGBA8888
		 * 0xe = ARGB8888 */
};

Note that ui_width is revised to 1280, ui_height is revised to 720, and ui_format is revised to 0x8 (RGB565).

Also, modify other items of device-tree source you want.

4. Configure kernel

Run make menuconfig to config features of Linux kernel you want.

5. Build all images

Run make all to build all (x-boot, u-boot, kernel, dtb and etc.).

6. Download Raspbian image file

Download Raspbian image file, for example “2019-07-10-raspbian-buster-full.zip“ from https://www.raspberrypi.org/downloads/raspbian/.

7 . Unzip image file

Raspbian image file from web is a zipped image file. You need to unzip it. For example, you can use 7-zip to unzip image file. First, download 7-zip from web: https://www.7-zip.org/download.html

Second, run '7-zip' to unzip image file.

8. Write (Burn) the unzip image file to an SD card

Use Win32DiskImager, BalenaEther or other SD card writers to write the unzip Raspbian image to an SD card. Note that size of SD card should be greater than 8 GB. Refer to step 4 of How to build SP7021 Linux image for booting from SD card for how to write image file to an SD card.

9. Copy files to boot partition of SD card

Copy the following files to boot partition of SD card:

out/boot2linux_SDcard/ISPBOOOT.BIN

out/boot2linux_SDcard/u-boot.img

out/boot2linux_SDcard/uImage

out/boot2linux_SDcard/uEnv.txt

out/boot2linux_SDcard/a926.img (optional image for ARM926)

10. Copy Linux modules to rootfs partition of SD card

Copy the following files to ‘/lib/modules/$(uname -r)/’ of rootfs partition of SD card:

linux/rootfs/initramfs/disk/lib/modules/$(uname -r)/kernel/

linux/rootfs/initramfs/disk/lib/modules/$(uname -r)/modules.*

For example, if $(uname -r)=“5.4.35-SUNPLUS-v7+”, please copy

linux/rootfs/initramfs/disk/lib/modules/5.4.35-SUNPLUS-v7+/kernel/

linux/rootfs/initramfs/disk/lib/modules/5.4.35-SUNPLUS-v7+/modules.*

to

/lib/modules/5.4.35-SUNPLUS-v7+/

of rootfs partition of SD card.

Note $(uname -r) is kernel release of SP7021 Linux, instead of kernel release of your Linux PC.

11. Modify script file for resizing rootfs partition of SD card

The latest version of Raspbian uses hardware random number generator (/dev/hwrng) to generate new Disk identifier SD card in process of resizing rootfs partition. Refer to snapshot of the script file, /usr/lib/raspi-config/init_resize.sh, for resizing:

Look at line 80, hardware random number generator device, /dev/hwrng, is used to generate DISKID.

Because SP7021 does not support hardware random number generator, we need to modify the line to use software random number (/dev/urandom) instead. Refer to snapshot of modified script file:

12. Modify uEnv.txt to run script, init_resize.sh for the first boot.

After U-Boot completes internal initialization, it runs uenvcmd command defined in script file uEnv.txt in boot partition. Refer to snapshot of original uEnv.txt file, Line 16 defines the uenvcmd command.

Please add run sRpi_args command as below:

sRpi_args command will parse Raspbian file cmdline.txt (in boot partition) and add init=/usr/lib/raspi-config/init_resize.sh to bootargs. At first boot, Linux runs /usr/lib/raspi-config/init_resize.sh as init process. init_resize.sh will then extend rootfs partition to end of SD card.

At second boot, resize2fs is invoked (in background) to extend file-system of rootfs partition.

13. Remove loading i2c-dev module

Refer to file /etc/modules-load.d/modules.conf in rootfs partition:

# /etc/modules: kernel modules to load at boot time.
#
# This file contains the names of kernel modules that should be loaded
# at boot time, one per line. Lines beginning with "#" are ignored.

i2c-dev

By default, kernel module, i2c-dev, will be loaded automatically. But I2c-dev is a Raspbian native i²C module for Raspberry boards. It cannot run on SP7021 board. Please comment it out. For example:

Note: You may skip this step if your source does not have the line “i2c-dev”.

14. Use software random number device

There is no hardware random number generator (/dev/hwrng) in SP7021. Please redirect /dev/hwrng to /dev/urandom in file /etc/default/rng-tools:

in which line “HRNGDEVICE=/dev/hwrng” is commented out and line “HRNGDEVICE=/dev/urandom” is added.

15. Install hardware and power on your board

a) Insert the SD card to SD card socket.

b) Set DIP-SW to for booting from SD card.

c) Install your USB keyboard, mouse, HDMI monitor and Ethernet cable (optional).

d) Install your UART console, Please set Baud-rate to 115,200 (optional).

e) Turn on power of your Plus 1 board and wait for system booting up.

16. Login Raspbian

After Raspbian boots up successfully, it will ask you to enter account name and password. The default user of Raspbian is pi, and the default password is raspberry.

Refer to screenshot of console below, Linux version is 5.4.35 and size of root folder has been extended to 16 GB.

17. Run depmod

After logging-in, please run depmod command to create a list of module dependencies. Linux needs the dependency list to know which module it needs to load when modules are probing.

Appendix: sudo command

You can use the sudo command to provide access as the superuser, root. For example, if you want to install additional software, gnome-disks, on Raspbian, then you need to prefix the apt-get command with sudo as below:

sudo apt-get install gnome-disk-utility