Copyright 2006 Suraj N. Kurapati <SNK at GNA dot ORG>
Copyright 1999 Kazuhiro HIWADA <HIWADA at KUEE dot KYOTO-U dot AC dot JP>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• All copies and substantial portions of the Software (the "Derivatives") and their corresponding machine-readable source code (the "Code") must include the above copyright notice and this permission notice.

• Upon distribution, the Derivatives must be accompanied by either the Code or—provided that the Code is obtainable for no more than the cost of distribution plus a nominal fee—information on how to obtain the Code.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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

  # NOTE: these are all equivalent
  
  your_register.intVal = 2 ** 2048
  your_register.put_value 2 ** 2048
  

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

  your_module.all_net? { |your_net| your_net.z? }
  
  # or, alternatively:
  
  your_nets = your_module.net_a
  your_nets.all? { |net| net.z? }
  

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

  # NOTE: these are all equivalent
  
  puts your_register
  p :path  => your_register.fullName
  p :width => your_register.size
  p :file  => your_register.fileName
  p :line  => your_register.lineNo
  

• Access the first five elements in a memory:

  # NOTE: these are all equivalent
  
  your_memory.memoryWord_a.first(5)
  your_memory.memoryWord_a[0..4]
  your_memory.memoryWord_a[0...5]
  your_memory.memoryWord_a[0, 5]
  

• Clear a memory by filling it with zeroes:

  # NOTE: these are all equivalent
  
  your_memory.each_memoryWord { |w| w.f! }
  your_memory.each_memoryWord { |w| w.vpi0! }
  your_memory.each_memoryWord { |w| w.intVal = 0 }
  your_memory.each_memoryWord { |w| w.put_value 0 }
  

• From the second edition of The Verilog PLI Handbook:
  • C language bus-functional models
  • Reading test vector files
  • Delay calculation
  • Custom output displays
  • Co-simulation
  • Design debug utilities
  • Simulation analysis

• Adapted from Pin Hong’s observations:
  • Writing hardware models in Ruby
  • Dumping or processing netlist data from Verilog database
  • Dumping or processing simulation data
  • Feeding dynamic simulation stimuli
  • Back-annotating delay information
  • Interactive logic simulation
  • Building a distributed simulation

• ANVIL is a C++ interface to VPI.
• Teal is a C++ interface to VPI.
• JOVE is a Java 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.

Your system needs the following software to run Ruby-VPI.

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

Tip 1.  Tuning for maximum performance

You can tune your installation of Ruby-VPI for maximum performance by adding your C compiler’s optimization flag to the CFLAGS environment variable before you run the installation command (shown below). For example, if your C compiler is GCC, then you can set CFLAGS to -O9 for maximum optimization.

gem install ruby-vpi
ruby-vpi -v

1. Download the newest tar.gz release package from the project download area.
2. Extract the release package anywhere you want on your system.
3. Go inside the extracted directory and run the following commands:

rake build
ruby bin/ruby-vpi -v

If the installation was successful, then you will see output like this:

ruby-vpi 21.0.0 (2008-06-08) http://ruby-vpi.rubyforge.org /home/sun/src/ruby-vpi

Otherwise, you can ask for help in the project mailing list.

You can upgrade to the latest release of Ruby-VPI by running the following command:

gem update ruby-vpi

You can uninstall Ruby-VPI by running the following command:

gem uninstall ruby-vpi

Learn more about using RubyGems in the RubyGems user guide.

• If you installed Ruby-VPI manually, then you already know the location of its installation directory.
• If you installed Ruby-VPI using RubyGems, then run

  ruby-vpi -v

  and select the right-most item in the output—that is the path of Ruby-VPI’s installation directory.

• bin/ – contains executable programs (see Section 4.8: Tools).
• doc/ – contains user documentation in various formats.
• ref/ – contains reference API documentation in HTML format.
• examples/ – contains example Ruby-VPI tests (see Section 4.9.8: More examples).
• ext/ – contains source code, written in the C language, for the core of Ruby-VPI.
• lib/ – contains Ruby libraries provided by Ruby-VPI.

