JHDL Module Generator Standards

This document's purpose is to set forth guidelines and standards that should be followed when writing a module generator for JHDL. These standards will help ease the task of maintaining the current library of module generators (the byucc.jhdl.modgen package) and serve as a tutorial to anyone new to the JHDL module generator scene. Thus this document will contain some very basic explanation to help those starting out as well as discussion and standards on how to implement the things that are common to most module generators. As with any standard, there will be exceptions to the rule because of different circumstances from what the standard was designed for, but module generator designers should do there best to follow every applicable standard to make it easier for those who come after. The following is an overview of the topics covered in this document:

• Module Generator Basics
  • What is a Module Generator?
  • Generic width input/output wires
  • Other Configuration Parameters
  • Valid Parameter Verification
  • Unique Cell Interfaces
  • Multiple Contructors
  • Implementation Independence
  • Readable Code
• Placement
• Behavioral Modeling
• Automatic Test Benches
• Documentation
  • Implementing a Custom Symbol
• Adding Your Module to the byucc.jhdl.modgen package
  • modgen Package Naming Conventions

Module Generator Basics

    public class NBitAdder extends Logic {
      public static CellInterface[] cell_interface = {
        in("a", "width"),
        in("b", "width"),
        out("sum", "width+1"),
        param("width", INTEGER)
      };
  
      public NBitAdder(Node parent, Wire a, Wire b, Wire sum, 
                       int width, String name) {
        super(parent, name);
        bind("width", width);
        connect("a", a);
        connect("b", b);
        connect("sum", sum);
        . . . 
        . . .
        . . .
      }
    }
    

     public NBitAdder(Node parent, Wire a, Wire b, Wire sum, 
                      String name) {
        super(parent, name);
        int width = a.getWidth();
        bind("width", width);
        connect("a", a);
        connect("b", b);
        connect("sum", sum);
        . . . 
        . . .
        . . .
      }
    

    //exception used for invalid parameters into constructor
    private class arrayMultException extends ModgenException  {
      protected arrayMultException(String gripe)  {
        super(gripe);     }   }
    

     if (width<3||height<3){
       throw new arrayMultException
         ("Width of input wires x and y must be 3 bits or greater."); }
    

1. ALL variables that are used to decide the structure of the module MUST be bound in the JHDL CellInterface.
2. All cells that a module calls must also return true on the aforementioned method.

For convenience multiple constructors can be used to help mantain backwards compatibility and to allow different configurations of a module generator. One must be VERY careful with multiple constructors when returning true for the method cellInterfaceDeterminesUniqueNetlistStructure() because making sure that every parameter is bound correctly can be tricky.

