Run Shell Command DPI module for Verilator

Version 1.0, November 2011

Many HDL simulators implement some sort of $system() routine that allows you to start an external child process from your Verilog source code.

Because Verilator (as of Oct 2011, version 3.824) does not have such a routine, I wrote a small DPI module as a replacement. [Later note: Verilator supports $system() since version 3.830 (2011/11/27)]

Instead of $system(), this implementation is called run_shell_command_dpi() and takes a printf-like format string with variable arguments. run_shell_command_dpi() returns an error/success indication and, in a separate output argument, the child process' exit code.

run_shell_command_dpi() calls Linux's system() behind the scenes, which is documented as having the same effect as calling sh -c <command> and does not return until the child process terminates. However, you can append an ampersand ('&') to the command in order to leave the child process running in the background, see the example below.

Note that the current version has been developed and tested only on Linux.

Installation instructions

You need to be familiar with Verilator, as you need to add file run_shell_command_dpi.cpp to the generated C++ code. There are a few ways to do that:

Alternative 1) Add run_shell_command_dpi.cpp to the Verilator command line.
Alternative 2) Include run_shell_command_dpi.cpp from your main .cpp file (with #include).
Alternative 3) Edit the makefile you are using.

You also need to add the following to your Verilog source code:

import "DPI-C" function int run_shell_command_dpi ( output int command_exit_code,
                                                    input string shell_cmd_to_run_formatted /*verilator sformat*/ );

Note that the /*verilator sformat*/ hint is specific to Verilator and will not work on other HDL simulators.

Usage example in Verilog:

int shell_cmd_exit_code;

if ( 0 != run_shell_command_dpi( shell_cmd_exit_code,
                                 "gnome-terminal --command \"sh -c 'telnet localhost %d'\" &",
                                 5678 ) )
  begin
     $display("Error trying to start the shell command.");
     $finish;
  end;

if ( 0 != shell_cmd_exit_code )
  begin
     $display( "The shell command exited with a non-zero status code." );
     $finish;
  end;

License

Copyright (C) R. Diez 2011, rdiezmail-openrisc at yahoo.de

The Run Shell Command DPI source code is released under the LGPL 3 license.

This document is released under the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) license.