|   JHDL Home Page   |   Configurable Computing Lab   |   User's Manual (TOC)   | Search

TBone -Universal Testbench (deprecated)

Deprecated in favor of DynamicTestBench
  1. Overview
    1. Purpose
    2. How it Works
    3. Preparing Your Circuit to Work with TBone
  2. Initialization
    1. Loading the Class
    2. Loading the Vector File
    3. Declaring Generic Parameters
    4. Specifying Build Options
  3. Simulation
    1. Clocking the Circuit
    2. Putting and Getting Values
    3. Holding and Releasing
    4. Targeting a Techmapper
    5. Netlisting
  4. Other Options
    1. Using the Graphical Interface
    2. List
    3. Listing Unspecified Parameters and Port Widths
    4. Closing Up


In order to use JAB or the JHDL circuit simulator it is necessary to write a testbench program. Though a relatively simple process, it becomes very tedious for small components and for quick testing of circuit designs. Also, because the testbench is a compiled java application, all test values are determined by the programmer at compile time. There is no way to dynamically change the inputs of the test circuit. TBone's purpose is to solve these problems.

How it Works

TBone is itself a testbench. In JAB, when you load a circuit that has no testbench wrapper JAB loads TBone which then loads the test circuit by reflection. Because TBone is a testbench, the circuits loaded into it can be seen with the schematic viewer. Inputs and outputs can be watched using the wire tracer. All TBone commands are loaded into the JAB command line interface, thus TBone runs with complete functionality inside JAB.

Preparing Your Circuit to Work with TBone