In Ruby-VPI, the process of functional verification is neatly packaged into self-contained, executable tests. As Figure 2: Organization of a test in Ruby-VPI illustrates, a test is composed of a bench, a design, and a specification.

Figure 2.  Organization of a test in Ruby-VPI

The design is an instantiated Verilog module. To extend the analogy of the electronics laboratory, it corresponds to the electronic component that is verified by an engineer.

The specification is a Ruby program. In the electronics laboratory analogy, it corresponds to the engineer who inspects, manipulates, and verifies the electronic component. In terms of specification-driven functional verification, it corresponds to the executable specification.

When you run a Ruby-VPI test, the following chain reaction occurs.

designHandle = vpi_handle_by_name("whatever", nil)
testFiles = Dir['path/to/files/*.whatever']

RubyVPI.load_test( designHandle, testFiles )

In a typical VPI application written in C, the Verilog simulator is in charge. Verilog code temporarily transfers control to C by invoking C functions, which return control to Verilog when they finish.

In contrast, Ruby-VPI puts the specification in charge. The specification temporarily transfers control to the Verilog simulator by invoking the advance_time method, which returns control to the specification after a given number of time steps. This process is illustrated in Figure 3: Interaction between Ruby and Verilog. You can also use the wait method, which is just an alias to the advance_time method, if you prefer.

Ruby-VPI’s approach is the same as any software testing framework, where the specification drives the design under test. In contrast, the VPI & C approach is literally backwards because the design under test drives the specification.

Figure 3.  Interaction between Ruby and Verilog

1. The current simulation time is X.
2. The specification invokes the advance_time method with parameter Y, which specifies the number of simulation time steps to be simulated.
3. The Verilog simulator is now in control (temporarily).
4. The current simulation time has not changed; it is still X.
5. The Verilog simulator simulates Y simulation time steps.
6. The current simulation time is now X + Y.
7. The Verilog simulator returns control back to the specification.

Ruby-VPI provides the entire IEEE Std 1364-2005 VPI interface to Ruby. This section will show you how to make use of it.

Note 1.  Constants are capitalized in Ruby

In the remainder of this guide, you may be surprised to see that VPI constants such as vpiIntVal are written with a captialized name, as VpiIntVal. The reason for this discrepancy is that in Ruby, the names of constants are capitalized.

However, keep in mind that Ruby-VPI provides all VPI constants in both (1) their original, uncapitalized form and (2) their capitalized Ruby form. You may use either version according to your preference; they are functionally equivalent.

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 )

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

value        = S_vpi_value.new
value.format = VpiIntVal

alarm        = S_cb_data.new
alarm.reason = CbValueChange
alarm.obj    = Counter.count
alarm.time   = time
alarm.value  = value
alarm.index  = 0

vpi_register_cb( alarm ) do |info|
  time  = info.time.integer
  count = info.value.value.integer
  puts "hello from callback! time=#{time} count=#{count}"
end

Ruby-VPI provides a concurrency model that allows you to run blocks of code in parallel. These blocks of code are known as concurrent processes and they are equivalent to the “initial”, “always” and “forever” blocks in Verilog.

Ruby-VPI’s concurrency model imposes two important constraints, which are inspired by GPGPU and fragment/vertex shader programming, in order to avoid race conditions and to make parallel programming simpler.

First, all processes execute in the same time step. That is, we only advance the entire simulation to the next time step when all processes are finished with the current time step. In this manner, we avoid race conditions where a process advances the entire simulation to a future time step but the other processes still think they are executing in the original time step (because they were not notified of the advancement).

Second, all processes see the same input (the state of the simulation database at the start of the current time step) while executing in a time step. That is, when a process modifies the simulation database, say, by changing the logic value of a register, the modification only takes effect at the end of the current time step. In this manner, we avoid race conditions where one process modifies the simulation midflight but some/all of other processes are unaware of that modification (because they were not notified of its occurence).

Note that these constraints are automatically enforced “under the hood”, so to speak, by Ruby-VPI. As a user, you need not do anything extra to implement or support these constraints; they are already taken care of.

