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.

U-Boot

The StarFive VisionFive 2 board can boot firmware from either of SPI flash, SD-card, eMMC, or UART. The boot source is selected via DIP switches.

The vendor U-Boot is not compatible with the EBBR specification and cannot boot Ubuntu without manual changes.

The preinstalled server image comes with U-Boot built from upstream sources. U-Boot SPL and U-Boot are installed in the partitions designated loader1 and loader2. Select the SD-card as boot source via the DIP switches as shown in the photo:

The next steps are only relevant when using the live installer.

The Ubuntu live installer image which can be used to install to an NVMe, eMMC, or USB drive does not provide U-Boot for the StarFive VisionFive 2 board. You will have to update U-Boot on the SPI flash to use it. Package u-boot-starfive contains the U-Boot SPL and main U-Boot binaries. The easiest way to update U-Boot in the SPI flash is by booting the preinstalled image and entering the U-Boot console by pressing enter when seeing the "Hit any key to stop autoboot:" message:

sf probe
load mmc 1:1 $kernel_addr_r /usr/lib/u-boot/starfive_visionfive2/u-boot-spl.bin.normal.out
sf update $kernel_addr_r 0 $filesize
load mmc 1:1 $kernel_addr_r /usr/lib/u-boot/starfive_visionfive2/u-boot.itb               
sf update $kernel_addr_r 0x100000 $filesize

Switch the board off and set the boot source to SPI flash via the DIP switches:

After rebooting reset the environment

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.

Enter the U-Boot console by pressing enter when seeing the "Hit any key to stop autoboot:" message to reset the environment:

env default -f -a
env save

Power cycle 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