VisionFive2 QSG
VisionFive2 QSG
VisionFive2 QSG
PROPRIETARY NOTICE
Copyright©Shanghai StarFive Technology Co., Ltd., 2023. All rights reserved.
Information in this document is provided "as is," with all faults. Contents may be periodically
updated or revised due to the product development. Shanghai StarFive Technology Co.,
Ltd.(hereinafter "StarFive") reserves the right to make changes without further notice to any
products herein.
StarFive expressly disclaims all warranties, representations, and conditions of any kind, whether
express or implied, including, but not limited to, the implied warranties or conditions of
merchantability, fitness for a particular purpose and non-infringement.
StarFive does not assume any liability rising out of the application or use of any product or circuit,
and specifically disclaims any and all liability, including without limitation indirect, incidental, special,
exemplary, or consequential damages.
All material appearing in this document is protected by copyright and is the property of StarFive.
You may use this document or any part of the document for internal or educational purposes only,
provided you do not modify, edit or take out of context the information in this document in any
manner. Information contained in this document may be used, at your sole risk, for any purposes.
StarFiveauthorizes you to copy this document, provided that you retain all copyright and other
proprietary notices contained in the original materials on any copies of the materials and that you
comply strictly with these terms. This copyright permission does not constitute an endorsement of
the products or services.
Contact Us
Address: Room 502, Building 2, No. 61 Shengxia Rd., China (Shanghai) Pilot Free Trade Zone,
Shanghai, 201203, China Room 502, Building 2, No. 61 Shengxia Rd., China (Shanghai) Pilot Free
Trade Zone, Shanghai, 201203, China
Website: http://www.starfivetech.com http://www.starfivetech.com
Email: sales@starfivetech.com(sales) , support@starfivetech.com(support)
ii
Preface
About this guide and technical support information.
Revision History
1.71 2023/11/06 Updated the partition info of QSPI Flash in Updating SPL
and U-Boot of Flash (on page 36).
iii
Table 0-1 Revision History (continued)
Version Released Revision
1.62 2023/05/10 Updated VisionFive 2 Boot Mode Settings (on page 50).
iv
Table 0-1 Revision History (continued)
Version Released Revision
• Tip:
Suggests how to apply the information in a topic or step.
• Note:
Explains a special case or expands on an important point.
• Important:
Points out critical information concerning a topic or step.
• CAUTION:
Indicates that an action or step can cause loss of data, security problems, or
performance issues.
• Warning:
Indicates that an action or step can result in physical harm or cause damage to
hardware.
v
Contents
List of Tables..........................................................................................................................................8
List of Figures........................................................................................................................................ 9
Legal Statements................................................................................................................................... ii
Preface.................................................................................................................................................. iii
1. Features and Specifications..................................................................................................... 10
1.1. Features................................................................................................................................10
1.1.1. Hardware................................................................................................................... 10
1.1.2. Interfaces................................................................................................................... 11
1.1.3. Software.................................................................................................................... 12
1.2. Specifications........................................................................................................................12
2. Hardware Overview.................................................................................................................15
2.1. Board Appearance................................................................................................................15
2.2. Pinout Diagram.....................................................................................................................17
3. Getting Started........................................................................................................................ 19
3.1. Required Hardware.............................................................................................................. 19
3.2. Connecting a Fan to VisionFive 2.........................................................................................21
3.3. Flashing OS to a Micro-SD Card........................................................................................... 21
3.3.1. Flashing with Linux or Windows............................................................................... 22
3.4. Logging into Debian............................................................................................................. 23
3.4.1. Using Desktop over HDMI.........................................................................................24
3.4.2. Using SSH over Ethernet........................................................................................... 25
3.4.3. Using a USB to Serial Converter................................................................................28
3.5. Avoid Running apt upgrade................................................................................................. 33
3.6. Extend Partition on SD Card or eMMC................................................................................ 33
3.7. Install Packages.................................................................................................................... 35
3.8. Updating SPL and U-Boot.....................................................................................................36
3.8.1. Updating SPL and U-Boot of Flash............................................................................ 36
3.8.2. Updating SPL and U-Boot of SD Card and eMMC..................................................... 41
3.9. Compiling and Updating Linux Kernel.................................................................................41
4. Appendix................................................................................................................................. 43
4.1. Debian Customization.......................................................................................................... 43
4.2. Using SSH over Ethernet as Root Account...........................................................................43
4.3. Recovering the Bootloader.................................................................................................. 44
List of Tables
Table 0-1 Revision History.................................................................................................................... iii
Table 2-1 Board Appearance Description........................................................................................... 16
Table 4-1 GitHub Repository Addresses..............................................................................................49
Table 4-2 Boot Mode Settings.............................................................................................................50
List of Figures
Figure 2-1 Board Appearance (Top View)........................................................................................... 15
Figure 2-2 Board Appearance (Bottom View)..................................................................................... 16
Figure 2-3 Pinout Diagram.................................................................................................................. 17
Figure 3-1 NPTHs on VisionFive 2.......................................................................................................20
Figure 3-2 Single head hexagonal copper columns............................................................................ 20
Figure 3-3 Double way hexagon copper studs....................................................................................20
Figure 3-4 SSD Mounting Location......................................................................................................21
Figure 3-5 Connecting a Fan to VisionFive 2...................................................................................... 21
Figure 3-6 Install BalenaEtcher........................................................................................................... 23
Figure 3-7 Debian Interface................................................................................................................ 25
Figure 3-8 Example Output................................................................................................................. 27
Figure 3-9 Example Output................................................................................................................. 28
Figure 3-10 Connecting Jumper Wire................................................................................................. 29
Figure 3-11 Example............................................................................................................................29
Figure 3-12 Example Configuration.....................................................................................................30
Figure 3-13 Example Output............................................................................................................... 31
Figure 3-14 Connecting Jumper Wires................................................................................................31
Figure 3-15 Example Output............................................................................................................... 32
Figure 3-16 Example Output............................................................................................................... 32
Figure 3-17 Example Output............................................................................................................... 33
Figure 4-1 Connecting to the Debug Pins of VisionFive 2 40-pin GPIO Header.................................. 44
Figure 4-2 Boot Mode Setting (UART)................................................................................................ 45
Figure 4-3 Example Output................................................................................................................. 45
Figure 4-5 Example Output................................................................................................................. 47
Figure 4-7 Example Output................................................................................................................. 48
Figure 4-9 Boot Mode Setting Location.............................................................................................. 51
Figure 4-10 Boot Mode Settings......................................................................................................... 52
1.1. Features
VisionFive 2 provides the following features.
• Hardware (on page 10)
• Interfaces (on page 11)
• Software (on page 12)
1.1.1. Hardware
Processor
• StarFive JH-7110 with RISC-V quad-core CPU with 2 MB L2 cache and a monitor core,
supporting RV64GC ISA, working up to 1.5 GHz
• IMG BXE-4-32 MC1 with work frequency up to 600 MHz
Memory
VisionFive 2 provides the system memory of 2 GB, 4 GB, or 8 GB LPDDR4 SDRAM up to 2,800 Mbps.
Storage
• Onboard TF card slot: The VisionFive 2 can boot from the TF card.
• Flash: The firmware to store U-Boot and BootLoader.
Video Processing
The video processing of VisionFive 2 has the following features.
1.1.2. Interfaces
1.1.3. Software
Operating System
VisionFive 2 supports Debian operating system.
For more software resources, please follow the StarFive GitHub repository.
1.2. Specifications
VisionFive 2 has the following specifications.
Note:
Only one MIPI DSI port can be used for
display at a time.
USB Device 1 × USB device port (by reusing the USB-C port)
PoE (Power over Ethernet) Power function is enabled and requires sepa
rate PoE HAT
GPIO 40-Pin GPIO Header 1 × 40-pin GPIO header, supporting various in
terface options:
• 3.3 V (on 2 pins)
• 5 V (on 2 pins)
• Ground (on 8 pins)
• GPIO
• CAN bus
• DMIC
• I2C
• I2S
• PWM
• SPI
Boot Mode Boot mode setting pins You can choose one of the following boot
modes:
• 1-bit QSPI Nor Flash
• SDIO3.0
• eMMC
• UART
Button Reset button To reset VisionFive 2, press and hold the Reset
button for more than 3 seconds to ensure the
reset is successful.
Dimensions 100 × 74 mm -
Other Debug function UART TX and UART RX are available through the
40-pin GPIO header.
CAUTION:
During the use of VisionFive 2, avoid contact with hard objects that may cause damage.
13 GMAC1 PHY - -
GPIO42 11 12 GPIO38
GPIO43 13 14 GND
GPIO47 15 16 GPIO54
3.3V Power 17 18 GPIO51
GPIO45 27 28 GPIO40
GPIO37 29 30 GND
GPIO60 37 38 GPIO61
GND 39 40 GPIO44
Note:
• Each GPIO pin can safely draw a maximum current of 32 mA, whereas the maximum
current draw when all GPIOs are combined should be less than 100 mA. Please take
this into account or otherwise, you will end up destroying the GPIO pins.
• All GPIOs can be configured to support different functions including but not limited
to SDIO, Audio, SPI, I2C, UART, and PWM. For the instructions, refer to the VisionFive
2 40-Pin GPIO Header User Guide.
Tip:
This is used for system recovery via UART boot mode.
Warning:
During the use of VisionFive 2, avoid contact with hard objects that may cause damage.
Thus, StarFive recommends that you use spacers for the following NPTHs (Non Plating
Through Hole):
For spacers, StarFive strongly recommends that you use the copper columns or studs with
the following specifications:
• Single head hexagonal copper columns (Size: M2.5*10+6mm)
Figure 3-2 Single head hexagonal copper columns
Note:
The recommended SSD mounting screw for VisionFive 2 is M2 × 3 mm (Head Diameter: 5.0
mm).
2/4/8 GB PoE
LPDDR4
MIPI CSI
EEPROM
PMIC
4-Lane MIPI DSI
JH7110 +5V
Fan Header
USB 3.0 GND
Host
Controller
GMAC1 GMAC0 - +
PHY PHY
HDMI 2.0
To flash the image with Linux or Windows, perform the following steps:
1. Insert a micro-SD card into the computer through a micro-SD card reader, or by a built-in card
reader on a laptop.
2. Download the latest Debian image from: this link.
Note:
The latest Debian images are located in the 202308 folder. Make sure you use the
latest image.
Since there are several boot modes as described in VisionFive 2 Boot Mode Settings
(on page 50), different Debian images are also prepared, which include:
• NVME image
• SD image
• eMMC image
Thus, depending on user’s preference, you will need to choose the image to
download accordingly.
bzip2 -d <filename>.img.bz2
4. Visit this link to download BalenaEtcher. We will use BalenaEtcher software to flash the
Debian image to a micro-SD card.
5. Install BalenaEtcher and open it.
6. Click Flash from file and select the location of the image where we just unzipped the
following file:
starfive-jh7110-VF2-<Version>.img
Tip:
<Version> indicates the version number of the Debian image.
Tip:
StarFive recommends that you use SD card or eMMC mode since the versions of SPL
and U-Boot in the QSPI flash may be outdated and require update. If you need to
update SPL and U-Boot, refer to Updating SPL and U-Boot (on page 36).
Tip:
If you need to load different DTB files, update the ./boot/uEnv.txt file as described
in the Step 6 under Adding New File section in the VisionFive 2 Single Board Computer
Software Technical Reference Manual.
Tip:
You can easily find the IP address of the VisionFive 2 by referring to its hostname,
starfive.
Tip:
Putty is an SSH and telnet client through which you can connect to the Carrier Board.
You can skip this step if you already have Putty installed.
Note:
If you don't need to login as root, skip this step.
Note:
If you want to login as root account, perform the previous step and change the
Username as root in the following credentials.
• Username: user
• Password: starfive
Result:
1. Log in to your router (usually you need to enter 192.168.1.1 on the web browser to enter the
router).
2. Go to DHCP configuration and find the IP address of the VisionFive 2.
Tip:
You can easily find the IP address of the VisionFive 2 by referring to its hostname,
starfive.
3. (Optional) Decide the user account. If you need to use the root account for privileged
operations in remote access, follow the instructions in Using SSH over Ethernet as Root
Account (on page 43).
Note:
If you don't need to login as root, skip this step.
Note:
The following command is using user account as an example. If you need to login as
root account, make sure you perform the previous step and change user as root in
the following command.
ssh user@192.168.1.xxx
Tip:
192.168.1.xxx is the IP address of VisionFive 2.
Tip:
192.168.1.xxx is the IP address of VisionFive 2.
IC
GND
+5V
GPIO42 11 12 GPIO38
GPIO43 13 14 GND
GPIO47 15 16 GPIO54
3.3V Power 17 18 GPIO51
GPIO45 27 28 GPIO40
GPIO37 29 30 GND
GPIO60 37 38 GPIO61
GND 39 40 GPIO44
Tip:
Putty is an SSH and telnet client through which you can connect to the Carrier Board
via SSH. You can skip this step if you already have Putty installed.
c. Click Open.
9. Power on the VisionFive 2.
10. Type username and password in the prompt as follows:
Note:
You can use either user or root account to login. The following example use user to
login.
• Username: user
• Password: starfive
Result:
1. Insert the micro-SD card with the Debian image burnt into VisionFive 2.
2. Connect one end of the USB Type-C cable to the USB Type-C port on the VisionFive 2, and
connect the other end of the cable to the power adapter.
3. Connect the jumper wires between the USB-to-Serial converter and the 40-Pin GPIO header
of the VisionFive 2 as follows.
Figure 3-14 Connecting Jumper Wires
3Y3
TXD
RXD
IC
GND
+5V
GPIO42 11 12 GPIO38
GPIO43 13 14 GND
GPIO47 15 16 GPIO54
3.3V Power 17 18 GPIO51
GPIO45 27 28 GPIO40
GPIO37 29 30 GND
GPIO60 37 38 GPIO61
GND 39 40 GPIO44
Note:
The baud rate is set to 115,200.
Note:
You can use either user or root account to login. The following example use user to
login.
• Username: user
• Password: starfive
Result:
~# df -h
Example Output:
Tip:
<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
Example Output:
3. Resize the /dev/mmcblk<X>p4 partition by running the resize2fs command to fully utilize
the unused block.
Tip:
<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
Verification:
Run df -h to verify the new size of partition, and to verify that our steps to extend partition
(/dev/mmcblk<X>p4) are successful.
Tip:
<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
root@starfive:~# df -h
Filesystem Size Used Avail Use% Mounted on
udev 3.7G 0 3.7G 0% /dev
tmpfs 793M 3.1M 790M 1% /run
/dev/mmcblk1p4 30G 1.9G 28G 7% /
tmpfs 3.9G 0 3.9G 0% /dev/shm
tmpfs 5.0M 12K 5.0M 1% /run/lock
tmpfs 793M 32K 793M 1% /run/user/107
tmpfs 793M 24K 793M 1% /run/user/0
Note:
Make sure VisionFive 2 is connected to the Internet before running the script.
wget
https://github.com/starfive-tech/Debian/releases/download/v0.8.0-engineerin
g-release-wayland/install_package_and_dependencies.sh
chmod +x install_package_and_dependencies.sh
sudo ./install_package_and_dependencies.sh
To update SPL and U-Boot of flash for VisionFive 2, two methods are provided:
Note:
For instructions to create SPL and fw_payload (U-Boot) files, refer to Creating SPL File
and Creating fw_payload File sections in the VisionFive 2 Single Board Computer Software
Technical Reference Manual.
Note:
Method 2 only supports versions equal to or later than VF2_v2.5.0.
Note:
Step 1-7 are performed on the host PC while Step 8-13 are performed on VisionFive 2.
1. Connect one end of an Ethernet cable to the VisionFive 2 RJ45 connector, and connect the
other end of the cable to a router.
2. Install a TFTP server on the host PC by executing:
TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/home/user/tftp"
TFTP_ADDRESS=":69"
TFTP_OPTIONS="-c -l -s"
Note:
TFTP_DIRECTORY refers to the directory to store bootloader, u-boot, SPL, image
and so on.
8. Power on VisionFive 2 and wait until it enters the U-Boot command line interface.
Tip:
• Prerequisite:
◦ An USB to TTL (Transistor-Transistor Logic) converter. Connect the USB
to the computer, and connect the Dupont cable to the correct extension
pin of VisionFive 2. Please pay attention to the cross connection of TX
and RX.
◦ Install Putty or secureCRT on your PC.
• When you power on the VisionFive 2, the serial port will print countdown,
usually starting from 3. Hit any key to stop autoboot before the number
decreases to 0, and you can enter the U-Boot command mode.
Note:
Generally, the default IP of a router is 192.168.120.1. In this case, use the server IP
as the IP assigned by the DHCP server of the router and use the VisionFive 2 IP as
192.168.120.xxx. However, if your router IP is different (for example, 192.168.2.1 ),
make sure the server IP and VisionFive 2 IP are in the same IP domain (for example,
192.168.2.xxx).
ping 192.168.120.99
Result:
The following output indicates that the host PC and VisionFive 2 have established
communication on the same network.
sf probe
Result:
StarFive # sf probe
SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB,
total 16 MiB
12. Update SPL binary, the following is the command and example output:
13. Update U-Boot binary, the following is the command and example output:
Note:
This method requires to enter the Debian OS and only supports versions equal to or later
than VF2_v2.5.0.
cat /proc/mtd
Example Output:
You will see the partition information in the QSPI flash:
To update SPL and U-Boot of SD Card and eMMC, perform the following steps:
1. Transfer the latest U-Boot-spl.bin.normal.out and
visionfive2_fw_payload.img files into Debian OS through SCP.
2. Update SPL.
3. Update U-Boot.
Tip:
<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
cd linux/
cp arch/riscv/configs/starfive_visionfive2_defconfig .config
make ARCH=riscv olddefconfig
make ARCH=riscv -j$(nproc) bindeb-pkg
dpkg -i *.deb
Note:
Currently the dtbs are not synced once you installed a different version of kernel,
you'll need to copy over the dtbs from /usr/lib/linux-image-<custom
version>/starfive to /boot/dtbs/
$ ssh root@192.168.120.41
ssh: connect to host 192.168.120.41 port 22: Connection refused
Result:
You will be able to use SSH login using the root account. The following output indicates the
login is successful:
Example Output:
$ ssh root@192.168.120.41
root@192.168.120.41's password:
Linux starfive 5.15.0-starfive #1 SMP Fri Feb 24 03:26:44 EST 2023
riscv64
The programs included with the Debian GNU/Linux system are free
software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
3. Login as root account using SSH as described in Using SSH over Ethernet (on page 25).
GPIO42 11 12 GPIO38
GPIO43 13 14 GND
GPIO47 15 16 GPIO54
3.3V Power 17 18 GPIO51
GPIO45 27 28 GPIO40
GPIO37 29 30 GND
GPIO60 37 38 GPIO61
GND 39 40 GPIO44
2. Before you recover the bootloader, double check the boot mode jumpers (Switch_2) on your
board has already been switched to UART mode (RGPIO_1,RGPIO_0: 1,1).
Tip:
The following figure shows the boot mode settings. For more information, refer to
VisionFive 2 Boot Mode Settings (on page 50).
CCCCCCCCCCCCCCCCCCCCC
Tip:
<Version> indicates the version number of the recovery file. Make sure you use the
latest version.
6. Type 0 and press Enter on your keyboard to update SPL binary <u-boot-
spl.bin.normal.out>.
8. Power off and switch jumpers back to Flash mode (RGPIO_1,RGPIO_0: 0,0).
Note:
Make sure you have switched to the corresponding branch.
Debian Debian -
Note:
StarFive recommends that you use 1-bit QSPI Nor Flash mode since there is a low possibility
that the VisionFive 2 may fail to boot in eMMC or SDIO3.0 boot mode. Try restarting the
VisionFive 2 if fails to boot in eMMC or SDIO3.0 boot mode.
The following figure displays the location and the pin definitions of the boot mode settings.
Note:
The silk prints may vary with different versions of boards.