Ubuntu Wiki

Board revision

Different revisions for the StarFive VisionFive 2 board exists which use different device-trees. The board revision is silkprinted on the board. The Ubuntu image assumes that you are using revision v1.3B. If you are using board revision v1.2A, you will have to update the used device-tree as described below.

Updating U-Boot

For running Ubuntu you need U-Boot. The boot mode must be set to SPI flash (DIP switches RGPIO_0 = 0, RGPIO_1 = 0) as the Ubuntu image comes without U-Boot.

With Ubuntu 24.04 (Noble) package u-boot-starfive is provided. File /usr/lib/u-boot/starfive_visionfive2/u-boot-spl.bin.normal.out is U-Boot SPL. /usr/lib/u-boot/starfive_visionfive2/u-boot.itb contains the main U-Boot. (The vendor U-Boot releases call this file visionfive2_fw_payload.img.) Or you can build U-Boot from the upstream source as described in the online documentation.

The Vendor U-Boot releases available at https://github.com/starfive-tech/VisionFive2/releases/ are not compliant to the EBBR specification and cannot boot Ubuntu without manual changes.

Updating U-Boot is described in https://doc-en.rvspace.org/VisionFive2/PDF/VisionFive2_QSG.pdf, chapter "3.8.1. Updating SPL and U-Boot of Flash".

After updating U-Boot it is necessary to reset the environment to the defaults. At the U-Boot console you can use the following commands:

env default -f -a
env save

Using the server install image

Since the 23.10 release an installer image can be used for the VisionFive 2 board for installation onto an NVMe or USB drive. The installer cannot install to the installation medium.

Copying Ubuntu onto the SD-card

Download the Ubuntu live install server image and flash it onto your sdcard using:

zcat ubuntu-23.10-live-server-riscv64.img.gz | sudo dd of=/dev/sdX bs=1M conv=fsync

You will have to replace /dev/sdX by the actual device name of your SD card. Please, be especially cautious not to overwrite the wrong drive as this cannot be undone.

Installation

Establish a serial console connection to the VisionFive 2 board.

sudo picocom -b 115200 /dev/ttyUSB1

Insert the SD card and power up the system.

If no prior operating system installation exists, U-Boot will start up GRUB on the SD card.

Otherwise press the enter key when seeing the Hit any key to stop autoboot: message and execute:

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

(Depending on the U-Boot version the SD-card might show up as mmc device 0. In this case you would have to use mmc 0:1.)

In the GRUB menu select Try or Install Ubuntu Server.

Loading the installer takes some time. Once it is loaded follow the installation steps in https://ubuntu.com/tutorials/install-ubuntu-server.

When the installation is finished reboot the board without removing the SD card.

U-Boot does not allow the operating system to write UEFI variables. You can do this manually. While rebooting press the enter key when seeing the Hit any key to stop autoboot: message. The following commands set up the installation on the NVMe drive as UEFI boot option 0001.

pci enum
nvme scan
efidebug boot add -b 0001 'Ubuntu' nvme 0:1 /EFI/ubuntu/grubriscv64.efi
efidebug boot order 0001

To boot into your fresh installation you can use:

bootefi bootmgr

On the next boot U-Boot will automatically start into GRUB.

Using the preinstalled server image

Copying Ubuntu onto the SD-card

Download the Ubuntu preinstalled server image from https://cdimage.ubuntu.com/releases/23.04/release/ and flash it on your sdcard using:

xzcat ubuntu-23.04-preinstalled-server-riscv64+visionfive2.img.xz | sudo dd bs=1M conv=fsync of=/dev/sdX

You will have to replace /dev/sdX by the actual device name of your SD card. Please, be especially cautious not to overwrite the wrong drive as this cannot be undone.

First boot

Connect to the UART using a UART-TTL USB adapter. For accessing the serial console you can use picocom:

picocom -b 115200 /dev/ttyUSB0

Insert the SD card and power on the board.

When booting the first time wait until you see an output line confirming that cloud-init has finished. Cloud init is responsible for generating the SSH keys and setting the default password. Cloud init itself will also need a few minutes. The line to wait for will look similar to

[  150.053340] cloud-init[1274]: Cloud-init v. 23.1.1-0ubuntu2 finished at Mon, 03 Apr 2023 11:14:35 +0000. Datasource DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net].  Up 150.00 seconds

Now you can login with user ubuntu and the default password ubuntu and will be asked to choose a new password.

The image assumes that you are using version v1.3B of the board (see silkprint on the board). If you are using board version v1.2A, please proceed as follows:

echo 'StarFive VisionFive 2 v1.2A' | sudo tee /etc/flash-kernel/machine
sudo flash-kernel $(uname -r)
sudo update-grub
sudo reboot

These steps will ensure that you use the v1.2A device-tree. Only the outermost Ethernet port is working.

Limitations

• The onboard GPU is not supported. You can use a PCIe connected external GPU.
• USB and PCIe are not supported by the 6.2 kernel.

• If only one network interfave is connected systemd-networkd-wait-online.service waits for minutes. In LP #2045756 the following solution was suggested: Create a file /etc/systemd/system/systemd-networkd-wait-online.service.d/override.conf with content

  [Service]
  ExecStart=
  ExecStart=/lib/systemd/systemd-networkd-wait-online --any