1**QEMU/RISCV64 VIRT 板级支持包使用说明**
2
3中文页 | [English](./README.md)
4
5<!-- TOC -->
6
7- [1. 简介](#1-简介)
8- [2. 构建](#2-构建)
9	- [2.1. 安装工具链](#21-安装工具链)
10	- [2.2. 设置 RT-Thread 工具链环境变量](#22-设置-rt-thread-工具链环境变量)
11	- [2.3. 下载内核](#23-下载内核)
12	- [2.4. 配置内核](#24-配置内核)
13	- [2.5. 编译内核](#25-编译内核)
14- [3. 运行](#3-运行)
15	- [3.1. 安装 QEMU](#31-安装-qemu)
16	- [3.2. 运行 QEMU](#32-运行-qemu)
17		- [3.2.1. 运行 RT-Thread 标准版](#321-运行-rt-thread-标准版)
18		- [3.2.2. 运行 RT-Thread Smart 版](#322-运行-rt-thread-smart-版)
19		- [3.2.3. 运行 RT-Thread Smart 版 + 根文件系统](#323-运行-rt-thread-smart-版--根文件系统)
20- [4. 如何使用 rv64ilp32 工具链](#4-如何使用-rv64ilp32-工具链)
21- [5. 联系人信息](#5-联系人信息)
22
23<!-- /TOC -->
24
25# 1. 简介
26
27RISC-V 是一种开放和免费的指令集体系结构 (ISA)。本工程是在 QEMU 的 RISCV64 VIRT 版本上进行的一份移植。
28
29本工程支持玄铁团队联合中科院软件所共同推出的全球首款 rv64ilp32 产品级开源工具链。
30
31# 2. 构建
32
33工作系统：以 Ubuntu 22.04 为例：
34
35```shell
36$ lsb_release -a
37No LSB modules are available.
38Distributor ID: Ubuntu
39Description:    Ubuntu 22.04.2 LTS
40Release:        22.04
41Codename:       jammy
42```
43
44## 2.1. 安装工具链
45
46具体使用的工具链，和 RT-Thread 官方保持一致，具体的工具链版本可以参考 RT-Thread 仓库的 <https://github.com/RT-Thread/rt-thread/blob/master/.github/workflows/action_utest.yml> 这个文件。
47
48```yaml
49    - name: Install RISC-V ToolChains
50      if: ${{ matrix.legs.QEMU_ARCH == 'riscv64' && matrix.legs.UTEST != 'rtsmart/riscv64' && success() }}
51      run: |
52        wget -q https://github.com/RT-Thread/toolchains-ci/releases/download/v1.4/riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14.tar.gz
53        sudo tar zxvf riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14.tar.gz -C /opt
54        /opt/riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14/bin/riscv64-unknown-elf-gcc --version
55        echo "RTT_EXEC_PATH=/opt/riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14/bin" >> $GITHUB_ENV
56
57    - name: Install RISC-V Musl ToolChains
58      if: ${{ matrix.legs.QEMU_ARCH == 'riscv64' && matrix.legs.UTEST == 'rtsmart/riscv64' && success() }}
59      shell: bash
60      run: |
61        wget -q https://github.com/RT-Thread/toolchains-ci/releases/download/v1.7/riscv64-linux-musleabi_for_x86_64-pc-linux-gnu_latest.tar.bz2
62        sudo tar xjf riscv64-linux-musleabi_for_x86_64-pc-linux-gnu_latest.tar.bz2 -C /opt
63        /opt/riscv64-linux-musleabi_for_x86_64-pc-linux-gnu/bin/riscv64-unknown-linux-musl-gcc --version
64        echo "RTT_EXEC_PATH=/opt/riscv64-linux-musleabi_for_x86_64-pc-linux-gnu/bin" >> $GITHUB_ENV
65        echo "RTT_CC_PREFIX=riscv64-unknown-linux-musl-" >> $GITHUB_ENV
66```
67
68其中 `riscv64-unknown-elf-gcc` 用于构建 RT-Thread 标准版，`riscv64-unknown-linux-musl-gcc` 用于构建 RT-Thread Smart 版。根据上面所示链接分别下载到本地后解压缩。
69
70## 2.2. 设置 RT-Thread 工具链环境变量
71
72和 RT-Thread 工具链相关的环境变量有三个
73
74- `RTT_CC` 为工具链名称, 这里统一为 `"gcc"`
75- `RTT_CC_PREFIX`: 为工具链前缀, 这里对于标准版是 `"riscv64-unknown-elf-"`，对于 Smart 版是 `"riscv64-unknown-linux-musl-"`。
76- `RTT_EXEC_PATH`: 工具链的 bin 文件夹所在路径, 如 `"$HOME/tools/riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14/bin"`, 这个根据个人下载解压后的实际路径进行设置，注意 RT-Thread 标准版和 Smart 版本的工具链是两套不同的版本，而且设置 `RTT_EXEC_PATH` 的路径名时要一直到 `bin`。
77
78如果一直使用的话，建议将这三个环境变量在 `.bashrc` 文件中 export。
79
80## 2.3. 下载内核
81
82假设工作路径是 `$WORKSPACE`。
83
84```shell
85$ cd $WORKSPACE
86$ git clone git@github.com:RT-Thread/rt-thread.git
87```
88
89进入 qemu-virt64-riscv 所在 BSP 目录，后面的操作不做另外介绍，默认就在这个目录下。
90
91```shell
92$ cd $WORKSPACE/rt-thread/bsp/qemu-virt64-riscv
93```
94
95## 2.4. 配置内核
96
97第一次编译前先刷新一下配置文件。
98
99```shell
100$ scons --menuconfig
101```
102
103默认配置就是 RT-Thread 标准版，所以如果没有什么特别需求，什么都不要改动，直接保存退出即可。
104
105如果要使用 RT-Thread Smart 版，进入配置菜单后至少要打开 `RT_USING_SMART` 这个选项(见下图)，其他的看自己的需求。
106
107```
108(Top) → RT-Thread Kernel
109                                                                RT-Thread Project Configuration
110(24) The maximal size of kernel object name
111[ ] Use the data types defined in ARCH_CPU
112[*] Enable RT-Thread Smart (microkernel on kernel/userland)
113[ ] Enable RT-Thread Nano
114...
115```
116
117修改后保存退出。
118
119## 2.5. 编译内核
120
121如果以前编译后，可以清理一下：
122
123```shell
124$ scons --clean
125```
126
127或者直接编译：
128
129```shell
130$ scons -j$(nproc)
131```
132
133在 `$WORKSPACE/rt-thread/bsp/qemu-virt64-riscv` 路径下会生成内核的二进制文件 `rtthread.bin`。
134
135# 3. 运行
136
137## 3.1. 安装 QEMU
138
139```shell
140$ sudo apt update
141$ sudo apt install qemu-system-misc
142```
143
144安装完毕后可以看一下版本。
145
146```shell
147$ qemu-system-riscv64 --version
148QEMU emulator version 6.2.0 (Debian 1:6.2+dfsg-2ubuntu6.24)
149Copyright (c) 2003-2021 Fabrice Bellard and the QEMU Project developers
150```
151
152## 3.2. 运行 QEMU
153
154仓库里已经提供了现成的执行脚本，可以直接执行：
155
156```shell
157$ ./run.sh
158```
159
160### 3.2.1. 运行 RT-Thread 标准版
161
162示例如下：
163
164```shell
165$ ./run.sh
166
167OpenSBI v0.9
168   ____                    _____ ____ _____
169  / __ \                  / ____|  _ \_   _|
170 | |  | |_ __   ___ _ __ | (___ | |_) || |
171 | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
172 | |__| | |_) |  __/ | | |____) | |_) || |_
173  \____/| .__/ \___|_| |_|_____/|____/_____|
174        | |
175        |_|
176
177Platform Name             : riscv-virtio,qemu
178Platform Features         : timer,mfdeleg
179Platform HART Count       : 1
180Firmware Base             : 0x80000000
181Firmware Size             : 100 KB
182Runtime SBI Version       : 0.2
183
184Domain0 Name              : root
185Domain0 Boot HART         : 0
186Domain0 HARTs             : 0*
187Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
188Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
189Domain0 Next Address      : 0x0000000080200000
190Domain0 Next Arg1         : 0x000000008f000000
191Domain0 Next Mode         : S-mode
192Domain0 SysReset          : yes
193
194Boot HART ID              : 0
195Boot HART Domain          : root
196Boot HART ISA             : rv64imafdcsu
197Boot HART Features        : scounteren,mcounteren,time
198Boot HART PMP Count       : 16
199Boot HART PMP Granularity : 4
200Boot HART PMP Address Bits: 54
201Boot HART MHPM Count      : 0
202Boot HART MHPM Count      : 0
203Boot HART MIDELEG         : 0x0000000000000222
204Boot HART MEDELEG         : 0x000000000000b109
205heap: [0x8028d8a8 - 0x8428d8a8]
206
207 \ | /
208- RT -     Thread Operating System
209 / | \     5.2.0 build Nov 14 2024 15:41:57
210 2006 - 2024 Copyright by RT-Thread team
211lwIP-2.0.3 initialized!
212[I/sal.skt] Socket Abstraction Layer initialize success.
213[I/utest] utest is initialize success.
214[I/utest] total utest testcase num: (0)
215file system initialization done!
216Hello RISC-V
217msh />
218```
219
220### 3.2.2. 运行 RT-Thread Smart 版
221
222示例如下：
223
224```shell
225$ ./run.sh
226
227OpenSBI v0.9
228   ____                    _____ ____ _____
229  / __ \                  / ____|  _ \_   _|
230 | |  | |_ __   ___ _ __ | (___ | |_) || |
231 | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
232 | |__| | |_) |  __/ | | |____) | |_) || |_
233  \____/| .__/ \___|_| |_|_____/|____/_____|
234        | |
235        |_|
236
237Platform Name             : riscv-virtio,qemu
238Platform Features         : timer,mfdeleg
239Platform HART Count       : 1
240Firmware Base             : 0x80000000
241Firmware Size             : 100 KB
242Runtime SBI Version       : 0.2
243
244Domain0 Name              : root
245Domain0 Boot HART         : 0
246Domain0 HARTs             : 0*
247Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
248Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
249Domain0 Next Address      : 0x0000000080200000
250Domain0 Next Arg1         : 0x000000008f000000
251Domain0 Next Mode         : S-mode
252Domain0 SysReset          : yes
253
254Boot HART ID              : 0
255Boot HART Domain          : root
256Boot HART ISA             : rv64imafdcsu
257Boot HART Features        : scounteren,mcounteren,time
258Boot HART PMP Count       : 16
259Boot HART PMP Granularity : 4
260Boot HART PMP Address Bits: 54
261Boot HART MHPM Count      : 0
262Boot HART MHPM Count      : 0
263Boot HART MIDELEG         : 0x0000000000000222
264Boot HART MEDELEG         : 0x000000000000b109
265heap: [0x002ef030 - 0x042ef030]
266
267 \ | /
268- RT -     Thread Smart Operating System
269 / | \     5.2.0 build Nov 14 2024 15:48:43
270 2006 - 2024 Copyright by RT-Thread team
271lwIP-2.0.3 initialized!
272[I/sal.skt] Socket Abstraction Layer initialize success.
273[I/utest] utest is initialize success.
274[I/utest] total utest testcase num: (0)
275[I/drivers.serial] Using /dev/ttyS0 as default console
276file system initialization done!
277Hello RISC-V
278msh />
279```
280
281### 3.2.3. 运行 RT-Thread Smart 版 + 根文件系统
282
283对于 Smart 版本的内核，也可以在执行 `run.sh` 脚本时指定根文件系统镜像文件的路径在启动过程中挂载根文件系统。
284
285需要注意的是，内核默认支持 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` 更新软件包索引后再尝试使能软件包。
286
287勾选该选项后还需要执行如下操作更新软件并安装源码到 bsp 的 packages 目录下(该操作只要执行一次即可)：
288
289```shell
290$ source ~/.env/env.sh
291$ pkgs --update
292```
293
294保存后重新编译内核。
295
296有关如何制作根文件系统，请参考 <https://github.com/RT-Thread/userapps/blob/main/README.md>，这里不再赘述。
297
298示例如下：
299
300```shell
301$ ./run.sh /home/u/ws/duo/userapps/apps/build/ext4.img
302
303OpenSBI v0.9
304   ____                    _____ ____ _____
305  / __ \                  / ____|  _ \_   _|
306 | |  | |_ __   ___ _ __ | (___ | |_) || |
307 | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
308 | |__| | |_) |  __/ | | |____) | |_) || |_
309  \____/| .__/ \___|_| |_|_____/|____/_____|
310        | |
311        |_|
312
313Platform Name             : riscv-virtio,qemu
314Platform Features         : timer,mfdeleg
315Platform HART Count       : 1
316Firmware Base             : 0x80000000
317Firmware Size             : 100 KB
318Runtime SBI Version       : 0.2
319
320Domain0 Name              : root
321Domain0 Boot HART         : 0
322Domain0 HARTs             : 0*
323Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
324Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
325Domain0 Next Address      : 0x0000000080200000
326Domain0 Next Arg1         : 0x000000008f000000
327Domain0 Next Mode         : S-mode
328Domain0 SysReset          : yes
329
330Boot HART ID              : 0
331Boot HART Domain          : root
332Boot HART ISA             : rv64imafdcsu
333Boot HART Features        : scounteren,mcounteren,time
334Boot HART PMP Count       : 16
335Boot HART PMP Granularity : 4
336Boot HART PMP Address Bits: 54
337Boot HART MHPM Count      : 0
338Boot HART MHPM Count      : 0
339Boot HART MIDELEG         : 0x0000000000000222
340Boot HART MEDELEG         : 0x000000000000b109
341heap: [0x00326438 - 0x04326438]
342
343 \ | /
344- RT -     Thread Smart Operating System
345 / | \     5.2.0 build Dec 17 2024 11:49:39
346 2006 - 2024 Copyright by RT-Thread team
347lwIP-2.0.3 initialized!
348[I/sal.skt] Socket Abstraction Layer initialize success.
349[I/utest] utest is initialize success.
350[I/utest] total utest testcase num: (0)
351[I/drivers.serial] Using /dev/ttyS0 as default console
352[W/DFS.fs] mount / failed with file system type: elm
353file system initialization done!
354Hello RISC-V
355msh />[E/sal.skt] not find network interface device by protocol family(1).
356[E/sal.skt] SAL socket protocol family input failed, return error -3.
357/ # ls
358bin         lib         proc        sbin        tmp
359dev         lost+found  root        services    usr
360etc         mnt         run         tc          var
361/ #
362```
363
364# 4. 如何使用 rv64ilp32 工具链
365
366- 工具链地址：https://github.com/ruyisdk/riscv-gnu-toolchain-rv64ilp32/tags
367
368- 使用方法：
369
370  - 配置工具链路径
371
372  - 修改ABI参数为：`-mabi=ilp32d`
373
374  - 然后执行常规编译
375
376  - 使用 [脚本](./qemu-rv64ilp32-nographic.sh) 启动 QEMU (INFO: QEMU 二进制同样在工具链目录)
377
378- 使用传统 64 位工具链与使用新 32 位工具链编译相同工程的固件大小对比：
379
380  传统 64 位工具链固件大小：
381
382  ```bash
383  Memory region         Used Size  Region Size  %age Used
384              SRAM:      225856 B        16 MB      1.35%
385  riscv64-unknown-elf-objcopy -O binary rtthread.elf rtthread.bin
386  riscv64-unknown-elf-size rtthread.elf
387     text    data     bss     dec     hex filename
388   150907    3664   71268  225839   3722f rtthread.elf
389  ```
390
391  新 32 位工具链固件大小：
392
393  ```bash
394  Memory region         Used Size  Region Size  %age Used
395              SRAM:      209376 B        16 MB      1.25%
396  riscv64-unknown-elf-objcopy -O binary rtthread.elf rtthread.bin
397  riscv64-unknown-elf-size rtthread.elf
398     text    data     bss     dec     hex filename
399   138739    1356   69276  209371   331db rtthread.elf
400  ```
401
402# 5. 联系人信息
403
404维护人：[bernard][1]
405
406[1]: https://github.com/BernardXiong
407
408
409
410