JHDL 0.3.39

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


EdifParser

This is an introduction to using the EdifParser to bring in external designs into JHDL.

A 4-Bit Adder Example

To begin with, assume that you have an EDIF file out on disk which you know contains the following interface:
        (interface
          (port (array (rename a "a[3:0]") 4) (direction INPUT))
          (port (array (rename b "b[3:0]") 4) (direction INPUT))
          (port (array (rename q "q[3:0]") 4) (direction OUTPUT))
        )
That is, it contains a 4-bit input named "a", a 4-bit input named "b", and a 4-bit output named "q". Further, assume that the EDIF is for a Xilinx Virtex design.

Here is a JHDL design which will read in the EDIF and treat it like any other JHDL module:

import byucc.jhdl.base.*;
import byucc.jhdl.Logic.*;
import byucc.jhdl.Xilinx.*;
import byucc.jhdl.Xilinx.Virtex.*;
import byucc.jhdl.parsers.edif.*;

public class add_wrapper extends Logic {

  public static CellInterface[] cell_interface = {
    in( "a", 4),    in( "b", 4),    out( "q", 4),
  };

  Wire a, b, q;

  public add_wrapper(Node parent,
                     Wire a,    Wire b,    Wire q
    ) {

    super(parent);
    this.a = connect( "a", a);
    this.b = connect( "b", b);
    this.q = connect( "q", q);

    PortInterface[] portWires = {
     PortInterface.addPort("a", a),
     PortInterface.addPort("b", b),
     PortInterface.addPort("q", q),
    };

    Cell cel = EdifParser.parse(this, "add.edn", portWires, "Virtex");
  } // end constructor
} // end class
The only things of interest to note include the following:
  1. You must import the EDIF parsers package as shown on line 5 of the testbench code.
  2. You create a PortInterface array to feed into the parse routine. These will be wired up to the ports of the EDIF design. The parser contains checking to ensure you pass in the right number of ports and wires and that all the various wire and port widths match up.
  3. As the parser attempts to recognize cells in the EDIF file, it needs to know the technology library to look in. The 4th parameter (optional) in the parse() call is the technology. The default if no 4th parameter is provided is "Virtex". The only other string currently allowed is "XC4000".
That's it! This mechanism can be used anywhere in any JHDL design to import an EDIF design and treat it otherwise like a JHDL module.

OK, so maybe there is more...

Automatically Generating a JHDL Wrapper for an EDIF File

An easy way to create the wrapper module shown above for importing EDIF is to let the tools automagically generate one for you. Execute the following:
    java byucc.jhdl.parsers.edif.BuildWrapper add.edn
and it will parse "add.edn" and create the file "add_wrapper.java" shown below which you can use instead of writing your own wrapper by hand:
// Automatically generated EDIF wrapper...
import byucc.jhdl.base.*;
import byucc.jhdl.Logic.*;
import byucc.jhdl.Xilinx.*;
import byucc.jhdl.Xilinx.Virtex.*;
import byucc.jhdl.parsers.edif.*;

public class add_wrapper extends Logic {

  public static CellInterface[] cell_interface = {
    in( "a", 4),
    in( "b", 4),
    out( "q", 4),
  };

  Wire a;
  Wire b;
  Wire q;

  public add_wrapper(Node parent,
    Wire a,
    Wire b,
    Wire q
    ) {

    super(parent);
    this.a = connect( "a", a);
    this.b = connect( "b", b);
    this.q = connect( "q", q);

    // Changes to make below if there is a clock port called "clk" on the imported EDIF and you want
    //   to wire it to the default global clock:
    //       PortInterface.addPort("clk", getGlobalClock(getSystem()));

    // Alternatively, if your wrapper has a port called "clk" and you want
    //   to hook it to a clock driver of your own making:
    // Put these two lines in:
    //   Wire myclk = wire(1, "myclk");
    //   clockDriver("clk", "myclk", "01", "clockDriver");
    // Now, change the PortInterface.addPort() below to be:
    //       PortInterface.addPort("clk", myclk);

    PortInterface[] portWires = {
     PortInterface.addPort("a", a),
     PortInterface.addPort("b", b),
     PortInterface.addPort("q", q),
    };

    Cell cel = EdifParser.parse(this, "add.edn", portWires, "Virtex");


  } // end constructor

} // end class

