bsp: qemu-virt64-riscv: update README for booting with rootfs

Now lwext4 is ready, and qemu-virt64-riscv smart can boot with rootfs. Updated README to introduce this. This patch also replace qemu-nographic.sh with run.sh, which has a more simple name and more robust to launch rootfs image binary. TBD: qemu-nographic.bat is not touched, hope some guys from Windows can give a hand. Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
2025-01-19 19:23:30 +08:00 · 2024-12-17 15:45:37 +08:00 · 2024-12-17 15:45:37 +08:00 · 6b246612a6
commit 6b246612a6
parent 1499dbda00
4 changed files with 219 additions and 23 deletions
--- a/bsp/qemu-virt64-riscv/README.md
+++ b/bsp/qemu-virt64-riscv/README.md
@ -14,6 +14,9 @@ English | [中文](./README_cn.md)
 - [3. Running](#3-running)
 	- [3.1. Installing QEMU](#31-installing-qemu)
 	- [3.2. Running QEMU](#32-running-qemu)
+		- [3.2.1. Running RT-Thread Standard Edition](#321-running-rt-thread-standard-edition)
+		- [3.2.2. Running RT-Thread Smart version](#322-running-rt-thread-smart-version)
+		- [3.2.3. Running RT-Thread Smart version + Root file-system](#323-running-rt-thread-smart-version--root-file-system)
 - [4. How to use rv64ilp32 toolchain](#4-how-to-use-rv64ilp32-toolchain)
 - [5. Contact information](#5-contact-information)

@ -83,8 +86,6 @@ $ cd $WORKSPACE
 $ git clone git@github.com:RT-Thread/rt-thread.git
 ```

-**Note: This document is based on the kernel version git commit ID: ebe2926cd6.**
-
 Enter the BSP directory where qemu-virt64-riscv is located. The following operations will not be introduced separately. By default, it is in this directory.

 ```shell
@ -153,13 +154,15 @@ Copyright (c) 2003-2021 Fabrice Bellard and the QEMU Project developers
 The repository has provided a ready-made execution script, which can be executed directly:

 ```shell
-$ ./qemu-nographic.sh
+$ ./run.sh
 ```

-The running results of the RT-Thread Standard version are as follows:
+### 3.2.1. Running RT-Thread Standard Edition
+
+The following is an example:

 ```shell
-$ ./qemu-nographic.sh 
+$ ./run.sh 

 OpenSBI v0.9
   ____                    _____ ____ _____
@ -213,11 +216,12 @@ file system initialization done!
 Hello RISC-V
 msh />
 ```
+### 3.2.2. Running RT-Thread Smart version

-The running results of RT-Thread Smart version are as follows:
+The following is an example:

 ```shell
-$ ./qemu-nographic.sh 
+$ ./run.sh 

 OpenSBI v0.9
   ____                    _____ ____ _____
@ -273,6 +277,89 @@ Hello RISC-V
 msh />
 ```

+### 3.2.3. Running RT-Thread Smart version + Root file-system
+
+For the Smart version of the kernel, you can also specify the path of the root file-system image file when executing the `run.sh` script to mount the root file-system during the startup process.
+
+It should be noted that the kernel supports fat by default. If you want to mount the ext4 file-system, you need to install the lwext4 package additionally, i.e. to enable the `PKG_USING_LWEXT4` option (the specific menuconfig path is (Top) -> RT-Thread online packages -> system packages -> lwext4: an excellent choice of ext2/3/4 filesystem for microcontrollers.). If you can't find the item in the menu, you can exit menuconfig and execute `pkgs --upgrade` to update the package index and then try to enable the package.
+
+After checking this option, you also need to perform the following operations to update the software and install the source code to the packages directory of bsp (this operation only needs to be performed once):
+
+```shell
+$ source ~/.env/env.sh
+$ pkgs --update
+```
+
+Save and recompile the kernel.
+
+For how to make a root file-system, please refer to <https://github.com/RT-Thread/userapps/blob/main/README.md>, which will not be repeated here.
+
+The example is as follows:
+
+```shell
+$ ./run.sh /home/u/ws/duo/userapps/apps/build/ext4.img 
+
+OpenSBI v0.9
+   ____                    _____ ____ _____
+  / __ \                  / ____|  _ \_   _|
+ | |  | |_ __   ___ _ __ | (___ | |_) || |
+ | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
+ | |__| | |_) |  __/ | | |____) | |_) || |_
+  \____/| .__/ \___|_| |_|_____/|____/_____|
+        | |
+        |_|
+
+Platform Name             : riscv-virtio,qemu
+Platform Features         : timer,mfdeleg
+Platform HART Count       : 1
+Firmware Base             : 0x80000000
+Firmware Size             : 100 KB
+Runtime SBI Version       : 0.2
+
+Domain0 Name              : root
+Domain0 Boot HART         : 0
+Domain0 HARTs             : 0*
+Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
+Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
+Domain0 Next Address      : 0x0000000080200000
+Domain0 Next Arg1         : 0x000000008f000000
+Domain0 Next Mode         : S-mode
+Domain0 SysReset          : yes
+
+Boot HART ID              : 0
+Boot HART Domain          : root
+Boot HART ISA             : rv64imafdcsu
+Boot HART Features        : scounteren,mcounteren,time
+Boot HART PMP Count       : 16
+Boot HART PMP Granularity : 4
+Boot HART PMP Address Bits: 54
+Boot HART MHPM Count      : 0
+Boot HART MHPM Count      : 0
+Boot HART MIDELEG         : 0x0000000000000222
+Boot HART MEDELEG         : 0x000000000000b109
+heap: [0x00326438 - 0x04326438]
+
+ \ | /
+- RT -     Thread Smart Operating System
+ / | \     5.2.0 build Dec 17 2024 11:49:39
+ 2006 - 2024 Copyright by RT-Thread team
+lwIP-2.0.3 initialized!
+[I/sal.skt] Socket Abstraction Layer initialize success.
+[I/utest] utest is initialize success.
+[I/utest] total utest testcase num: (0)
+[I/drivers.serial] Using /dev/ttyS0 as default console
+[W/DFS.fs] mount / failed with file system type: elm
+file system initialization done!
+Hello RISC-V
+msh />[E/sal.skt] not find network interface device by protocol family(1).
+[E/sal.skt] SAL socket protocol family input failed, return error -3.
+/ # ls
+bin         lib         proc        sbin        tmp
+dev         lost+found  root        services    usr
+etc         mnt         run         tc          var
+/ # 
+```
+
 # 4. How to use rv64ilp32 toolchain

 - Toolchain address: <https://github.com/ruyisdk/riscv-gnu-toolchain-rv64ilp32/tags>
--- a/bsp/qemu-virt64-riscv/README_cn.md
+++ b/bsp/qemu-virt64-riscv/README_cn.md
@ -14,6 +14,9 @@
 - [3. 运行](#3-运行)
 	- [3.1. 安装 QEMU](#31-安装-qemu)
 	- [3.2. 运行 QEMU](#32-运行-qemu)
+		- [3.2.1. 运行 RT-Thread 标准版](#321-运行-rt-thread-标准版)
+		- [3.2.2. 运行 RT-Thread Smart 版](#322-运行-rt-thread-smart-版)
+		- [3.2.3. 运行 RT-Thread Smart 版 + 根文件系统](#323-运行-rt-thread-smart-版--根文件系统)
 - [4. 如何使用 rv64ilp32 工具链](#4-如何使用-rv64ilp32-工具链)
 - [5. 联系人信息](#5-联系人信息)

@ -83,8 +86,6 @@ $ cd $WORKSPACE
 $ git clone git@github.com:RT-Thread/rt-thread.git
 ```

-**注：本文档基于的内核版本 git commit ID 为: ebe2926cd6。**
-
 进入 qemu-virt64-riscv 所在 BSP 目录，后面的操作不做另外介绍，默认就在这个目录下。

 ```shell
@ -153,13 +154,15 @@ Copyright (c) 2003-2021 Fabrice Bellard and the QEMU Project developers
 仓库里已经提供了现成的执行脚本，可以直接执行：

 ```shell
-$ ./qemu-nographic.sh
+$ ./run.sh
 ```

-RT-Thread 标准版运行结果如下：
+### 3.2.1. 运行 RT-Thread 标准版
+
+示例如下：

 ```shell
-$ ./qemu-nographic.sh 
+$ ./run.sh

 OpenSBI v0.9
   ____                    _____ ____ _____
@ -214,10 +217,12 @@ Hello RISC-V
 msh />
 ```

-RT-Thread Smart 版本运行结果如下：
+### 3.2.2. 运行 RT-Thread Smart 版
+
+示例如下：

 ```shell
-$ ./qemu-nographic.sh 
+$ ./run.sh

 OpenSBI v0.9
   ____                    _____ ____ _____
@ -273,6 +278,89 @@ Hello RISC-V
 msh />
 ```

+### 3.2.3. 运行 RT-Thread Smart 版 + 根文件系统
+
+对于 Smart 版本的内核，也可以在执行 `run.sh` 脚本时指定根文件系统镜像文件的路径在启动过程中挂载根文件系统。
+
+需要注意的是，内核默认支持 fat, 如果要挂载 ext4 的文件系统，则还需要额外安装 lwext4 软件包，即使能 `PKG_USING_LWEXT4`（具体 menuconfig 路径是 (Top) -> RT-Thread online packages -> system packages ->  lwext4: an excellent choice of ext2/3/4 filesystem for microcontrollers.）。如果在菜单中找不到该软件包，可以退出 menuconfig 并执行 `pkgs --upgrade` 更新软件包索引后再尝试使能软件包。
+
+勾选该选项后还需要执行如下操作更新软件并安装源码到 bsp 的 packages 目录下(该操作只要执行一次即可)：
+
+```shell
+$ source ~/.env/env.sh
+$ pkgs --update
+```
+
+保存后重新编译内核。
+
+有关如何制作根文件系统，请参考 <https://github.com/RT-Thread/userapps/blob/main/README.md>，这里不再赘述。
+
+示例如下：
+
+```shell
+$ ./run.sh /home/u/ws/duo/userapps/apps/build/ext4.img 
+
+OpenSBI v0.9
+   ____                    _____ ____ _____
+  / __ \                  / ____|  _ \_   _|
+ | |  | |_ __   ___ _ __ | (___ | |_) || |
+ | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
+ | |__| | |_) |  __/ | | |____) | |_) || |_
+  \____/| .__/ \___|_| |_|_____/|____/_____|
+        | |
+        |_|
+
+Platform Name             : riscv-virtio,qemu
+Platform Features         : timer,mfdeleg
+Platform HART Count       : 1
+Firmware Base             : 0x80000000
+Firmware Size             : 100 KB
+Runtime SBI Version       : 0.2
+
+Domain0 Name              : root
+Domain0 Boot HART         : 0
+Domain0 HARTs             : 0*
+Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
+Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
+Domain0 Next Address      : 0x0000000080200000
+Domain0 Next Arg1         : 0x000000008f000000
+Domain0 Next Mode         : S-mode
+Domain0 SysReset          : yes
+
+Boot HART ID              : 0
+Boot HART Domain          : root
+Boot HART ISA             : rv64imafdcsu
+Boot HART Features        : scounteren,mcounteren,time
+Boot HART PMP Count       : 16
+Boot HART PMP Granularity : 4
+Boot HART PMP Address Bits: 54
+Boot HART MHPM Count      : 0
+Boot HART MHPM Count      : 0
+Boot HART MIDELEG         : 0x0000000000000222
+Boot HART MEDELEG         : 0x000000000000b109
+heap: [0x00326438 - 0x04326438]
+
+ \ | /
+- RT -     Thread Smart Operating System
+ / | \     5.2.0 build Dec 17 2024 11:49:39
+ 2006 - 2024 Copyright by RT-Thread team
+lwIP-2.0.3 initialized!
+[I/sal.skt] Socket Abstraction Layer initialize success.
+[I/utest] utest is initialize success.
+[I/utest] total utest testcase num: (0)
+[I/drivers.serial] Using /dev/ttyS0 as default console
+[W/DFS.fs] mount / failed with file system type: elm
+file system initialization done!
+Hello RISC-V
+msh />[E/sal.skt] not find network interface device by protocol family(1).
+[E/sal.skt] SAL socket protocol family input failed, return error -3.
+/ # ls
+bin         lib         proc        sbin        tmp
+dev         lost+found  root        services    usr
+etc         mnt         run         tc          var
+/ # 
+```
+
 # 4. 如何使用 rv64ilp32 工具链

 - 工具链地址：https://github.com/ruyisdk/riscv-gnu-toolchain-rv64ilp32/tags
--- a/bsp/qemu-virt64-riscv/qemu-nographic.sh
+++ b/bsp/qemu-virt64-riscv/qemu-nographic.sh
@ -1,9 +0,0 @@
-if [ ! -f "sd.bin" ]; then
-dd if=/dev/zero of=sd.bin bs=1024 count=65536
-mkfs.fat sd.bin
-fi
-
-qemu-system-riscv64 -nographic -machine virt -m 256M -kernel rtthread.bin \
-drive if=none,file=sd.bin,format=raw,id=blk0 -device virtio-blk-device,drive=blk0,bus=virtio-mmio-bus.0 \
-netdev user,id=tap0 -device virtio-net-device,netdev=tap0,bus=virtio-mmio-bus.1 \
-device virtio-serial-device -chardev socket,host=127.0.0.1,port=4321,server=on,wait=off,telnet=on,id=console0 -device virtserialport,chardev=console0
--- a/bsp/qemu-virt64-riscv/run.sh
+++ b/bsp/qemu-virt64-riscv/run.sh
@ -0,0 +1,30 @@
+#!/bin/bash
+
+usage ()
+{
+	echo "Usage:"
+	echo "./run.sh [<path_to_image>]"
+	echo "Note: if <path_to_image> is not provided, will create a 'sd.bin'"
+	echo "in the current directory and load it by default."
+}
+
+path_image=${1}
+
+if [ -z $path_image ]; then
+	path_image="./sd.bin"
+	if [ ! -f $path_image ]; then
+		dd if=/dev/zero of=$path_image bs=1024 count=65536
+		mkfs.fat $path_image
+	fi
+fi
+
+if [ ! -f $path_image ]; then
+	echo "ERROR: $path_image does not exist!"
+	usage
+	exit
+fi
+
+qemu-system-riscv64 -nographic -machine virt -m 256M -kernel rtthread.bin \
+-drive if=none,file=$path_image,format=raw,id=blk0 -device virtio-blk-device,drive=blk0,bus=virtio-mmio-bus.0 \
+-netdev user,id=tap0 -device virtio-net-device,netdev=tap0,bus=virtio-mmio-bus.1 \
+-device virtio-serial-device -chardev socket,host=127.0.0.1,port=4321,server=on,wait=off,telnet=on,id=console0 -device virtserialport,chardev=console0