JHDL 0.2
| JHDL Doc Home Page | Getting Started Home Page | << | < | > | >>
In order to familiarize you with circuit descriptions in JHDL, this section will walk through the design of a parameterized n-bit adder, beginning with the full-adder building block. Each stage will describe an important aspect of circuit description in JHDL.
The first circuit we will describe is a full-adder named FullAdder.java. We will step through this file in detail, emphasizing important points.
JHDL is a Java(tm) based HDL, and so every circuit in JHDL is an object. Wires, logic gates, and other circuit building blocks are also objects. In order to be able to instantiate these JHDL building blocks, we must import their class files. The first lines in your circuit description should import the class files byucc.jhdl.base.* and byucc.jhdl.Logic.*. Our implementation is meant to run on a Xilinx 4K part, so we also import libraries describing Xilinx and Xilinx 4K specific structures.
import byucc.jhdl.base.*; import byucc.jhdl.Logic.*; import byucc.jhdl.Xilinx.*; import byucc.jhdl.Xilinx.XC4000.*;
With these class files available, we can now begin to describe our circuit. Our circuit is an object, so we begin with the line:
public class FullAdder extends Logic {
Note how FullAdder extends Logic. This is important so we can have access to methods that will build the gates in our circuit.
One other important point is necessary in this section. The first line of the constructor is:
super(parent);
This line must be the first line of each of your circuit constructors. It is required so JHDL knows who the hierarchical parent of your circuit is.
In the previous section, we skipped the interface lines in order to
talk about super(parent). Let's go back and look
at those lines.
public static CellInterface[] cell_interface = {
in("a", 1),
in("b", 1),
in("cin", 1),
out("sum", 1),
out("cout", 1)
};
Each circuit you build should have ports (unless you don't ever want
to use it). Ports are used to connect wires to the circuit block when it is instantiated. These ports are described in the CellInterface. The
static object cell_interface describes an array of these
ports. Each port must be described by a direction, a name, and a
width. The call for an input port is in(name,width).
For example:
in("a", 1)
describes an input port named "a" that is 1 bit wide. Output ports
are described with out(name,width).
The CellInterface describes the ports to the circuit, but in order to
connect wires to the ports, separate connect() calls must
be made in the circuit object constructor.
public FullAdder(Node parent, Wire a, Wire b, Wire cin, Wire sum, Wire cout) {
super(parent);
connect("a", a);
connect("b", b);
connect("cin", cin);
connect("sum", sum);
connect("cout", cout);
The above code is the beginning of the circuit constructor. Wires to
be connected to the ports are passed to the constructor, and a
connect() call hooks each wire to its corresponding port.
connect() takes as arguments the String used in the
CellInterface that is the name of the port and a wire passed to the
circuit constructor. All of our CellInterface names and Wire names match, but matching names are not required.
Most cells are useful only if they perform a logic function on the inputs and pass the result to the outputs. Once wires are connected to the ports of the cell, the only thing left is to describe the logical function of the cell. This is done in the next two lines of our constructor:
or_o( and(a,b), and(a,cin), and(b,cin), cout ); /* cout is output */ xor_o( a, b, cin, sum ); /* sum is output */
Our cell's logic is described with calls to Logic methods
and(), or_o(), and xor_o(). The
first line above performs an or on the outputs of three 2-input and
gates and returns the output to cout. The second line
performs an xor on three inputs and puts the result on the output wire sum.
The Logic class provides two types of methods to instantiate gates:
gate() and gate_o(). For instance, we use
and() calls inside the or_o() call.
gate_o() and gate() differ only that the output wire is
passed to gate_o(), whereas gate() returns a newly
created output wire. It is important that we use the _o methods to
connect logic to outputs. Otherwise our output wire pointer will be
replaced with a new wire created by the gate() method and no
logic will be connected to the output.
We've finished the implementation of our full-adder. But this circuit only takes some inputs and passes them through logic to the outputs. What if we want to wire several logic functions or cells together inside of a cell?
Enter the parameterized n-bit adder. This cell shows other important points of Logic, including wires and parameters.
The n-bit adder circuit description is called NBitAdder.java. Notice that this
cell also imports important classes, calls
super(parent) in its constructor, and defines an
interface. Differences include an extra line in the interface,
parameterized port sizes, a wire in the constructor, and cells we
created used in this cell instead of logic gates.
In order to connect cells or logic together within a cell, we must instantiate wire objects. Logic provides a method to create wires. It is called in our constructor with:
Wire carries = wire(width-1); // Here are the intermediate carry wires.
Notice that the wire() method is passed a width parameter. Wires can
be made any width in JHDL and their bits can be accessed
independently. Our wire is used to provide a carry path for our
adder, as shown below:
for (int i=0; i<width; i++) {
if (i==0)
new FullAdder(this, a.gw(i), b.gw(i), gnd(), sum.gw(i), carries.gw(0));
else if (i == (width-1))
new FullAdder(this, a.gw(i), b.gw(i), carries.gw(i-1), sum.gw(i), sum.gw(i+1));
else
new FullAdder(this, a.gw(i), b.gw(i), carries.gw(i-1), sum.gw(i), carries.gw(i));
}
This code snippet shows the generation of our n-bit adder using the
FullAdder cells we created earlier. Notice that we pass
this to the parent Node of FullAdder. this
is a pointer to the current object. The wires that are connected to
FullAdder ports are accessed using the Wire method
gw(bit). gw is short for
getWire. This method returns the 1-bit wire at the
position in the n-bit wire given by "bit."
The previous snippet also shows that our circuit is parameterized according to width. In order to parameterize wire widths, we must provide the parameter to the cell_interface:
param("width", INTEGER)
The param() call provides a parameter name and type to
the cell. Parameters are then bound to values in the cell constructor using:
bind("width", width);
The integer width was passed into our constructor. Because "width" describes the size of the a,b, and sum wires (as shown in the interface calls below),
in("a", "width"),
in("b", "width"),
out("sum", "width+1"),
all bind() calls must be made before any
connect() calls are made.
Notice that an algebraic expression is used to describe the size of
the sum wire.
JHDL includes a "tech-mapping" interface for describing the architecture mapping and placement. For example, calling
map(a, b, cin, sum); map(a, b, cin, cout);
in the FullAdder code tells JHDL to map both the sum and carry-out functions to "atomic FPGA units", i.e. a single LUT for the XC4000 architecture, a single ALU for the HP-Chess architecture, etc. Calling
place(sum, 0, 0); place(cout, 0, 1);
sets the relative placement of the resulting logic. In this case, we have constrained the carry-out logic to be vertically adjacent to the sum logic.
public static void main(String argv[]) {
HWSystem hw= new HWSystem();
NBitAdderTB tb = new NBitAdderTB(hw);
hw.cycle(20);
}
In order to simulate or run a JHDL circuit, that circuit must be
placed in a HWSystem. The main() function
shown above is used for command line simulation of our testbench
circuit. First we create a new HWSystem and then we
place the testbench inside the HWSystem by passing the
HWSystem pointer to the testbench constructor. The final
line in main() instructs the HWSystem to
step its clock 20 times.
private final static int width = 8; Wire a = wire(this, width); Wire b = wire(this, width); Wire sum = wire(this, width+1); Random rand; int count=0;
rand will be used to provide random inputs to our adder.
count will tell us the current cycle number of the simulation.
public NBitAdderTB(Node parent) {
super(parent);
new NBitAdder(this, a, b, sum, width);
rand = new Random();
}
Note that in the constructor we must first call
super(parent), as with any other JHDL circuit.
The constructor then instantiates the circuit we want to test
and anything else desired.
reset() and clock() methods. Both the reset and clock
methods put values on the input wires of the circuit we created in the
constructor. In simulation, it is required that every input wire
have a value put on it in every call to reset() or clock(). The reset
method (shown below) for our circuit simply puts 0's onto the a and b
input wires and resets the class variable count to 0.
public void reset() {
a.put(this, 0);
b.put(this, 0);
count=0;
}
The clock() method of our testbench is called on every clock cycle. The
clock method below simply puts two randomly generated integers onto
the two input wires a and b. It then prints out the cycle count and
the values on the wires a, b and sum before incrementing the class
variable count.
public void clock() {
a.put(this, rand.nextInt());
b.put(this, rand.nextInt());
System.out.println("\nCycle "+ count + ":"+
"\n\ta="+ a.get(this)+
"\tb="+ b.get(this)+
"\tsum="+ sum.get(this));
count++;
}
Note the use of the put and get methods from the
Wire class. The method call a.put(this,
1) simply puts the integer value 1 onto the Wire a.
Logically the method call a.get(this) will return
the current integer value on the wire a. An important constraint on
the put and get method is that they respectively take and return an
integer value, thus constraining their use to only wires that are not
greater than 32 bits. For more information on put and get methods
valid for wire widths greater than 32 see the Wires and Simulation :
General Concepts section
in the users manual.
As one can imagine, testbenches can range from very simple, as shown above, to very complex tests allowing one to exhaustively test a complicated circuit. We recommend using a script to generate simple testbenches quickly. Using a Perl script, we generated a simple example testbench called tb_FullAdder.java, to test our FullAdder circuit example from earlier in this section. Overall, testbenches can be powerful tools that allow a designer to extensively test a circuit by combining Java code with the JHDL environment.
| JHDL Doc Home Page | Getting Started 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.