This tutorial was tested and works with kernel 6.12.5, with StarFive's vendor kernel for Debian-based distros. If you're reading this in the future with a different kernel, or a different setup, this may not work for you.

This was originally part of a blog post I'm working on, but I'm splitting it to a separate page due to its length.

I believe the correct way to compile the Linux kernel for the VisionFive 2 is to use the full toolchain here, but that will compile a lot more things than just the kernel.

Part 1: The kernel

Compiling the Linux kernel is not particularly hard assuming the sight of a terminal doesn't make you squirm. It is however rather time consuming.

First we need to download the build tools: sudo apt install build-essential bc bison flex rsync libelf-dev libssl-dev debhelper libncurses-dev dwarves python3-minimal

After that, we can download the source code to the Linux kernel. For this we'll use the same vendor kernel that the system is running.

git clone https://github.com/starfive-tech/linux -b JH7110_VisionFive2_6.12.y_devel --depth=1

Do note that the additions to the vendor kernel are kinda buggy and won't compile if you use certain settings, so we'll reuse the current kernel config as a base.

cd linux
cp /boot/config-6.12.5-starfive .config

From here, you make your changes and then compile. For this tutorial, we'll focus on enabling hidraw, which is needed for hardware security keys (like YubiKeys) to work, as it's not provided by default.

Run make -j4 menuconfig, go to Device drivers, and HID bus support. Highlight /dev/hidraw raw HID device support and press Enter to enable it. Then, scroll down to USB HID support, press Enter to see options, and enable the same option. After that, you can save and exit the config utility.

Now with your options ready to be compiled into the kernel, we can kick off the build with make -j4 bindeb-pkg. This will take over an hour to compile, but once it's done you can install the new kernel with dpkg -i ../linux-image-6.12.5.deb. Reboot into your new kernel, and now the things you enabled will be available!

A note about the boot partition

The boot partition stores the Linux kernel in addition to the usual boot files, but it's only 100MB. If you start installing kernels you will quickly run into trouble with running out of disk space.

Once you've confirmed your custom kernel works, you can remove the original one:

sudo apt remove linux-image-6.12.5-starfive

Part 2: The VPU modules

After rebooting to use your newly compiled kernel, you might discover that video playback no longer works! This is because VPU support is handled by out-of-tree modules. To get video playback working again, we'll need to compile those modules. The Linux source code that was used earlier will be needed, so go dig it out of the trash if you deleted it.

Naturally, the source code to those modules will be needed:

git clone https://github.com/starfive-tech/soft_3rdpart --depth=1

Now, you need to go to the following directories in the soft_3rdpart folder and run make -j4 KERNELDIR=/path/to/linux in them, where /path/to/linux is the Linux kernel source you cloned earlier:

• codaj12/jdi/linux/driver (jpu.ko)

• wave420l/code/vdi/linux/driver (venc.ko)

• wave511/code/vdi/linux/driver (vdec.ko)

Now the generated .ko files need to be moved to their proper place under /lib/modules/(compiled kernel)/extra. If you're already running the compiled kernel, you can get the name of the folder by running uname -r in a terminal. Create the extra folder if it doesn't exist.

Loading the modules

For whatever reason, even with the modules in the right place, they won't load automatically like with the original kernel. I have not figured out why as of writing, but a workaround is to load them in vpudev, which exists to allow user applications to use the modules.

Add these lines to /etc/init.d/vpudev, just after the start):

insmod "/lib/modules/$(uname -r)/extra/jpu.ko"
insmod "/lib/modules/$(uname -r)/extra/venc.ko"
insmod "/lib/modules/$(uname -r)/extra/vdec.ko"

The beginning of the case statement in the file should now look like this:

case "$1" in
  start)
    insmod "/lib/modules/$(uname -r)/extra/jpu.ko"
    insmod "/lib/modules/$(uname -r)/extra/venc.ko"
    insmod "/lib/modules/$(uname -r)/extra/vdec.ko"
    echo "make vpu dev accesible to non root"
    chmod 666 /dev/jpu
    ...

Save and close the file. If you're running the compiled kernel, you can now load the modules with sudo systemctl restart vpudev. Or just restart.

Your custom kernel can now play back video!