JHDL 0.2

| JHDL Doc Home Page | Getting Started Home Page | << | < | > | >>


Describing circuits in JHDL

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.

Circuits are objects

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.

Circuits have interfaces

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.

Circuits have logic

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.

Circuits are connected via wires

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."

Circuits can be parameterized

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.

Circuits can have placement hints

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.

Circuits can be simulated

In JHDL, the standard way to simulate a circuit is by using a testbench. A testbench is a Java class that constructs a circuit or circuits, puts values onto the input wires, and gets values off the output wires. Using a Java class as a testbench provides a great deal of flexibility in the way one can test a circuit constructed in JHDL. We have created an example of a basic testbench that can be made for our n-bit adder called NBitAdderTB.java. It creates an 8-bit adder and then passes random inputs into its two input wires.

Testbenches use the HWSystem class

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.

A testbench does not have ports

A testbench is different from a normal circuit because it does not have input or output ports. Instead, it has local wire objects that are connected to the circuit object(s) under test. In order to test our NBitAdder, first we must create the wires and other pertinent class variables as follows:
 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.

A testbench's constructor builds the desired circuitry

After declaring and creating all necessary class variables, the constructor is called with the parent as its only parameter as follows:
  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.

Testbenches must have a reset and clock method

Because all testbenches implement the TestBench interface, they must all have 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.

Testbenches can be executed in a GUI environment

An alternative to having to rely on command line print statements is JAB, a GUI environment for testing circuits that still requires a basic testbench, but will allow one to see the values on all the wires of the circuit. JAB is covered in the next section, JAB and the Simulation Environment.

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.