Contents

  1. Overall Status
  2. Installation
    1. Update firmware (U-Boot)
    2. Debian 13 Trixie installation
      1. Hardware boot mode selection
      2. Devicetree
      3. Booting debian-installer cdimage from hybrid ISO9660 media
      4. Booting debian-installer netinst from network
      5. Booting debian-installer netinst from MMC (eMMC, SD Card)
      6. Booting debian-installer netinst from serial port
      7. Common part
      8. Install with Linux kernel from trixie-backports
    3. U-Boot Linux Access
    4. JH-7110 SoC USB support missing from U-Boot v2025.01
    5. LUA Support
    6. HDMI and/or GPU support (experimental)

Overall Status

Core Components

[ATTACH]

Boot Standard Kernel:

{OK}

LAN network card:

{OK}

Detect hard drives (NVMe):

{OK}

Detect hard drives (microSD):

{OK}

USB ports

{OK}

Analog audio output

{OK}

HDMI

🔧 see below

GPU

🔧 see below

Extra Features

CPU Frequency Scaling

{OK}

Hibernation

[?]

Sleep / Suspend

[?]

Power Off / Reboot

{OK}

Xorg

[?]

Legend :
{OK} = OK ; {X} = Unsupported(No Driver) ; /!\ = Error (Couldn't get it working); [?] Unknown, Not Test ; [-] Not-applicable
{i} = Configuration Required; X-( = Only works with a non-free driver and or firmware
🔧 = with custom kernel

Current support state could be followed at RVSpace JH7110 Upstream Status page.

Installation

Be sure to set the DIP switches correctly for your boot medium. Boot methods SD and eMMC directly from StarFive JH7110 CPU loader are deprecated and should not be used as they have been removed from vendor documentation and are incompatible to GUID Partition Table disk representation. Remaining valid boot methods are UART for recovery action and SPI NOR flash for U-Boot bootloader (which can then itself correctly boot from SD and eMMC). See VisionFive 2 Boot Mode Settings for more details.

{i} Use of another small board computer host as a serial interface requires that there is no other activity (such as getty login services) on that serial port by the host. For the example of Raspberry Pi GPIO UART console /dev/ttyS1 in place of a dedicated UART serial adapter then it is necessary to stop the getty login service attached to that device file. Stop the getty service with sudo systemctl stop getty@tty1.service and substitute throughout this guide the use of device /dev/ttyUSB0 for /dev/ttyS1 of the Raspberry Pi, e.g. tio /dev/ttyS1 -o 1

Update firmware (U-Boot)

Refer to the official U-Boot StarFive boards documentation for detailed instructions specific to your particular board variant, on building and uploading U-Boot SPL plus U-Boot Main to SPI Flash memory. This guide follows the official U-Boot usage advice however with the following packaged builds of U-Boot in the Debian package archives: 

   1 wget http://deb.debian.org/debian/pool/main/u/u-boot/u-boot-starfive_2025.01-3.1_riscv64.deb
   2 dpkg -x u-boot-starfive_2025.01-3.1_riscv64.deb u-boot-starfive_2025.01-3.1_riscv64
   3 cd u-boot-starfive_2025.01-3.1_riscv64/usr/lib/u-boot/starfive_visionfive2

<!> It is required to update SPI NOR flash to contain a version of U-Boot upstream release v2025.01 or newer: https://packages.debian.org/trixie/riscv64/u-boot-starfive/download

Debian 13 Trixie installation

Hardware boot mode selection

Adjust the boot mode DIP switch to select the 'QSPI NOR Flash' boot mode for normal operation.

Devicetree

Device driver configuration parameters are specified during the boot process as in .dtb devicetree format. U-Boot contains internally its own platform-specific devicetree data for the StarFive VisionFive 2 board (and variant boards) and previous to version U-Boot v2026.01 this information is not consistent for use with Linux kernel, and so there are additional overrides for this devicetree data. Depending on the particular variant board this can affect configured DRAM capacity, network signal delay line parameters, MMC, UART console, and USB or PCIe enablement etc. As U-Boot loads the next EFI bootloader in the chain the Flattened device tree (or "Fdt" as devicetree data is known when loaded into memory) is available:

Prepare .dtb file (e.g. for variant Pine64 Star64) from Debian daily-images https://d-i.debian.org/daily-images/riscv64/daily/device-tree/starfive/ 

   1 wget https://d-i.debian.org/daily-images/riscv64/daily/device-tree/starfive/jh7110-pine64-star64.dtb

Booting debian-installer cdimage from hybrid ISO9660 media

Likely the device you want to install Debian to is the only storage device from which you could boot the installer media. This does not typically work for the full cdimage and in the strategy of mini.iso to overwrite the installer media with the installed Debian system and so is not explained in depth. Although not covered in detail by this guide, offline installation may be possible:

U-Boot will then discover the EFI System Partition of cdimage boot media and boot the installer.

Booting debian-installer netinst from network

U-Boot v2025.01 has TFTP support. Configuring TFTP is non-trivial and not explained here.

U-Boot v2026.01 and newer have HTTPS web get support allowing to download mini.efi and any .dtb file content directly from Debian archive into memory without storage boot media or prepared download to the UART serial connected host. Debian 13 Trixie does have only the older U-Boot v2025.01 packaged and so this is not explained in detail for the guide. The use of U-Boot v2026.01 and newer wget command may be substituted in place of loady where booting debian-installer netinst from serial port is explained in this guide.

Booting debian-installer netinst from MMC (eMMC, SD Card)

Likely the device you want to install Debian to is the same MMC storage device from which you will access in U-Boot to transfer files data from. This is possible when the MMC media is prepared for temporary use to read in U-Boot the files to memory, after which the MMC media is available as an debian-installer installation target.

Loading mini.efi from FAT32 filesystem on device mmc1 partition 1: 

   1 load mmc 1:1 $loadaddr /mini.efi
   2

The above example may be adapted as a substitute for where loady is used throughout the guide.

Booting debian-installer netinst from serial port

Prepare mini.efi file EFI application of debian-installer netinst 

   1 wget https://deb.debian.org/debian/dists/trixie/main/installer-riscv64/current/images/netboot/mini.efi

Use a suitable serial terminal i.e. tio described herein: 

   1 tio /dev/ttyUSB0 -o 1
   2     [21:18:47.463] tio 3.9
   3     [21:18:47.463] Press ctrl-t q to quit
   4     [21:18:47.480] Connected to /dev/ttyUSB0

power-on the board ready to enter commands over UART serial 

   1     U-Boot SPL 2025.01-3.1 (Jan 05 2026 - 19:15:58 +0000)
   2     DDR version: dc2e84f0.
   3     Trying to boot from SPI
   4     
   5     
   6     U-Boot 2025.01-3.1 (Jan 05 2026 - 19:15:58 +0000)
   7     
   8     CPU:   sifive,u74-mc
   9     Model: Pine64 Star64
  10     DRAM:  4 GiB
  11     Core:  136 devices, 26 uclasses, devicetree: board
  12     WDT:   Not starting watchdog@13070000
  13     MMC:   mmc@16010000: 0, mmc@16020000: 1
  14     Loading Environment from SPIFlash... SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB
  15     OK
  16     StarFive EEPROM format v2
  17     
  18     --------EEPROM INFO--------
  19     Vendor : PINE64
  20     Product full SN: STAR64V1-2310-D004E000-0000xxxx
  21     data version: 0x2
  22     PCB revision: 0xc1
  23     BOM revision: A
  24     Ethernet MAC0 address: 6c:cf:39:00:xx:xx
  25     Ethernet MAC1 address: 6c:cf:39:00:xx:xx
  26     --------EEPROM INFO--------
  27     
  28     starfive_7110_pcie pcie@2b000000: Starfive PCIe bus probed.
  29     starfive_7110_pcie pcie@2c000000: Starfive PCIe bus probed.
  30     In:    serial@10000000
  31     Out:   serial@10000000
  32     Err:   serial@10000000
  33     Net:   eth0: ethernet@16030000, eth1: ethernet@16040000
  34     starting USB...
  35     No USB controllers found
  36     Working FDT set to ff731a10
  37     Hit any key to stop autoboot:  2 1 0
  38 
  39 (press enter i.e. or any other key to interrupt autoboot here)
  40     StarFive # 
  41

{i} Outputs presented in this guide may demonstrate a previous version of U-Boot however the theory of operation is the same for newer versions

Load .dtb data (e.g. for variant Pine64 Star64) from U-Boot via YMODEM transfer for this session: 

   1 loady $fdt_addr_r
   2     ## Ready for binary (ymodem) download to 0x46000000 at 115200 bps...
   3     CCC
   4 
   5 (Control-t,y)
   6     Send file with YMODEM
   7     Enter file name: 
   8 
   9 jh7110-pine64-star64.dtb
  10     Sending file 'jh7110-pine64-star64.dtb'  
  11     Press any key to abort transfer
  12     ...…|
  13     Done
  14     ## Total Size      = 0x0000800e = 32782 Bytes
  15     ## Start Addr      = 0x46000000
  16     StarFive #
  17 
  18 fdt addr $fdt_addr_r $filesize
  19     Working FDT set to 46000000
  20     StarFive # 
  21

Mask Fdt base compatible property by removal for this session: 

   1 fdt rm / compatible
   2     StarFive #
   3

On the StarFive VisionFive 2 (and variants) the value of an empty fdtfile environment variable is replaced at U-Boot Main phase by a preset search path specific to the model of that variant; the model detection occurs during U-Boot SPL phase and depends on EEPROM content to determine the model. For preventing the override of Fdt it is not sufficient thus to unset the fdtfile variable as it will be overwritten by this detection routine; a value in fdtfile of e.g. "invalid" that is unlikely to be found in the filesystem is preferred to disable this mechanism for the installation of Debian 13 Trixie.

Mask the loading of any .dtb from EFI System Partition this session: 

   1 env set fdtfile invalid
   2     StarFive #
   3

{i} If you want to avoid the long wait (~2h) of transferring the 70 MiB+ mini.efi over a 115 kbps serial connection, you can instead transfer it via a TFTP server, from MMC storage, or from USB on board variants that support USB in U-Boot. See the U-Boot documentation for more details on alternatives to serial data transfer. 

   1 loady $loadaddr && bootefi $loadaddr
   2     StarFive # loady $loadaddr && bootefi $loadaddr
   3     ## Ready for binary (ymodem) download to 0x82000000 at 115200 bps...
   4     CCC
   5 
   6 (Control-t,y)
   7     Send file with YMODEM
   8     Enter file name: 
   9 
  10 mini.efi
  11     Sending file 'mini.efi'  
  12     Press any key to abort transfer
  13     ...…|
  14     Done
  15     ## Total Size      = 0x047cba00 = 75282944 Bytes
  16     ## Start Addr      = 0x82000000
  17     Card did not respond to voltage select! : -110
  18     Card did not respond to voltage select! : -110
  19     Cannot persist EFI variables without system partition
  20     Booting /MemoryMapped(0x0,0x82000000,0x867cba00)
  21     EFI stub: Booting Linux Kernel...
  22     EFI stub: Loaded initrd from LINUX_EFI_INITRD_MEDIA_GUID device path
  23     EFI stub: Using DTB from configuration table
  24     EFI stub: Exiting boot services...
  25     Linux version 6.12.73+deb13-riscv64 (debian-kernel@lists.debian.org) (riscv64-linux-gnu-gcc-14 (Debian 14.2.0-19) 14.2.0, GNU ld (GNU Binutils for Debian) 2.44) #1 SMP Debian 6.12.73-1 (2026-02-17)
  26     Machine model: Pine64 Star64
  27     …
  28

Common part

From then on are the familiar steps in sequence for a debian-installer workflow.

Installation notes:

Install with Linux kernel from trixie-backports

Variant boards needing trixie-backports Linux kernel may be configured during the last step of Debian 13 Trixie debian-installer as follows. During the last step of installation, at the Finish the installation: Installation complete prompt:

Advance screen text window to the (n)ext screen window for access to a command line prompt 

   1 (Control-a,n)

Pin Debian Backports to reduced priority 

   1 cat > /target/etc/apt/preferences.d/debian-backports.pref << EOF
   2 Package: *
   3 Pin: release o=Debian Backports,a=stable-backports
   4 Pin-Priority: -1
   5 EOF

Add Debian Trixie Backports to apt sources 

   1 cat > /target/etc/apt/sources.list.d/debian-trixie-backports.sources << EOF
   2 Types: deb deb-src
   3 URIs: http://deb.debian.org/debian
   4 Suites: trixie-backports
   5 Components: main non-free-firmware
   6 Enabled: yes
   7 Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
   8 EOF

Install Linux kernel from Debian Trixie Backports 

   1 for i in /proc /run /sys ; do mount -o bind $i /target$i ; done
   2 chroot /target apt update
   3 chroot /target apt install -t trixie-backports linux-image-riscv64
   4 for i in /proc /run /sys ; do umount /target$i ; done

Return screen text window to the (p)revious screen window and continue with the installation 

   1 (Control-a,p)

U-Boot Linux Access

To access and edit U-Boot environment from a running OS, one can use u-boot-tools which are available in Debian repositories.

u-boot-tools should be configured to read the environment: 

# Edit /etc/fw_env.config and set to content as below:

# NOR example
# MTD device name       Device offset   Env. size       Flash sector size       Number of sectors
/dev/mtd1               0x0000          0x10000         0x1000

When configuration above is complete, one can try to read environment using fw_printenv and set using fw_setenv commands. For these commands to be successful it will first be necessary that there is a valid environment to modify having run env save from U-Boot command line environment.

JH-7110 SoC USB support missing from U-Boot v2025.01

The following errors appearing to console or in dmesg are an indication that a compatible Fdt and Linux Kernel are active however U-Boot is not enabling some required features for JH-7110 integrated USB hardware to function: 

[   27.479820] xhci-hcd xhci-hcd.0.auto: can't setup: -110
[   27.485178] xhci-hcd xhci-hcd.0.auto: probe with driver xhci-hcd failed with error -110

The errors are harmless and USB functionality may be possible with U-Boot v2025.07 and newer (not available in Debian package repository; see upstream U-Boot documentation for advice on building a recent U-Boot release)

LUA Support

At the moment (Feb 10th, 2024), LUA JIT compilation support is not implemented for RISC-V, see Add support for RISC-V issue for the current state. A work in progress JIT support is available at LuaJIT.

HDMI and/or GPU support (experimental)

HDMI / DC8200 can be enabled with a small kernel patch https://github.com/domibel/linux/tree/jh7110_dc8200_hdmi_v7.0.3

Kconfig: 

   1   CONFIG_CMA=y
   2   CONFIG_DMA_CMA=y
   3   CONFIG_DRM_VERISILICON=y

Append cma=64M to the kernel command line (typically via grub, GRUB_CMDLINE_LINUX_DEFAULT).

The GPU can be enabled with a small kernel patch https://github.com/domibel/linux/tree/powervr_on_jh7110_visionfive2_v7.0.3 This is enough for a proof-of-concept compute dispatch and to run vkcube under Weston, but rendering performance is too slow to be practically usable. Requires Mesa 26.1.0 or newer.

Both patches are independent.

CategoryHardware