README.md

   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.