TBone extracts information about each circuit from its .class file. In order to correctly use this extracted information, TBone has been written with two important assumptions. First, the wires in the cell_interface must be written in the same order as the wires in the constructor. For example, if I have a cell interface like this:

   public static CellInterface[] cell_interface = {
      in ("wireA", 5), 
      in ("wireB",1), 
      out ("wireC", 4), 

I would need to have a constructor with the wires in exactly the same order:

   public MyCircuit (Wire wireA, Wire wireB, Wire wireC) { ... }

The second convention TBone uses is that it chooses the first constructor in the circuit .class file to build the circuit. Often, several constructors with varying parameters are included in the class file. Rather than forcing the user to specify which constructor to use with TBone, it simply requires the first constructor be prepared for TBone to use. When these two conditions are met:

  1. The order of parameters in the cell_interface matches the order of parameters in the constructor.
  2. The first constructor is prepared for TBone to use.

TBone can be used instead of writing a testbench class.


TBone has two different modes. First, there is an initialization process where TBone itself is loaded by JAB, and then a circuit is constructed and loaded within TBone. This first step can be thought of as an initialization process, where all generic circuit parameters are specified. This section covers this initialization process. The second mode is the simulation mode. It will be discussed in the next section.

Loading the Class

JAB allows you to load regular full-featured testbenches or to load any other circuit using TBone. When Jab's load command is invoked it detects whether the loaded class is a testbench. If it is not, Jab loads TBone automatically. To load a circuit to test, type the command load followed by the name of the class you would like to load on the command line. This begins the TBone initialization process. For example, if I wanted to load the booth multiplier supplied in the Logic.Modules package, I would type on the command line the following:

   load byucc.jhdl.Logic.Modules.booth

Loading the Vector File

TBone allows you to optionally load a vector file containing inputs and the outputs that they should produce. The vector file must end with the suffix ".vec". All values for each clock cycle must appear on the same line in the order they appear in the circuit's constructor. In-values are listed first, separated by any amount of space. These values are followed by a colon and then, optionally, a list of the out-values, also listed in the that they appear in the circuit's constructor. The out-values should be what you would expect after all values have propagated. This means that if you have a purely combinational design the output should contain the out-value after all inputs have propagated through the circuit. If there is no output value specified, the in-values are still placed on the in-wires but no verification is performed on the out-values. The format looks something like this:

   [in-value] [in-value] ... : [out-value] [out-value] ...

The colon between the two sections in and out, is very important. The order of the wires in the vector file must match that of the constructor. My booth multiplier has three input wires and two output wires. Namely, the inputs are in1, in2, and start, and the outputs are finished, and out.

My vector file might look like this:

   4 3 1 : 0 0
   4 3 0 : 0 0
   4 3 0 : 0 0
   4 3 0 : 1 12

On the first clock, 4 is put on in1, 3 on in2, and 1 on start, and the simulator should produce nothing on either output. We see that not until many cycles afterward do the outputs finally trickle out marked by the assertion of the finished wire. The format of the values are by default decimal, but can be in hex (started with 0x), binary (started with 0b) and octal (started with 0o). Vector files can be loaded after the initialization process.

To load a vector file, type "loadvector [filename]" on the command line of either the console or the circuit browser. Then, cycle the simulator and Tbone will put the values on the wires as indicated in the vector file and look for the expected outputs. If an output specified in the vector file does not match up to the output present in the circuit, it will be noted in the console.

Declaring Generic Parameters

Before TBone can be run, all of the generic parameters and port widths in the circuit's constructor must be specified. After the circuit has been loaded, TBone reports a list of the ports or parameters which need to be specified.

The port command defines the generic port widths. Its format is straightforward as follows: type the command port, followed by the port name, followed by the port width. Several port names can be defined after the same port command. Continuing the booth multiplier example, I could type:

   port in1 4
   port in2 4
   port out 8

or I could do all of these on one line, like this:

   port in1 4 in2 4 out 8

The param command works in an identical manner. The command param is followed by a TBone supplied name, followed by the value. TBone currently only recognizes integers, strings, and boolean parameters. The parameter name assigned by TBone is just the parameter type followed by its location in the constructor. For example if the first parameter of a circuit were an integer, the second a boolean, the third a string, the fourth a wire called in, and the fifth a wire called out, then I would need to call the following commands (in no particular order):

   port in 10
   port out 20
   param integer0 1
   param boolean1 false
   param string2 henry

or, I could do all on one line again like so:

   port in 10 out 20
   param integer0 1 boolean1 false string2 henry

If you try to step your circuit with undefined parameters, TBone will inform you of the names of the parameters you need to define.

Specifying Build Options

Another step of the initialization stage is defining the TBone build options. These are entered on the command line using the command option followed by a hyphen and the name of the option. If I decided I would like to netlist my booth multiplier, I would type on the command line:

   option -net

The other available options are as follows:

This will netlist your circuit under the specified techmapper.
The verify only option only prints outputs on cycles when the vector file output and the circuit's output don't match, or the behavioral and structural models do not produce matching outputs.
The out put command opens an output file and saves all simulation results. If any errors were found it indicates the row and wire where the errors occurred.
This options instantiates a behavioral model along with the structural model and compares their outputs.

All of these tasks except -net must be completed before the circuit is clocked. The only steps absolutely required are to load a class and to define its parameters. A vector file is not needed and all of the options are turned off by default.


This section describes the commands available for simulation.

Clocking the Circuit

Typing the commands step, and cycle followed by the number of steps or cycles will clock the circuit the given number of times. An added feature to clock is the clock all command. This command clocks the simulator the remaining number of lines in the vector file. If there is no vector file, the circuit cycles once.

Putting and Getting Values

One of the greatest benefits of TBone is the ability to supply values to the wires during simulation. Like port, put is followed by the port name and the desired value. If I would like to place a 4 on the first input of my multiplier I would type:

   put in1 4

The put command also takes many values on one line. If I wanted to put the same values on my wires as the vector file sample above, I could type:

   put in1 4 in2 3 start 1

The get command is similar to port and put but requires only the name of the wire you wish to sample. If I want to see the outputs of my circuit, I would type:

   get finished

Again, I can type as many wire names as I desire, like so:

   get finished out

The put command can only be used with in-ports, but get works with both in- and out-ports. The format of the put-values are by default decimal. Other formats include hex (started with 0x), binary (started with 0b) and octal (started with 0o).

Holding and Releasing

Often when stepping though a vector file it becomes very desirable to stop fetching values from the file and to use your own supplied values. TBone allows you to halt simulation using the hold command. Once TBone is held, the values placed on the wires remain constant until changed by the user using the put command. Of course, the outputs will continue to change on every clock cycle. Verification also is paused and TBone will no longer check for discrepancies between the vector file and the circuit's output. hold is automatically called with the put command so users need not worry about calling it explicitly. It must be remembered though that after the put command has been called, TBone must be released to continue using the vector file.

When you are ready to resume fetching values from the vector file, use the release command. This begins putting values from the vector file on the lines and also begins verifying output values. It should be noted that TBone begins immediately comparing outputs even though the new values might not have propagated all the way through the circuit. If the circuit has a long pipeline, several cycles of errors might be reported.

Targeting a Techmapper

TBone allows three techmappers to be targeted. By default, the VirtexTechMapper is selected. The Xilinx "XC4000" techmapper is also supported. To target the XC4000 techmapper type the command target followed by the name of the techmapper you wish to target, like so:

   target XC4000


   target Virtex

When this command is invoked before the circuit has been constructed it will set the techmapper with which your circuit will be built. After the circuit has been constructed the command will rebuild the circuit according to the newly specified techmapper. The target command can also accept two additional arguments to determine the inclusion or suppression of techmapping hints. By default, the techmapper will include techmapping hints (e.g. rloc and other properties). To explicity turn off techmapping hints, simply use the -t switch followed by f:

   target Virtex -t f


The netlist command will generate a netlist using the currently specified techmapper. Remember, the default techmapper is the Virtex techmapper. The netlist command can also take a netlist file name as an argument (with a -f swith). If no name is specified a name will be derived from the class name and the name of the current techmapper. For a circuit called mult, the default netlist file name for XC4000 is "mult_xc4.edn," and for Virtex, it would be named "mult_vtx.edn."

Additionally, the netlist command can also be used to tell the techmapper to insert pads into the design, so that the netlist can then be used as a top-level design. If pads are not inserted, and if the target technology requires such components in the netlist, the design can only be used as a subcomponent of some other design. The default for pad insertion is to not insert pads on the top-level ports.

Here is an example of explicitly giving the desired netlist name, and indicating that pads should be inserted into the circuit.

   netlist -f myWonderfulCircuit.edn -insertpads t

Other Options

Using the Graphical Interface

TBone provides several graphical dialogs to help in the initialization process. They provide a simple way to set the parameter values, choose options such as netlisting, and to declare a class and vector file to load. This option is very useful when the exact parameters of the circuit constructor is not known. To use the graphical user interface, type usegui on the command line. This will bring up the necessary dialog boxes. The GUI will also be displayed if the load command is followed by nothing. It should be noted that even if the GUI is used, all of the specifications can be changed as long as the circuit has not been built.


The TBone command list prints to the console the names of all of the in-ports and out-ports of the loaded circuit.

Listing Unspecified Parameters and Port Widths

To help remind the user of the unspecified parameters and port widths, TBone provides the listparams command. This command will display all of the unspecified parameters and port widths left in the constructor. This list will shrink as each parameter is defined. When no undefined parameters remain, the circuit will automatically build.

Closing Up

TBone has some tasks that are only performed on a close. Namely, the output file must be closed and a determination must be made on the successfulness of the simulation. These tasks are taken care of with the close command. Note that JAB will also quit when close is called. If you are not worried about these functions, do not worry about the close command.

|   JHDL Home Page   |   Configurable Computing Lab   |   Prev (Jab)   |   Next (Modgen)   |

JHDL 0.3.45