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 12 Bookworm

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 python3-setuptools python3-pyelftools

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 ATF

Get 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 ROCKCHIP_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 ..

# Make the baudrate match our U-Boot
sed -i 's/uart baudrate=/uart baudrate=115200/' rkbin/tools/ddrbin_param.txt
rkbin/tools/ddrbin_tool 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 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/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 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 JAGUAR_LINUX_DIR="$PWD/jaguar-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 JAGUAR_UBOOT_DIR and JAGUAR_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 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

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

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

5.5.2.1. Debian 12 Bookworm

# 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

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

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