JHDL 0.3.39

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


The Logic Class: Part 1 - Wires and General Logic

The Logic class provides a platform-independent API for instantiating standard FPGA gates and wires. The Logic API creates 7 basic types of objects:
  1. boolean logic gates.
  2. flip-flops.
  3. new wires.
  4. new constant-value wires.
  5. adders or subtracters.
  6. RAMs and ROMs.
  7. other: multiplexors, buffers, etc..
Also, the Logic class provides a special placement API for specifying the technology mapping and placement of your cells. The Logic API is huge, with over 270 method calls defined at the present and growing! This is to allow the user the maximum flexibility possible in constructing a circuit. Before delving into all the details of the API, it will help you to understand a few basic rules and conventions that the Logic API follows. Understanding these basic rules will help you avoid referring to the documentation to find every function. Also, you will want to understand the nature of the TechMapper class in order to understand how the Logic methods get implemented in your target FPGA architecture.


Logic API Method Conventions

The JHDL user can quickly commit standard Logic class constructs to memory by remembering four basic conventions:
  1. The _o suffix distinguishes methods that accept output wires as parameters from those that create new wires for the outputs.
  2. Virtually all Logic methods automatically adapt themselves to the widths of the wires passed as parameters, as appropriate.
  3. All gate-instantiating methods take an optional String argument to name the gate as the last parameter.
  4. All Logic methods follow a standard parameter ordering convention.

The _o suffix distiguishes how output wires are handled.

A critical rule to remember in the Logic API is that virtually every method call returns the output wire of the gate that is created. This allows you to nest your method calls to make your JHDL code concise and readable. For example, you can do the following to create a carry-out function:
     Wire cout = or( and(a,b), and(a,ci), and(b,ci) );

because the and() methods create the 2-input and gates with a new wire attached to the output and return the new wire. This nested form of gate instantiation can make your structural design very clean and readable; in fact your structural code almost begins to look behavioral.

Every basic Logic function has at least two versions: one which creates a new wire as the output of the gate, and one which accepts the output wire as a parameter. By convention, the latter case always appends an _o suffix to the method name to indicate that the output is supplied by the user. To be concrete,

     Wire cout = or( and(a,b), and(a,ci), and(b,ci) );

creates new output wires for each of the gates instantiated, while
     or_o( and_o(a, b, t1), and_o(a, ci, t2), and_o(b, ci, t3), cout );

implements precisely the same carry-out function but with user-supplied wires as the outputs to all gates. Note that the _o methods still return the output wire to allow for nesting (i.e. t1, t2, and t3 will be the return values of the and_o() call, and cout will be the return value of the or_o() call in the example above). Note that some of the add()/sub()/addsub() methods have two outputs (sum and carry-out); in these cases, the sum wire is the return value of the method.

Most Logic methods adapt to the width of the wire parameters.

Most of the methods in the Logic API instantiate variable-width logic, based on the widths of the wires that are passed as parameters. For example, when we call
     Wire a = wire(8), b = wire(8), cin = wire(8);
     Wire cout = concat( wire(1), cin.range(7, 1) );
     or_o( and(a,b), and(a,ci), and(b,ci), cout );

we will get a full 8-bit carry chain. In this example, the wire() calls create new wires; the concat() call creates the carry-out bus as the right-shifted version of the carry-in bus. Then, when we invoke the and() / or() methods, each of these implement an 8-bit bitwise function, creating the carry chain with a single JHDL statement. Generally, all Logic methods will do similar things with arbitrary-width wires, allowing the JHDL designer to rapidly build up parallel computational structures, but without having to explicitly request the width of the block. All width adaptation is automatic, based on the width of the wire parameters.

All Logic methods allow you to name instantiated gates.

All Logic methods which instantiate gates allow you to pass an optional argument for naming the new gate and any output wires that are created. This String argument is always last in the parameter list. For example:
     Wire cout = or( and(a,b), and(a,ci), and(b,ci), "carry_cell" );

