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/jaguar .

At the time of writing this document, the following Debian image variants are available for Jaguar:

• Debian 13 Trixie

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 the 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=0/' 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/jaguar-u-boot.git

(
cd jaguar-u-boot || return

# Load u-boot config
make jaguar-rk3588_defconfig

# Build U-Boot
make -j"$(nproc)"
)

# Make the resulting file available to later steps
export JAGUAR_UBOOT_DIR="$PWD/jaguar-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/jaguar-linux.git

(
cd jaguar-linux || return

# Compile
make jaguar-rk3588_defconfig
make -j"$(nproc)"
make KBUILD_IMAGE=arch/arm64/boot/Image -j"$(nproc)" bindeb-pkg
)

KERNELRELEASE=$(make -C jaguar-linux -s kernelrelease)
# shellcheck disable=SC2012
JAGUAR_LINUX_DEB=$(ls -1t "$PWD"/linux-image-"$KERNELRELEASE"_*.deb | head -1)
ls -l "$JAGUAR_LINUX_DEB"
export JAGUAR_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 JAGUAR_UBOOT_DIR and JAGUAR_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 the necessary components that were built in the 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 jaguar/overlay/var/tmp/linux-*.deb

# Copy linux-image deb package into the ``jaguar`` folder.
# It will be installed from within debos.
mkdir --parents --verbose jaguar/overlay/var/tmp
cp --verbose "$JAGUAR_LINUX_DEB" jaguar/overlay/var/tmp

# Copy U-Boot binaries into the ``jaguar`` folder
cp "$JAGUAR_UBOOT_DIR"/u-boot-rockchip.bin jaguar/

5.5.2. Build a complete image

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-jaguar-debos-trixie.XXX.YYY.img and, for convenience, the symlink sdcard-jaguar-debos-trixie.img that always points to the latest version.

5.5.2.1. Debian 13 Trixie

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

# Or: Build the image using podman (for host PCs not using Debian)
# build_board=jaguar debos_host=podman ./build.sh
#
# Or: Build the image using chroot (For inside virtual machines without nesting support)
# build_board=jaguar debos_host=chroot ./build.sh

# Make the resulting image available to later steps
export SDCARD_IMG="$PWD/sdcard-jaguar-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.