5. Debian image guide#

As opposed to Yocto, Debian does not provide a completely integrated build experience by itself. Linux kernel and U-Boot have to be compiled manually and copied to the appropriate directory to be picked up by Debian build system.

This chapter will go through all neccessary steps, finally building a complete image using the debos Debian image builder. The result will be a fully-functional Debian system.

Alternatively, prebuilt images can be downloaded from https://downloads.embedded.cherry.de/tiger/

At the time of writing this document, the following Debian image variants are available for TIGER SOM-RK3588-Q7:

Debian 12 Bookworm
Debian 12 Bookworm with Phosh graphical shell.

Note

While Debian is a great tool for fast prototyping of your product, it is highly recommended to use a distribution/image tailored to your need. This can be achieved by Yocto or Buildroot for example.

5.1. Prepare the host PC#

The debos Debian OS Builder is only available for Debian and Debian-based distributions (like Ubuntu). This chapter assumes you use Debian or a Debian-based distribution as the host PC.

Install packages for compiling the parts and the complete image:

sudo apt-get -y install debos git build-essential gcc-aarch64-linux-gnu make bison bc flex \
  libssl-dev device-tree-compiler python3-dev python3-pkg-resources swig fdisk \
  bmap-tools python-is-python3

As debos internally uses kvm virtualization, your user must be a member of the kvm group:

sudo adduser "$(id -un)" kvm

Log out and back for the change to take affect. Then verify that kvm is listed in your groups:

id -Gn

Note

If you are not using Debian distribution on your host PC you need to use podman to build debos image:

sudo apt-get install podman

5.2. Compile the ATF#

Get the source code and compile the Arm Trusted Firmware as follows:

# Set up cross-compilation
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-

# Download the source code
git clone https://github.com/rockchip-linux/rkbin
cd rkbin || return
# Tag  linux-5.10-gen-rkr4.1
git checkout "1356c978"
export RKBIN_FOLDER="$PWD"
export BL31="$RKBIN_FOLDER/bin/rk35/rk3588_bl31_v1.38.elf"
export BL32="$RKBIN_FOLDER/bin/rk35/rk3588_bl32_v1.13.bin"
export TPL="$RKBIN_FOLDER/bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2736MHz_v1.11.bin"
# shellcheck disable=SC2103  # we want to export variables, not possible within subshell
cd ..

This step should take under 1 minute total.

5.3. Compile U-Boot#

Note

Variables BL31, BL32, TPL must be already set as described in Section 5.2 Compile the ATF .

Get the source code and compile the U-Boot bootloader as follows:

# Set up cross-compilation
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-

# Download the source code
git clone https://git.embedded.cherry.de/tiger-u-boot.git

(
cd tiger-u-boot || return

# Load u-boot config
make tiger-rk3588_defconfig

# Build idbloader.img
make spl/u-boot-spl.bin -j"$(nproc)"
./tools/mkimage -n rk3588 -T rksd -d "$TPL":spl/u-boot-spl.bin idbloader.img

# Build u-boot.dtb/u-boot.itb
cp "$BL31" bl31.elf
cp "$BL32" tee.bin
make u-boot.dtb u-boot.itb -j"$(nproc)"
)

# Make the resulting file available to later steps
export TIGER_UBOOT_DIR="$PWD/tiger-u-boot"

This step should take about 1 minute total.

5.4. Compile the Linux kernel#

Get the source code and compile the Linux kernel as follows:

# Set up cross-compilation
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-

# Download the source code
git clone https://git.embedded.cherry.de/tiger-linux.git

(
cd tiger-linux || return

# Compile
make tiger-rk3588_defconfig
make -j"$(nproc)"
## Make sure there are no modules from older builds, otherwise may pollute rootfs
## if using debos-recipes instructions.
rm --recursive --force overlay/
make -j"$(nproc)" INSTALL_MOD_PATH=overlay modules_install
)

# Make the resulting files available to later steps
export TIGER_LINUX_DIR="$PWD/tiger-linux"

The time required for this step heavily depends on your internet connection and CPU power. On a quad-core 2.9GHz machine with an 1Gb/s internet connection, it takes about 20 minutes total.

Warning

It is essential the kernel modules installed on the system are built from the exact same sources as the kernel Image itself or the modules will fail to be detected by the kernel.

Note

One can install new modules without needing to recompile the debos image entirely by running the following command:

export IP=10.11.12.13 # set to the IP address of the device
rsync --delete --recursive overlay/lib/modules/ root@"$IP":/lib/modules

Update the kernel Image if there was some change made to it so that it will find the new modules upon reboot.

Reboot for the new modules to be loaded.

5.5. Building the debos image#

5.5.1. Prepare required components#

Note

The variables TIGER_UBOOT_DIR and TIGER_LINUX_DIR must be already set as described in Section 5.3 Compile U-Boot and Section 5.4 Compile the Linux kernel, respectively.

Get the source code for the debos recipe and copy necessary components built in previous steps:

# Download the source code
git clone https://git.embedded.cherry.de/debos-recipes.git
cd debos-recipes || return

# Copy Linux binaries into the ``tiger`` folder
cp "$TIGER_LINUX_DIR"/arch/arm64/boot/Image tiger/overlay/boot/
## Match dtb and dtbo
cp "$TIGER_LINUX_DIR"/arch/arm64/boot/dts/rockchip/rk3588-tiger*.dtb* tiger/overlay/boot/
rm --recursive --force tiger/overlay/lib/modules
mkdir --parents tiger/overlay/lib/modules
cp --archive "$TIGER_LINUX_DIR"/overlay/lib/modules/ tiger/overlay/lib/
## Remove known problematic symlinks as debos would dereference them
rm tiger/overlay/lib/modules/*/build
rm tiger/overlay/lib/modules/*/source

# Copy U-Boot binaries into the ``tiger`` folder
cp "$TIGER_UBOOT_DIR"/idbloader.img tiger/
cp "$TIGER_UBOOT_DIR"/u-boot.itb tiger/

5.5.2. Build a complete image#

Both bookworm and bookworm-phosh Debian images are available. You can build one of your choice or both of them. Default variant is Debian 12 Bookworm. The other variant can be chosen by setting the debos_variant environment variable when running build.sh.

Depending on your host PC and internet connection, this step should complete in about 5-10 minutes.

The resulting image is a file called sdcard-tiger-debos-bookworm.XXX.YYY.img and, for convenience, the symlink sdcard-tiger-debos-bookworm.img that always points to the latest version.

5.5.2.1. Debian 12 Bookworm#

# Build the image using debos
build_board=tiger ./build.sh

# Or: Build the image using podman (for host PCs not using Debian)
# build_board=tiger debos_host=podman ./build.sh

# Make the resulting image available to later steps
export SDCARD_IMG="$PWD/sdcard-tiger-debos-bookworm.img"

Note

When running inside a virtual machine that does not support nesting, you may get an error like this:

open /dev/kvm: no such file or directory

In this case, prepend debos_host=chroot to the build.sh command, resulting in:

debos_host=chroot build_board=tiger ./build.sh

The debos_host=chroot mode uses sudo internally as it requires root permissions.