2.7.1   Ye olde PLI

• ScriptSim is a Perl, Python, and Tcl/Tk interface to PLI.
• Verilog::Pli is a Perl interface to PLI.

3.3.1   Text merging tool

• kdiff3 is a graphical, three-way merging tool for KDE.

• meld is a graphical, three-way merging tool for GNOME.

• tkdiff is a graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.

• xxdiff is a graphical, three-way merging tool.

• imediff2 is a textual, fullscreen two-way merging tool. It is very useful when you are working remotely via SSH.

3.4.1   Installing on Windows

After Ruby-VPI is compiled, it is linked to symbols whose names begin with _vpi. In GNU/Linux and similar operating systems, these symbols are allowed to be undefined. However, one cannot compile a shared object file with references to undefined symbols in Windows.

One solution to this problem is to supply the Verilog simulator’s VPI object file, which contains definitions of all VPI symbols, to the linker. The following steps illustrate this process.

• Install Cygwin, the Linux-like environment for Windows.

• Search for object files whose names end with .so, .o, or .dll in your Verilog simulator’s installation directory.

• Determine which object files, among those found in the previous step, contain symbols whose names begin with “_vpi” by running the

  for x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' && echo $x; done

  command in Cygwin.
  • If you are using Mentor Modelsim, the desired object file can be found at a path similar to C:\Modeltech\win32\libvsim.dll.
  • If you are using GPL Cver, the desired object file can be found at a path similar to C:\gplcver\objs\v_vpi.o.

• Assign the path of the object file (determined in the previous step) to the LDFLAGS environment variable. For example, if the object file’s path is /foo/bar/vpi.so, then you would run the

  export LDFLAGS=/foo/bar/vpi.so

  command in Cygwin.

• You may now install Ruby-VPI by running the

  gem install ruby-vpi

  command in Cygwin.

4.3.1   Deviations from the VPI standard

Ruby-VPI makes the entire IEEE Std 1364-2005 VPI interface available to Ruby, but with the following minor differences.

#include <stdarg.h>
void foo(va_list ap) {
  va_list *p = &ap;
}

4.3.2   Handles

A handle is a reference to an object (such as a module, register, wire, and so on) inside the Verilog simulation. Handles allows you to inspect and manipulate the design under test and its internal components. They are instances of the Vpi::Handle class (see reference documentation for details) in Ruby-VPI.

Handles have various properties, listed in the second column of Table 1, which provide different kinds of information about the underlying Verilog objects they represent. These properties are accessed through the VPI functions listed in the last column of Table 1.

Handles are typically obtained through the vpi_handle_by_name and vpi_handle functions. These functions are hierarchical in nature, as they allow you to obtain new handles that are related to existing ones. For example, to obtain a handle to a register contained within a module, one would typically write: your_reg = vpi_handle( VpiReg, your_handle )

foo = vpi_handle_by_name( "foo", nil )
bar = vpi_handle_by_name( "bar", foo )
baz = vpi_handle_by_name( "baz", bar )

wrapper = S_vpi_value.new
wrapper.format = VpiIntVal
vpi_get_value( foo.bar, wrapper )
result = wrapper.value.integer

wrapper = S_vpi_value.new
wrapper.format = VpiHexStrVal
vpi_get_value( foo.bar, wrapper )
result = wrapper.value.str.to_i( 16 )

4.3.3   Callbacks

A callback is a mechanism that makes the Verilog simuluator execute a block of code, which is known as a “callback handler”, when some prescribed event occurs in the simulation.

Callbacks are added using the vpi_register_cb function and removed using the vpi_remove_cb function. However, instead of storing the address of a C function in the cb_rtn field of the s_cb_data structure (as you would do in C) you pass a block of code to the vpi_register_cb method in Ruby. This block will be executed whenever the callback occurs.

cbTime         = S_vpi_time.new
cbTime.type    = VpiSimTime
cbTime.low     = 0
cbTime.high    = 0

cbValue        = S_vpi_value.new
cbValue.format = VpiIntVal

cbData         = S_cb_data.new
cbData.reason  = CbValueChange
cbData.obj     = Counter.count
cbData.time    = cbTime
cbData.value   = cbValue
cbData.index   = 0

