riscv-tests

No description available

1,029

503

1,029

144

View on GitHub

Top Related Projects

riscv-gnu-toolchain

4,053

GNU toolchain for RISC-V, including GCC

riscv-boom

1,947

SonicBOOM: The Berkeley Out-of-Order Machine

ibex

1,599

Ibex is a small 32 bit RISC-V CPU core, previously known as zero-riscy.

Quick Overview

The riscv-software-src/riscv-tests repository contains a collection of test programs for the RISC-V instruction set architecture (ISA). These tests are designed to verify the correctness of RISC-V implementations and compilers, ensuring that the RISC-V ecosystem remains robust and reliable.

Pros

Comprehensive Test Suite: The repository includes a wide range of test cases covering various aspects of the RISC-V ISA, including integer arithmetic, floating-point operations, memory management, and more.
Vendor-Neutral: The tests are developed and maintained by the RISC-V community, ensuring vendor-neutrality and a level playing field for RISC-V implementations.
Continuous Integration: The repository is integrated with continuous integration (CI) systems, allowing for automated testing and validation of RISC-V implementations.
Actively Maintained: The project is actively maintained by the RISC-V community, with regular updates and improvements to the test suite.

Cons

Specific to RISC-V: The tests are designed specifically for the RISC-V ISA, and may not be directly applicable to other processor architectures.
Complexity: The test suite can be complex, with a large number of individual tests and configurations, which may make it challenging for newcomers to navigate.
Dependency on RISC-V Toolchain: Running the tests requires a compatible RISC-V toolchain, which may not be readily available on all platforms.
Limited Portability: While the tests are designed to be portable across different RISC-V implementations, there may be some platform-specific quirks or requirements that need to be addressed.

Getting Started

To get started with the riscv-software-src/riscv-tests repository, follow these steps:

Clone the repository:

git clone https://github.com/riscv-software-src/riscv-tests.git

Install the required RISC-V toolchain. You can find instructions for your specific platform on the RISC-V Toolchain Downloads page.
Navigate to the riscv-tests directory and build the tests:

cd riscv-tests
make

Run the tests using a RISC-V simulator or hardware platform. For example, to run the tests using the QEMU RISC-V emulator:

make run-tests RISCV_DEVICE=qemu

Examine the test results and debug any failures. The test output will be available in the build/ directory.

Competitor Comparisons

riscv-gnu-toolchain

4,053

GNU toolchain for RISC-V, including GCC

Pros of riscv-gnu-toolchain

Provides a complete toolchain for RISC-V development, including GCC, binutils, and GDB
Supports multiple RISC-V configurations and extensions
Regularly updated with the latest upstream changes

Cons of riscv-gnu-toolchain

Larger and more complex to build and maintain
Requires more system resources and longer compilation times
May include features not needed for specific RISC-V projects

Code comparison

riscv-tests:

#include "riscv_test.h"

RVTEST_RV64U
RVTEST_CODE_BEGIN

  li a0, 0x55aa55aa
  li a1, 0xaa55aa55
  xor a2, a0, a1
  TEST_CASE( 2, a2, 0xffffffff );

RVTEST_CODE_END

riscv-gnu-toolchain:

#include <stdio.h>

int main() {
    printf("Hello, RISC-V!\n");
    return 0;
}

The riscv-tests repository focuses on providing test cases for RISC-V implementations, while riscv-gnu-toolchain offers a complete development environment for building RISC-V applications. The code examples reflect this difference, with riscv-tests showing a low-level test case and riscv-gnu-toolchain demonstrating a simple C program that can be compiled and run on RISC-V hardware.

riscv-isa-sim

2,733

Spike, a RISC-V ISA Simulator

Pros of riscv-isa-sim

More comprehensive simulation of RISC-V architecture
Supports a wider range of RISC-V extensions and configurations
Provides a full system emulation, including memory and peripherals

Cons of riscv-isa-sim

More complex to set up and use
Slower execution compared to direct hardware testing
Requires more computational resources

Code Comparison

riscv-isa-sim (Spike):

#include "riscv/sim.h"
#include "riscv/processor.h"

int main(int argc, char** argv) {
  sim_t sim(argc, argv);
  sim.run();
  return 0;
}

riscv-tests:

#include "riscv-test.h"

RVTEST_RV64U
RVTEST_CODE_BEGIN

  li a0, 1
  li a1, 2
  add a2, a0, a1

RVTEST_CODE_END

The riscv-isa-sim code shows the setup for a full system simulation, while riscv-tests focuses on individual instruction testing. riscv-isa-sim provides a more comprehensive environment but requires more setup, whereas riscv-tests offers simpler, targeted tests that are easier to write and run.

riscv-boom

1,947

SonicBOOM: The Berkeley Out-of-Order Machine

Pros of riscv-boom

Implements a high-performance, out-of-order RISC-V core
Provides a complete SoC design with configurable parameters
Offers a more realistic representation of modern RISC-V processors

