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 13 Trixie,
Debian 13 Trixie 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 (Section 6 Building a Yocto image) 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 python3-setuptools python3-pyelftools libgnutls28-dev \
debhelper rsync
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. Get the TF-A¶
Get the Trusted Firmware-A (or TF-A) 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
# Latest public commit at the time of writing
git checkout 7c35e21a8529b3758d1f051d1a5dc62aae934b2b
export RKBIN_FOLDER="$PWD"
export BL31="$RKBIN_FOLDER/bin/rk35/rk3588_bl31_v1.47.elf"
export ROCKCHIP_TPL="$RKBIN_FOLDER/bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2400MHz_v1.18.bin"
# shellcheck disable=SC2103 # we want to export variables, not possible within subshell
cd ..
# Make the baudrate and console match our U-Boot
sed -i 's/^uart baudrate=.*/uart baudrate=115200/' rkbin/tools/ddrbin_param.txt
sed -i 's/^uart iomux=.*$/uart iomux=2/' rkbin/tools/ddrbin_param.txt
rkbin/tools/ddrbin_tool rk3588 rkbin/tools/ddrbin_param.txt "$ROCKCHIP_TPL"
This step should take under 1 minute total.
5.3. Compile U-Boot¶
Note
Variables BL31 and ROCKCHIP_TPL must be already set as described
in Section 5.2 Get the TF-A .
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 U-Boot
make -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 KBUILD_IMAGE=arch/arm64/boot/Image -j"$(nproc)" bindeb-pkg
)
KERNELRELEASE=$(make -C tiger-linux -s kernelrelease)
# We must take care to not match the "-dbg" package or older builds here
# shellcheck disable=SC2012
TIGER_LINUX_DEB=$(ls -1t "$PWD"/linux-image-"$KERNELRELEASE"_*.deb | head -1)
ls -l "$TIGER_LINUX_DEB"
export TIGER_LINUX_DEB
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_DEB 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
# Make sure there's no deb package from previous kernel builds
rm --force tiger/overlay/var/tmp/linux-*.deb
# Copy linux-image deb package into the ``tiger`` folder.
# It will be installed from within debos.
mkdir --parents --verbose tiger/overlay/var/tmp
cp --verbose "$TIGER_LINUX_DEB" tiger/overlay/var/tmp
# Copy U-Boot binaries into the ``tiger`` folder
cp "$TIGER_UBOOT_DIR"/u-boot-rockchip.bin tiger/
5.5.2. Build a complete image¶
Different variants of Debian images are available. You can build the one of your
choice or all of them. Default variant is Debian 13 Trixie. Other variants
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-VARIANT.XXX.YYY.img
and, for convenience, the symlink sdcard-tiger-debos-VARIANT.img that
always points to the latest version.
5.5.2.1. Debian 13 Trixie¶
# 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
# Or: Build the image using chroot (For inside virtual machines without nesting support)
# build_board=tiger debos_host=chroot ./build.sh
# Make the resulting image available to later steps
export SDCARD_IMG="$PWD/sdcard-tiger-debos-trixie.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, use the debos_host=chroot example as given at the beginning
of the section.
The debos_host=chroot mode uses sudo internally as it requires
root permissions.
5.5.2.2. Debian 13 Trixie with Phosh graphical shell¶
This image variant is targeted for the Haikou-Video-Demo. Please see the DEVKIT ADDON CAM-TS-A01 User Manual for more information about the DEVKIT ADDON CAM-TS-A01.
More details about the Phosh graphical shell can be found in the Phosh graphical shell section.
# Build the image using debos
build_board=tiger debos_variant=trixie-phosh ./build.sh
# Or: Build the image using podman (For host PCs not using Debian)
# build_board=tiger debos_variant=trixie-phosh debos_host=podman ./build.sh
# Or: Build the image using chroot (For inside virtual machines without nesting support)
# build_board=tiger debos_variant=trixie-phosh debos_host=chroot ./build.sh
# Make the resulting image available to later steps
export SDCARD_IMG="$PWD/sdcard-tiger-debos-trixie-phosh.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, use the debos_host=chroot example as given at the beginning
of the section.
The debos_host=chroot mode uses sudo internally as it requires
root permissions.