Don't Forget the Clock Port!

JHDL designs can be done in a way that the clock is hidden - it is implied in every cell which needs it. If you want to parse in such a design that JHDL generated, make no mistake about it - the CLK port really is there (check the EDIF file). In this case, you must hook a wire to it.

In the following automatically generated wrapper, you will see that the tool saw that the EDIF had a clock port and so created a clock port on the wrapper's interface as well as created a PortInterface entry for it:

...
public class ramtest_wrapper extends Logic {

  public static CellInterface[] cell_interface = {
    in( "a", 4),
    in( "clk", 1),
    in( "d", 1),
    out( "q", 1),
    in( "we", 1),
  };

  ...

    // Changes to make below if there is a clock port called "clk" on the imported EDIF and you want
    //   to wire it to the default global clock:
    //       PortInterface.addPort("clk", getGlobalClock(getSystem()));

    // Alternatively, if your wrapper has a port called "clk" and you want
    //   to hook it to a clock driver of your own making:
    // Put these two lines in:
    //   Wire myclk = wire(1, "myclk");
    //   clockDriver("clk", "myclk", "01", "clockDriver");
    // Now, change the PortInterface.addPort() below to be:
    //       PortInterface.addPort("clk", myclk);

    PortInterface[] portWires = {
     PortInterface.addPort("a", a),
     PortInterface.addPort("clk", clk),
     PortInterface.addPort("d", d),
     PortInterface.addPort("q", q),
     PortInterface.addPort("we", we),
    };

    Cell cel = EdifParser.parse(this, "ramtest.edn", portWires, "Virtex");


  } // end constructor

} // end class
However, you will see that it also suggested how you might hook a clock to that port, depending on what you wanted to do. The first suggestion simply hooks the clock up to the global default clock. The second lets you insert a ClockDriver and specify the clock's waveform.

As an alternative to doing this in the wrapper, you could write a testbench to directly import the EDIF. Below is a complete testbench to load the EDIF for a CLB RAM test circuit and read all 16 locations. When executed in JAB, one can see the successive values of the memory coming out on the "q" port.

import byucc.jhdl.Logic.*;
import byucc.jhdl.Xilinx.*;
import byucc.jhdl.base.*;
import byucc.jhdl.Xilinx.Virtex.*;
import byucc.jhdl.parsers.edif.*;

public class tbe_ramtest extends Logic implements TestBench {
  public static void main(String argv[]) {
    HWSystem hw = new HWSystem();
    tbe_ramtest tb = new tbe_ramtest(hw);
    hw.cycle(iterations);
  }

  // Here are the addresses
  static final int[] a_data = {
    0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 0, 0, 0, 0, 0, 0,
  };

  Wire d;
  Wire we;
  Wire a;
  Wire q;

  public void reset() {
    count = 0;
    d.put(this, 0);
    we.put(this, 0);
    a.put(this, 0);
  }

  static final int iterations = 20;
  int count = 0;

  public void clock() {
    d.put(this, 0);
    we.put(this, 0);
    a.put(this, a_data[count%iterations]);
    count++;
  }

  public tbe_ramtest(Node parent) {
    super(parent);
    VirtexTechMapper tm = new VirtexTechMapper( true );
    Logic.setDefaultTechMapper( tm );
    d = Logic.wire(this, 1, "d");
    we = Logic.wire(this, 1, "we");
    a = Logic.wire(this, 4, "a");
    q = Logic.wire(this, 1, "q");

    PortInterface[] ports = {
      PortInterface.addPort("d", d),
      PortInterface.addPort("we", we),
      PortInterface.addPort("a", a),
      PortInterface.addPort("q", q),
      PortInterface.addPort("clk", getGlobalClock(getSystem())),
    };

    Cell my_ramtest = EdifParser.parse(this, "ramtest.edn", ports, "Virtex");
  }
}