Caution 1.  Assignments inside processes are non-blocking

As a result of the constraints described above, all assignments inside processes are treated like Verilog’s non-blocking assignments. Think about it: blocking assignments allow a process to make changes to simulation values (possibly) before other processes read those values. Since the second constraint makes all processes see the same input while they are executing, it is impossible to support blocking assignments inside processes.

always @(posedge clock1 and negedge clock2) begin
  foo <= foo + 1;
  bar  = bar + 5;
end

always do
  wait until clock.posedge? and clock2.negedge?

  foo.intVal += 1
  bar.intVal += 5 # this is a NON-blocking assignment!
end

always @(apple, banana, cherry, date) begin
  $display("Yum! Fruits are good for health!");
end

always do
  wait until apple.change? or banana.change? or cherry.change? or date.change?
  puts "Yum! Fruits are good for health!"
end

always do
  wait until [apple, banana, cherry, date].any? {|x| x.change?}
  puts "Yum! Fruits are good for health!"
end

Ruby-VPI enables you to rapidly prototype your designs in Ruby without having to do full-scale implementations in Verilog. This lets you explore and evaluate different design choices quickly.

The prototyping process is completely transparent: there is absolutely no difference, in the eyes of your executable specification, between a real Verilog design or its Ruby prototype. In addition, the prototyping process is completely standard-based: Ruby prototypes emulate the behavior of real Verilog designs using nothing more than the VPI itself.

For example, compare the Verilog design shown in Example 13: Implementation of a simple up-counter with synchronous reset with its Ruby prototype shown in figure Example 10: Ruby prototype of our Verilog design. The prototype uses only VPI to (1) detect changes in its inputs and (2) manipulate its outputs accordingly. In addition, notice how well the prototype’s syntax reflects the intended behavior of the Verilog design. This similarity facilitates rapid translation of a prototype from Ruby into Verilog later in the design process.

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

