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:
-
boolean logic gates.
-
flip-flops.
-
new wires.
-
new constant-value wires.
-
adders or subtracters.
-
RAMs and ROMs.
-
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:
-
The _o suffix distinguishes methods that accept output wires as
parameters from those that create new wires for the outputs.
-
Virtually all Logic methods automatically adapt themselves to the widths
of the wires passed as parameters, as appropriate.
-
All gate-instantiating methods take an optional String argument to name
the gate as the last parameter.
-
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:
-
reg( d ) creates a default D flip-flop.
-
regc( d ) creates a globally, asynchronously cleared D flip-flop
.
-
regce( d, ce ) creates a globally, asynchronously cleared, clock-enabled
D flip-flop.
-
regp( d ) creates a globally, asynchronously preset D flip-flop.
-
regpe( d, ce ) creates a globally, asynchronously preset, clock-enabled
D flip-flop.
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:
-
wire() creates a wire of the "atomic" width of the target architecture.
"Atomic width" means the minimum width wire allowed by the target architecture,
i.e. 1 bit for XC4000, 4-bit for HP-Chess, etc.
-
wire(String name) creates a named wire of the default width of
the target architecture.
-
wire(int width) creates a wire of the given width.
-
wire(int width, String name) creates a named wire of the given
width.
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:
-
concat(wire1, wire2, ..., wireN) concatenates the given wire list
into a single wire object. In this case, wire1 would be the most
significant bit(s) of the new wire. The concat() method accepts
from 1 to 16 wire parameters of any width, and an optional name for the
new wire.
-
nc() creates a special "dangling output" wire. This wire cannot
be connected to the input of any cell. It is completely omitted in all
netlisting. You can optionally specify the width of the dangling wire if
desired.
-
range(wire, int hi, int lo) returns the subrange [hi:lo]
from the given wire. Note that the same functionality is performed by calling
wire.range(hi,lo);
in this case, the method is part of the Wire class, but again it does the
same thing. The Wire version of range() seems to be the slightly
preferred version.
-
ashiftr(wire, int shift) performs the arithmetic right shift of
the wire.
-
shiftr(wire, int shift) performs the logical right shift of the
wire.
-
shiftl(wire, int shift) performs the logical left shift of the
wire.
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:
-
constant(int width, int value) creates a width-bit wire
with the given initialization value.
-
constant(int width, long value) does the same, but uses a long
to let you initialize up to 64-bit wires.
-
constant(int width, int[] value) does the same, but uses an array
of integers to let you initialize an arbitrary-width constant.
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