Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• VisionFiveV1

Translation(s): none

Models covered
StarFive VisionFiveV1

• StarFive VisionFive V1, StarFive JH7100 (Dual-core 64-bit SiFive U74) + Embedded 32-bit SiFive E24 Core, 8 GB 64-bit LPDDR4, Gigabit Ethernet, microSD Card.

Overall Status

Legend :
= OK ; Unsupported(No Driver) ; = Error (Couldn't get it working); [?] Unknown, Not Test ; [-] Not-applicable
= Configuration Required; = Only works with a non-free driver and or firmware

Important Note

There are no official Debian images available yet.

Boot process overview

The full boot process is documented in the official documentation. This guide is focused on getting u-boot to boot the Linux kernel.

The board comes with the u-boot bootloader flashed on the internal SPI flash. This u-boot first tries to load the file /boot/uEnv.txt from the third partition of the SD card, allowing to customize the boot process. It then implements the "generic distro" concept of u-boot.

Unfortunately, as of May 2022 (U-Boot 2022.04-rc2-?VisionFive built on Mar 07 2022 - 21:12:22 +0800), the bundled u-boot on the board doesn't do anything except loading the uEnv.txt file, because it's missing a built-in definition of "bootcmd". That is, the uEnv.txt file is currently mandatory and needs to specify how to boot. It also needs to define load addresses for the kernel, FDT, and/or EFI image. See https://github.com/starfive-tech/u-boot/pull/31 and https://github.com/starfive-tech/u-boot/pull/32 for patches fixing these issues.

In any case, u-boot can boot Linux using two main methods:

1. either it can load an extlinux.conf file describing which kernel/FDT/initrd images to boot, load all three images, and boot the kernel directly. This fits the "generic distro" model.

2. or it can load an EFI image, typically grub, and delegate the boot process to this second bootloader. Like in the previous case, u-boot will scan partitions to find an EFI image at a specific location (/efi/boot/bootriscv64.efi).

In the long term, using EFI is the preferred and more standard way.

Installing Debian on VisionFive V1

As described above, two boot options are presented in this guide: either using u-boot directly or using a Grub EFI image.

Most of the steps are common for the two options.

Cross-compile build Linux kernel package on Debian 13 Trixie

StarFive JH7100 CPU in mainline Linux requires ERRATA_STARFIVE_JH7100=y config option incompatible to the Debian Linux release kernel. It is required to build or obtain a kernel image with this option enabled for correct function of VisionFive JH7100 peripherals (i.e. network, mmc).

# Set up multi-arch environment
dpkg --add-architecture riscv64
apt update

# Prepare Debian Linux kernel source i.e. version 6.12
apt install --install-recommends linux-source-6.12
tar xaf /usr/src/linux-source-6.12.tar.xz

# Prepare Kconfig stems suitable for Debian Linux
apt install --install-recommends git
git clone --depth 1 https://salsa.debian.org/kernel-team/kernel-team.git
git clone --depth 1 https://salsa.debian.org/kernel-team/linux.git
apt install '^linux-support-.*$'
kernel-team/utils/kconfigeditor2/process.py -c linux/debian/config -s linux-source-6.12 linux

# Prepare Kconfig input suitable for VisionFive JH7100
pushd linux-source-6.12
scripts/kconfig/merge_config.sh -m ../linux/debian/config/config ../linux/debian/config/riscv64/config
scripts/config --enable ERRATA_STARFIVE_JH7100 --enable NONPORTABLE --disable ARCH_SUNXI --disable ARCH_THEAD --disable RISCV_ISA_ZICBOM

# Optional: Build without debug info to reduce disk and compile time requirements
scripts/config --enable DEBUG_INFO_NONE --undefine CONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT

# Generate Kconfig and compiled kernel package
apt install crossbuild-essential-riscv64
make ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- olddefconfig
apt install debhelper libssl-dev:riscv64
make ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- KDEB_CHANGELOG_DIST=unreleased -j$(nproc) bindeb-pkg LOCALVERSION=-starfivejh7100
popd

Also see: https://kernel-team.pages.debian.net/kernel-handbook/ch-common-tasks.html#s-common-official

Prepare debian-installer initramfs image

Embed a copy of the above compiled Linux kernel package into the netboot debian-installer initramfs image:

apt install fakeroot curl ca-certificates cpio

curl -L https://d-i.debian.org/daily-images/riscv64/daily/netboot/netboot.tar.gz | tar xz ./debian-installer

fakeroot  # enter fakeroot environment to preserve initrd permissions
gzip -dc debian-installer/riscv64/initrd.gz | cpio -id --directory=initrd
cat linux-image-*-starfivejh7100*.deb | tee initrd/linux-image-custom.deb | dpkg -x - initrd/custom
gzip -dc initrd/custom/boot/vmlinuz-* > debian-installer/riscv64/linux-custom
mv initrd/lib/modules initrd/custom/
mv initrd/custom/lib/modules initrd/lib/
mv initrd/custom/usr/lib/* debian-installer/device-tree-custom
find initrd -path initrd/custom -prune -o -printf '%P\0' | cpio -0oH newc --directory=initrd | gzip -c > debian-installer/riscv64/initrd-custom.gz
exit  # leave fakeroot environment

The embedded package can then be installed manually at the very last installation step of debian-installer before reboot.

Note the necessary files to begin installation are now located at:

• debian-installer/device-tree-custom/starfive/jh7100-starfive-visionfive-v1.dtb
• debian-installer/riscv64/linux-custom
• debian-installer/riscv64/initrd-custom.gz

These files may be copied to a convenient location i.e. for serial UART data transfer or TFTP server.

Load installer from U-Boot

Power-on the VisionFiveV1 board and interrupt U-Boot when prompted.

Data may be transferred via UART serial method (which may take several hours) or another supported U-Boot method, such as TFTP over the local network. The example is given here for loading data from TFTP server at example 10.0.0.2 IP address.

U-Boot environment command line:

env set ipaddr 10.0.0.1  # set IP address of VisionFiveV1 or, optionally, replace by 'dhcp -' command
env set serverip 10.0.0.2  # TFTP server to get installer data from
tftpboot $kernel_addr_r debian-installer/riscv64/linux-custom
tftpboot $fdt_addr_r debian-installer/device-tree-custom/starfive/jh7100-starfive-visionfive-v1.dtb
tftpboot $ramdisk_addr_r debian-installer/riscv64/initrd-custom.gz
env set bootargs 'initrd='$ramdisk_addr_r',0x'$filesize
bootefi $kernel_addr_r $fdt_addr_r

The debian-installer should now begin as usual.

Note: debian-installer text user interface itself runs as the first window in a 'screen' terminal session, and there are additional windows i.e. with command shell and logging information. At the very last step of installation when the installer is asking to confirm a reboot we will firstly change to the "next" window which has a command shell and manually install the specially embedded Linux kernel package.

To advance to the next window, control-key with 'a' followed by 'n' (as in "next"):

# Install custom kernel image
cp linux-image-custom.deb /target/tmp/
mount -o bind /dev/pts /target/dev/pts
chroot /target /bin/bash  # enter chroot
dpkg -i /tmp/linux-image-custom.deb
exit  # leave chroot

When completed, return to the previous (first) window, control-key with 'a' followed by 'p' (as in "previous"). Confirm the installer question about reboot of the system.

At next boot the U-Boot bootloader will find the installed EFI System Partition by its partition GUID identifier, and then to chainload the discovered well-known EFI executable by name '/EFI/BOOT/BOOTRISCV64.EFI'. The installer question about removable media determined whether an additional copy of '/EFI/debian/grubriscv64.efi' is made to this well-known filename '/EFI/BOOT/BOOTRISCV64.EFI'. From there Grub2 is running and presents a menu as is standard for Debian 13 Trixie systems.

If you are missing this well-known filename or otherwise wish to customize this process then U-Boot 'eficonfig' command will present a menu allowing to add an alternative EFI boot menu entry different from the global well-known method. You may specify the location of Grub2, a Linux Kernel, or something else as desired, but these data sources must be on the EFI System Partition. For typical Debian 13 Trixie systems the Linux kernel and initramfs images are located on the root filesystem outside of the EFI System Partition environment. The chainload of Grub2 allows to access the installed root filesystem and complete the boot process. If you want to use U-Boot to directly load kernel, initramfs, and devicetree data images then these data must be located on the EFI System Partition and configured with U-Boot 'eficonfig' interface.

Updating the kernel

To update the kernel, you need to:

• build a new kernel using exactly the same steps as during installation (cross-compilation)
• copy and install the resulting .deb on the device

The rest should work automatically (DTB synchronization)