Dealing With Designs With Pads

In general, you will want to import designs that have a top level interface and insert them into your JHDL design. However, the EDIF parser has the ability to deal with designs with pads.

Building Wrappers For Designs With Pads

The BuildWrapper mechanism described above will detect that no top-level ports exist on a design. In this case it will do the following: In common cases this will correctly remove the pad ring from the design. However, there are cases where it will fail. Specifically, if a clock signal goes through a CLKDLL and then into a BUFG, the output of the CLKDLL will be the input port. If the signal went through an IBUF before going into the CLKDLL, the output of the IBUF will also be n input port. Thus, there will be cases where you may want to modify the wrapper after it is generated. However, the goal is for this to get you close to the final design you want.

Actually Importing Designs With Pads

If you attempt to parse an EDIF file and construct the JHDL circuit for it and the EDIF file contains pads, the tool will attempt something similar to above. It will throw away all pads and try to create a top level interface based on the combination of buf's it sees. In this case, however, once it does this it will write out a new EDIF file without the pads, print a warning message that it has done so and suggest you import that EDIF file instead, and exit.

An Example of Importing a Circuit With Pads

Let's assume that the RAMTEST circuit shown above was created by some CAD tool but with pads. Let's assume it is in a file called "ramtest_pads.edn".
Step 1 - Build A Wrapper For It
By executing:
    java byucc.jhdl.parsers.edif.BuildWrapper ramtest_pads.edn
The file "ramtest_pads_wrapper.java" will be created. This design has a clock port on it. There will be a comment in "ramtest_pads_wrapper.java" showing how you might want to modify the design to add a clock driver to the circuit in case it was going to be your top-level design. You should read the comment to understand how to do that.
Step 2 - Import the JHDL
Compile and execute "ramtest_pads_wrapper.java":
    javac ramtest_pads_wrapper.java
    java jab ramtest_pads_wrapper
This will:
Step 3 - Modify the Wrapper and Import the JHDL Again
After modifying the wrapper file to parse this newly generated EDIF file, compile it and execute it:
    ... modify the wrapper ...
    javac ramtest_pads_wrapper.java
    java jab ramtest_pads_wrapper
NOTE: if you used an automatically-generated wrapper you will see that it has many 1-bit ports as in: "a_0_", "a_1_", etc. (this is what happens when pads are thrown away). However, the EDIF parser on import will always merge these into a wide port by looking at the indices. Thus, when you modify the wrapper you will want to replace all these by a single port and wire named "a". Otherwise, you will get an error.

Other Information

Wire Widths

The widths of the wires must match the widths in the EDIF file. The width of the ports from the EDIF netlist is determined by the bus reconstruction algorithm. To reconstruct the buses, the EdifParser looks at the names of the ports. Moving from the rear of the name, the parser looks for a number to indicate its position in the bus. For example, port in2 has a 2 at the end of the name. This port will be placed in a multi-width port called in with an index of 2. Any port that does not end in an integer will not be reconstructed and remain a single bit port. To prevent invalid ports from being created, the parser counts the number of ports placed in a multibit port. If this count does not match the index of the largest element of the port, each element is created as a single bit port. For example, an EDIF file has a declaration with the following interface. In addition the EDIF parser can reconstruct buses based on bus delimiters such as (, {, or [. The ports in[0] and in[1] will create a 2 bit port in.
  (interface
    (port in0 (direction INPUT))
    (port in1 (direction INPUT))
    (port in2 (direction INPUT))
    (port in3 (direction INPUT))
   (port out0 (direction OUTPUT))
    (port out3 (direction OUTPUT))
  )
the ports in0 - in3 will be reconstructed into a 4 bit port called in. The other 2 ports will attempt to reconstruct a 2 bit port out. However, since the number of ports is less than the greatest port index, the ports will remain single bit ports with their given names. The final reconstructed port interface for this EDIF section is shown in the following JHDL code.
  public static CellInterface[] cell_interface{
    in( "in", 4 );
    out( "out0", 1);
    out( "out3", 1);
  }

For Help

Please send comments to: [email protected]. 

| 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 per