Skip to content
STIMSMITH

Handshaking Mechanism

Concept WIKI v1 · 6/6/2026

The handshaking mechanism is a runtime status-reporting facility, provided by the RISCV-DV instruction generator, that allows a core under test to communicate execution state to the testbench during program execution. In Ibex's RTL/ISS co-simulation flow it compensates for the inability of ISS golden models to model traps caused by external stimulus (interrupts, debug requests, memory faults), enabling verification that the core entered the proper interrupt handler, entered Debug Mode, or updated CSRs correctly.

Handshaking Mechanism

Purpose and Motivation

In an end-to-end RTL/ISS co-simulation flow, the final stage normally parses the trace log produced by the core and the trace log produced by the chosen golden-model ISS, and compares the sets of register writebacks (correct data, to the correct registers, in the correct order) to determine correctness of a given simulation.

This register-writeback comparison model is sufficient for ordinary execution, but it breaks down when tests involve external stimulus such as interrupts and debug requests. ISS models can simulate traps caused by exceptions, but they cannot model traps caused by external stimulus. As a result, register-writeback comparison alone cannot verify that the core has:

  • Entered the proper interrupt handler,
  • Entered Debug Mode properly, or
  • Updated CSRs correctly.

To regain verification coverage in these scenarios, the Ibex testbench makes heavy use of the handshaking mechanism provided by the RISCV-DV instruction generator, which effectively allows the core to send status information to the testbench during program execution for any analysis that is required to increase verification effectiveness.

Mechanism

The mechanism is documented in detail by Google RISCV-DV at:

https://github.com/google/riscv-dv/blob/master/docs/source/handshake.rst

The handshaking is performed by the core writing to a designated signature address, which in the Ibex testbench is fixed to:

0x8ffffffc

A small set of API tasks is provided in dv/uvm/core_ibex/tests/core_ibex_base_test.sv to enable easy and efficient integration and usage of this mechanism in the Ibex test environment.

Use Sites in the Ibex Testbench

The handshake is used in practice in dv/uvm/core_ibex/tests/core_ibex_test_lib.sv, where it is extensively used to provide runtime verification for situations involving:

  • External debug requests,
  • Interrupt assertions, and
  • Memory faults.

Complementary Trace-Log Comparison

To add another layer of correctness checking to the checking already provided by the handshaking mechanism, a modified version of the trace-log comparison is used. Comparing every register write performed during the entire simulation would lead to an incorrect result, because the ISS trace log will not contain any execution information in the debug ROM or in any interrupt handler code. As a result, only the final values contained in every register at the end of the test are compared against each other, since any code executed in the debug ROM and trap handlers should not corrupt register state in the rest of the program.

Flow Control

The entirety of this RTL/ISS co-simulation flow (including the handshaking mechanism and the modified register-comparison check) is controlled by the Makefile found at dv/uvm/core_ibex/Makefile.

LINKED ENTITIES

7 links
signature address USES
riscv-dv IMPLEMENTS
RTL/ISS co-simulation USES
core_ibex_base_test.sv IMPLEMENTS
core_ibex_test_lib.sv USES
Debug Mode USES
CSR USES

CITATIONS

7 sources
7 citations
[1] The handshaking mechanism is provided by the RISCV-DV instruction generator and allows the core to send status information to the testbench during program execution. Verification — Ibex Documentation
[2] The handshaking mechanism is used in the Ibex end-to-end RTL/ISS co-simulation flow because ISS models cannot model traps due to external stimulus, and it enables verification that the core entered the proper interrupt handler, entered Debug Mode properly, and updated CSRs correctly. Verification — Ibex Documentation
[3] The signature address used by the Ibex testbench for the handshaking is 0x8ffffffc. Verification — Ibex Documentation
[4] API tasks for the handshaking mechanism are provided in dv/uvm/core_ibex/tests/core_ibex_base_test.sv, and example real-simulation usage is in dv/uvm/core_ibex/tests/core_ibex_test_lib.sv. Verification — Ibex Documentation
[5] The handshaking mechanism is extensively used to provide runtime verification for situations involving external debug requests, interrupt assertions, and memory faults. Verification — Ibex Documentation
[6] Complementing the handshake, the trace-log comparison is modified to compare only the final values of every register at the end of the test, because the ISS trace log lacks execution information from the debug ROM and interrupt handler code. Verification — Ibex Documentation
[7] The full co-simulation flow, including use of the handshaking mechanism, is controlled by the Makefile at dv/uvm/core_ibex/Makefile. Verification — Ibex Documentation