1. Compile Linux firmware

1.1. Compile Ubuntu firmware

This chapter introduces the compilation process of Ubuntu firmware. It is recommended to develop under Ubuntu 20.04 system environment. If you use other system versions, you may need to adjust the compilation environment accordingly.

The compilation portion of this tutorial works with SDK versions above v0.1.0a

$ readlink -f .repo/manifest.xml
/home/daijh/p/rk3576/.repo/manifests/rk3576/rk3576_linux_release_20240606_v0.1.0a.xml

1.1.1. Preparatory work

1.1.1.1. Set up compilation environment

sudo apt-get install repo git ssh make gcc libssl-dev liblz4-tool \
expect g++ patchelf chrpath gawk texinfo chrpath diffstat binfmt-support \
qemu-user-static live-build bison flex fakeroot cmake gcc-multilib g++-multilib \
unzip \
device-tree-compiler ncurses-dev \

1.1.2. Compile SDK

1.1.2.1. Precompile Configuration

There are configuration files for different board in device/rockchip/rk3576/, select the configuration file:

./build.sh firefly_rk3576_roc-rk3576-pc_ubuntu_defconfig

1.1.2.2. Build

1.1.2.2.1. Automatic compilation

• Download: Rootfs，put in SDK path

7z x Ubuntu[xx.xx]-xxxx_RK3576_vx.x.xx_xxxxxxxx.7z
mkdir prebuilt_rootfs/
mv Ubuntu[xx.xx]-xxxx_RK3576_vx.x.xx_xxxxxxxx.img prebuilt_rootfs/rk3576_ubuntu_rootfs.img

• start compiling

./build.sh

the firmware will be saved to the directory output/update/.

1.1.2.2.2. Partial compilation

• u-boot

./build.sh uboot

• kernel

./build.sh extboot

• recovery

./build.sh recovery

• Download: Rootfs，put in SDK path

7z x Ubuntu[xx.xx]-xxxx_RK3576_vx.x.xx_xxxxxxxx.7z
mkdir prebuilt_rootfs/
mv Ubuntu[xx.xx]-xxxx_RK3576_vx.x.xx_xxxxxxxx.img prebuilt_rootfs/rk3576_ubuntu_rootfs.img

• Pack the firmware, the firmware will be saved to the directory output/update/.

./build.sh updateimg

1.2. Compile Yocto firmware

1.2.1. Compile

1.2.1.1. Select image

The Yocto project provides some images that can be used without layers. The following table lists currently supported build images and associated recipes.

Image name	Target	provided by layer
core-image-minimal	A small image that only allows a device to boot	Poky
core-image-minimal-xfce	A XFCE minimal demo image	meta-openembedded/meta-xfce
core-image-sato	Image with Sato, a mobile environment and visual style for mobile devices. The image supports X11 with a Sato theme, Pimlico applications, and contains terminal, editor, and file manager	Poky
core-image-weston	A very basic Wayland image with a terminal	Poky
core-image-x11	A very basic X11 image with a terminal	Poky

1.2.2. Build image

The process of building with the bitbake command needs to ensure that the network connection is normal. If it is a customer in inland China, you need to ensure that it can ping the external network

• Enter the directory <path/to/yocto/poky> and execute the following commands in sequence

# Install the required environment packages
# sudo apt install zstd
source oe-init-build-env

# add layer
bitbake-layers add-layer ../../meta-openembedded/meta-oe
bitbake-layers add-layer ../../meta-openembedded/meta-python
bitbake-layers add-layer ../../meta-openembedded/meta-networking
bitbake-layers add-layer ../../meta-openembedded/meta-multimedia
bitbake-layers add-layer ../../meta-openembedded/meta-gnome
bitbake-layers add-layer ../../meta-openembedded/meta-xfce
bitbake-layers add-layer ../../meta-clang
bitbake-layers add-layer ../../meta-browser/meta-chromium
bitbake-layers add-layer ../../meta-rockchip

Choose one of the commands to compile the complete core-image recipes. The following is an x11 based core-image.

MACHINE=roc-rk3576-pc bitbake core-image-minimal
MACHINE=roc-rk3576-pc bitbake core-image-minimal-xfce
MACHINE=roc-rk3576-pc bitbake core-image-x11
MACHINE=roc-rk3576-pc bitbake core-image-sato

The following is a core-image based on wayland. You need to modify DISPLAY_PLATFORM to wayland in /path/to/yocto/meta-rockchip/conf/machine/include/display.conf. Modify as follows:

DISPLAY_PLATFORM ?= "wayland"
# DISPLAY_PLATFORM ?= "x11"

After completing the above modifications, execute the command to compile core-image-weston

MACHINE=roc-rk3576-pc bitbake core-image-weston

Note: If you need to change the compiled core-image recipes after you have already compiled core-image once, you need to clean up the currently compiled core-image and then compile a new core-image.

For example: the currently compiled one is core-image-minimal. You need to change it to core-image-sato.