One other issue regarding multiple constructors: each module generator should have the ability for the user to specify or not specify an instance name. This should be accomplished with two constructors for each configuration as in the following example showing the use of two constructors for the arrayMult module generator:

  
  public arrayMult(Node parent, Wire x, Wire y, Wire clk_en, 
                    boolean signed, int pipedepth, Wire pout) {
    this(parent, x, y, clk_en, signed, pipedepth, pout, null);
  }

  public arrayMult(Node parent, Wire x, Wire y, Wire clk_en, 
                   boolean signed, int pipedepth, Wire pout, 
		   String instanceName) {
    super(parent, instanceName);
    ...(connect ports, do error checking and build circuit)

    

      TechMapper defaultTechMapper = Logic.getDefaultTechMapper();
      if (defaultTechMapper instanceof VirtexTechMapper) {
        set flags here so that a Virtex optimized module is built
      }
      else if (defaultTechMapper instanceof XC4000TechMapper) {      
        set flags here so that a XC4000 optimized module is built
      }
      else {
        set flags so a generic Logic module is built
      }
      

Placement

A good general rule is to make your design as square as possible so that it can easily be placed with other circuits by the end user. Remember that the origin will be translated to the upper left-hand corner of the bounding box of cell automatically.

Behavioral Modeling

• Make your default simulation model behavioral.
• Depending on the parameters that are passed into your module, your module could be purely synchronous or purely combinational. Therefore you should make sure that if your circuit is purely synchronous that you disable the propagate method and if your circuit is purely combinational that you disable the clock method, both of which should be done in your constructor.
• Make sure that no matter your configuration that you only do one put per clock cycle on any given output wire.
• Make sure that you clear out any arrays or variables that you use to model circuit timing in your reset method. Note that the reset method with NOT be called if the clock method is disabled and therefore any initialization essential to both synchronous and asychrounous behavior shouldn't be put in the reset method.
• If applicable, the compute method should return, at the very least, a long integer (so it can model an output wire of at most 64 bits). If there are multiple outputs you should make a unified compute method that returns an array of longs with the values of all the output signals. Have this unified compute method then call other compute methods for the inidividual signals. To be completely generic you should code your behavioral model using the byucc.jhdl.base.BV class which will allows operations on wires of widths of any size.
• Realize the presense of the implied register that is inherant to the clock method. To illustrate the implied register idea notice the following behavioral code:

  public void clock() { out.put(this, in.get(this)); }
  public void propagate() { out.put(this, in.get(this)); }
  	

  In the code above, the clock method will behave like a register while the propagate method will behave like a buffer. This implied register is important to remember when you model pipelining structure because there is one less register that you need to model with an array.

Automatic Test Benches

• Make sure that all possible configurations are tested in a comprehensive run by using a loop in the main method and instantiating a new hardware system and constructing a new module every iteration in the loop in the main method. Since a comprehensive test of all configurations can take a long time (in some cases many hours), the testbench should also have a mode that builds random or pre-defined configurations and passes random or pre-defined inputs into the module.
• On each test iteration instantiate both a behavioral and structural module and then compare the results to each other and to an internal testbench calculation.
• Have a public static boolean variable named testOK which returns true if all tests on the module are successful and false if any one of the tests failed.
• Support command line arguments that allow the setting of different test parameters other than the defaults. Examples of ones that could be implemented are:
  • A parameter that indicates how many configurations should be tested.
  • A parameter that toggles the verbose mode (therefore there should also be both a verbose and quiet mode).
  • A parameter that indicates how many cycles per test should be tested.
  • A parameter that indicates the size or maximum size of the circuits built.
  • A parameter to test different technologies.
  • A parameter to indicate whether techmapping is enabled.
  As referred to above, all the test parameters should have default values that are taken when no command arguments are given. Make sure to print out the valid syntax of the command line arguments if the parameters passed in are invalid.
• A very useful feature when there are errors (particularly when one is testing randomly generated parameters and inputs) is that those errors are written to a file or PrintSTrem. This may be accomplished using the JHDLOutput mechanism or by the module generator itself.

Documentation

• All parameters to all constructors and methods (using the @param tag).
• The return types for methods such as the compute method (using the @return tag).
• All possible exceptions thrown by the module (using the @exception tag) and the reason why they are thrown.
• How your module is placed. This should be done by describing the shape of the placed module and providing a formula to calculate how many CLBs will be taken by the module for any given configuration and input and output widths. If the formula is very complicated or there are just a plethora of cases that need to be covered, a JavaScript is probably the best way to go to indicate the placement and size of a particular design. Also remember to desribe the location of the origin of your placed module.

Adding Your Module to the byucc.jhdl.modgen package

Any unique helper classes that your top-level file calls and any automatic testbenches should reside in its their own subpackage of modgen. For example the modules that the Cordic module generator calls are contained in the byucc.jhdl.modgen.CordicPack package, implying that they are found in the directory CordicPack found in the modgen directory. Thus you should create a directory in modgen with a name that as well as possible uniquely identifies the purpose of the files contained therein with the word Pack added on the end (no underscores please). Remember that once you've selected a name where your submodules will reside and have made the files part of that package, you will need to import that submodules package in the top-level file in that lives in the modgen package. Once you've put all your files in this new directory and are ready to add this module to the repository do a CVS add followed by a commit on this directory and all the files within it . Add the class files you've added to the modgen Makefile as well as any helper directories you've added. Also when adding a new helper directory make sure there is a Makefile in play (you probably want to copy another helper directory's Makefile) and then you need to make sure that that directory is included in JHDL.jar by modifying the byuc.jhdl Makefile under the MODGEN_CLASSES variable (see Wes if you need more help regarding Makefiles). For modules that don't use any helper classes (like the accum module generator), please make the automatic testbench associated with this module a part of the byucc.jhdl.modgen.modtest package while importing the byucc.jhdl.modgen package and add it to the appropriate directory (fpga/byucc/jhdl/modgen/modtest) in the CVS tree.

For those of you whose top-level module(s) will reside in a seperate directory off the modgen tree it is a good idea to follow the same conventions as if your module was in the modgen directory because although it may not be so now, you may in the future share the directory with another designer and following the above conventions will help maintain organization in the directory structure. The msd directory structure, which is off the modgen package, is a good example of what someone has done in this case.

modgen Package Naming Conventions