Terms

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the the file named LICENSE.

Admonition and navigation graphics are Copyright© 2005, 2006 Tango Desktop Project. They are licensed under these terms.

Introduction

Ruby-VPI is a Ruby interface to Verilog VPI. It lets you create complex Verilog test benches easily and wholly in Ruby.

Features

• Supports the entire IEEE Std 1364-2005 VPI standard.

• Works with all major Verilog simulators available today.

• Enables agile practices such as
  • test-driven development
  • behavior-driven development
  • rapid prototyping for design exploration

• Eliminates unneccesary work:
  • Specifications are readable, portable, and executable.
  • The automated test generator helps you accomodate design changes with minimal effort.

• Utilizes the power and elegance of Ruby:
  • Unlimited length integers
  • Regular expressions
  • Multi-threading
  • System calls and I/O
  • ad infinium

• Gives you the freedom to study, modify, and distribute this software, in accordance with the GNU General Public License.

Appetizers

Here is a modest sampling to whet your appetite.

• Assign the value 2²⁰⁴⁸ to a register:

some_register.intVal = 2 ** 2048

• Check if all nets in a module are at high impedance:

some_module.all_net? { |net| net.z? }

• See a register’s path, width, and location (file & line number):

puts some_register

• Simulate fifteen clock cycles:

15.times { relay_verilog }

License

Ruby-VPI is free software ; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation ; either version 2 of the License, or (at your option) any later version.

Related works

• JOVE is a Java interface to VPI.
• Teal is a C++ interface to VPI.
• ScriptEDA is a Perl, Python, and Tcl interface to VPI.
• RHDL is a hardware description and verification language based on Ruby.
• MyHDL is a hardware description and verification language based on Python, which features conversion to Verilog and co-simulation.

Ye olde PLI

The following projects utilize the archaic tf and acc PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005.

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

Background

Ruby-VPI is a bench which lets you test Verilog modules using the Ruby language.

Methodology

Ruby-VPI presents an open-ended interface to VPI. Thus, you can use any methodology you wish when writing tests.

Terminology

As a newcomer into the world of Verilog, I often heard the term test bench: “I ran the test bench, but it didn’t work!” or “Are you crazy?!! You still haven’t written the test bench?”, for example. I flipped through my textbook and surfed the Internet for a definition of the term, but it was to no avail. Instead, both resources nonchalantly employed the term throughout their being, as if mocking my ignorance of what seems to be universal knowledge.

Defeated, I turned to my inner faculties to determine the answer. Let’s see, the term test bench has the word test—so it has something to do with testing—and it has the word bench—so maybe it’s referring to a table where the testing should occur. This reasoning grew increasingly familiar as my mind rummaged through towering stores of obsolescence and ultimately revealed dreaded memories of sleepless anguish: debugging electronics in the robotics laboratory.

Aha! I exclaimed hesitantly, trying to dismiss the past. The term has its roots in the testing of electronic devices, where an engineer would sit at a bench in an electronics laboratory and verify that an electronic component satisfies some criteria. The bench would be furnished with tools of measurement and manipulation—such as oscilloscopes, voltmeters, soldering irons, and so on—which help the engineer to verify the electronic component or locate the sources of defects in the component.

Alright, now I remember what a laboratory bench is, but how does that compare with the term test bench? Surely they cannot have the same meaning, because it doesn’t make sense to run a laboratory bench or to write one. Thus, to avoid propagating such confusion into this manual, I have attempted to clarify the terminology by simplifying and reintroducing it in a new light.

Organization

As the figure named “Overall organization of a test” shows, a test is composed of a bench, a design, and a specification. To extend the analogy of an electronics laboratory, the first acts as the laboratory bench which provides measurement and manipulation tools. The second acts as the electronic component being verified by the engineer. And the third acts as the engineer who measures, manipulates, and verifies the electronic component.

Interface to VPI

In the figure named “Detailed organization of a test”, Ruby-VPI acts as the bench, a Verilog simulator encapsulates the design, and a Ruby interpreter encapsulates the specification. Notice that Ruby-VPI encapsulates all communication between the Ruby interpreter and VPI. This allows the specification, or any Ruby program in general, to access VPI using nothing more than the Ruby language! Thus, Ruby-VPI removes the burden of having to write C programs in order to access VPI.

Furthermore, Ruby-VPI presents the entire IEEE Std 1364-2005 VPI interface to the Ruby interpreter, but with the following minor changes.