Cons of riscv-boom

More complex and resource-intensive to simulate and test
Requires deeper understanding of computer architecture concepts
May be overkill for simple RISC-V software testing

Code Comparison

riscv-boom:

class BoomCore(implicit p: Parameters) extends BoomModule()(p)
  with HasBoomCoreParameters
  with HasL1ICacheBankedParameters
{
  val io = IO(new BoomCoreIO)
  // ... (core implementation)
}

riscv-tests:

#define RVTEST_RV64U
#define TEST_CASE_1

#include "riscv_test.h"
#include "test_macros.h"

RVTEST_CODE_BEGIN

  TEST_CASE_1
  // ... (test implementation)

RVTEST_CODE_END

The riscv-boom repository focuses on implementing a complete RISC-V core in Chisel, while riscv-tests provides a suite of assembly tests for verifying RISC-V implementations. riscv-boom is more suitable for hardware design and exploration, whereas riscv-tests is ideal for basic functionality testing of RISC-V processors and simulators.

ibex

1,599

Ibex is a small 32 bit RISC-V CPU core, previously known as zero-riscy.

Pros of ibex

Comprehensive RISC-V core implementation, offering a complete processor design
Extensive documentation and design verification resources
Supports various configurations and extensions of the RISC-V ISA

Cons of ibex

More complex and resource-intensive than a simple test suite
Requires more in-depth knowledge of processor architecture to utilize effectively
May be overkill for basic RISC-V software testing needs

Code Comparison

ibex (SystemVerilog):

module ibex_core #(
  parameter bit          PMPEnable         = 1'b0,
  parameter int unsigned PMPGranularity    = 0,
  parameter int unsigned PMPNumRegions     = 4,
  parameter int unsigned MHPMCounterNum    = 0,
  parameter int unsigned MHPMCounterWidth  = 40,
  parameter bit          RV32E             = 1'b0,
  parameter bit          RV32M             = 1'b1,
  parameter bit          RV32B             = 1'b0,
  parameter bit          BranchTargetALU   = 1'b0,
  // ... (additional parameters)
) (
  // ... (port declarations)
);

riscv-tests (Assembly):

#define TESTNUM x28

#define RVTEST_RV64U                                                    \
  .macro init;                                                          \
  .endm

#define RVTEST_RV64UF                                                   \
  .macro init;                                                          \
  RVTEST_FP_ENABLE;                                                     \
  .endm

The ibex repository provides a full RISC-V core implementation, while riscv-tests focuses on assembly-level test cases for RISC-V software development.

rocket-chip

3,503

Rocket Chip Generator

Pros of rocket-chip

More comprehensive RISC-V implementation, including a full processor generator
Highly configurable and customizable for different use cases
Actively maintained with frequent updates and contributions

Cons of rocket-chip

Steeper learning curve due to its complexity
Requires more resources to build and simulate
May be overkill for simple RISC-V testing needs

Code comparison

rocket-chip (Chisel):

class Rocket extends Module {
  val io = IO(new Bundle {
    val imem = new FrontendIO
    val dmem = new HellaCacheIO
    val ptw = new TLBPTWIO
  })
  // ... (implementation details)
}

riscv-tests (Assembly):

.global _start
_start:
    li a0, 1
    li a7, 93
    ecall

The rocket-chip example shows a Chisel class definition for a Rocket core, while riscv-tests uses simple RISC-V assembly for testing instructions. rocket-chip is more complex and flexible, while riscv-tests focuses on basic instruction testing.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

riscv-tests

About

This repository hosts unit tests for RISC-V processors.

Building from repository

We assume that the RISCV environment variable is set to the RISC-V tools install path, and that the riscv-gnu-toolchain package is installed.

$ git clone https://github.com/riscv/riscv-tests
$ cd riscv-tests
$ git submodule update --init --recursive
$ autoconf
$ ./configure --prefix=$RISCV/target
$ make
$ make install

The rest of this document describes the format of test programs for the RISC-V architecture.

Test Virtual Machines

To allow maximum reuse of a given test, each test program is constrained to only use features of a given test virtual machine or TVM. A TVM hides differences between alternative implementations by defining:

The set of registers and instructions that can be used.
Which portions of memory can be accessed.
The way the test program starts and ends execution.
The way that test data is input.
The way that test results are output.

The following table shows the TVMs currently defined for RISC-V. All of these TVMs only support a single hardware thread.

TVM Name	Description
`rv32ui`	RV32 user-level, integer only
`rv32si`	RV32 supervisor-level, integer only
`rv64ui`	RV64 user-level, integer only
`rv64uf`	RV64 user-level, integer and floating-point
`rv64uv`	RV64 user-level, integer, floating-point, and vector
`rv64si`	RV64 supervisor-level, integer only
`rv64sv`	RV64 supervisor-level, integer and vector

