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.theobroma-systems.com/ringneck/.

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

  • Debian 11 Bullseye (stable),

  • Debian 12 Bookworm (testing) 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

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

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://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
cd trusted-firmware-a

# Use most recent release
LAST_ANNOTATED_V_TAG=$(git describe --abbrev=0 --match "v*")
git checkout "$LAST_ANNOTATED_V_TAG"

TF_LDFLAGS=""

# Fix for aarch64-linux-gnu-ld 2.39+ and TF-A prior to v2.9
# Fix available in commit 1f49db5f25cd ("feat(build): add support for new binutils versions")
if "${CROSS_COMPILE}ld" --no-warn-rwx-segments -v >/dev/null 2>&1; then
	TF_LDFLAGS="-z noexecstack --no-warn-rwx-segments"
fi

# Compile
TF_LDFLAGS="$TF_LDFLAGS" make PLAT=px30 bl31

# Make the resulting file available to later steps
export BL31=$PWD/build/px30/release/bl31/bl31.elf

cd ..

This step should take under 1 minute total.

5.3. Compile U-Boot

Note

The variable BL31 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.theobroma-systems.com/ringneck-u-boot.git
cd ringneck-u-boot

# Compile
make ringneck-px30_defconfig
make -j$(nproc)

# Make the resulting file available to later steps
export RINGNECK_UBOOT_DIR=$PWD

cd ..

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.theobroma-systems.com/ringneck-linux.git
cd ringneck-linux

# Compile
make ringneck-px30_defconfig
make -j$(nproc)

# Make the resulting files available to later steps
export RINGNECK_LINUX_DIR=$PWD

cd ..

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.

5.5. Building the debos image

5.5.1. Prepare required components

Note

The variables RINGNECK_UBOOT_DIR and RINGNECK_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.theobroma-systems.com/debos-recipes.git
cd debos-recipes

# Copy Linux & U-Boot binaries into the ``ringneck`` folder
cp $RINGNECK_LINUX_DIR/arch/arm64/boot/Image ringneck/overlay/boot/
cp $RINGNECK_LINUX_DIR/arch/arm64/boot/dts/rockchip/px30-ringneck*.dtb ringneck/overlay/boot
cp $RINGNECK_UBOOT_DIR/u-boot-rockchip.bin ringneck

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

5.5.2.1. Debian 11 Bullseye

# Build the image
build_board=ringneck ./build.sh

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

5.5.2.2. Debian 12 Bookworm with Phosh graphical shell

This image variant is targeted for the Haikou-Video-Demo. Please see the AN60501 Haikou-Video-Demo for the Haikou baseboard application note for more information about the Haikou-Video-Demo.

More details about the Phosh graphical shell can be found in the Phosh graphical shell section.

# Build the image
build_board=ringneck debos_variant=bookworm-phosh ./build.sh

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