• The first letter in the name of every function, type, structure, and constant becomes capitalized. For example, the s_vpi_value structure in C becomes the S_vpi_value class in Ruby. Likewise, the vpiIntVal constant in C becomes the VpiIntVal constant in Ruby.

• The VPI functions vpi_vprintf and vpi_mcd_vprintf are not made accessible to Ruby. However, this isn’t a big problem because you can use Ruby’s printf method instead.

The reason for this limitation is that some C compilers have trouble with pointers to the va_list type. For these compilers, the second line in the code shown below causes a “type mismatch” error.

void foo(va_list ap) {
  va_list *p = ≈
}

VPI utility layer

From a user’s perspective, the VPI utility layer greatly enhances the ability to interact with handles. One simply invokes a handle’s methods, which are carefully named in the following manner, to access either (1) its children or (2) its VPI properties.

The children of a handle are simply the handles that are immediately contained within it in. For example, suppose that you had a Verilog module that contains some registers. The children, of a handle to the module, would be handles to the registers.

In the event that a child handle has the same name as a VPI property, the child is given priority. However, you can always access VPI properties explicitly via the Vpi::Handle.get_value and Vpi::Handle.put_value methods.

Running a test

Unlike an engineer who can verify an electronic component in real-time, the Verilog simulator and the Ruby interpreter (see the figure named “Detailed organization of a test”) take turns working with objects in a simulation when a test is run. In particular, they take turns manipulating the design and transfer control to each other when appropriate.

The situation is similar to a pair of friends playing catch. One friend throws a ball to the other, and the other throws it back. Either is able to inspect and modify the ball, but only when it is in hand.

Initialization

A test is first initialized before it is executed. the figure named “Initialization of a test” illustrates the initialization process described below.

1. The Verilog simulator initializes the Ruby interpreter by invoking the $ruby_init; system task/function, whose parameters represent the command-line invocation of the Ruby interpreter. For example, one would specify $ruby_init("ruby", "-w"); in Verilog to achieve the same effect as running

   ruby -w

   at a command-prompt.
2. The Verilog simulator is paused and the Ruby interpreter is initialized with the arguments of the $ruby_init; system task/function.
3. When the Ruby interpreter invokes the Vpi::relay_verilog method, it is paused and the Verilog simulator is given control.

Execution

After a test is initialized, it is executed such that the design is verified against the specification. the figure named “Execution of a test” illustrates the execution process described below.

1. The Verilog simulator transfers control to the Ruby interpreter by invoking the $ruby_relay; system task/function.
2. The Verilog simulator is paused and the Ruby interpreter is given control.
3. When the Ruby interpreter invokes the Vpi::relay_verilog method, it is paused and the Verilog simulator is given control.

Setup

Manifest

When you extract a release package, the following is what you would expect to find.

• doc contains user documentation in various formats.
• ref contains reference API documentation in HTML format.
• ext contains source code, written in the C language, for the core of Ruby-VPI.
• lib contains Ruby libraries provided by Ruby-VPI.
• bin contains various tools. See the section named “Tools” for more information.
• samp contains example tests. See the section named “Examples” for more information.

Requirements

The following software is necessary in order to use Ruby-VPI.

• Verilog simulator – Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports VPI.
  • GPL Cver – version 2.11a or newer is acceptable.
  • Icarus Verilog – version 0.8 or newer is acceptable.
  • Synopsys VCS – any version that supports the -load option is acceptable.
  • Mentor Modelsim – any version that supports the -pli option is acceptable.

• make – any distribution should be acceptable.

• C compiler – the GNU Compiler Collection is preferred, but any C compiler should be acceptable.

• POSIX threads – header and linkable object files, and operating system support for this library are necessary.

• Ruby – version 1.8 or newer, including header and linkable object files for building extensions, is necessary. You can install Ruby by following these instructions.

• RubyGems – any recent version should be acceptable. You can install RubyGems by following these instructions.

Recommendations

The following software may make your interactions with Ruby-VPI more pleasant.

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.

Installation

Once you have satisfied the necessary requirements, you can install Ruby-VPI by running the

gem install ruby-vpi

gem env gemdir

$ gem env gemdir
/usr/lib/ruby/gems/1.8

$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/

Installing on Windows

• 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' > /dev/null && 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.

Maintenance

• You can uninstall Ruby-VPI by running the

  gem uninstall ruby-vpi

  command.