cbHandle = vpi_register_cb(cbData) do |data|
  time   = (data.time.high << 32) | data.time.low
  count  = data.value.value.integer
  puts "hello from callback! time=#{time} count=#{count}"
end

5.1.2   How does prototyping work?

The advance_time method normally transfers control from the executable specification to the Verilog simulator. However, when prototyping is enabled, Ruby-VPI redefines it so that the feign! method (which is defined in a test’s proto.rb file) is invoked on the design under test. The feign! method artificially simulates the behavior of the real Verilog design.

In this manner, control is kept within the Ruby interpreter when prototyping is enabled. An advantage of this approach is that it reduces the total execution time of a Ruby-VPI test by allowing Ruby’s POSIX thread to commandeer the Verilog simulator’s process. A disadvantage of this approach is that callbacks, which require the transfer of control to the Verilog simulator, must be ignored.

5.2.1   Advanced initialization

1. Deactivate the DEBUG environment variable.
2. Put your own code, which initializes the debugger, at the top of your test’s spec.rb file.

5.3.1   Environment variables

Test runners support the following environment variables, which allow you to easily change the behavior of the test runner.

• COVERAGE enables code coverage analysis and generation of code coverage reports.
• DEBUGGER enables the interactive debugger in its post-mortem debugging mode.
• PROTOTYPE enables the Ruby prototype for the design under test so that the prototype, rather than the real Verilog design, is verified by the specification.

To activate these variables, simply assign the number 1 to them. For example, DEBUG=1 activates the DEBUG variable.

To deactivate these variables, simply assign a different value to them or unset them in your shell. For example, both DEBUG=0 and DEBUG= dectivate the DEBUG variable.

rake DEBUG=1

DEBUG=1
export DEBUG
rake

setenv DEBUG 1
rake

rake -f your_test_runner.rake PROTOTYPE=1 COVERAGE=1

rake -f your_test_runner.rake PROTOTYPE=0 COVERAGE=1

rake -f your_test_runner.rake PROTOTYPE=  COVERAGE=1

rake -f your_test_runner.rake COVERAGE=1

5.4.1   Automated test generation

The generate tool generates scaffolding for Ruby-VPI tests from Verilog module declarations (written in either Verilog 2001 or Verilog 95 style).

• runner.rake runs the test by starting a Verilog simulator and loading Ruby-VPI into it.
• spec.rb is the executable specification for the design under test.
• design.rb is an optional file that provides convenience methods for controlling the design under test.
• proto.rb is an optional file that defines a Ruby prototype of the design under test.
• Rakefile is an optional file that recursively executes all runner.rake files found immediately within or beneath the current directory. It lets you simply run

  rake ...

  instead of having to write

  rake -f runner.rake ...

  every time.

As Example 4 shows, the name of each generated file is prefixed with the name of the Verilog module for which the test was generated. This convention helps organize tests within the file system, so that they are readily distinguishable from one another.

Caution 1.   Do not rename generated files

Ruby-VPI uses the convention described above to dynamically create a direct Ruby interface to the design under test, so do not rename the generated files arbitrarily.

You can try this tool by running the

ruby-vpi generate --help

Tip 3.   Using kdiff3 with the automated test generator.

1. Create a file named merge2 with the following content:

   #!/bin/sh
   # args: old file, new file
   kdiff3 --auto --output "$2" "$@"
   

2. Make the file executable by running the

   chmod +x merge2

   command.
3. Place the file somewhere accessible by your PATH environment variable.
4. Assign the value “merge2” to the MERGER environment variable using your shell’s export or setenv command.

From now on, kdiff3 will be invoked to help you transfer your changes between generated files. When you are finished transferring changes, simply issue the “save the file” command and quit kdiff3. Or, if you do not want to transfer any changes, simply quit kdiff3 without saving the file.

5.4.2   Verilog to Ruby conversion

The convert tool can be used to convert Verilog header files into Ruby. You can try it by running the

ruby-vpi convert --help

