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