MACHINE=roc-rk3576-pc bitbake core-image-minimal -c clean
MACHINE=roc-rk3576-pc bitbake core-image-sato

If you want to compile some recipes separately, you can refer to the following:

# kernel
MACHINE=roc-rk3576-pc bitbake linux-rockchip
        
# u-boot
MACHINE=roc-rk3576-pc bitbake u-boot-rockchip
        
# rkmpp
MACHINE=roc-rk3576-pc bitbake rockchip-mpp
        
# rockchip-librga
MACHINE=roc-rk3576-pc bitbake rockchip-librga
        
# See more compilation objects
MACHINE=roc-rk3576-pc bitbake -s

1.2.3. Adjust compilation speed

Modify the BB_NUMBER_THREADS and PARALLEL_MAKE variables in the file /path/to/yocto/meta-rockchip/conf/machine/firefly-rk3576.conf. If the number of threads is set too large, the machine may run out of memory and cause compilation failure. Please set the compilation speed according to the configuration of the compilation machine.

BB_NUMBER_THREADS = "4"
PARALLEL_MAKE = "-j 4"

• BB_NUMBER_THREADS: The maximum number of threads BitBake simultaneously executes.

• BB_NUMBER_PARSE_THREADS: The number of threads BitBake uses during parsing.

• PARALLEL_MAKE: Extra options passed to the make command during the do_compile task in order to specify parallel compilation on the local build host.

• PARALLEL_MAKEINST: Extra options passed to the make command during the do_install task in order to specify parallel installation on the local build host.

1.2.4. More bitbake options

Fundamentally, BitBake is a generic task execution engine that allows shell and Python tasks to be run efficiently and in parallel while working within complex inter-task dependency constraints. One of BitBake’s main users, OpenEmbedded, takes this core and builds embedded Linux software stacks using a task-oriented approach.For more detailed usage, please check《bitbake-user-manual》。

MACHINE=roc-rk3576-pc bitbake <target> <paramater>
# e.g
MACHINE=roc-rk3576-pc bitbake u-boot-rockchip -c clean
MACHINE=roc-rk3576-pc bitbake u-boot-rockchip

Bitbake paramater	Description
-c fetch	Fetches if the downloads state is not marked as done
-c clean	Removes all output files for a target
-c cleanall	Removes all output files, shared state cache, and downloaded source files for a target
-c compile -f	It is not recommended that the source code under the temporary directory is changed directly, but if it is, the Yocto Project might not rebuild it unless this option is used. Use this option to force a recompile after the image is deployed.
-c listtasks	Lists all defined tasks for a target

1.2.5. Partition firmware upgrade

The compiled firmware is located in the directory <path/to/yocto>/build/tmp/deploy/images/<board>/

$ sudo upgrade_tool di -boot boot.img
$ sudo upgrade_tool di -uboot uboot.img
$ sudo upgrade_tool di -misc misc.img
$ sudo upgrade_tool di -recovery recovery.img

• Partition burning is suitable for debugging stage. For firmware verification, please use the unified firmware burning below.

• Rootfs does not support separate burning. You need to pack the complete firmware before burning.

1.2.6. Unified firmware upgrade

The compiled firmware is located in the directory <path/to/yocto>/build/tmp/deploy/images/<board>/, the files to be downloaded are .wic and update.img, and after entering the loader mode, execute the following commands :

$ sudo upgrade_tool wl 0 <IMAGE NAME>.wic
$ sudo upgrade_tool uf update.img

• The default login account of the firmware is: root, password: firefly. The firmware contains a common user account named firefly, and the password is firefly.

Note: If you are developing on a Windows PC, you can use RKdevtool to directly burn update.img, no need to burn <IMAGE NAME>.wic. However, please note that update.img is a link file, so you must select the actual file that the link file points to.

1.2.7. Related overview

The Yocto Project is an open source collaborative project focused on embedded Linux® operating system development that provides a flexible toolset and development environment that allows embedded device developers worldwide to share technologies, software stacks, configurations and tools for creating these customizations Best Practices for Linux Imaging Collaboration. For more information about the Yocto Project, please refer to the official Yocto Project website:www.yoctoproject.org/. The Yocto Project home page has the Yocto Project Reference Manual and the Yocto Project Overview and other related documents describe in detail how to build the system.

1.2.8. Introduction to Yocto Project Release layer

layer	path	priority(The higher the number, the higher the priority)	describe
meta-oe	meta-openembedded/meta-oe	6	contains a large amount of additional recipes
meta-python	meta-openembedded/meta-python	7	Provide Python recipes
meta-qt5	meta-qt5	7	Provides QT5 recipes
meta-clang	meta-clang	7	clang compiler
meta-rockchip	meta-rockchip	9	Rockchip board level support available
meta	meta	5	Contains the OpenEmbedded-Core metadata
meta-poky	meta-poky	5	Holds the configuration for the Poky reference distribution
meta-yocto-bsp	meta-yocto-bsp	5	Configuration for the Yocto Project reference hardware board support package.
meta-chromium	meta-chromium	7	Provide chromium browser recipe