JHDL 0.3.39
| JHDL Doc Home Page | User's Manual Home Page |
The most commonly seen Test Bench is TBone (deprecated), which is an adaptive Test Bench that provides a lot of interactive control to the circuit it is loaded around. TBone is what runs in JAB when you load any circuit that is not a TestBench itself. When a Test Bench other than TBone is used, all of TBone's built in interactive functionality is disabled, so using a TestBench in JAB (deprecated) may seem a little crippled at first. For a partial remedy, see the section below on the ProgrammaticTestBench Interface.
In many cases, it's easier and faster to use TBone by running the JAB browser directly on a circuit. However, sometimes it's preferable to have a TestBench for automated regression testing, complex scripting, or getting hooks into other non-JHDL code.
TestBench itself is simply a tag interface, and therefore does not contain any methods that must be implemented. However, for a TestBench to work properly, it must be coupled with a proper extending class. Using the TestBench interface directly is an advanced topic. For most uses, ProgrammaticTestBench, as described below, should be used instead.
A ProgrammaticTestBench, when coupled with the Logic class, provides a simple and powerful way to create Test Benches while avoiding many pitfalls. When a ProgrammaticTestBench is used, the additional feature of single stepping in JAB can be used, allowing the best of both scripting and interactivity when using TestBenches. The following section will illustrate, through example, the components of creating a basic ProgrammaticTestBench.
The file tb_NBitAdder.java is an example ProgrammaticTestBench for use with the NBitAdder.java circuit previously used as an example in this User's Manual. Some of the important parts of code are discussed below.
import byucc.jhdl.base.*;
import byucc.jhdl.Logic.*;
import byucc.jhdl.Xilinx.*;
import byucc.jhdl.Xilinx.Virtex.*;
public class tb_NBitAdder extends Logic implements ProgrammaticTestBench {
As usual, we need to include the base and Logic packages, as well as the libraries of whatever platform we are targeting. In this example (and the current default for JHDL) we use Virtex. To work correctly, a ProgrammaticTestBench must extend the Logic class, and implement the ProgrammaticTestBench interface.
private Cell design;
public static void main(String argv[]) {
tb_NBitAdder tb = new tb_NBitAdder(new HWSystem())
boolean netlist = false, cvt = false;
for ( int argi = 0; argi < argv.length; ++argi ) {
String arg = argv[argi];
if ( arg.equals("--netlist") && !cvt ) {
netlist = true;
} else if ( arg.equals("--cvt") && !netlist ) {
cvt = true;
} else {
System.err.println("USAGE: java tb_NBitAdder [--netlist|--cvt]");
return;
}
}
if ( netlist ) {
tb.getDefaultTechMapper().netlist(tb.design);
System.out.println("Netlisted NBitAdder, now exiting.");
return;
} else if ( cvt ) {
new cvt( tb );
return;
} else {
tb.execute();
}
}
JHDL Test Benches are usually run directly. The main method of the Test Bench controls its execution. In this case, we simply construct an instance of our tb_NBitAdder and, depending on a command-line switch, either netlist it, view it using the default CVT (Circuit Visualization Tool), or run it by calling its execute() method.
private Wire a, b, sum;
public tb_NBitAdder(Node parent) {
super(parent);
setDefaultTechMapper(new VirtexTechMapper(true));
final int adder_width = 63;
a = wire(adder_width, "a");
b = wire(adder_width, "b");
sum = wire(adder_width, "sum");
design = new NBitAdder(this, a, b, sum);
}
The constructor of a ProgrammaticTestBench looks much the same as a standard Logic cell. Note that a TestBench has no cell interface, does not make any connect() calls, and does not take any Wires through its constructor. Note that we set the default TechMapper as a VirtexTechMapper. If this call is not made, Virtex is the default target. This could be changed to XC4000, CSRC, or other libraries to enable targeting to those technologies. Also note that our Wires are defined as members of our class so that we can use get in the functions where they are required.
private long a_val, b_val, sum_val;
public void execute() {
The execute method is the heart of the ProgrammaticTestBench. We define some variables that will hold the values of our wires. These will be used in the execute() method. Wires themselves should never be directly used inside execute(). Instead, these value holder variables are updated, and the Wires will be updated during reset() and clock(), which will be described further along.
final long a_iterations = 10;
final long b_iterations = 500;
for (long i=0;i<a_iterations;i++) {
for (long j=0;j<b_iterations;j++) {
a_val = i;
b_val = j;
getSystem().cycle(1);
getValues();
long correct = a_val + b_val;
if (sum_val != correct) {
System.out.println("NBitAdder failed miserably!");
System.out.println("a = " + a_val);
System.out.println("b = " + b_val);
System.out.println("sum = " + sum_val);
System.out.println("correct = " + correct);
return;
}
}
}
System.out.println("NBitAdder passed with flying colors.");
}
Our execute() method for tb_NBitAdder is fairly simple. We decide a number of iterations to perform for both the a input and the b input. Then we put the values we want our wires to take into the variables we defined above, and call getSystem().cycle(1) to, in this case, cycle the simulator 1 clock cycle. If we wished, we could cycle any number of cycles before returning to examine the results. We then call getValues() to read all of our output Wires. If we desired, we could use these results to decide what inputs to give the next time around. Finally, we compare the result of the NBitAdder against what we get by adding a_val and b_val ourself. If the answer is ever incorrect, we print out an error message and quit.
public void reset() {
a.putL(this, 0);
b.putL(this, 0);
}
public void clock() {
a.putL(this, a_val);
b.putL(this, b_val);
}
public void getValues() {
sum_val = sum.getL(this);
}
}
In this final section of code, we define the reset(), clock(), and getValues() methods. These methods should not do anything but put and get values from Wires, and shouldn't try to be smart--that's what execute() is for.
As shown, reset() should put on all inputs the proper value that should happen whenever the simulator is reset(). The clock() method should be identical, except that it should put the values from the variables set in execute() that correspond to our input Wires. Finally, getValues() should read all output Wires and put their value into the proper variables for examination in the execute() method.
With this Test Bench in place, we can run in the following modes:
java tb_NBitAdder
java tb_NBitAdder --gui
java tb_NBitAdder --netlist
| JHDL Doc Home Page | User's Manual Home Page |
Copyright (c) 1998-2003 Brigham Young University. All rights
reserved.
Reproduction in whole or in part in any form or medium
without express permission of Brigham Young University is
prohibited.
Documentation Revision: $Date: 2003/04/24 14:15:12 $