• You can upgrade to the latest release of Ruby-VPI by running the

  gem update ruby-vpi

  command.

Usage

Tools

The bin directory contains various utilities which ease the process of writing tests. Each tool provides help and usage information invoked with the —help option.

Automated test generation

The automated test generator (generate_test.rb) generates tests from Verilog 2001 module declarations, as demonstrated in the tutorial. A generated test is composed of the following parts:

• Runner – written in Rake, this file builds and runs the test.
• Bench – written in Verilog and Ruby, these files define the testing environment.
• Design – written in Ruby, this file provides an interface to the design being verified.
• Prototype – written in Ruby, this file defines a prototype of the design being verified.
• Specification – written in Ruby, this file describes the expected behavior of the design.

The reason for dividing a single test into these parts is mainly to decouple the design from the specification. This allows you to focus on writing the specification while the remainder is automatically generated by the tool. For example, when the interface of a Verilog module changes, you would simply re-run this tool and incorporate those changes (using a text merging tool) into the test without diverting your focus from the specification.

Verilog to Ruby conversion

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

header_to_ruby.rb --help

Tutorial

1. Declare the design, which is a Verilog module, using Verilog 2001 syntax.
2. Generate a test for the design using the automated test generator tool.
3. Identify your expectations for the design and implement them in the specification.
4. (Optional) Implement the prototype of the design in Ruby.
5. (Optional) Verify the prototype against the specification.
6. Implement the design in Verilog once the prototype has been verified.
7. Verify the design against the specification.

Start with a design

First, we need a design to verify. In this tutorial, the example named “Declaration of a simple up-counter with synchronous reset” will serve as our design. 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

Generate a test

Now that we have a design to verify, let us generate a test for it using the automated test generator. This tool allows us to implement our specification in either rSpec, xUnit, or our very own format.

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

Both rSpec and xUnit are presented in this tutorial.

Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. the example named “Generating a test with specification in rSpec format” and the example named “Generating a test with specification in xUnit format” illustrate this process.

$ generate_test.rb counter.v --rspec --name rspec

  module  counter
  create  counter_rspec_runner.rake
  create  counter_rspec_bench.v
  create  counter_rspec_bench.rb
  create  counter_rspec_design.rb
  create  counter_rspec_proto.rb
  create  counter_rspec_spec.rb

$ generate_test.rb counter.v --xunit --name xunit

  module  counter
  create  counter_xunit_runner.rake
  create  counter_xunit_bench.v
  create  counter_xunit_bench.rb
  create  counter_xunit_design.rb
  create  counter_xunit_proto.rb
  create  counter_xunit_spec.rb

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. 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. the example named “Specification implemented in rSpec format” and the example named “Specification implemented in xUnit format” illustrate this process. Note the striking similarities between our expectations and their implementation.

# This file is a behavioral specification for the design under test.

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

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

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

  specify "should be zero" do
    Counter.count.intVal.should_equal 0
  end

  specify "should increment by one count upon each rising clock edge" do
    LIMIT.times do |i|
      Counter.count.intVal.should_equal i
      relay_verilog # increment the counter
    end
  end
end

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

    # increment the counter to maximum value
    MAX.times {relay_verilog}
    Counter.count.intVal.should_equal MAX
  end

  specify "should overflow upon increment" do
    relay_verilog # increment the counter
    Counter.count.intVal.should_equal 0
  end
end

# This file is a behavioral specification for the design under test.

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

# 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
      relay_verilog # increment the counter
    end
  end
end

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

    # increment the counter to maximum value
    MAX.times {relay_verilog}
    assert_equal MAX, Counter.count.intVal
  end

  def test_overflow
    relay_verilog # increment the counter
    assert_equal 0, Counter.count.intVal
  end
end

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 example named “Ruby prototype of our Verilog design” shows the completed prototype for our design.

def Counter.simulate!
  if reset.intVal == 1
    count.intVal = 0
  else
    count.intVal += 1
  end
end

Verify the prototype

Now that we have implemented our prototype, we are ready to verify it against our specification by running the test. the example named “Running a test with specification in rSpec format” and the example named “Running a test with specification in xUnit format” illustrate this process.

Here, the PROTOTYPE environment variable is assigned a non-empty value while running the test, so that, instead of our design, our prototype is verified against our specification. You can also assign a value to PROTOTYPE before running the test, by using your shell’s export or setenv command. Finally, the Icarus Verilog simulator, denoted by cver, is used to run the simulation.