A test program for RISC-V is written within a single assembly language file, which is passed through the C preprocessor, and all regular assembly directives can be used. An example test program is shown below. Each test program should first include the riscv_test.h header file, which defines the macros used by the TVM. The header file will have different contents depending on the target environment for which the test will be built. One of the goals of the various TVMs is to allow the same test program to be compiled and run on very different target environments yet still produce the same results. The following table shows the target environment currently defined.

Target Environment Name	Description
`p`	virtual memory is disabled, only core 0 boots up
`pm`	virtual memory is disabled, all cores boot up
`pt`	virtual memory is disabled, timer interrupt fires every 100 cycles
`v`	virtual memory is enabled

Each test program must next specify for which TVM it is designed by including the appropriate TVM macro, RVTEST_RV64U in this example. This specification can change the way in which subsequent macros are interpreted, and supports a static check of the TVM functionality used by the program.

The test program will begin execution at the first instruction after RVTEST_CODE_BEGIN, and continue until execution reaches an RVTEST_PASS macro or the RVTEST_CODE_END macro, which is implicitly a success. A test can explicitly fail by invoking the RVTEST_FAIL macro.

The example program contains self-checking code to test the result of the add. However, self-checks rely on correct functioning of the processor instructions used to implement the self check (e.g., the branch) and so cannot be the only testing strategy.

All tests should also contain a test data section, delimited by RVTEST_DATA_BEGIN and RVTEST_DATA_END. There is no alignment guarantee for the start of the test data section, so regular assembler alignment instructions should be used to ensure desired alignment of data values. This region of memory will be captured at the end of the test to act as a signature from the test. The signature can be compared with that from a run on the golden model.

Any given test environment for running tests should also include a timeout facility, which will class a test as failing if it does not successfully complete a test within a reasonable time bound.

#include "riscv_test.h"

RVTEST_RV64U        # Define TVM used by program.

# Test code region.
RVTEST_CODE_BEGIN   # Start of test code.
        lw      x2, testdata
        addi    x2, 1         # Should be 42 into $2.
        sw      x2, result    # Store result into memory overwriting 1s.
        li      x3, 42        # Desired result.
        bne     x2, x3, fail  # Fail out if doesn't match.
        RVTEST_PASS           # Signal success.
fail:
        RVTEST_FAIL
RVTEST_CODE_END     # End of test code.

# Input data section.
# This section is optional, and this data is NOT saved in the output.
.data
        .align 3
testdata:
        .dword 41

# Output data section.
RVTEST_DATA_BEGIN   # Start of test output data region.
        .align 3
result:
        .dword -1
RVTEST_DATA_END     # End of test output data region.

User-Level TVMs

Test programs for the rv32u* and rv64u* TVMs can contain all instructions from the respective base user-level ISA (RV32 or RV64), except for those with the SYSTEM major opcode (syscall, break, rdcycle, rdtime, rdinstret). All user registers (pc, x0-x31, f0-f31, fsr) can be accessed.

The rv32ui and rv64ui TVMs are integer-only subsets of rv32u and rv64u respectively. These subsets can not use any floating-point instructions (major opcodes: LOAD-FP, STORE-FP, MADD, MSUB, NMSUB, NMADD, OP-FP), and hence cannot access the floating-point register state (f0-f31 and fsr). The integer-only TVMs are useful for initial processor bringup and to test simpler implementations that lack a hardware FPU.

Note that any rv32ui test program is also valid for the rv32u TVM, and similarly rv64ui is a strict subset of rv64u. To allow a given test to run on the widest possible set of implementations, it is desirable to write any given test to run on the smallest or least capable TVM possible. For example, any simple tests of integer functionality should be written for the rv64ui TVM, as the same test can then be run on RV64 implementations with or without a hardware FPU. As another example, all tests for these base user-level TVMs will also be valid for more advanced processors with instruction-set extensions.

At the start of execution, the values of all registers are undefined. All branch and jump destinations must be to labels within the test code region of the assembler source file. The code and data sections will be relocated differently for the various implementations of the test environment, and so test program results shall not depend on absolute addresses of instructions or data memory. The test build environment should support randomization of the section relocation to provide better coverage and to ensure test signatures do not contain absolute addresses.

Supervisor-Level TVMs

The supervisor-level TVMs allow testing of supervisor-level state and instructions. As with the user-level TVMs, we provide integer-only supervisor-level TVMs indicated with a trailing i.

History and Acknowledgements

This style of test virtual machine originated with the T0 (Torrent-0) vector microprocessor project at UC Berkeley and ICSI, begun in 1992. The main developers of this test strategy were Krste Asanovic and David Johnson. A precursor to torture was rantor developed by Phil Kohn at ICSI.

A variant of this testing approach was also used for the Scale vector-thread processor at MIT, begun in 2000. Ronny Krashinsky and Christopher Batten were the principal architects of the Scale chip. Jeffrey Cohen and Mark Hampton developed a version of torture capable of generating vector-thread code.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot