1**QEMU/RISCV64 VIRT Board Support Package User Guide**
2
3English | [中文](./README_cn.md)
4
5<!-- TOC -->
6
7- [1. Introduction](#1-introduction)
8- [2. Building](#2-building)
9	- [2.1. Installing the toolchain](#21-installing-the-toolchain)
10	- [2.2. Setting RT-Thread toolchain environment variables](#22-setting-rt-thread-toolchain-environment-variables)
11	- [2.3. Downloading the kernel](#23-downloading-the-kernel)
12	- [2.4. Configuring the kernel](#24-configuring-the-kernel)
13	- [2.5. Compiling the kernel](#25-compiling-the-kernel)
14- [3. Running](#3-running)
15	- [3.1. Installing QEMU](#31-installing-qemu)
16	- [3.2. Running QEMU](#32-running-qemu)
17		- [3.2.1. Running RT-Thread Standard Edition](#321-running-rt-thread-standard-edition)
18		- [3.2.2. Running RT-Thread Smart version](#322-running-rt-thread-smart-version)
19		- [3.2.3. Running RT-Thread Smart version + Root file-system](#323-running-rt-thread-smart-version--root-file-system)
20- [4. How to use rv64ilp32 toolchain](#4-how-to-use-rv64ilp32-toolchain)
21- [5. Contact information](#5-contact-information)
22
23<!-- /TOC -->
24
25# 1. Introduction
26
27RISC-V is an open and free instruction set architecture (ISA). This project is a port on the RISCV64 VIRT version of QEMU.
28
29This project supports the world's first rv64ilp32 product-level open source toolchain jointly launched by the Xuantie team and the Institute of Software of the Chinese Academy of Sciences.
30
31# 2. Building
32
33Working system: take Ubuntu 22.04 as an example:
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. Installing the toolchain
45
46The specific toolchain used is consistent with the official RT-Thread. For the specific toolchain version, please refer to the file <https://github.com/RT-Thread/rt-thread/blob/master/.github/workflows/action_utest.yml> in the RT-Thread repository.
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
68Among them, `riscv64-unknown-elf-gcc` is used to build the RT-Thread Standard version, and `riscv64-unknown-linux-musl-gcc` is used to build the RT-Thread Smart version. Download them to your local computer according to the links shown above and decompress them.
69
70## 2.2. Setting RT-Thread toolchain environment variables
71
72There are three environment variables related to the RT-Thread toolchain
73
74- `RTT_CC` is the toolchain name, which is `"gcc"` here
75- `RTT_CC_PREFIX`: is the toolchain prefix, which is `"riscv64-unknown-elf-"` for the Standard version and `"riscv64-unknown-linux-musl-"` for the Smart version.
76- `RTT_EXEC_PATH`: the path where the bin folder of the toolchain is located, such as `"$HOME/tools/riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14/bin"`. This is set according to the actual path after personal download and decompression. Note that the toolchains of the RT-Thread standard version and the Smart version are two different versions, and the path name of `RTT_EXEC_PATH` must be set to `bin`.
77
78If you use them all the time, it is recommended to export these three environment variables in the `.bashrc` file.
79
80## 2.3. Downloading the kernel
81
82Assume that the working path is `$WORKSPACE`.
83
84```shell
85$ cd $WORKSPACE
86$ git clone git@github.com:RT-Thread/rt-thread.git
87```
88
89Enter the BSP directory where qemu-virt64-riscv is located. The following operations will not be introduced separately. By default, it is in this directory.
90
91```shell
92$ cd $WORKSPACE/rt-thread/bsp/qemu-virt64-riscv
93```
94
95## 2.4. Configuring the kernel
96
97Refresh the configuration file before compiling for the first time.
98
99```shell
100$ scons --menuconfig
101```
102
103The default configuration is the RT-Thread standard version, so if you don't have any special requirements, don't change anything, just save and exit.
104
105If you want to use the RT-Thread Smart version, at least turn on the `RT_USING_SMART` option after entering the configuration menu (see the figure below), and the rest depends on your needs.
106
107```
108(Top) → RT-Thread Kernel
109RT-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
117Save and exit after modification.
118
119## 2.5. Compiling the kernel
120
121If you have compiled before, you can clean it up:
122
123```shell
124$ scons --clean
125```
126
127Or compile directly:
128
129```shell
130$ scons -j$(nproc)
131```
132
133The kernel binary file `rtthread.bin` will be generated in the `$WORKSPACE/rt-thread/bsp/qemu-virt64-riscv`.
134
135# 3. Running
136
137## 3.1. Installing QEMU
138
139```shell
140$ sudo apt update
141$ sudo apt install qemu-system-misc
142```
143
144After the installation is complete, you can check the version.
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. Running QEMU
153
154The repository has provided a ready-made execution script, which can be executed directly:
155
156```shell
157$ ./run.sh
158```
159
160### 3.2.1. Running RT-Thread Standard Edition
161
162The following is an example:
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### 3.2.2. Running RT-Thread Smart version
220
221The following is an example:
222
223```shell
224$ ./run.sh
225
226OpenSBI v0.9
227   ____                    _____ ____ _____
228  / __ \                  / ____|  _ \_   _|
229 | |  | |_ __   ___ _ __ | (___ | |_) || |
230 | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
231 | |__| | |_) |  __/ | | |____) | |_) || |_
232  \____/| .__/ \___|_| |_|_____/|____/_____|
233        | |
234        |_|
235
236Platform Name             : riscv-virtio,qemu
237Platform Features         : timer,mfdeleg
238Platform HART Count       : 1
239Firmware Base             : 0x80000000
240Firmware Size             : 100 KB
241Runtime SBI Version       : 0.2
242
243Domain0 Name              : root
244Domain0 Boot HART         : 0
245Domain0 HARTs             : 0*
246Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
247Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
248Domain0 Next Address      : 0x0000000080200000
249Domain0 Next Arg1         : 0x000000008f000000
250Domain0 Next Mode         : S-mode
251Domain0 SysReset          : yes
252
253Boot HART ID              : 0
254Boot HART Domain          : root
255Boot HART ISA             : rv64imafdcsu
256Boot HART Features        : scounteren,mcounteren,time
257Boot HART PMP Count       : 16
258Boot HART PMP Granularity : 4
259Boot HART PMP Address Bits: 54
260Boot HART MHPM Count      : 0
261Boot HART MHPM Count      : 0
262Boot HART MIDELEG         : 0x0000000000000222
263Boot HART MEDELEG         : 0x000000000000b109
264heap: [0x002ef030 - 0x042ef030]
265
266 \ | /
267- RT -     Thread Smart Operating System
268 / | \     5.2.0 build Nov 14 2024 15:48:43
269 2006 - 2024 Copyright by RT-Thread team
270lwIP-2.0.3 initialized!
271[I/sal.skt] Socket Abstraction Layer initialize success.
272[I/utest] utest is initialize success.
273[I/utest] total utest testcase num: (0)
274[I/drivers.serial] Using /dev/ttyS0 as default console
275file system initialization done!
276Hello RISC-V
277msh />
278```
279
280### 3.2.3. Running RT-Thread Smart version + Root file-system
281
282For 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.
283
284It 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.
285
286After 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):
287
288```shell
289$ source ~/.env/env.sh
290$ pkgs --update
291```
292
293Save and recompile the kernel.
294
295For 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.
296
297The example is as follows:
298
299```shell
300$ ./run.sh /home/u/ws/duo/userapps/apps/build/ext4.img
301
302OpenSBI v0.9
303   ____                    _____ ____ _____
304  / __ \                  / ____|  _ \_   _|
305 | |  | |_ __   ___ _ __ | (___ | |_) || |
306 | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
307 | |__| | |_) |  __/ | | |____) | |_) || |_
308  \____/| .__/ \___|_| |_|_____/|____/_____|
309        | |
310        |_|
311
312Platform Name             : riscv-virtio,qemu
313Platform Features         : timer,mfdeleg
314Platform HART Count       : 1
315Firmware Base             : 0x80000000
316Firmware Size             : 100 KB
317Runtime SBI Version       : 0.2
318
319Domain0 Name              : root
320Domain0 Boot HART         : 0
321Domain0 HARTs             : 0*
322Domain0 Region00          : 0x0000000080000000-0x000000008001ffff ()
323Domain0 Region01          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
324Domain0 Next Address      : 0x0000000080200000
325Domain0 Next Arg1         : 0x000000008f000000
326Domain0 Next Mode         : S-mode
327Domain0 SysReset          : yes
328
329Boot HART ID              : 0
330Boot HART Domain          : root
331Boot HART ISA             : rv64imafdcsu
332Boot HART Features        : scounteren,mcounteren,time
333Boot HART PMP Count       : 16
334Boot HART PMP Granularity : 4
335Boot HART PMP Address Bits: 54
336Boot HART MHPM Count      : 0
337Boot HART MHPM Count      : 0
338Boot HART MIDELEG         : 0x0000000000000222
339Boot HART MEDELEG         : 0x000000000000b109
340heap: [0x00326438 - 0x04326438]
341
342 \ | /
343- RT -     Thread Smart Operating System
344 / | \     5.2.0 build Dec 17 2024 11:49:39
345 2006 - 2024 Copyright by RT-Thread team
346lwIP-2.0.3 initialized!
347[I/sal.skt] Socket Abstraction Layer initialize success.
348[I/utest] utest is initialize success.
349[I/utest] total utest testcase num: (0)
350[I/drivers.serial] Using /dev/ttyS0 as default console
351[W/DFS.fs] mount / failed with file system type: elm
352file system initialization done!
353Hello RISC-V
354msh />[E/sal.skt] not find network interface device by protocol family(1).
355[E/sal.skt] SAL socket protocol family input failed, return error -3.
356/ # ls
357bin         lib         proc        sbin        tmp
358dev         lost+found  root        services    usr
359etc         mnt         run         tc          var
360/ #
361```
362
363# 4. How to use rv64ilp32 toolchain
364
365- Toolchain address: <https://github.com/ruyisdk/riscv-gnu-toolchain-rv64ilp32/tags>
366
367- Usage:
368
369  - Configure toolchain path
370
371  - Modify ABI parameter to: `-mabi=ilp32d`
372
373  - Then perform regular compilation
374
375  - Use [script](./qemu-rv64ilp32-nographic.sh) to start QEMU (INFO: QEMU binary is also in the toolchain directory)
376
377- Compare the firmware size of the same project compiled using the traditional 64-bit toolchain and the new 32-bit toolchain:
378
379  Traditional 64-bit toolchain firmware size:
380
381  ```bash
382  Memory region         Used Size  Region Size  %age Used
383              SRAM:      225856 B        16 MB      1.35%
384  riscv64-unknown-elf-objcopy -O binary rtthread.elf rtthread.bin
385  riscv64-unknown-elf-size rtthread.elf
386     text    data     bss     dec     hex filename
387   150907    3664   71268  225839   3722f rtthread.elf
388  ```
389
390  New 32-bit toolchain firmware size:
391
392  ```bash
393  Memory region         Used Size  Region Size  %age Used
394              SRAM:      209376 B        16 MB      1.25%
395  riscv64-unknown-elf-objcopy -O binary rtthread.elf rtthread.bin
396  riscv64-unknown-elf-size rtthread.elf
397     text    data     bss     dec     hex filename
398   138739    1356   69276  209371   331db rtthread.elf
399  ```
400
401# 5. Contact information
402
403Maintainer: [bernard][1]
404
405[1]: https://github.com/BernardXiong