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.
  • Compile once (during installation) and use forever!

• 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 infinitum

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

Applications

Here is a modest sampling of tasks, paraphrased from Pin Hong, that Ruby-VPI can be used to perform.

• Writing hardware models in Ruby
• Dumping/processing netlist data from Verilog database
• Dumping/processing simulation data
• Feeding dynamic simulation stimuli
• Back-annotating delay information
• Interactive logic simulation
• Building a distributed simulation

Appetizers

Here is a modest sampling of code 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. However, being an agile language, Ruby makes it very easy to use agile development practies such as TDD and BDD.

Terminology

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, rushing 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

To extend the analogy of an electronics laboratory, the bench acts as the laboratory bench which provides measurement and manipulation tools. The design acts as the electronic component being verified by the engineer. And the specification acts as the engineer who measures, manipulates, and verifies the electronic component.

Interface to VPI

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 (see the figure named “Detailed organization of a test”) 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 that module would be handles to that module’s 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 handles when a test is run. In particular, they take turns manipulating the Verilog 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. This process is illustrated by the figure named “Initialization of a test”.

Execution

After a test is initialized, it is executed such that the design is verified against the specification. This process is illustrated by the figure named “Execution of a test”.

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 “Sample tests” 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 is mostly acceptable—you will not be able to access child handles through method calls. The reason for this limitation is explained in the section named “Give full paths to Verilog objects”.
  • 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 -y 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.

• 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.

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

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

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

$ 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. This process is illustrated by the example named “Specification implemented in rSpec format” and the example named “Specification implemented in xUnit format”.

# 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 == 0
  end

  specify "should increment by one count upon each rising clock edge" do
    LIMIT.times do |i|
      Counter.count.intVal.should == 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 == MAX
  end

  specify "should overflow upon increment" do
    relay_verilog # increment the counter
    Counter.count.intVal.should == 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 result of this proceess is illustrated by the example named “Ruby prototype of our Verilog 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. This process is illustrated by the example named “Running a test with specification in rSpec format” and the example named “Running a test with specification in xUnit format”.

$ 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 result of this process is illustrated by the example named “Implementation of a simple up-counter with synchronous reset”.

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

$ 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

Test runner

A test runner is a file, generated by the automated test generator, whose name ends with .rake. It helps you run generated tests—you can think of it as a makefile if you are familiar with C programming in a UNIX environment.

$ rake -f some_test_runner.rake

(in /home/sun/src/ruby-vpi/doc)
rake clean    # Remove any temporary products.
rake clobber  # Remove any generated file.
rake cver     # Simulate with GPL Cver.
rake default  # Show a list of available tasks.
rake ivl      # Simulate with Icarus Verilog.
rake vcs      # Simulate with Synopsys VCS.
rake vsim     # Simulate with Mentor Modelsim.

rake cver

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.
• DEBUG enables the interactive debugger in its post-mortem debugging mode.
• PROTOTYPE enables the Ruby prototype for the design under test.

To activate these variables, simply assign a non-empty value to them. For example, DEBUG=1 and DEBUG=yes and DEBUG=foo_bar_baz all activate the DEBUG variable.

To deactivate these variables, simply assign an empty value to them, unset them in your shell, or do not specify them as command-line arguments to rake. For example, both DEBUG= dectivates the DEBUG variable.

In addition, you can specify variable assignments as arguments to the rake command. For example,

rake DEBUG=1

$ DEBUG=1
$ export DEBUG
$ rake

% setenv DEBUG 1
% rake

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

rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1

rake -f some_test_runner.rake COVERAGE=1

Interactive debugger

The ruby-debug project serves as the interactive debugger for Ruby-VPI.

1. Enable the debugger by activating the DEBUG environment variable (see the section named “Test runner” for details).
2. Put the debugger command in your code—anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish.

Advanced initialization

By default, Ruby-VPI enables the debugger by invoking the Debugger.start method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an IDE (see the ruby-debug documentation for details), then:

1. Deactivate the DEBUG environment variable.
2. Put your own code, which initializes the debugger, above the RubyVpi.init_bench line in your generated spec.rb file.

Sample tests

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

rake

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

ulimit -s unlimited

test/unit

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 always returns nil when its second parameter is specified.

For example, consider the example named “Part of a bench which instantiates a Verilog design”. 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

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();

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.

Behavior driven development (BDD)

An agile software development methodology which emphasizes thinking in terms of behavior when designing, implementing, and verifying software.

See the official wiki for more information.

Design

A Verilog module 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

A reference to an object inside the Verilog simulation that was obtained through the vpi_handle_by_name function.

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

rSpec

The BDD framework for Ruby.

See the rSpec website and tutorial for more information.

Specification

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

Test driven development (TDD)

An agile software development methodology which emphasizes (1) testing functionality before implementing it and (2) refactoring.

See this introductory article for more information.

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.