JHDL 0.2

| JHDL Doc Home Page | User's Manual Home Page | << | < | > | >>


Browser User's Manual

The debugger can be controlled via text command entry in the Console as well as through the main tree view. Each command available in the Console corresponds an action which can be performed though the GUI in the tree view. Each command whether entered via the Console or the GUI will be added to a command history which can be viewed in the Console or saved as a file.

The following is a simple overview of the commands available in the system.


Available GUI Commands

File Menu

  Save executed commands to a specified file
  Exit Jab.  Automatically saves command log file to command.log

View Menu

Selects between different types of waveform viewers
  Selects whether or not child cells of behaviorally modeled cells will
  show up in the tree view
  Selected whether or not wires created in a parent cell will
  be visible in that cell

Tools Menu

  Enable behavioral modeling on the selected cell ( cell selected in tree view )
  Disable behavioral modeling on the selected cell ( cell selected in tree view )
  View schematic of selected cell
  View layout of selected cell (currently not implemented)
  Trace selected wire
  Invoke reflection viewer on selected cell
  Invoke reflection viewer on selected wire
  Invoke reflection viewer on selected port
  View contents of selected cell ( cell must implement BrowserMemory interface )
  Jab will load the entered class into the browser.  Keyed on < return >
  Pressing the step button will cycle the system 1 time.  Also, a value
  can be entered into the field, on < return > the system will be cycled
  the specified number of times.

Available Console Commands

  Sets the behavioral modeling on or off on the given cell
  Change console working directory (level of cell hierarchy) to < cell name >
  Exit the system.
  Print a listing of available commands to the console,
  if a command is specified, help specific to the command
  will be provided
  If a hardware module is loaded, help on that module will
  be printed to the console.
  View a listing of commands performed
  Invoke reflection tool on provided object
  Load the specified class into Jab
  View information on the current cell
  Assert the simulator's reset
  Cycle the system < cycles > times
  Execute the script file < file name >
  Save the current command history to < file name >
  Stop watching < wire name > in waveform viewer
  Watch < wire name > in waveform viewer
  View schematic of < cell name >
  View contents of selected ram cell < cell name >

Tbone - Universal Testbench

Tutorial and Users Guide for a Dynamic Testbench

Purpose:
    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 previously determined by the programmer. There is no way to dynamically test circuits. Tbone's purpose is to solve these problems.

How it Works:
    Tbone is itself a testbench. Like other testbenches, it runs as a stand alone application and within JAB. When run by itself, Tbone brings up a command line interface and allows the user to enter commands. If loaded into JAB, Tbone uses the console window and JAB's command line in place of its own. The benefits of using Tbone as a stand alone application are only its reduced start up time. However, there are several benefits of running Tbone through JAB. 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. The rest of this tutorial assumes that Tbone has been loaded into JAB.


Initialization

Tbone two different modes. First, there is an intilization process where Tbone itself is loaded by JAB, and then, within Tbone, a circuit is constructed and loaded into Jab. This first step can be thought of as an intilization process, where all generic parameters are specified and then a simulation process. This section covers the initilization 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 and to load any other circuit using Tbone. When Jab's load command is invoked it detects if the loaded class is a testbench. If it is not, Jab loads Tbone automatically. To load a circuit to test, type the command loadclass 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 modgen package, I would type on the command line the following:

    load byucc.jhdl.modgen.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-values are listed first, separated by any amount of space. These values are followed by a colon and then a list of the out-values that you would expect after all values have propigated. This means that if you have a purely combinational design the output should contain the out-value after all inputs have propigated through the circuit. 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, 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 at any time, not just during the initilization process.

Declaring generic parameters:
Before Tbone can be run, all of the generic parameters and port widths in the circuit's constructor must be specified. Tbone informs you after the circuit has been loaded which of the ports or parameters need specification. Using the port command defines the generic port widths. Its format is straightforward as follows: the command name (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. Right now Tbone 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. 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 clock your circuit with undefined parameters, Tbone will inform you of the names of the parameters you need to define.

Tbone 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:

    -net   This will netlist your circuit under the specified techmapper.
    -vo    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.
    -out   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 occured.
    -behav 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.


Simulation


This section will describe the commands available for simulation.

Clocking the circuit:
Typing the command clock (or using the JAB command step) followed by the number of cycles will cycle 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 and 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 as long as you like 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 is held.

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 GenericTechMapper is selected. While the GenericTechMapper is targeted, no netlisting will take place. The Xilinx "XC4000" techmapper is supported as is the Xilinx "Virtex" techmapper. To target one of the second two techmappers type the command target followed by the name of the techmapper you wish to target, like so:

    target XC4000   or  target Virtex

When this command is invoked before the circuit has been constructed it will set the techmapper and will netlist the circuit when it is built. After the circuit has been constructed the command will rebuild and netlist the circuit according to the newly specified techmapper. The target command can accept a third argument, a name for the netlist file. This is specified after the name of the techmapper. For example, if I wanted to techmap my circuit with the Virtex techmapper and call the netlist file "myWonderfulCircuit.edn" I would enter the following command:

    target Virtex myWonderfulCircuit.edn

If no name is specified Tbone automaticly assignes one derived from the class name and an the name of the 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".

Netlisting:
The netlist command will generate a netlist using the currently specified techmapper. If the GenericTechMapper is specified, no netlist will be generated. A techmapper must first be targeted with the target command. Like the target command, netlist takes a netlist file as an argument. If no name is specified a name will be generated according to the guildlines specifed in the target command.


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 graphcial user interface, type usegui on the command line. This will bring up the necessary dialog boxes. The GUI will also be dislplayed if the loadclass 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.

List:
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 uspecified parameters and port widths left in the constructor. This list will shrink as each parameter is defined. When no undefined parameters remain, the circuit can be built.

Closing up:
Tbone has some tasks that are only performed only on 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.


Plea for Feedback
The only way Tbone will make users happy is if they tell me what they like or don't like. Tell me if you would like to see any changes.

last updated, November 2, 1999 by Preston Jackson.


| JHDL Doc Home Page | User's Manual Home Page | << | < | > | >>

Copyright (c) 1998-1999 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.