1. Enable the debugger by activating the DEBUGGER environment variable (see Section 4.7: 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.

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.

When you invoke a test runner without any arguments, it will show you a list of available tasks:

% rake -f your_test_runner.rake

(in /home/sun/src/ruby-vpi)
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 ncsim    # Simulate with Cadence NC-Sim.
rake setup    # User-defined task that is invoked before the simulator runs.
rake vcs      # Simulate with Synopsys VCS.
rake vsim     # Simulate with Mentor Modelsim.

rake DEBUGGER=1

DEBUGGER=1
export DEBUGGER
rake

setenv DEBUGGER 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

The ruby-vpi command serves as a front-end to the tools provided by Ruby-VPI. You can see its help information (reproduced below) by simply running the command without any arguments.

This is a front-end for tools provided by Ruby-VPI.

Usage:
  ruby-vpi                      Show this help message
  ruby-vpi -v                   Show version information
  ruby-vpi TOOL --help          Show help message for TOOL
  ruby-vpi TOOL arguments...    Run TOOL with some arguments

Tools:
  convert    Converts Verilog `defines, constants, ranges, etc. into Ruby syntax.
  generate   Generates test skeletons from Verilog 2001/1995 module declarations.

Simulators:
  cver       GPL Cver
  ivl        Icarus Verilog
  ncsim      Cadence NC-Sim
  vcs        Synopsys VCS
  vsim       Mentor Modelsim

4.8.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).

A Ruby-VPI test is composed of the following files:

• 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.
• loader.rb is a user-defined Ruby script which loads the test (see Section 4.1: Theory of operation).
• 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 6: Generating a test with specification in RSpec format 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 2.  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.

By producing multiple files, the automated test generator physically decouples the various parts of a test. As a result, when the interface of a Verilog module changes, you can simply regenerate the test to incorporate those changes without diverting your focus from the task at hand. Furthermore, the incorporation of changes can be catalyzed by interactive text merging tools, which allow you to selectively accept or reject the merging of changes into your source code. Fully automated text merging tools may also be used for this purpose.

You can try this tool by running the

ruby-vpi generate --help

command.

Tip 2.  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.

ruby-vpi convert --help

1. Declare a design 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.

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

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

$ 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

require 'spec'

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

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

describe "A #{DUT.name} after being reset" do
  setup do
    DUT.reset! # reset the counter
  end

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

  it "should increment upon each subsequent posedge" do
    LIMIT.times do |i|
      DUT.count.intVal.should == i
      DUT.cycle! # increment the counter
    end
  end
end

describe "A #{DUT.name} with the maximum value" do
  setup do
    DUT.reset! # reset the counter

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

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

require 'test/unit'

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

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

class A_counter_after_being_reset < Test::Unit::TestCase
  def setup
    DUT.reset! # reset the counter
  end

  def test_should_be_zero
    assert_equal( 0, DUT.count.intVal )
  end

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

class A_counter_with_the_maximum_value < Test::Unit::TestCase
  def setup
    DUT.reset! # reset the counter

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

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

if RubyVPI::USE_PROTOTYPE
  always do
    wait until DUT.clock.posedge?

    if DUT.reset.t?
      DUT.count.intVal = 0
    else
      DUT.count.intVal += 1
    end
  end
end

4.9.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 11: Running a test with specification in RSpec format and Example 12: Running a test with specification in xUnit format.

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 4.7.1: Environment variables for details). Also, the GPL Cver simulator denoted by cver, is used to run the simulation.

Example 11.  Running a test with specification in RSpec format

$ cd RSpec
$ rake cver PROTOTYPE=1

Ruby-VPI: prototype is enabled
...

Finished in 0.05106 seconds

3 examples, 0 failures
cd -

Example 12.  Running a test with specification in xUnit format

$ 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 3.  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.

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

$ 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

rake

Obtain the source code from the project Darcs repository:

darcs get http://ruby-vpi.rubyforge.org/src ruby-vpi

Go inside the obtained directory and run the following commands:

rake build
ruby bin/ruby-vpi -v

If the commands were successful, then you will see output like this:

ruby-vpi 21.0.0 (2008-06-08) http://ruby-vpi.rubyforge.org /home/sun/src/ruby-vpi

Otherwise, you can ask for help in the project mailing list.

After successfully building from source (see Section 5.1: Building from source code), set the RUBYLIB environment variable to the path where you checked out the source code plus the lib/ directory.

For example, if you checked out the source code into /home/foo/ruby-vpi/ then you would set the value of the RUBYLIB environment variable to /home/foo/ruby-vpi/lib/. Afterwards, any Ruby-VPI tests you run will use the checked-out source code directly.

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

• RedCloth
• CodeRay

Once you have satisfied these requirements, you can run the following command to build the release packages:

rake release

For more build options, see below:

$ rake -T
(in /home/sun/src/ruby-vpi)
rake build                 # Builds object files for all simulators.
rake build_cver            # Builds object files for GPL Cver.
rake build_ivl             # Builds object files for Icarus Verilog.
rake build_ncsim           # Builds object files for Cadence NC-Sim.
rake build_vcs             # Builds object files for Synopsys VCS.
rake build_vsim            # Builds object files for Mentor Modelsim.
rake clean                 # Remove any temporary products.
rake clobber               # Remove any generated file.
rake clobber_doc/api/ruby  # Remove rdoc products
rake clobber_package       # Remove package products
rake dist                  # Build release packages.
rake doc                   # Build the documentation.
rake doc/api/c             # Build API reference for C.
rake doc/api/ruby          # Build the doc/api/ruby HTML Files
rake gem                   # Build the gem file ruby-vpi-21.0.0.gem
rake gem_config_inst       # Configures the gem during installation.
rake package               # Build all the packages
rake redoc/api/ruby        # Force a rebuild of the RDOC files
rake ref                   # Build API reference.
rake repackage             # Force a rebuild of the package files
rake test                  # Ensure that examples work with $SIMULATOR
rake upload                # Upload to project website.

rake doc

The following sections describe problems that occur when Icarus Verilog is used with Ruby-VPI.

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

module TestFoo;
  reg clk_reg;
endmodule

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

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

The BDD framework for Ruby.

See the RSpec website and tutorial for more information.

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

See this introductory article for more information.

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.