1gem5 Specifc RISC-V tests
2=========================
3
4About
5-----
6
7This work provides assembly testing infrastructure including single-threaded
8and multi-threaded tests for RISC-V ISA in gem5. Each test targets an
9individual RISC-V instruction or a Linux system call. This work targets
10system call emulation (SE) mode in gem5.
11
12This work is based on the riscv-tests project.
13
14Link to the orignal riscv-tests projects can be found here:
15  https://github.com/riscv/riscv-tests
16
17Link to the original riscv-tests project's LICENSE and README can be found
18here:
19  https://github.com/riscv/riscv-tests/blob/master/LICENSE
20  https://github.com/riscv/riscv-tests/blob/master/README.md
21
22Specific commit ID that this work is based off:
23  68cad7baf3ed0a4553fffd14726d24519ee1296a
24
25Changes from the orignal riscv-tests project
26--------------------------------------------
27
281. Only rv64 tests are imported into this work
29
30The original project offers both rv64 and rv32 tests. Since the current
31implementation of RISC-V in gem5 is focused on its 64-bit version, only
3264-bit tests (rv64) are imported from the original project. Future work
33on 32-bit can easily integrate all 32-bit tests into gem5.
34
352. New testing environment for gem5
36
37Since the original riscv-tests project is designed for bare-metal system (i.e.,
38without OS support), it offers several environments to control how a test
39interacts with a host machine (to-host communication). However, in gem5 SE
40mode, gem5 emulates an OS, and there is no host machine. Therefore, we
41developed a new testing environment called `ps` for gem5.
42
43This testing environment uses system call `exit` to return test results as an
44exit code of a particular test instead of writing them to a host machine. This
45environment requires the testing platform to implement/emulate at least `exit`
46system call.
47
483. Minimal threading library written in assembly (`isa/macros/mt`)
49
50To simplify debugging multi-threading systems, we developed a minimal threading
51library that supports very basic threading functionality including creating a
52thread, exiting a thread, waiting for some thread(s) on a condition, and waking
53up some thread(s).
54
55Multi-threaded tests can rely on this library to manage multiple threads.
56
574. RISC-V AMO, LR, and SC instruction tests (`isa/rv64uamt`)
58
59This is a set of assembly tests that target multi-core systems and test AMO
60instructions. This test set uses a minimal number of system calls (i.e., clone,
61mmap, munmap and exit) to create and manage threads.  It does not use any
62complex sleep/wakeup mechanism to manage and synchronize threads to avoid
63adding extra unnecessary complexity. The major goal of this test set is to
64stress AMO instructions. Threads only synchronize at the end of their
65execution. The master thread does a spin-wait to wait for all threads to
66complete before it checks final results.
67
685. Thread-related system call tests (`isa/rv64samt`)
69
70This is a set of assembly tests that target thread-related system calls and
71thread wait/wakeup behaviors. This set reuses some of the tests in
72`isa/rv64uamt` but uses more advanced futex system call operations to make
73threads wait and wake up in certain cases. This test set also checks functional
74behaviors of threads after a wait/wakeup operation.
75
76How to compile this test suite
77------------------------------
78
791. Install RISC-V GNU toolchain. Source code and instruction on how to install
80it can be found here: https://github.com/riscv/riscv-gnu-toolchain
81
822. Run `make`
83
843. Test binaries are in `$GEM5/tests/test-progs/asmtest/bin/riscv/` ($GEM5 is
85your gem5 directory)
86
87How to run all tests
88--------------------
89
901. Run `./run-tests.py`
91
922. Test outputs are in ./test-summary.out
93