Ubuntu on the VisionFive and the Nezha boards

Below you will find the instructions for installing the Nezha and the VisionFive 22.04.1 Ubuntu images.


1. Setup RISC-V Ubuntu Team PPA

This PPA contains the very last version of the packages we are working on and the packages for the boards that are experimental.

Use the following commands to add the PPA:

$ sudo add-apt-repository ppa:ubuntu-risc-v-team/release
$ sudo apt update

2. Cloud-init and SSH keys

At the very first boot of the following images, the default login/password (“ubuntu/ubuntu”) may not work: this is because cloud-init is generating SSH keys in the background, and we must wait for this generation to finish before being able to login, it generally takes a few minutes.


In order to boot Ubuntu on the VisionFive board, the factory u-boot firmware must be installed. In case you modified the firmware, here is the link to flash it back.

1. Flash the Ubuntu image on the sdcard

Download the Ubuntu image and flash it on your sdcard using:

$ xz -d jammy-preinstalled-server-riscv64+visionfive.img.xz
$ dd if=jammy-preinstalled-server-riscv64+visionfive.img of=/dev/YOUR_SDCARD_BLOCK_DEVICE

Insert the sdcard and then enjoy using Ubuntu on the VisionFive :slight_smile:

2. Bluetooth

The VisionFive board needs a specific firmware for the Bluetooth chipset and we failed to find its origin, so instead of adding it in the archive, we provide it through the RISC-V PPA in the linux-firmware-starfive package. In addition to this package, another piece of software must be used to load this firmware and was packaged into a package called brcm-patchram-plus-starfive.

So to use the Bluetooth on the VisionFive board, you’ll need to enable the RISC-V PPA (refer to the “Setup RISC-V Ubuntu Team PPA“ section on how to enable this PPA) and do the following:

$ apt install linux-firmware-starfive brcm-patchram-plus-starfive

Note that for some unknown reasons, the Bluetooth interface might fail to appear at first: the service installed by the brcm-patchram-plus-starfive package handles this and retries until it actually works.

3. Known issues

  • Shutdown fails: this is a board limitation.

  • The default xfce4 desktop environment is very slow, we looked into this and found a workaround to this issue: we’ll keep digging and try to provide a better alternative. At the moment though, one should use the following commands:

    $ sudo rm /usr/lib/riscv64-linux-gnu/dri/kms_swrast_dri.so
    $ sudo apt install openbox
    $ DISPLAY=:0 openbox –replace


1. Flash the Ubuntu image on the sdcard

Download the Ubuntu image and flash it on your sdcard using:

$ xz -d jammy-preinstalled-server-riscv64+nezha.img.xz
$ dd if=jammy-preinstalled-server-riscv64+nezha.img  of=/dev/YOUR_SDCARD_BLOCK_DEVICE

Insert the sdcard and then enjoy using Ubuntu on the Nezha :slight_smile:

2. Known issues

  • Wifi/BT not working: the Wifi driver is only available on the 5.4.61 kernel.
  • Ethernet MAC address changes at every boot: this “feature” is described here https://linux-sunxi.org/Ethernet along with the solutions to fix this in section “Setting the MAC address”
    Shutdown fails

Neither the jammy nor ubuntu pre-installed server images have the file “/usr/lib/riscv64-linux-gnu/dri/kms_swrast_dri.so”. Also, there is no DISPLAY variable being generated on the initial login, so there is nothing for openbox to replace.

Error message:

Openbox-Message: Failed to open the display from the DISPLAY environment variable.

You must install xinit before openbox can run, as it relies on the xServer environment.
sudo apt install xinit
sudo apt -y install python3-xdg
sudo apt -y install openbox obconf
then run command: startx

However this environment still has issues starting a terminal session, which I have yet to solve.

1 Like

Hi resoldier,

The tutorial is indeed unclear on this point: the prerequisite to the proposed workaround is to install xfce4. So the thorough instructions are:

$ sudo apt install xfce4
$ sudo rm /usr/lib/riscv64-linux-gnu/dri/kms_swrast_dri.so
$ sudo apt install openbox
$ sudo startxfce4&
$ DISPLAY=:0 openbox –replace

