OpenBSD on the VisionFive 2 - NVMe Installation Guide

Table of contents

OpenBSD on the VisionFive 2 - NVMe Installation Guide

It is possible to install OpenBSD for the VisionFive 2 utilizing another computer, this external machine must have a spare NVMe M.2 socket. The general idea is to use RISCV64 emulation (QEMU) to run the OpenBSD RISC-V installer.

You should know that there’s no GPU support (maybe some time in the future if the PowerVR open source driver team decides to implement the support for the JH7110’s BXE-4-32 GPU) therefore, the goal is to end up with a headless OpenBSD system.

NOTE: A serial connection to the board is a must for carrying the installation, I used a USB to TTL adapter.

Preparing the computer

My external computer is a desktop x86_64 PC running Void Linux, nevertheless, the steps would be very similar on other Linux distributions.

After making sure the VisionFive 2’s NVMe is being recognized by the external machine, we have to install the needed software.

Needed software

Let’s install the riscv64 system emulator from QEMU, in my machine this is done by:

sudo xbps-install -S qemu-system-riscv64

Needed files

NOTE: I’ll assume that all these files will be placed inside a directory named obsd-vf2.

We have to download the OpenBSD RISC-V install image (at the time of writting this is the riscv64/install79.img) from the official site. This image also includes the OpenBSD sets.

Also we will need some firmware files for running the OpenBSD installer on the QEMU emulated RISC-V system: fw_jump.bin, which you can find on the opensbi riscv64 package (I got it from here) and the qemu-riscv64_smode/u-boot.bin, from the u-boot-riscv64 package (here.)

We will also need the Device Tree Blob (dtb) for the specific board version you own (v1.3B in my case), this can be downloaded from the StarFive’s official github, you shuld get the latest release.

NOTE: At the time of writting this article the latest dtb files are located in the JH7110_VF2_6.12_v6.0.0-github-2025-10-10.zip file. Which also contains the latest firmware that you must flash to your board (I recommend following the Gentoo Wiki guide for this, I used the UART method.)

Installation

Let’s assume that we are at the obsd-vf2 directory I mentioned earlier. From there let’s start our emulated RISC-V system by running:

sudo qemu-system-riscv64 -M virt -m 2G -smp 2 -nographic \
    -bios ./fw_jump.bin
    -kernel ./u-boot.bin
    -drive file=install79.img, format=raw,id=installer,if=none \
    -device virtio-blk-device,drive=installer \
    -drive file=/dev/nvme0n1,format=raw,id=nvme,if=none \
    -device virtio-blk-device,drive=nvme

WARNING: In my setup /dev/nvme0n1 is the block device location of my VisionFive 2’s NVMe, please triple-check that you select the correct drive on your environment, failing to do so could lead you to data loss. Be careful and responsible for your actions.

Now we can carry on with our standard OpenBSD installation process (using offline sets.)

After finishing the installation we must place the .dtb file inside the EFI partition (/dev/nvme0n1p1 in my case.) Just:

sudo mount /dev/nvme0n1p1 /mnt
sudo mkdir /mnt/vendor
sudo cp *.dtb /mnt/vendor

It’s now time to unmount and unplug the NVMe and place it on the VisionFive 2! Also don’t forget to plug in your USB to TTL Serial Adapter. For the dial in terminal I’ll use:

sudo cu -l /dev/ttyUSB0 -s 115200

Configuring U-Boot on the VisionFive 2

First let’s make sure we start clean by resetting the U-Boot environment variables to their default values:

env default -f -a

For a singe shot boot we would run the following commands:

pci enum
nvme scan
load nvme 0:1 ${fdt_addr_r} vendor/jh7110-starfive-visionfive-2-v1.3b.dtb
load nvme 0:1 ${kernel_addr_r} efi/boot/bootriscv64.efi
bootefi ${kernel_addr_r} ${fdt_addr_r}

Nevertheless, since we want to make this persistent between reboots, we have to run these commands:

setenv distro_boot_env "echo Booting OpenBSD from NVMe;\
pci enum;\
nvme scan;\
load nvme 0:1 ${fdt_addr_r} vendor/jh7110-starfive-visionfive-2-v1.3b.dtb;\
load nvme 0:1 ${kernel_addr_r} efi/boot/bootriscv64.efi;\
bootefi ${kernel_addr_r} ${fdt_addr_r}"
saveenv
reset

OpenBSD!

That’s it! You should have now a working OpenBSD fresh install on the VisionFive 2. I would strongly recommend setting up network and making sure sshd is enabled so you can SSH to it instead of using the USB to TTL Serial adapter.

ยท 4 min read
../