$ rake -f counter_rspec_runner.rake cver PROTOTYPE=1

Ruby-VPI: prototype has been enabled for test "counter_rspec" 

A resetted counter's value
- should be zero
- should increment by one count upon each rising clock edge

A counter with the maximum value
- should overflow upon increment

Finished in 0.018199 seconds

3 specifications, 0 failures

$ rake -f counter_xunit_runner.rake cver PROTOTYPE=1

Ruby-VPI: prototype has been enabled for test "counter_xunit" 

Loaded suite counter_xunit_bench
Started
...
Finished in 0.040668 seconds.

3 tests, 35 assertions, 0 failures, 0 errors

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 example named “Implementation of a simple up-counter with synchronous reset” illustrates the result of this process. Once again, note the striking similarities between the implementation of our prototype and design.

/**
  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

Verify the design

Now that we have implemented our design, we are ready to verify it against our specification by running the test. the example named “Running a test with specification in rSpec format” and the example named “Running a test with specification in xUnit format” illustrate this process.

Here, 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 Verilog simulator, denoted by cver, is used to run the simulation.

rake cver

$ rake -f counter_rspec_runner.rake cver

A resetted counter's value
- should be zero
- should increment by one count upon each rising clock edge

A counter with the maximum value
- should overflow upon increment

Finished in 0.005628 seconds

3 specifications, 0 failures

$ rake -f counter_xunit_runner.rake cver

Loaded suite counter_xunit_bench
Started
...
Finished in 0.006766 seconds.

3 tests, 35 assertions, 0 failures, 0 errors

Examples

The samp directory contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated Rakefile which simplifies the process of running it. Therefore, simply navigate into an example directory and run the

rake

Also, some example specifications make use of BDD through the rSpec library. See the section named “Methodology” for a discussion of rSpec.

Hacking

Building release packages

In addition to the normal requirements, you need the following software to build release packages:

• SWIG
• RedCloth
• CodeRay

Once you have satisfied these requirements, you can run

rake release

rake -T

Known problems

This chapter presents known problems and possible solutions. In addition, previously solved problems have been retained for historical reference.

Ruby

SystemStackError

If a “stack level too deep (SystemStackError)” error occurs during the simulation, then increase the system-resource limit for stack-size by running the

ulimit -s unlimited

test/unit

If your specification employs Ruby’s unit testing framework, then you will encounter an error saying “[BUG] cross-thread violation on rb_gc()”.

Icarus Verilog

Vpi::vpi_handle_by_name

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 is unable to retrieve the handle for a module parameter.

For example, consider the example named “Part of a bench which instantiates a Verilog design” Here, one needs to specify TestFoo.my_foo.clk instead of my_foo.clk 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

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 the example named “Bad design with unconnected registers” 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 the example named “Fixed design with wired registers” where the register is connected to a wire, or the example named “Part of a bench which instantiates a Verilog design” 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

Vpi::reset

In version 0.8 of Icarus Verilog, the vpi_control(vpiReset) VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.

Mentor Modelsim

ruby_run();

Version 6.1b of Mentor Modelsim doesn’t play nicely with either an embedded Ruby interpreter or POSIX threads in a PLI application. When Ruby-VPI invokes the ruby_run function (which starts the Ruby interpreter), the simulator terminates immediately with an exit status of 0.

Glossary

Bench

An environment in which a design is verified against a specification. Often, it is used to emulate conditions in which the design will be eventually deployed.

BDD

Behavior driven development.

A software development methodology which emphasizes thinking in terms of behavior when designing, implementing, and verifying software. See the official wiki for more information.

Design

An idea or entity that is verified against a specification in order to ensure correctness or soundness of its being. In other words, it is the thing being checked: does it work or not?

Expectation

The desired response to some stimulus.

Handle

An object in a Verilog simulation. For example, a handle can represent a wire, register, module, if-statement, expression, and so on.

Rake

Rake is a build tool, written in Ruby, using Ruby as a build language. Rake is similar to make in scope and purpose. —Rake documentation

See the Rake website for more information.

rSpec

Ruby framework for BDD. See the rSpec website and tutorial for more information.

Specification

A set of expectation which define the desired behavior of a design when it is subjected to certain conditions.

TDD

Test Driven Development.

Test

Something that checks if a design satisfies a specification.

Test bench

An allusion to a bench in an electronics laboratory, or so it seems.