By converting Verilog header files into Ruby, your test can utilize the same `define constants that are used in the Verilog design.

5.6.1   Start with a Verilog design

First, we need a Verilog design to test. In this tutorial, Example 3 will serve as our design under test. Its interface is composed of the following parts:

• Size defines the number of bits used to represent the counter’s value.
• clock causes the count register to increment whenever it reaches a positive edge.
• reset causes the count register to become zero when asserted.
• count is a register that contains the counter’s value.

module counter #(parameter Size = 5) (
  input                   clock,
  input                   reset,
  output reg [Size-1 : 0] count
);
endmodule

5.6.2   Generate a test

Now that we have a Verilog design to test, we shall use the generate tool to generate some scaffolding for our test. This tool allows us to implement our specification using RSpec, xUnit, or any other format.

• RSpec represents BDD
• xUnit represents TDD
• our own format can represent another methodology

In this tutorial, you will see how both RSpec and xUnit formats are used. So let us make separate directories for both formats to avoid generated tests from overwriting each other:

$ mkdir RSpec xUnit
$ cp counter.v RSpec
$ cp counter.v xUnit

Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. This process is illustrated by Example 4 and Example 5.

$ ruby-vpi generate counter.v --RSpec

  module  counter
  create  counter_runner.rake
  create  counter_design.rb
  create  counter_proto.rb
  create  counter_spec.rb
  create  Rakefile

$ ruby-vpi generate counter.v --xUnit

  module  counter
  create  counter_runner.rake
  create  counter_design.rb
  create  counter_proto.rb
  create  counter_spec.rb
  create  Rakefile

5.6.3   Specify your expectations

So far, the test generation tool has created a basic foundation for our test Now we must build upon this foundation by identifying our expectation of the design under test. That is, how do we expect the design to behave under certain conditions?

• A resetted counter’s value should be zero.
• A resetted counter’s value should increment by one count upon each rising clock edge.
• A counter with the maximum value should overflow upon increment.

Now that we have identified a set of expectations for our design, we are ready to implement them in our specification. This process is illustrated by Example 6 and Example 7.

require 'spec'

# lowest upper bound of counter's value
LIMIT = 2 ** Counter::Size

# maximum allowed value for a counter
MAX = LIMIT - 1

describe "A resetted counter's value" do
  setup do
    Counter.reset!
  end

  it "should be zero" do
    Counter.count.intVal.should == 0
  end

  it "should increment upon each rising clock edge" do
    LIMIT.times do |i|
      Counter.count.intVal.should == i
      Counter.cycle! # increment the counter
    end
  end
end

describe "A counter with the maximum value" do
  setup do
    Counter.reset!

    # increment the counter to maximum value
    MAX.times { Counter.cycle! }
    Counter.count.intVal.should == MAX
  end

  it "should overflow upon increment" do
    Counter.cycle! # increment the counter
    Counter.count.intVal.should == 0
  end
end

require 'test/unit'

# lowest upper bound of counter's value
LIMIT = 2 ** Counter::Size

# maximum allowed value for a counter
MAX = LIMIT - 1

class ResettedCounterValue < Test::Unit::TestCase
  def setup
    Counter.reset!
  end

  def test_zero
    assert_equal( 0, Counter.count.intVal )
  end

  def test_increment
    LIMIT.times do |i|
      assert_equal( i, Counter.count.intVal )
      Counter.cycle! # increment the counter
    end
  end
end

class MaximumCounterValue < Test::Unit::TestCase
  def setup
    Counter.reset!

    # increment the counter to maximum value
    MAX.times { Counter.cycle! }
    assert_equal( MAX, Counter.count.intVal )
  end

  def test_overflow
    Counter.cycle! # increment the counter
    assert_equal( 0, Counter.count.intVal )
  end
end

1. Replace the contents of the file named RSpec/counter_spec.rb with the source code shown in Example 6.
2. Replace the contents of the file named xUnit/counter_spec.rb with the source code shown in Example 7.

5.6.4   Implement the prototype

Now that we have a specification against which to verify our design let us build a prototype of our design. By doing so, we exercise our specification, experience potential problems that may arise when we later implement our design in Verilog, and gain confidence in our work. The result of this proceess is illustrated by Example 8.

# Ruby prototype of the design under test's Verilog implementation.
def feign!
  if clock.posedge?
    if reset.high?
      count.intVal = 0
    else
      count.intVal += 1
    end
  end
end

5.6.5   Verify the prototype

Now that we have implemented our prototype, we are ready to verify it against our specification by running the test This process is illustrated by Example 9 and Example 10.

In these examples, the PROTOTYPE environment variable is assigned the value 1 while running the test so that, instead of our design, our prototype is verified against our specification (see Section 5.3.1 for details). Also, the GPL Cver simulator denoted by cver, is used to run the simulation.

$ cd RSpec
$ rake cver PROTOTYPE=1

Ruby-VPI: prototype is enabled
...

Finished in 0.05106 seconds

3 examples, 0 failures
cd -

$ cd xUnit
$ rake cver PROTOTYPE=1

Ruby-VPI: prototype is enabled
Loaded suite counter
Started
...
Finished in 0.043859 seconds.

3 tests, 35 assertions, 0 failures, 0 errors

Tip 4.   What can the test runner do?

If you invoke the test runner (1) without any arguments or (2) with the --tasks option, it will show you a list of tasks that it can perform for you.

5.6.6   Implement the design

Now that we have implemented and verified our prototype, we are ready to implement our design This is often quite simple because we translate existing code from Ruby (our prototype) into Verilog (our design). The result of this process is illustrated by Example 11.

/**
  A simple up-counter with synchronous reset.

  @param  Size   Number of bits used to represent the counter's value.
  @param  clock  Increments the counter's value upon each positive edge.
  @param  reset  Zeroes the counter's value when asserted.
  @param  count  The counter's value.
*/
module counter #(parameter Size = 5) (
  input                   clock,
  input                   reset,
  output reg [Size-1 : 0] count
);
  always @(posedge clock) begin
    if (reset)
      count <= 0;
    else
      count <= count + 1;
  end
endmodule

5.6.7   Verify the design

Now that we have implemented our design we are ready to verify it against our specification by running the test Example 12 and Example 13 illustrate this process.

In these examples, the PROTOTYPE environment variable is not specified while running the test, so that our design, instead of our prototype, is verified against our specification. You can also achieve this effect by assigning an empty value to PROTOTYPE, or by using your shell’s unset command. Finally, the GPL Cver simulator denoted by cver, is used to run the simulation.

$ cd RSpec
$ rake cver

...

Finished in 0.041198 seconds

3 examples, 0 failures

$ cd xUnit
$ rake cver

Loaded suite counter
Started
...
Finished in 0.040262 seconds.

3 tests, 35 assertions, 0 failures, 0 errors

7.1.1   Give full paths to Verilog objects

In version 0.8 and snapshot 20061009 of Icarus Verilog, the vpi_handle_by_name function requires an absolute path (including the name of the bench which instantiates the design) to a Verilog object. In addition, vpi_handle_by_name always returns nil when its second parameter is specified.

For example, consider Example 14. Here, one must write vpi_handle_by_name("TestFoo.my_foo.clk", nil) instead of vpi_handle_by_name("my_foo.clk", TestFoo) in order to access the clk input of the my_foo module instance.

module TestFoo;
  reg clk_reg;
  Foo my_foo(.clk(clk_reg));
endmodule

7.1.2   Registers must be connected

In version 0.8 of Icarus Verilog, if you want to access a register in a design, then it must be connected to something (either assigned to a wire or passed as a parameter to a module instantiation). Otherwise, you will get a nil value as the result of vpi_handle_by_name method.

For example, suppose you wanted to access the clk_reg register, from the bench shown in Example 15 If you execute the statement clk_reg = vpi_handle_by_name("TestFoo.clk_reg", nil) in a specification, then you will discover that the vpi_handle_by_name method returns nil instead of a handle to the clk_reg register.

The solution is to change the design such that it appears like the one shown in Example 16 where the register is connected to a wire, or Example 14 where the register is connected to a module instantiation.

module TestFoo;
  reg clk_reg;
endmodule

module TestFoo;
  reg clk_reg;
  wire clk_wire;
  assign clk_wire = clk_reg;
endmodule

7.1.3   Vpi::reset

7.2.1   Cannot force values onto handles

When you write to a handle’s value using vpi_put_value() with the VpiForceFlag propagation parameter, it does not have any effect. As a result, the “register_file” sample test fails when you run it with NC-Sim.

This might be a bug in NC-Sim itself: even though I specified the “+access+rwc” command-line option for NC-Sim, I’m thinking that the force/release capability is not really enabled. However, it’s more likely that there’s a bug in the “register_file” sample test.

If you happen to know the solution, please tell me either on the project forums or via e-mail (see the LICENSE file for my e-mail address). Thanks.