README.md (8034B)
1 tests imported from the official RISC-V test suite but without the mandatory 2 Zicsr and it's accomodation for non-baremetal EEIs. it's licensed under 3 the BSD-3-Clause license. 4 5 --- 6 7 riscv-tests 8 ================ 9 10 About 11 ----------- 12 13 This repository hosts unit tests for RISC-V processors. 14 15 Building from repository 16 ----------------------------- 17 18 We assume that the RISCV environment variable is set to the RISC-V tools 19 install path, and that the [riscv-gnu-toolchain]( 20 https://github.com/riscv-collab/riscv-gnu-toolchain) package is installed. 21 22 $ git clone https://github.com/riscv/riscv-tests 23 $ cd riscv-tests 24 $ git submodule update --init --recursive 25 $ autoconf 26 $ ./configure --prefix=$RISCV/target 27 $ make 28 $ make install 29 30 The rest of this document describes the format of test programs for the RISC-V 31 architecture. 32 33 Test Virtual Machines 34 ------------------------- 35 36 To allow maximum reuse of a given test, each test program is constrained to 37 only use features of a given *test virtual machine* or TVM. A TVM hides 38 differences between alternative implementations by defining: 39 40 * The set of registers and instructions that can be used. 41 * Which portions of memory can be accessed. 42 * The way the test program starts and ends execution. 43 * The way that test data is input. 44 * The way that test results are output. 45 46 The following table shows the TVMs currently defined for RISC-V. All of these 47 TVMs only support a single hardware thread. 48 49 TVM Name | Description 50 --- | --- 51 `rv32ui` | RV32 user-level, integer only 52 `rv32si` | RV32 supervisor-level, integer only 53 `rv64ui` | RV64 user-level, integer only 54 `rv64uf` | RV64 user-level, integer and floating-point 55 `rv64uv` | RV64 user-level, integer, floating-point, and vector 56 `rv64si` | RV64 supervisor-level, integer only 57 `rv64sv` | RV64 supervisor-level, integer and vector 58 59 A test program for RISC-V is written within a single assembly language file, 60 which is passed through the C preprocessor, and all regular assembly 61 directives can be used. An example test program is shown below. Each test 62 program should first include the `riscv_test.h` header file, which defines the 63 macros used by the TVM. The header file will have different contents depending 64 on the target environment for which the test will be built. One of the goals 65 of the various TVMs is to allow the same test program to be compiled and run 66 on very different target environments yet still produce the same results. The 67 following table shows the target environment currently defined. 68 69 Target Environment Name | Description 70 --- | --- 71 `p` | virtual memory is disabled, only core 0 boots up 72 `pm` | virtual memory is disabled, all cores boot up 73 `pt` | virtual memory is disabled, timer interrupt fires every 100 cycles 74 `v` | virtual memory is enabled 75 76 Each test program must next specify for which TVM it is designed by including 77 the appropriate TVM macro, `RVTEST_RV64U` in this example. This specification 78 can change the way in which subsequent macros are interpreted, and supports 79 a static check of the TVM functionality used by the program. 80 81 The test program will begin execution at the first instruction after 82 `RVTEST_CODE_BEGIN`, and continue until execution reaches an `RVTEST_PASS` 83 macro or the `RVTEST_CODE_END` macro, which is implicitly a success. A test 84 can explicitly fail by invoking the `RVTEST_FAIL` macro. 85 86 The example program contains self-checking code to test the result of the add. 87 However, self-checks rely on correct functioning of the processor instructions 88 used to implement the self check (e.g., the branch) and so cannot be the only 89 testing strategy. 90 91 All tests should also contain a test data section, delimited by 92 `RVTEST_DATA_BEGIN` and `RVTEST_DATA_END`. There is no alignment guarantee for 93 the start of the test data section, so regular assembler alignment 94 instructions should be used to ensure desired alignment of data values. This 95 region of memory will be captured at the end of the test to act as a signature 96 from the test. The signature can be compared with that from a run on the 97 golden model. 98 99 Any given test environment for running tests should also include a timeout 100 facility, which will class a test as failing if it does not successfully 101 complete a test within a reasonable time bound. 102 103 #include "riscv_test.h" 104 105 RVTEST_RV64U # Define TVM used by program. 106 107 # Test code region. 108 RVTEST_CODE_BEGIN # Start of test code. 109 lw x2, testdata 110 addi x2, 1 # Should be 42 into $2. 111 sw x2, result # Store result into memory overwriting 1s. 112 li x3, 42 # Desired result. 113 bne x2, x3, fail # Fail out if doesn't match. 114 RVTEST_PASS # Signal success. 115 fail: 116 RVTEST_FAIL 117 RVTEST_CODE_END # End of test code. 118 119 # Input data section. 120 # This section is optional, and this data is NOT saved in the output. 121 .data 122 .align 3 123 testdata: 124 .dword 41 125 126 # Output data section. 127 RVTEST_DATA_BEGIN # Start of test output data region. 128 .align 3 129 result: 130 .dword -1 131 RVTEST_DATA_END # End of test output data region. 132 133 User-Level TVMs 134 -------------------- 135 136 Test programs for the `rv32u*` and `rv64u*` TVMs can contain all instructions 137 from the respective base user-level ISA (RV32 or RV64), except for those with 138 the SYSTEM major opcode (syscall, break, rdcycle, rdtime, rdinstret). All user 139 registers (pc, x0-x31, f0-f31, fsr) can be accessed. 140 141 The `rv32ui` and `rv64ui` TVMs are integer-only subsets of `rv32u` and `rv64u` 142 respectively. These subsets can not use any floating-point instructions (major 143 opcodes: LOAD-FP, STORE-FP, MADD, MSUB, NMSUB, NMADD, OP-FP), and hence cannot 144 access the floating-point register state (f0-f31 and fsr). The integer-only 145 TVMs are useful for initial processor bringup and to test simpler 146 implementations that lack a hardware FPU. 147 148 Note that any `rv32ui` test program is also valid for the `rv32u` TVM, and 149 similarly `rv64ui` is a strict subset of `rv64u`. To allow a given test to run 150 on the widest possible set of implementations, it is desirable to write any 151 given test to run on the smallest or least capable TVM possible. For example, 152 any simple tests of integer functionality should be written for the `rv64ui` 153 TVM, as the same test can then be run on RV64 implementations with or without a 154 hardware FPU. As another example, all tests for these base user-level TVMs will 155 also be valid for more advanced processors with instruction-set extensions. 156 157 At the start of execution, the values of all registers are undefined. All 158 branch and jump destinations must be to labels within the test code region of 159 the assembler source file. The code and data sections will be relocated 160 differently for the various implementations of the test environment, and so 161 test program results shall not depend on absolute addresses of instructions or 162 data memory. The test build environment should support randomization of the 163 section relocation to provide better coverage and to ensure test signatures do 164 not contain absolute addresses. 165 166 Supervisor-Level TVMs 167 -------------------------- 168 169 The supervisor-level TVMs allow testing of supervisor-level state and 170 instructions. As with the user-level TVMs, we provide integer-only 171 supervisor-level TVMs indicated with a trailing `i`. 172 173 History and Acknowledgements 174 --------------------------------- 175 176 This style of test virtual machine originated with the T0 (Torrent-0) vector 177 microprocessor project at UC Berkeley and ICSI, begun in 1992. The main 178 developers of this test strategy were Krste Asanovic and David Johnson. A 179 precursor to `torture` was `rantor` developed by Phil Kohn at ICSI. 180 181 A variant of this testing approach was also used for the Scale vector-thread 182 processor at MIT, begun in 2000. Ronny Krashinsky and Christopher Batten were 183 the principal architects of the Scale chip. Jeffrey Cohen and Mark Hampton 184 developed a version of torture capable of generating vector-thread code.