DiffTest (差分测试): a modern co-simulation framework for RISC-V processors.

DiffTest interfaces are provided in Chisel bundles and expected to be integrated into Chisel designs with auto-generated C++ interfaces. However, we also provide examples of the generated Verilog modules.

make difftest_verilog NOOP_HOME=$(pwd)

1. Add this submodule to your design.

In your Git project:

git submodule add https://github.com/OpenXiangShan/difftest.git

In Mill build.sc:

import $file.difftest.build

// We recommend using a fixed Chisel version.
object difftest extends millbuild.difftest.build.CommonDiffTest {
  def crossValue: String = "3.5.6"

  override def millSourcePath = os.pwd / "difftest"
}

// This is for advanced users only. All supported Chisel versions are listed in `build.sc`.
// To pass a cross value to difftest:
object difftest extends Cross[millbuild.difftest.build.CommonDiffTest](chiselVersions) {
  override def millSourcePath = os.pwd / "difftest"
}

In Makefile:

emu: sim-verilog
	@$(MAKE) -C difftest emu WITH_CHISELDB=0 WITH_CONSTANTIN=0

2. Add difftest modules (in Chisel or Verilog) to your design.

import difftest._

val difftest = DifftestModule(new DiffInstrCommit, delay = 1, dontCare = true)
difftest.valid  := io.in.valid
difftest.pc     := SignExt(io.in.bits.decode.cf.pc, AddrBits)
difftest.instr  := io.in.bits.decode.cf.instr
difftest.skip   := io.in.bits.isMMIO
difftest.isRVC  := io.in.bits.decode.cf.instr(1, 0)=/="b11".U
difftest.rfwen  := io.wb.rfWen && io.wb.rfDest =/= 0.U
difftest.wdest  := io.wb.rfDest
difftest.wpdest := io.wb.rfDest

3. Call val difftesst = DifftestModule.finish(cpu: String) at the top module whose name should be SimTop. The variable name difftest must be used to ensure DiffTest could capture the input signals.

An optional UART input/output can be connected to DiffTest. DiffTest will automatically DontCare it internally.

val difftest = DifftestModule.finish("Demo")

// Optional UART connections. Remove this line if UART is not needed.
difftest.uart <> mmio.io.uart

4. Generate verilog files for simulation.

5. make emu and start simulating & debugging!

We provide example designs, including:

• XiangShan
• NutShell
• Rocket

Currently we are supporting the RISC-V base ISA as well as some extensions, including Float/Double, Debug, and Vector. We also support checking the cache coherence via RefillTest.

The DiffTest framework comes with a simulation framework with some top-level IOs.

• LogCtrlIO
• PerfCtrlIO
• UARTIO

These IOs can be used along with the controller wrapper at src/main/scala/common/LogPerfControl.scala.

For compatibility on different platforms, the CPU should access a C++ memory via DPI-C interfaces. This memory will be initialized in C++.

val mem = DifftestMem(memByte, 8)
when (wen) {
    mem.write(
    addr = wIdx,
    data = in.w.bits.data.asTypeOf(Vec(DataBytes, UInt(8.W))),
    mask = in.w.bits.strb.asBools
    )
}
val rdata = mem.readAndHold(rIdx, ren).asUInt

To use DiffTest, please include all necessary modules and top-level IOs in your design. It's worth noting the Chisel Bundles may have arguments with default values. Please set the correct parameters for the interfaces.

• Difftest: detailed usage (Chinese)
• SMP-Difftest 支持多处理器的差分测试方法