Let me know how this works for you, thanks for your feedback!


  1. macOS user reached dd: /dev/disk2: Resource busy, try this
diskutil list

sudo diskutil unmount /dev/disk2

ref: https://unix.stackexchange.com/questions/271471/running-dd-why-resource-is-busy

  1. show progress when dd
sudo dd if=jammy-preinstalled-server-riscv64+nezha.img of=/dev/disk2 status=progress

  1. windows user flash img try:
  • clean target disk with diskpart
  • Win32DiskImager:sourceforge.net/projects/win32diskimager/


  • Rufus:github.com/pbatard/rufus

I reached no resp when I try booting the Nezha img on my Lichee RV (with Dock)

Loading Linux 5.17.0-1003-allwinner ...
Loading initial ramdisk ...
Loading device tree blob...
EFI stub: Booting Linux Kernel...
EFI stub: Using DTB from configuration table
EFI stub: Loaded initrd from LINUX_EFI_INITRD_MEDIA_GUID device path
EFI stub: Exiting boot services...

Can you porting the Ubuntu to it? It’s a cheaper DevKit than Nezha but without EMMC.

offical wiki: https://wiki.sipeed.com/hardware/zh/lichee/RV/RV.html
board spec: https://linux-sunxi.org/Sipeed_Lichee_RV
working debian img:github.com/tmolteno/d1_build/releases
buy it:www.aliexpress.com/item/3256803554972410.html

Hi initrd,

As-is, the Nezha image won’t work on the LicheeRV dock board because the LicheeRV comes with only 512MB of RAM which is not enough for handling the Nezha image initrd. To circumvent this issue, you can uninstall cryptsetup-initramfs which will regenerate a smaller initrd.

And we will provide an official image for the LicheeRV Dock board in Kinetic :slight_smile:



1 Like

I made Nezha img boot on my LicheeRV Dock after remove cryptsetup-initramfs

First of all, write the img to a microSD card
the following steps:

  1. A Ubuntu Linux host (Live CD should be OK)
  2. install qemu-user-static
  3. mount VFS by using https://github.com/initdc/rootfs-tools/blob/master/mount.rb
  4. chroot /media/ubuntu/cloudimg-rootfs
  5. apt remove cryptsetup-initramfs
  6. Cause LicheeRV Dock doesn’t have a Eth port, you may need install net-tools network-manager to connnect Wi-Fi if wireless card working well. A USB to Eth Connector will work well if you have one.
  7. umount VFS, eject card.
  8. After boot up, you can login with ubuntu/ubuntu, then you NEED set new password.
  9. A good UART client will makes you feel smooth. try MobaXterm
  10. try first RISC-V program from https://github.com/initdc/golang-project-workflow/releases/download/v0.0.1/demo-v0.0.1-linux-riscv64

I think dual-core CPU is the key to avoid stuttering, Is there any way to make it run faster for now?

That’s nice, well done. For the image that we will release for Kinetic, we simply install wpasupplicant so that netplan can configure the wireless network interface. I’m working on the packaging of the Wifi driver using dkms, if you’re interested, you can give it a try here: https://launchpad.net/~alexghiti/+archive/ubuntu/riscv/+files/licheerv-rtl8723ds-dkms_1.0-0~ppa1_riscv64.deb

What do you mean by “making it run faster”?

1 Like

Not sure if I’m the only one, but I couldn’t get my VisionFive to boot with any of the Ubuntu images (the jammy-preinstalled mentioned here, nor any of the kinetic nightlies up to and including today). I bought a USB-to-serial cable, and saw it was failing to get past u-boot.

Checking u-boot, I saw that bootcmd (the default command?) was undefined:

bootcmd_dhcp=devtype=dhcp; if dhcp ${scriptaddr} ${boot_script_dhcp}; then source ${scriptaddr}; fi;setenv efi_fdtfile ${fdtfile}; setenv efi_old_vci ${bootp_vci};setenv efi_old_arch ${bootp_arch};setenv bootp_vci PXEClient:Arch:00027:UNDI:003000;setenv bootp_arch 0x1b;if dhcp ${kernel_addr_r}; then tftpboot ${fdt_addr_r} dtb/${efi_fdtfile};if fdt addr ${fdt_addr_r}; then bootefi ${kernel_addr_r} ${fdt_addr_r}; else bootefi ${kernel_addr_r} ${fdtcontroladdr};fi;fi;setenv bootp_vci ${efi_old_vci};setenv bootp_arch ${efi_old_arch};setenv efi_fdtfile;setenv efi_old_arch;setenv efi_old_vci;
bootcmd_mmc0=devnum=0; run mmc_boot

Setting bootcmd thusly got me up and running:

setenv bootcmd “load mmc 0:4 0xa0000000 /EFI/ubuntu/grubriscv64.efi; bootefi 0xa0000000”

Maybe my board came with some funky config? It booted just fine with the StarFive Fedora image, though.

This is my first experience with RISC-V and its boot process, so I could very well be missing something.

After re-build kernel on the LicheeRV by runing sudo apt --fix-broken install ./licheerv-rtl8723ds-dkms_1.0-0\~ppa1_riscv64.deb, wireless card works now.

It really cost long long time, I’ve drunk tons of water when I was waitting.

here is the log

➜ ~ lshw                                                                                                  130 <<2:49:57

       description: Wireless interface
       physical id: 7
       bus info: mmc@1:0001:1
       logical name: wlan0
       capabilities: ethernet physical wireless
       configuration: broadcast=yes driver=rtl8723ds driverversion=5.17.0-1005-allwinner ip=192.168. multicast=yes wireless=IEEE 802.11bgn

➜ ~ uname -a                                                                                                0 <<2:50:01
Linux ubuntu 5.17.0-1005-allwinner #5-Ubuntu SMP Fri Aug 19 15:36:32 UTC 2022 riscv64 riscv64 riscv64 GNU/Linux

Hi scottfk,

Can you give me the version of u-boot on your board? Ideally the whole boot log would be nice.




I started with the version in your post (fw_payload_jh7100_20211230/u-boot-2022.01-rc4-g0c08d33). That didn’t work, so I upgraded to fw_payload_jh7100_20220311/u-boot-2022.04-rc2. Still didn’t fix the issue, but I left it there.

I’ll reattach it to the serial rig and get you the boot log a bit later today.


Boot log:

> bootloader version:211102-0b86f96                                                                                       
> ddr 0x00000000, 1M test                                                                                                 
> ddr 0x00100000, 2M test                                                                                                 
> DDR clk 2133M,Version: 211102-d086aee                                                                                   
> 0 crc flash: 7816e82f, crc ddr: 7816e82f                                                                                
> crc check PASSED                                                                                                        
> bootloader.                                                                                                             
> OpenSBI v1.0                                                                                                            
>    ____                    _____ ____ _____                                                                             
>   / __ \                  / ____|  _ \_   _|                                                                            
>  | |  | |_ __   ___ _ __ | (___ | |_) || |                                                                              
>  | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |                                                                              
>  | |__| | |_) |  __/ | | |____) | |_) || |_                                                                             
>   \____/| .__/ \___|_| |_|_____/|____/_____|                                                                            
>         | |                                                                                                             
>         |_|                                                                                                             
> fdt_reset_driver_init: gpio-restart init failed, -1001                                                                  
> Platform Name             : StarFive VisionFive V1                                                                      
> Platform Features         : medeleg                                                                                     
> Platform HART Count       : 2                                                                                           
> Platform IPI Device       : aclint-mswi                                                                                 
> Platform Timer Device     : aclint-mtimer @ 6250000Hz                                                                   
> Platform Console Device   : uart8250                                                                                    
> Platform HSM Device       : ---                                                                                         
> Platform Reboot Device    : ---                                                                                         
> Platform Shutdown Device  : ---                                                                                         
> Firmware Base             : 0x80000000                                                                                  
> Firmware Size             : 300 KB                                                                                      
> Runtime SBI Version       : 0.3                                                                                         
> Domain0 Name              : root                                                                                        
> Domain0 Boot HART         : 1                                                                                           
> Domain0 HARTs             : 0*,1*                                                                                       
> Domain0 Region00          : 0x0000000002000000-0x000000000200ffff (I)                                                   
> Domain0 Region01          : 0x0000000080000000-0x000000008007ffff ()                                                    
> Domain0 Region02          : 0x0000000000000000-0xffffffffffffffff (R,W,X)                                               
> Domain0 Next Address      : 0x0000000080200000                                                                          
> Domain0 Next Arg1         : 0x0000000082200000                                                                          
> Domain0 Next Mode         : S-mode                                                                                      
> Domain0 SysReset          : yes                                                                                         
> Boot HART ID              : 1                                                                                           
> Boot HART Domain          : root                                                                                        
> Boot HART ISA             : rv64imafdcsux                                                                               
> Boot HART Features        : scounteren,mcounteren                                                                       
> Boot HART PMP Count       : 16                                                                                          
> Boot HART PMP Granularity : 4096                                                                                        
> Boot HART PMP Address Bits: 36                                                                                          
> Boot HART MHPM Count      : 2                                                                                           
> Boot HART MIDELEG         : 0x0000000000000222                                                                          
> Boot HART MEDELEG         : 0x000000000000b109                                                                          
> U-Boot 2022.04-rc2-VisionFive (Mar 07 2022 - 21:12:22 +0800)StarFive                                                    
> CPU:   rv64imafdc                                                                                                       
> Model: StarFive VisionFive V1                                                                                           
> DRAM:  8 GiB                                                                                                            
> Core:  13 devices, 9 uclasses, devicetree: separate                                                                     
> MMC:   mmc@10000000: 0, mmc@10010000: 1                                                                                 
> Loading Environment from SPIFlash... cadence_spi spi@11860000: Can't get reset: -524                                    
> SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB                                         
> OK                                                                                                                      
> StarFive EEPROM format v1                                                                                               
> --------EEPROM INFO--------                                                                                             
> Vendor : StarFive Technology Co., Ltd.                                                                                  
> Product full SN: VF7100A1-2204-D008E000-0000009A                                                                        
> data version: 0x1                                                                                                       
> PCB revision: 0x1                                                                                                       
> BOM revision: A                                                                                                         
> Ethernet MAC address: 6c:cf:39:00:00:99                                                                                 
> --------EEPROM INFO--------                                                                                             
> In:    serial@12440000                                                                                                  
> Out:   serial@12440000                                                                                                  
> Err:   serial@12440000                                                                                                  
> Net:   dwmac.10020000                                                                                                   
> MMC CD is 0x1, force to True.                                                                                           
> MMC CD is 0x1, force to True.                                                                                           
> switch to partitions #0, OK                                                                                             
> mmc0 is current device                                                                                                  
> MMC CD is 0x1, force to True.                                                                                           
> MMC CD is 0x1, force to True.                                                                                           
> Can't set block device                                                                                                  
> Can't set block device                                                                                                  
> Autoboot in 2 seconds                                                                                                   
> 151552 bytes read in 52 ms (2.8 MiB/s)                                                                                  
> MMC CD is 0x1, force to True.                                                                                           
> Card did not respond to voltage select! : -110                                                                          
> Disk mmc@10010000.blk not ready                                                                                         
> Welcome to GRUB!

Hi there!

I just want to let you know that I’ve tried the nezha image (without changes) in a MangoPi board and it runs OK with HDMI. I haven’t made tests (I need an usb-c adapter for my keyboard), nonetheless it runs and when I connect to network I’ll reply here. :grin:

Is that the failing bootlog? If yes, this is weird since at the end, we can see “Welcome to GRUB!”.

Hi zxnord,

Thanks for your feedback, that’s nice to know! I guess you have the 1GB of DDR3 version of the board otherwise you would have probably fallen into the same issue as the LicheeRV.



1 Like

Successful bootlog. I’ll need to reset variables to defaults to get failure. Coming soon…

Hello Alex:

I want to know how to build the preinstalled image, I want made a ubuntu distro for my intel edison board.

Is it https://github.com/canonical/ubuntu-image ?

HI, I managed to burn the image, now I wonder what are the login credentials, as I’m asked about them> image
Thanks for the help!

Nevermind, browsing a bit here and there, found it is ubuntu - ubuntu