| JHDL Doc Home Page | User's
Manual Home Page |
The browser 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 to 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 schematic viewer currently does not route between two inout ports. This is because the schematic viewer does not know how to treat a port that can act as both and an output. This is a known and documented bug and should be dealt with accordingly. The inout simmulate correctly, but will be unconnected in the schematic viewer.
The following is a simple overview of the commands available in the system.
Exit Jab.
Jab will load the entered class into the browser. Keyed on < return >
The step command will cycle the system 1 time.
The cycle command prompts for a count and steps the specified number of cycles.
Reset the system to its initial state.
Selects between different types of waveform viewers. Default is Waves mode where wire values appear as high and low lines. The Table form places each wire value in a table or spreadsheet like form.
This option selects whether or not cells with a property marking them as invisible can be seen in the tree view.
Selects whether or not wires created in a parent cell will be visible in that cell
Enable behavioral modeling on the selected cell ( cell selected in tree view )
Disable behavioral modeling on the selected cell ( cell selected in tree view )
Start the wave viewer on selected wire
View schematic of selected cell
View layout of selected cell (valid only for XC4000 netlisted circuits)
View contents of selected cell ( cell must implement BrowserMemory interface )
Invoke reflection viewer on selected cell
Invoke reflection viewer on selected wire
Invoke reflection viewer on selected port
Removes the selected wire from the waves viewer.
Shows cells that do not effect output and would be optimized away. The schematic viewer draws all these cells in the top left corner.
When selected this changes the cell names to include the cell properties so you can see the properties on the cell in the info box.
When selected this changes the wires on the ports names to include the wire properties so you can see the properties on the port wires in the info box.
Enlarges the circuit.
Shrinks the circuit.
Changes the size of the circuit to fit into the circuit view window.
Adds the selected wire(s) to the waves viewer.
Removes the selected wire(s) from the waves viewer.
Creates a histogram view of your memory unit.
Creates command aliases.
Changes font size to the specified size if entered and tells you the current font size.
Displays a list of commands if no command is specified, or if a command is specified it tells you how to use it.
Prints up the history of the comamnds you have used.
Creates a log file of all successful commands. This can be run latter using the source command.
Rehashes the class path for calss name completions.
Executes a log file that is basically a script file with recognized CLI commands.
Removes command aliases.
Sets the behavioral modeling on or off on the given cell
Change console working directory (level of cell hierarchy) to < cell name >
Cycle the system < cycles > times
Write the specified ram contents to the specified file.
Exit the system.
Load the specified class into Jab. If the class is not a testbench, Tbone will be loaded which will then load the specified class.
Load the specified module into JAB
View information on the current cell
Invoke reflection tool on provided object
Display the current hierarchical level.
Read state from file saved after < cycles > clock cycles.
Assert the simulator's reset
Sets the wave type for a wire
steps the system < steps > times
Switches between wave and table modes in the waveform viewer.
Removes the schematic viewer for < cell name >
Stop watching < wire name > in waveform viewer
Records of the behavioral children are reported with cellInfo when this field is true
Returns the currently used version of JHDL.
View schematic of < cell name >
View the layout of < cell name >. This currently only works for XC4000 archetecture.
View contents of selected ram cell < cell name >
Watch < wire name > in waveform viewer
When true, this option will bring up each tool in its own view. When false the tool windows will appear as panels in the original Browser window
Write the state to a file. It will be unique to the current cycle count
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.
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. Firts,
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 requres 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 touse
Tbone can be used instead of writing a test bench class.
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 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 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 at any time, not just during the initialization 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
to be specified.
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. 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 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.
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 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
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 automatically assigns 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 guidelines
specifed in the target command.
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 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 be automaticly 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.
last updated, April 11, 2000 by Preston Jackson.
| 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: 19 Mar, 2001