This PR introduces new DPI-Instrumentation capabilities for Verilator. Additionally to make the configuration of the instrumantion via the Verilator configuration file easier a signal dumping capability is introduced, that prints the signal hierarchy that is needed for the instrumentation into a log file.

Motivation

Verilator supports the usage of the DPI functionalities of SystemVerilog, but implementing the DPI into the design, especially for complex designs, can be cumbersome. This PR provides a pass for automating the adding of DPI calls into the provided module. (V3Instrumentation)
To make the configuration of this automation easier for the user the instrumentation an additional pass is part of the PR, which dumps signals that can be currently addressed by the DPI-Instrumentation. (V3DumpSignals)

Features

V3Instrumentation:

• Added a Verilator execution argument that enables the usage for the instrumentation in form of --instrument.
• Automatically inserts DPI interface calls on the Verilog design side, based on an instrumentation configuration provided in a Verilator .vlt configuration file.
• A new configuration structure for the instrumentation is introduced for the .vlt files, following the syntax: instrument --model "<function name>" --id "<switch_case_id>" --target "<topmodule.instance.instance.variable>"
  • The keyword instrument informs Verilator that instrumentation is required for the provided signal hierarchy.
  • model specifies the DPI function to be called.
  • id defines the case, if a case depended functionality like a switch case statement is used. This can be used if depending on the provided case a different functionality should be executed by the DPI while keeping the same function name, e.g. fault injection stuck-at-1 vs. stuck-at-0 for the same signal type.
  • target provides the full hierarchical path to the signal that should be instrumented.
• The instrumentation pass works in two steps:
  1. Collection/Finding Phase: The pass parses the provided configuration, collects the relevant information from the provided --target path, and stores it in a map. It also inserts parameters along the module hierarchy to ensure structural consistency and enable precise instrumentation. These parameters are used to enable the instrumentation for specific hierarchy paths while disabling them for hierarchy paths that should not use the instrumentation.
  2. Insertion/Instrumentation Phase: The pass modifies the AST, inserting the required nodes for the DPI call environment and ensuring that references initially occupied by the original signal node are properly reconnected to the instrumented signal nodes.

V3DumpSignals:

• Iterates over the AST and collects all signals that can currently be instrumented (see limitations).
• Dumps each signal’s hierarchy path, type, and bit width into a signalDump.log file inside obj_dir.
• This functionality can be enabled with the Verilator flag --dump-signals.

Limitations

• The top module can currently not be instrumented. Instrumenting it will be intercepted and lead to an error-message.
• Signals above 64bit can currently not be instrumented, due to interaction with the DPI Task does not work reliable.
• Signals that are not C++ literal types can not be instrumented, due to interaction with the DPI Task does not work reliable.
• Signals that are provided by packages or interfaces can not be instrumented, due to interaction with the DPI Task does not work reliable.

Future Plans/To Dos

• Extending the signal amounts that can be instrumented
• Enable the instrumentation of the Top module (Probably some discussion would be nice if the current idea has some drawbacks)
• Setup an regression test for failing instrumentation (not sure how to set it up properly so some help would be nice here)

Thanks a lot in advance for any feedback for my first big PR. Looking forward for the upcoming discussions, improvements and ideas!