1 Ruby-VPI user manual
This manual was last updated on Sat Jan 13 16:42:19 PST 2007.
It is meant to be read in conjunction with the reference documentation for Ruby-VPI. In addition, if you are new to the Ruby language, you are encouraged to explore its documentation alongside this manual.
You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the project forums.
Happy reading!
1.1 Terms
Copyright© 2006 Suraj N. Kurapati.
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.
The admonition and navigation graphics used in this manual are Copyright© 2005, 2006 Tango Desktop Project and are licensed under these terms.
2 Introduction
Ruby-VPI is a Ruby interface to IEEE 1364-2005 Verilog VPI. It lets you create complex Verilog test benches easily and wholly in Ruby.
2.1 Features
2.1.1 Portable
2.1.2 Agile
- Eliminates unneccesary work:
2.1.3 Powerful
2.1.4 Free
2.2 Applications
Here is a modest sampling of tasks that Ruby-VPI can be used to perform.
- 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
2.3 Appetizers
Here is a modest sampling of code to whet your appetite.
- Assign the value 22048 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 { simulate }
2.4 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.
- 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.
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.
3 Background
3.1 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.
3.2 Terminology
Note:
Have a look at the glossary for definitions of terms used in this manual.
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 poured through my textbook for a definition of the term, but it was to no avail. Instead, it nonchalantly employed the term throughout its 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, 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.
3.3 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 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.
Now, let us take a more detailed look at this organization, as illustrated in the figure named “Detailed organization of a test”.
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 use VPI.
3.4 Ruby/Verilog interaction
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 Vpi::advance_time method, which returns control to the specification when it finishes. This process is illustrated in the figure named “Interaction between Ruby and Verilog”.
Ruby-VPI’s approach is the same as any software testing framework, where the specification drives the design under test. Whereas, the typical VPI & C approach is literally backwards because the design under test drives the specification.
4 Setup
4.1 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.
4.2 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.
Tip: Add support for your Verilog simulator
Write a support request for your simulator, while providing a sample transcript of the commands you use to run a test with your simulator, and we will add support for your simulator in the next release!
- make
– any distribution 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.
4.3 Recommendations
The following software may make your interactions with Ruby-VPI more pleasant.
4.3.1 Text merging tool
An interactive text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the automated test generator. A handful of the currently available open-source text merging tools are listed below.
- 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.
4.4 Installation
Once you have satisfied the necessary requirements, you can install Ruby-VPI by running the
gem install -y ruby-vpi
command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the gem env gemdir
command. Within this directory, there is a gems/ subdirectory which contains the Ruby-VPI installation, as illustrated below.
$ 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/
4.4.1 Installing on Windows
- Install Cygwin, the Linux-like environment for Windows.
Note: Undefined symbols in 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 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.
- Search for object files whose names end with .so, .o, or .dll in your Verilog simulator’s installation directory.
- You may now install Ruby-VPI by running the
gem install ruby-vpi
command in Cygwin.
4.5 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.
5 Usage
5.1 VPI in Ruby
The entire IEEE Std 1364-2005 VPI interface is available in Ruby, but with one minor difference: the names of all VPI types, structures, and constants become capitalized because Ruby requires that the names of constants begin with a capital letter.
For example, the s_vpi_value structure becomes the S_vpi_value class in Ruby. Likewise, the vpiIntVal constant becomes the VpiIntVal constant in Ruby.
Note that this capitalization rule does not apply to VPI functions; their names remain unchanged in Ruby.
5.1.1 Handles
A handle is a reference to an object, such as a module, register, wire, and so on, inside the Verilog simulation. In short, handles allow you to inspect and manipulate the design under test and its components.
Handles have various properties, which provide different kinds of information (see the “Kind of value accessed” column in the table named “Possible accessors and their implications”) about the underlying Verilog object represented by a handle. These properties are accessed through various functions, which are listed in the “VPI functions used to access the value” column in the table named “Possible accessors and their implications”.
Handles are typically obtained through the vpi_handle_by_name and vpi_handle functions. These functions are hierarchical in nature, because they allow you to obtain new handles that are related to existing handles. For example, to obtain a handle to a register inside a module, you would typically write: some_reg = vpi_handle(VpiReg, some_handle).
Shortcuts for productivity
Given a handle, Ruby-VPI allows you to access (1) its relatives and (2) its properties by simply invoking its methods.
If a handle’s relative happens to have the same name as one of the handle’s properties, then the relative is given preference. However, if you really need to access a handle’s property in such a situation, then you can use the Vpi::Handle.get_value and Vpi::Handle.put_value methods.
5.1.1.1 Accessing a handle’s relatives
To access a handle’s relative (a handle related to it), simply invoke the relative’s name as a method on the handle.
For example, to access the reset signal of the counter module shown in the example named “Declaration of a simple up-counter with synchronous reset”, you would write the following:
counter_module = vpi_handle_by_name("counter", nil)
reset_signal = counter_module.reset # <== shortcut!
In this code, the shortcut is that you simply wrote counter_module.reset instead of having to write vpi_handle_by_name("reset", counter_module).
5.1.1.2 Accessing a handle’s properties
To access a handle’s properties, invoke the property name, using the following format, as a method on the handle. the example named “Examples of accessing a handle’s properties” shows how this naming format is used.
5.1.2 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. They are set up using the vpi_register_cb function and torn down using the vpi_remove_cb function.
5.2 Prototyping
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.
In order to create a prototype,
- Determine the interface (Verilog module declaration) of your design.
- Generate a test for that interface.
- Implement the prototype in the generated proto.rb file.
- Verify the prototype against its specification.
Once you are satisfied with your prototype, you can proceed to implement your design in Verilog. This process is often a simple translation your Ruby prototype into your Verilog. At the very least, your prototype serves as a reference while you are implementing your Verilog design.
Once your design has been implemented in Verilog, you can use the same specification, which was originally used to verify your prototype, to verify your Verilog design.
5.3 Debugging
The ruby-debug project serves as the interactive debugger for Ruby-VPI.
- Enable the debugger by activating the
DEBUG environment variable (see the section named “Test runner” for details).
- 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.
5.3.1 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:
- Deactivate the
DEBUG environment variable.
- Put your own code, which initializes the debugger, above the
RubyVpi.init_bench line in your generated spec.rb file.
5.4 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.
Tip: Running multiple tests at once.
Create a file named Rakefile containing the following line.
require 'ruby-vpi/runner_proxy'
Now you can invoke all test runners in the current directory simply by executing
rake cver
(where
cver denotes the
GPL Cver simulator).
5.4.1 Environment variables
Test runners support the following environment variables, which allow you to easily change the behavior of the test runner.
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
is equivalent to
$ DEBUG=1
$ export DEBUG
$ rake
in Bourne shell or
% setenv DEBUG 1
% rake
in C shell.
5.5 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
command to get started.
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.
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.
Tip: Using kdiff3 with the automated test generator.
- Create a file named merge2 with the following content:
#!/bin/sh
# args: old file, new file
kdiff3 --auto --output "$2" "$@"
- Make the file executable by running the
chmod +x merge2
command.
- Place the file somewhere accessible by your
PATH environment variable.
- 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.
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
command.
By converting Verilog header files into Ruby, your test can utilize the same `define constants that are used in the Verilog design.
5.7 Tutorial
- Declare the design, which is a Verilog module, using Verilog 2001 syntax.
- Generate a test for the design using the automated test generator tool.
- Identify your expectations for the design and implement them in the specification.
- (Optional) Implement the prototype of the design in Ruby.
- (Optional) Verify the prototype against the specification.
- Implement the design in Verilog once the prototype has been verified.
- Verify the design against the specification.
5.7.1 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.
5.7.2 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.
Each format represents a different software development methodology:
- rSpec represents BDD
- xUnit represents TDD
- our own format can represent another methodology
Note:
Both rSpec and xUnit formats 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. This process is illustrated by the example named “Generating a test with specification in rSpec format” and the example named “Generating a test with specification in xUnit format”.
5.7.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. That is, how do we expect the design to behave under certain conditions?
Here are some reasonable expectations for our simple counter:
- 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”.
Important: Before we continue…
- Replace the contents of the file named counter_rspec_spec.rb with the source code shown in the example named “Specification implemented in rSpec format”.
- Replace the contents of the file named counter_xunit_spec.rb with the source code shown in the example named “Specification implemented in xUnit format”.
- Replace the contents of the files named counter_rspec_design.rb and counter_xunit_design.rb with the following code.
# This is a Ruby interface to the design under test.
# This method resets the design under test.
def Counter.reset!
reset.intVal = 1
simulate
reset.intVal = 0
end
5.7.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 the example named “Ruby prototype of our Verilog design”.
5.7.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 the example named “Running a test with specification in rSpec format” and the example named “Running a test with specification in xUnit format”.
In these examples, 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 GPL Cver simulator, denoted by cver, is used to run the simulation.
Tip: 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.7.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 the example named “Implementation of a simple up-counter with synchronous reset”.
5.7.7 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.
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.
6 Hacking
6.1 Building release packages
In addition to the normal requirements, you need the following software to build release packages:
Once you have satisfied these requirements, you can run
rake release
to build the release packages. Also, see the output of rake -T
for more build options.
7 Known problems
This chapter presents known problems and possible solutions. In addition, previously solved problems have been retained for historical reference.
7.1 Ruby
7.1.1 SystemStackError
Note: Fixed in 2.0.0.
This problem was fixed in release 2.0.0 (2006-04-17).
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
command before starting the simulation.
7.1.2 test/unit
Note: Fixed in 2.0.0.
This problem was fixed in release 2.0.0 (2006-04-17).
If your specification employs Ruby’s unit testing framework, then you will encounter an error saying “[BUG] cross-thread violation on rb_gc()”.
7.2 Icarus Verilog
7.2.1 Vpi::vpi_handle_by_name
7.2.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 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.
7.2.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 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.
7.2.2 Vpi::reset
Caution:
The vpi_control method was removed in release 3.0.0 (2006-04-23). Please use Vpi::vpi_control(VpiReset) instead.
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.
7.3 Mentor Modelsim
7.3.1 ruby_run();
Note: Fixed in 2.0.0.
This problem was fixed in release 2.0.0 (2006-04-17).
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.
8 Glossary
8.1 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.
8.2 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.
8.3 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?
8.4 Expectation
The desired response to some stimulus.
8.5 Handle
A reference to an object inside the Verilog simulation that was obtained through the vpi_handle_by_name function.
8.6 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
8.7 rSpec
The BDD framework for Ruby.
See the rSpec website and tutorial for more information.
8.8 Specification
A set of expectations which define the desired behavior of a design when it is subjected to certain stimulus.
8.9 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.
9.0 Test
Something that checks if a design satisfies a specification.
9.1 Test bench
An allusion to a bench in an electronics laboratory, or so it seems.