will give the or gate the instance name "carry_cell". Also, the returned wire will be named "carry_cell_o".

All Logic methods follow a standard JHDL-wide parameter order convention.

In general, you should be able to develop a "gut-feel" for the correct order of parameters in the Logic API. As with all of core JHDL, the Logic methods tend to have this parameter order:
     some_method( Cell parent, /* For static methods only */
                  Wire input0,
                  ...
                  Wire inputN,
                  Wire output0,
                  ...
                  Wire outputN,
                  int any_integer_arguments,
                  String name);


Logic API boolean logic methods

The Logic API defines methods to invoke and, or, and xor-type boolean gates. These methods, combined with the not operation, can be combined to implement any logic function. The methods are overloaded to accept between 2 and 9 input wires; thus and( a, b, c, d ); creates a 4-input and gate while and( a, b ); creates a 2-input and gate. Boolean gate methods with up to four inputs will accept arbitrary-width wires; methods with five or more inputs only accept 1-bit wires. This is because wider gates are seldom encountered. If the need arises, we can extend the arbitrary-width benefit to all boolean logic methods.

Also, each boolean gate type has a special 1-input-parameter version. For example,

     Wire a = wire(4);
     Wire f = and(a);

will build the function a[0] & a[1] & a[2] & a[3]. Thus by concatenating bits into a single wire, the JHDL designer can get a boolean function of any width. By contrast, if we do the following:
     Wire a = wire(4);
     Wire b = wire(4);
     Wire f = and(a,b);

will build four parallel bitwise functions: f[0] = a[0] & b[0]; f[1] = a[1] & b[1]; f[2] = a[2] & b[2]; f[3] = a[3] & b[3].

The API also implements the boolean "not" function (i.e. an inverter) with the following:

     not(in);
     not_o(in, out);


Logic API flip-flop methods

The Logic API defines several methods to create flip-flops: As usual, these methods automatically adapt to the width of the wire parameters, and optionally accept a String parameter to name the register.


Logic API wire methods

The Logic API defines several methods to create wires: So
     Wire a = wire(3);
     Wire b = wire(4, "jomama");
creates a new 3-bit wire with a default name, and a new 4-bit wire with name "jomama". In addition, each of these methods has a static counterpart that accepts the parent Cell as the first parameter. This allows new wires to be instantiated in an architecture-independent manner, outside of the Logic class (most useful in test-benches, etc.). This looks like:
     Wire a = Logic.wire(this, 4);
This could be invoked from any class to create a new wire in a platform-independent manner.

In addition to creating new wires, the Logic class will help you to manipulate wires in special ways:

Note that each of the shift methods have an _o version to let you supply the output wire. As mentioned above, the range() method can be used outside the Logic class by using the analogous Wire.range() method. Similarly, the user can get concatenation behavior outside the Logic class using the static versions of the method:
     Wire concatenation = Logic.concat(this, a, b, c, d, e, f);
Also, the same thing can usually be done using the constructors provided by the wire class. This is a little trickier because the exact wire class being used is generally platform-dependent (thus the advantage of using the Logic class to hide this). But most Wire classes should have constructors analogous to this one implemented by Xwire, the Xilinx atomic wire class:
      Wire concatention = new Xwire(this, a, b, c, d, e, f);
If for some reason the Logic API does not meet your specific needs for creating wires, you should be able to get the desired results by directly calling the constructor of your target-specific wire class.


Logic API constant wire methods

In addition to the standard wire methods, the Logic API also provides methods for creating constant() wires, i.e., wires that need no (and will not allow) driver cells to be attached to them. These look like the following: Note that each constant() method will optionally accept a String to name the new wire. As with the wire() methods, static versions also exist which accept the parent Cell as a parameter. Using these methods, the JHDL designer can instantiate constant wires in a platform-independent manner from outside the Logic class like this:
     Wire constant5 = Logic.constant(this, 8, 5);
