¶ StarFive VisionFive 2 Debian User Guide
About This Manual
Introduction
This document mainly provides the users with the necessary information to install and use StarFive Debian into VisionFive 2.
Debian is an open-source GNU/Linux distribution created by the Debian community.
This document is intended to help users:
- Help users to get started with StarFive VisionFive 2 Single Board Computer (SBC)
- Install StarFive Debian image into VisionFive 2 SBC.
- Learn about the features/applications available on StarFive Debian
¶ Receiving your VisionFive 2 SBC
¶ 2.1 Overview
This section generally explains the setup of VisionFive 2 and some information, including on the boot modes, and setting up serial port.
You can move on to Chapter 3 if you are familiar with Single Board Computers (SBC) in general.
¶ 2.2 Setting Up VisionFive 2 - Checklist
So, after receiving your VisionFive 2 and taken it out of the box, you will need to set up VisionFive 2.
In general, to prepare for VisionFive 2, you will need to prepare the following components:
- USB-C Power Supply
- microSD card (the guide will cover on microSD card usage later)
- eMMC module / NVME can also be used if preferred
- USB card reader for your host PC (unless your PC has it)
For desktop environment usage, don’t forget these too:
- Keyboard and mouse
- Monitor or TV
- HDMI cable
Additionally, here are some optional components which you may also need:
- Ethernet LAN cable or a compatible Wi-Fi dongle (ESWIN6600U or AIC8800 module is enabled by default)
- USB to UART Serial converter module
¶ 2.3 Boot Modes
On VisionFive 2, there are several boot modes available, which include:
- QSPI boot
- SDIO boot
- eMMC boot
- UART (recovery mode)
The following figure displays the location and the pin definitions of the boot mode settings:
¶ 2.4 Serial Port
On setting up serial port, you can refer to the following documents:
For Windows: https://doc-en.rvspace.org/VisionFive2/Quick_Start_Guide/VisionFive2_QSG/for_windows2%20-%20vf2.html
For Mac/Linux: https://doc-en.rvspace.org/VisionFive2/Quick_Start_Guide/VisionFive2_QSG/for_maclinux2%20-%20vf2.html
¶ Installing the StarFive Debian image
¶ 3.1 Overview
After setting up VisionFive 2, we can start to flash the Debian image.
Since there are several boot modes [Chapter 2.4], 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.
You can find the image on the website: https://debian.starfivetech.com/
As of the time of writing, the latest image is the 202306 version which was released in June 2023.
¶ 3.2 Extracting the image
The image downloaded is in an img.bz2 compressed format. To extract the image, you will need to use a tool like 7-Zip in Windows/Linux or `bzip2` command.
For bzip2, you can use the following command, this command will remove the original img.bz2 file. :
bzip2 -d <filename>.img.bz2To preserve the original file, you will need to use
bzip2 -dk <filename>.img.bz2
¶ 3.3 Flashing the image
To flash the image, you can use applications such as balenaEtcher to flash the image into SD card. Insert SD card into your host PC and launch balenaEtcher.
You will just need to choose the extracted .img file and your SD card device. Then, press ‘Flash!’ to proceed.
¶ StarFive Debian
Please refer to JH7110 Technical Documents for your reference
¶ 4.1 Introduction
After flashing the image into your respective SD/eMMC/NVME, now it is the time to boot into Debian Desktop.
Before proceeding, please ensure your respective boot mode is selected correctly:
- If you are booting into your NVME, you will need to set your boot mode as QSPI boot.
- If you are booting with SD card, you will need to set your boot mode as SDIO boot.
- If you are booting with eMMC, you will need to set your boot mode as eMMC boot.
Note: Please refer to 2.3 Boot Modes to set the correct boot modes
¶ 4.2 First Boot Up
1. Connect a display to VisionFive 2 via HDMI cable, or connect VisionFive to your host computer via a USB to serial converter.
2. Set the boot mode as required. You can refer to [2.4 Boot Modes] for more information.
3. Depending on your image (SD/eMMC/NVME), insert it (that contains Debian image) into VisionFive 2 respectively and power it on.
¶ 4.2.1 Logging into Debian
After booting, you will be greeted with the Gnome login interface.
If you are logging in through serial, you will need to specify the username as ‘user’. For Gnome UI, just choose the ‘user’ account and enter the password as follows to login:
- Username: user
- Password: starfive
¶ 4.3 Updating and Upgrading Debian
At the current state, please avoid running `apt upgrade` as it will override the existing customized packages provided by StarFive.
¶ 4.3.1 Expanding the rootfs partition
To fully utilize the unused space on the SD card or eMMC after logging into Debian, perform the following steps:
- Use the following command to list available elements:
~# df -hExample Output:
Filesystem Size Used Avail Use% Mounted on
udev 3.7G 0 3.7G 0% /dev
tmpfs 793M 3.1M 790M 1% /run
/dev/mmcblk1p4 2.0G 1.9G 88M 96% /
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/0Run the fdisk command with disk name as an argument.
- Example Command:
root@starfive:~# fdisk /dev/mmcblk<X>Tip:<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
- Example Output:
root@starfive:~# fdisk /dev/mmcblk1
Welcome to fdisk (util-linux 2.38.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
GPT PMBR size mismatch (4505599 != 62929919) will be corrected by write.
This disk is currently in use - repartitioning is probably a bad idea.
It's recommended to umount all file systems, and swapoff all swap
partitions on this disk.
Command (m for help): d
Partition number (1-4, default 4): 4
Partition 4 has been deleted.
Command (m for help): n
Partition number (4-128, default 4): 4
First sector (34-62929886, default 221184):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (221184-62929886, default 62928895):
Created a new partition 4 of type 'Linux filesystem' and of size 29.9 GiB.
Partition #4 contains a ext4 signature.
Do you want to remove the signature? [Y]es/[N]o: N
Command (m for help): w
The partition table has been altered.
Syncing disks.
- Resize the /dev/mmcblk<X>p4 partition by running the
resize2fscommand to fully utilize the unused block.
Tip:<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
Example Command and Output:
root@starfive:~# resize2fs /dev/mmcblk1p4
resize2fs 1.46.6-rc1 (12-Sep-2022)
Filesystem at /d[ 295.372617] EXT4-fs (mmcblk1p4): resizing filesystem from 535291 to 7838464 blocks
ev/mmcblk1p4 is mounted on /; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 4
[ 295.993163] EXT4-fs (mmcblk1p4): resized filesystem to 7838464
The filesystem on /dev/mmcblk1p4 is now 7838464 (4k) blocks long.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.
The following output indicates the modification is successful:
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
¶ 4.3.2 Installing some essential packages
There are some packages that you can install to improve the overall user experience, which includes:
- vim
- nautilus (Gnome File Viewer)
¶ 4.3.3 Installing packages provided by StarFive
Some packages particular are not available to download via apt/apt-get, and is provided by StarFive, which includes (as of June 2023):
- Node.js 18.0.0
- v8 10.2.154.13
- libsdl2-dev
- QT 5.15.2
- Firefox 105.0
- Libreoffice 7.5
- NW.js
- FFmpeg
- GStreamer
- v4l2test (This is a custom shell script to use the CSI camera)
- Chromium 103
- VLC 3.0.18
Debian Repo for StarFive Packages: Github Link
There is a script prepared so that you can install the packages (and its runtime dependencies) with the run of a script. You will just need to run:
wget https://github.com/starfive-tech/Debian/releases/download/v0.12.0-engineering-release-wayland/install_package_and_dependencies.sh
chmod +x install_package_and_dependencies.sh
sudo ./install_package_and_dependencies.shThis script will help to install the packages provided by StarFive. Feel free to customize the script to suit your needs.
¶ 4.4 Updating U-boot in SPI (using mtd-utils)
To update SPL and U-Boot through the flashcp command, perform the following steps:
Note:This method requires to enter the Debian OS and only supports versions equal to or later than VF2_v2.5.0.
Install the mtd-utils package by executing the following command:
apt install mtd-utilsTransfer the latest u-boot-spl.bin.normal.out and visionfive2_fw_payload.img files to Debian system through SCP.
Execute the following command to check the MTD partition:
cat /proc/mtdExample Output:
You will see the partition information in the QSPI flash:
dev: size erasesize name
mtd0: 00020000 00001000 "spl"
mtd1: 00300000 00001000 "uboot"
mtd2: 00100000 00001000 "data"
Update the SPL and U-Boot binaries according to different partitions:
- Example command to update SPL:
flashcp -v u-boot-spl.bin.normal.out /dev/mtd0
- Example command to update U-Boot:
flashcp -v visionfive2_fw_payload.img /dev/mtd1Example Command and Output:
# flashcp -v u-boot-spl.bin.normal.out /dev/mtd0
Erasing blocks: 32/32 (100%)
Writing data: 124k/124k (100%)
Verifying data: 124k/124k (100%)
# flashcp -v visionfive2_fw_payload.img /dev/mtd1
Erasing blocks: 682/682 (100%)
Writing data: 2727k/2727k (100%)
Verifying data: 2727k/2727k (100%)Restart the system to make the updates take effect.
¶ 4.5 Updating U-boot in SD/eMMC (using dd)
To update SPL and U-Boot of SD Card and eMMC, perform the following steps:
Transfer the latest U-Boot-spl.bin.normal.out and visionfive2_fw_payload.img files into Debian OS through SCP.
- Update SPL.
dd if=u-boot-spl.bin.normal.out of=/dev/mmcblk<X>p1 conv=fsync
- Update U-Boot.
dd if=visionfive2_fw_payload.img of=/dev/mmcblk<X>p2 conv=fsyncTip:<X>: The application value is 0 or 1. 1 for SD card and 0 for eMMC.
Example command and output:
root@starfive:~# dd if=u-boot-spl.bin.normal.out of=/dev/mmcblk1p1 conv=fsync
255+1 records in
255+1 records out
130688 bytes (131 kB, 128 KiB) copied, 0.033136 s, 3.9 MB/s
root@starfive:~# dd if=visionfive2_fw_payload.img of=/dev/mmcblk1p2 conv=fsync
5469+1 records in
5469+1 records out
2800501 bytes (2.8 MB, 2.7 MiB) copied, 0.619333 s, 4.5 MB/sRestart the system to make the updates take effect.
¶ 4.6 Compiling and Updating Linux Kernel
Install dependencies to build kernel
apt-get install build-essential linux-source bc kmod cpio flex libncurses5-dev libelf-dev libssl-dev dwarves bison gitClone the kernel from StarFive Github
git clone https://github.com/starfive-tech/linuxCheckout the desired kernel version
git checkout <tag version>Build the kernel with bindeb-pkg
cd linux/
cp arch/riscv/configs/starfive_visionfive2_defconfig .config
make ARCH=riscv olddefconfig
make ARCH=riscv -j$(nproc) bindeb-pkgOnce the compile is finished, install the .deb kernel packages
dpkg -i *.debNote: 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>/ to /boot/dtbs/
¶ Debian User Guide
¶ 5.1 Gnome Customization (gnome-tweaks and gnome-extension)
The Gnome Tweak Tools allows you to configure advanced settings, which include settings like startup applications, themes, fonts and much more. You can access the application via Gnome overview or
¶ 5.2 Package Manager (apt)
TBD
¶ 5.3 Search for Available Software/Packages (apt-cache search)
You can search for software that is available for apt install too.
You will just need to run `sudo apt-cache search <name>` to find if the package is available, for example:
sudo apt-cache search tree
¶ 5.4 Network Information (ip a & ssh)
To view the current IP address of VisionFive, you can either go to the Network Settings in Gnome desktop, or you can open an terminal (or serial) and use the `ip a` command to view it.