Also, "_o" versions of constant exist so that the user can drive a pre-created wire with the given constant value:
     public MyCell(Cell parent, Wire out1, Wire out2) {
       ...
       constant_o(out1, 5);
       constant_o(out1, 7);
     }
Finally, the user can explicitly insert a 1 bit "power" or "ground" symbol with the vcc() and gnd() methods:
     vcc()
     vcc_o(Wire o)
     gnd()
     gnd_o(Wire o)

Logic API adders and subtracters

The Logic API provides method calls to instantiate basic adders and subtracters in the target architecture. These methods will optionally accept a carry-in and carry-out, if desired. Each of these methods returns the wire connected to the "sum" port of the adder / subtracter. The add() method has the following basic prototypes:
       add(a, b);
       add(a, b, ci);

       add_o(a, b, s);
       add_o(a, b, ci, s);
       add_o(a, b, ci, s, co);
Notice that the only way to get the carry-out signal is to use the last add_o() method shown, explicitly providing the carry-out wire yourself. And of course, each of these is further overloaded to accept an optional String as the instance name of the adder. As always, the exact implementation of adder is very platform-specific, and is determined by the TechMapper class of the corresponding platform. The user should generally expect the layout of the adder to be predetermined by the TechMapper, using the default style of the architecture. For example in the XC4000 architecture, this call would most likely result in a 2-bits-per-CLB, north-to-south column layout. If more control of the adder layout is desired, the user will need to use a platform-specific way of invoking the adder.

The API for creating subtracters and adder-subtracters, via the sub() and addsub() methods, is exactly analogous to the add() API; the addsub() method includes the add wire parameter just after ci, which tells the circuit to add if high-asserted, or to subtract if low-asserted.

All methods accept generic-width wires on the a, b, and sum ports.


Logic API RAMs and ROMs

In the Logic class, basic memory cells can be invoked via the ram() and rom() methods. For all methods, the initial contents of the memory are specified with an array of long values, such that index 0 of the array specifies the initial contents of address 0 in the memory, and index 1 of the array specifies the initial contents of address 1 in the memory, etc. The Logic API currently limits you to a memory width of no more than 64 bits. Because the exact implementation of memories is very device specific, please consult the documentation on the target-specific TechMapper class to see its inference rules on how to instantiate memories.

The basic memory API is shown below; again, standard overloads exist to provide an instance name String.

     ram(din, we, addr, long[] init);
     ram_o(din, we, addr, o, long[] init);
     rom(addr, int width, long[] init);
     rom_o(addr, o, long[] init);
Widths of ram cells are determined from the width of the din wire, and depth is determined by the width of the addr wire. Width of rom cells is determined by the width parameter for rom() calls and by the o wire for rom_o() calls. Note that there also exists a rams() API to implement a synchronous-write RAM; its prototypes are identical to the ram() API shown above.


Logic API miscellaneous: multiplexors, buffers, etc.

The Logic API currently has two gate types that fall into the "miscellaneous" category: multiplexors and buffers:
     mux(d0, d1, sel);
     mux_o(d0, d1, sel, q);
     buf(in);
     buf_o(in, out);
The mux() call will implement a selection such that d1 is selected if sel is high-asserted, else d0. The buf() call instantiates a wire connection buffer. This buffer does not correspond to actual hardware; it is only used to connect two Wire objects. Again all methods optionally accept a String instance name parameter, and self-adapt to the width of the wires passed in.


The TechMapper class

The TechMapper class implements the exact Logic API for a given target FPGA architecture. The Logic class provides only an abstract definition of what transpires when its methods are called; the TechMapper class makes the final decisions as to how these methods are best implemented in its architecture. This is illustrated below:

If the user does not select a TechMapper to target a specific library, Logic uses a generic cell library as default. These generic cells provide efficient simulation models but are not netlistable. To understand exactly what circuit gets implemented when you call Logic methods, you need to understand the TechMapper class that you are using. See the next section for TechMapper descriptions. 


| 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