## 4. HDL Modules

(click to enlarge)
Figure 4.1: HDL Editor Window
Verilog is a widely-used textual language for specifying high-level designs for simulation, synthesis and verification. It is an example of a Hardware Description Language (HDL). It is quite versatile allowing specification from CMOS transistor level, up to high-level algorithmic specifications. TkGate supports a subset of the complete Verilog specification. This chapter assumes that the reader is already familiar with Verilog, and is not intended to be a complete description of Verilog and its features. The reader is directed to one of the many books on Verilog for this purpose. Instead, this chapter is intended to document the features of Verilog that are supported in TkGate's implementation.

The TkGate simulator, called Verga (VERilog simulator for GAte), is a discrete time simulator with time advancing in discrete units called "epochs". All delay must be an integer number of epochs. The Verga simulator is normally used through the TkGate interface, but it can also be run by itself directly on text Verilog files.

### 4.1 HDL Editor Window

When you open a module that you have designated as an HDL module, the HDL editor window will appear as shown in Figure 4.1. This window is essentially a text editor, and you can edit the Verilog text directly in this window. The editing commands that are available depend on which key-binding style you have selected through the Interface Options dialog box. Additional editor options controlling indentation and colorization can be set through the HDL Options dialog box.

#### 4.1.1 Net List

The nets in your module are shown in the "Nets" list in the lower left corner. The nets list is updated when you open the module, but may not display correctly if there are too many syntax errors in your module.

#### 4.1.2 Cut/Paste

Figure 4.2: Full Adder
You can use the cut and paste tools to cut and paste blocks of text that you select with the mouse. You can also drag the selected block of text with the mouse to a new location if you have that option enabled in the HDL Options dialog box.

It is also possible to paste chunks of gates that you have cut or copied from a graphical module. When you paste such modules into a text HDL module, TkGate will convert that chunk into Verilog netlist format. For example, if you cut or copied the full adder shown in Figure 4.2, pasting it into an HDL module would result in the following Verilog code being generated:

      _GGOR2 #(6) g34 (.I0(w3), .I1(w4), .Z(co));   //: @(216,139) /sn:0 /w:[ 0 0 1 ] /eb:0
      _GGAND2 #(6) g28 (.I0(a), .I1(b), .Z(w4));   //: @(150,141) /sn:0 /w:[ 5 5 1 ] /eb:0
      //: joint g32 (w8) @(172, 65) /w:[ 1 -1 2 4 ]
      //: SWITCH g27 (ci) @(56,26) /sn:0 /w:[ 0 ] /st:0
      _GGAND2 #(6) g31 (.I0(w8), .I1(ci), .Z(w3));   //: @(175,110) /sn:0 /R:3 /w:[ 5 5 1 ] /eb:0
      //: LED g15 (s) @(246,87) /sn:0 /R:2 /w:[ 0 ] /type:0
      //: joint g29 (a) @(117, 62) /w:[ 2 -1 1 4 ]
      //: SWITCH g25 (a) @(56,62) /sn:0 /w:[ 0 ] /st:0
      //: LED g14 (co) @(245,122) /sn:0 /w:[ 0 ] /type:0
      _GGXOR2 #(8) g24 (.I0(w8), .I1(ci), .Z(s));   //: @(213,68) /sn:0 /w:[ 0 3 1 ] /eb:0
      _GGXOR2 #(8) g23 (.I0(a), .I1(b), .Z(w8));   //: @(138,65) /sn:0 /w:[ 3 3 3 ] /eb:0
      //: SWITCH g26 (b) @(56,97) /sn:0 /w:[ 0 ] /st:1
      //: joint g33 (ci) @(177, 70) /w:[ 2 1 -1 4 ]
      //: joint g30 (b) @(111, 97) /w:[ -1 2 1 4 ]

The generated code includes comments (positions starting with "//") that are included as part of TkGate save files indicating the position information for that circuit element. For circuit elements that do not have direct Verilog counter-parts, such as the LEDs and switches, pure comments are generated. In this example, the only actual Verilog code generated is for the five gates. These are represented in terms of TkGate cells with names beginning in "_GG".

#### 4.1.3 Module Navigation

Just as you can open a module in the graphical editor by right clicking on a module and selecting "Open", you can do the same thing with modules in the Verilog text. Right click on the text with the name of the module and select "Open". Right click and select "Close" to close the current module and reopen the next one on the stack. In TkGate, each Verilog module should be opened individually. If you define more than one module, or you change the name in the text description so that it no longer matches the name of the module you have open, TkGate will complain and give you options on how to resolve the problem.

### 4.2 Verilog Basics

This section gives a very brief overview of Verilog.

#### 4.2.1 Comments

Comments in Verilog follow the same rules as in C. Block comments are enclosed between "`/*`" and "`*/`". Line comments begin with "`//`" and run to the end of the line.

#### 4.2.2 Literals

Verilog literals begin with a letter or a "`_`" character. The subsequent characters can be letters, digits or "`_`" characters. TkGate supports escaped literals, but their use is discouraged. Escaped literals begin with a backslash "`\`" and continue to the next white-space character. "`\3+4jk`", "`\u8[]*9`" and "`\3342`" are examples of escaped literal.

#### 4.2.3 Numbers and Values

##### Sized Numbers

Verilog numbers can be sized or unsized. Sized numbers have the general form:
<size>'<base><value>
where <size> is the number of bits, <base> is a single letter indicating the number base, and <value> is the actual value of the number. The possible bases are `'d` for decimal, `'h` for hexadecimal, `'o` for octal and `'b` for binary. Examples of sized numbers include:

       8'd42        // The 8-bit decimal number 42
       16'h4fe3     // The 16-bit hexadecimal number 4fe3
       8'b10010011  // The 8-bit binary number 10010011

##### Unsized Numbers

Unsized numbers can be those that still include the base, or plain numbers with an implied decimal base such as:

       83           // The decimal number 83
       'd42         // The decimal number 42
       'o53         // The octal number 53
       'b11         // The binary number 11

The actual size used to represent unsized numbers is machine dependent, but is guaranteed to be at least 32 bit.

##### Special digit values

Binary, octal and hexadecimal number may also use a "`z`" digit to indicate the floating or high impedance state in one or more digits. Similarly an "`x`" or `?` digit can be used to indicate an unknown value. Numbers including a base, may also contain one or more "`_`" characters to help make the number more readable. The "`_`" characters are ignore in interpreting the value. Some examples are:

       12'b0101_0111_0010
       16'h7zz3
       1'bx
       8'bx

When the highest digit of a number is `x` or `z`, that value is extended to the highest bit in the number. For example `8'bx` is equivalent to `8'bxxxxxxxx` not `8'b0000000x`. If you really mean the later, you should use `8'b0x`.

##### Floating Point Numbers

Verilog specifications can also use floating point numbers. Examples of floating point numbers are "`42.0`", "`0.45`" and "`3.14`". The bit size of floating point numbers is machine dependent, but is at least 32 bits.

##### Strings

Verilog strings are delimited by the double quote character. The backspace character can be used to quote any double quote characters used in the string. Some examples of string values are:

       "Hello world."
       "Please push \"Enter\" to begin."
       "Exterminate! Exterminate! Exterminate!"

String values are essentially bit vectors with a size equal to eight times the number of characters.

### 4.3 Data Types

Variables in Verilog can be used to represent registers, or nets connecting components. Each bit in a variables can take on one of six states:

Value | Description
--- | ---
0 | Logic 0 or false
1 | Logic 1 or true
x | Unknown state (could be 0, 1 or z)
z | Floating state
H | High unknown state (could be 1 or z)
L | Low unknown state (could be 0 or z)

#### 4.3.1 Net Types

Net data types are those that must be driven to have a value. The difference between the types is primarily in how collisions are handled. Collisions occur when two or more gates attempt to drive the wire to different values. The supported net types are:

Type | Description
--- | ---
`wire` | Basic net used to connect components. Collisions result in unknown value.
`wand` | Wired AND net. Collisions result in the AND of the values driven on the net.
`wor` | Wired OR net. Collisions result in the OR of the values driven on the net.
`tri` | Equivalent to "wire", but indicates to reader that tri state values will be used.
`tri1` | Net with resistive pull up. Takes on 1 value if nothing is driving it.
`tri0` | Net with resistive pull down. Takes on 0 value if nothing is driving it.
`triand` | Same as wand. Collisions result in the AND of the values driven on the net.
`trior` | Same as wor. Collisions result in the OR of the values driven on the net.
`trireg` | Net with capacitance store. Retains last value written if all drivers are floating.

Nets are declared by specifying the data type followed by a comma separated list of variables, and terminated with a semicolon. Some example net declarations are:

      wire w1;
      wire a,b,c;
      wor p;
      trireg x;

#### 4.3.2 Supply Types

Supply types are used to model ground and supply signals fixed to a 0 or 1 value. The supply types are:

Type | Description
--- | ---
`supply0` | Net fixed at logic 0.
`supply1` | Net fixed at logic 1.

Examples of supply types are:

       supply1 vdd;
       supply0 gnd;

#### 4.3.3 Register Types

Register types retain their value until they are assigned again. The behave similarly to variables in a C program.

Type | Description
--- | ---
`reg` | One bit register variable.
`integer` | General purpose integer variable.
`real` | General purpose floating point variable.
`time` | 64-bit simulation time variable.

Examples of register types are:

       reg r1, r2;
       integer i, j;
       time t;
       real f;

#### 4.3.4 Port Types

Port types are used to declare the type of a port. Variables using one of these types must also appear in the port list of a module.

Type | Description
--- | ---
`input` | Module input port.
`output` | Module output port.
`inout` | Module inout (bidirectional) port.

The port types normally act like "wire" nets, but the output variables may be also declared as `reg` in addition to `output`. This can either be in two separate declarations such as:

       output z;
       reg z;

or in a combined declaration:

       output reg z;

#### 4.3.5 Event Types

Event variables do not take on a value per se. Instead, they can be used in signaling from one portion of the design to another. They are declared with the `event` keyword. For example:

      event e;

#### 4.3.6 Parameter Types

You may also use the `parameter` type to declare constant variables. Constant variables must be assigned from constant value, or an expression involving only constants and other parameter variables. Examples of `parameter` declarations are:

       parameter delay1 = 9;
       parameter delay2 = 2*delay1 + 7;
       parameter myvalue = 8'h4e;
       parameter mystring = "impudent moose";

Parameters can be used both as values in expressions, and as the value in a delay.

#### 4.3.7 Bit Size Declaration

A bit size declaration can be used with any of the net, supply or port data types. In addition they can be used with the `reg` data type. The bit size is declared right after the keyword and before the variable. The bit size specifier has the form "`[`msb`:`lsb`]`" where msb is the most significant bit and msb is the least significant bit. Currently TkGate Verilog only supports bit ranges with a 0 least significant bit, and a non-negative most significant bit. Examples include:

       wire [7:0] w1, w2;   // 8-bit wires
       reg [11:0] r1, r2;   // 12-bit registers

#### 4.3.8 Memories

Memories are declared by specifying an address range after the variable name in a `reg` declaration. For example:

    reg [7:0] m[0:1023];

Declares a memory with 1024 eight-bit values. TkGate Verilog only supports memories that start at address 0.

#### 4.3.9 String Variables

You can store strings in `reg` variables, but you must allocate enough bits to store the string. For example:

       reg [8*11-1:0] s = "hello world";

### 4.4 Expressions

Verilog uses an infix notation for expressions similar to expressions in C. A wide range of arithmetic, logical, bit-wise and comparison operators are supported. Operator precedence is similar to C, and parenthesis may be used to group expressions. Some example expressions are:

       x*u*(3 + j) + 1
       z + 8'h5
       (q*8'h2) < 8'h5

When the bit sizes of operands in an expression do not match, the bit size of the entire expression is expanded to the bit size of the largest value. For example, when evaluating the expression `16'h3423 + 8'hff`, both values are first extended to 16 bits before performing the sum.

#### 4.4.1 Operators

The operators supported in TkGate's implementation of Verilog are shown in the table below. Operators are grouped by precedence from highest to lowest.

Operator | Description
--- | ---
`{`a`,` b `,...}` | Concatenation - Concatenates the bits of two or more nets (or expressions) into a single expression. If all of the components are nets, the concatenation may be used as the target of an assignment.
`{`n`{`a`}}` | Bit Replications - Concatenates n copies of a together. n must be a constant.
`!` a | Logic NOT - Returns zero if a is zero, one if a is non-zero.
`~` a | Bit-wise compliment - Reverses all bits in a.
`-` a | Negation - Performs an arithmetic negation of a.
`&` a | Reduction AND - ANDs together all the bits of a and returns the 1-bit result.
`|` a | Reduction OR - ORs together all the bits of a and returns the 1-bit result.
`^` a | Reduction XOR - XORs together all the bits of a and returns the 1-bit result.
`~&` a | Reduction NAND - NANDs together all the bits of a and returns the 1-bit result.
`~|` a | Reduction NOR - NORs together all the bits of a and returns the 1-bit result.
`~^` a | Reduction XNOR - XNORs together all the bits of a and returns the 1-bit result.
a `*` b | Multiplication - Returns the product of a and b.
a `/` b | Division - Returns the quotient of a and b.
a `%` b | Remainder/Modulo - Returns the remainder of a/b.
a `+` b | Addition - Returns the sum of a and b.
a `-` b | Subtraction - Returns the difference of a and b.
a >> b | Right Shift - Shifts the bits in a to the right by b places.
a `<<` b | Left Shift - Shifts the bits in a to the left by b places.
a >>> b | Arithmetic Right Shift - Shifts the bits in a to the right by b places arithmetically.
a `<<<` b | Arithmetic Left Shift - Shifts the bits in a to the left by b places arithmetically.
a `>` b | Greater Than - Returns 1 if a is greater than b, otherwise returns 0.
a `<` b | Less Than - Returns 1 if a is less than b, otherwise returns 0.
a `>=` b | Greater Than or Equal - Returns 1 if a is greater than or equal to b, otherwise returns 0.
a `<=` b | Less Than r Equal - Returns 1 if a is less than or equal to b, otherwise returns 0.
a `==` b | Equality - Returns 1 if a and b are equal and 0 if they are not equal. Returns unknown (`x`) if any bits in a or b are unknown or floating.
a `!=` b | Inequality - Returns 0 if a and b are equal and 1 if they are not equal. Returns unknown (`x`) if any bits in a or b are unknown or floating.
a `===` b | Case Equality - Returns 1 if a and b match exactly including unknown and floating bits. Returns 0 otherwise.
a `!==` b | Case Inequality - Returns 0 if a and b match exactly including unknown and floating bits. Returns 1 otherwise.
a `&` b | Bit-wise AND - Each bit of the result is the AND of the corresponding bits of a and b.
a `~&` b | Bit-wise NAND - Each bit of the result is the NAND of the corresponding bits of a and b.
a `^` b | Bit-wise XOR - Each bit of the result is the XOR of the corresponding bits of a and b.
a `~^` b | Bit-wise XNOR - Each bit of the result is the XNOR of the corresponding bits of a and b.
a `|` b | Bit-wise OR - Each bit of the result is the OR of the corresponding bits of a and b.
a `~|` b | Bit-wise NOR - Each bit of the result is the NOR of the corresponding bits of a and b.
a `&&` b | Logical AND - If both a and b have non-zero bits, then return 1, otherwise return 0. However, unknown will be returned if unknown bits in the operands prevent determining the actual result.
a `||` b | Logical OR - If either a and b have non-zero bits, then return 1, otherwise return 0. However, unknown will be returned if unknown bits in the operands prevent determining the actual result.
a `?` b `:` c | Conditional Operator - If `a` is non-zero, then the result is b. If a is zero, then the result is c. If `a` is unknown or floating, then the result is the bit-wise XNOR of the bits in b and c.

#### 4.4.2 Bit and Memory Addressing

Bits on sized multi-bit variables can be address using the syntax:
name`[`bit`]`
For example, suppose we have the declaration:

       reg [7:0] r;

The expression `r[4]` represents the single-bit expression for the value of bit-4 in `r`. This syntax can be used either to use its value in an expression, or in an assignment statement. The bit address can be either a constant or an expression. For example, `r[i+1]` will address the bit corresponding to the current value of the expression `i`+1. A run-time error will result if you attempt to simulate a circuit where `i+1` goes out of bounds.

You can also address ranges of bits using the syntax:
name`[`high`:`low`]`
For example, `r[6:2]` is a 5-bit value formed from bits 2 to bit 6 of `r`. In this syntax, the high and low values specified must be constants, although they can be constant expressions that can be evaluated at compile time.

In order to get indexable ranges of bits, you can use the syntax:
name`[`low`+:`num`]`
In this expression low is the bit number of the lowest bit, and num is the number of bits. num must be a constant expression, but low may be an expression evaluated at execution time. For example `r[i +: 3]` will address a three bit sub-range of `r` starting at the bit addressed by `i`.

Memories are addressed using the same syntax as bits. For example, if you define the following memory of 1024 8-bit words:

       reg [7:0] mem[0:1023];

then `mem[45]` will address word 45 of the memory and `mem[45][6]` will address bit 6 of the word 45 of the memory.

### 4.5 Compiler Directives

Verilog compiler directives are similar to the `#define` and `#ifdef` directives that are used in C programs. Verilog compiler directives begin with the ` (back-quote) character.

#### 4.5.1 The ``define` Directive

The ``define` directive is analogous to the `#define` directive in C. It allows you to associate a value or piece of text with a symbolic macro. For example:

    `define THEANSWER 42

To use a macro that you have defined, you must use a back quote in front of the name. For example, to use the value of the macro defined in the example above you might write:

      x = y + `THEANSWER;

#### 4.5.3 The ``ifdef`, ``ifndef`, ``else` and ``endif` Directives

The ``ifdef`, ``ifndef`, ``else` and ``endif` directives can be used to conditionally compile Verilog code. They are analogous to the similarly named directives in C. The ``ifdef` directive causes code to be compiled only if the macro given after it is defined. The ``ifndef` directive causes code to be compiled only if the macro given after it is not defined. You can nest ``ifdef` and ``ifndef` directives and use the ``else` directive to provide alternatives. The ``endif` directive marks the end of the conditionally compiled portion.

An example of conditionally compiled code is shown here:

      `ifdef INCBY2
         x = x + 2;
      `else
         x = x + 1;
      `endif

In this example, if the macro `INCBY2` has been defined by a ``define` then the `x = x + 2;` statement is compiled, otherwise the `x = x + 1;` statement is compiled. Note that when using macro names in an ``ifdef` you do not precede them with a ` (backquote).

#### 4.5.2 The ``timescale` Directive

The ``timescale` directive is used to set the time scale of a module or modules for simulation. It must be followed by a units value and a precision value. These values must be a 1, 10 or 100 followed by time units "s" (seconds), "ms" (milliseconds), "us" (microseconds), "ns" (nanoseconds), "ps" (picoseconds) or "fs" (femotoseconds). For example:

      `timescale 1ns / 100ps

would set the time units to 1ns and the simulation precision to 100ps. This would cause any delay specifications in modules defined after the ``timescale` directive to be counted as 1ns. The simulator itself would simulate in steps of 100ps. It is important not to set the precision value lower than necessary (relative to the delay values of components used in your design) since this can impact simulator performance. If the ``timescale` directive is not uses, the default time scale and precision is 1ns.

### 4.6 Module Declarations

Module declarations begin with the `module` keyword, and end with the `endmodule` keyword. Consider the simple module:

     (1) module ANDOR(z, a, b, c);
     (2) output z;
     (3) input a,b,c;
     (4) wire x;
     (5)
     (6)   or o1(z,a,x);
     (7)   and a1(z,b,c);
     (8)
     (9) endmodule

The literal `ANDOR` after the `module` keyword is the name of the module. The module name is usually followed by a list of the port names in parenthesis. The port list must be followed by a ";". Inside the body of the module are declarations for any nets used in the module. The nets declared as ports for the module, should also have declarations to indicate if they are `input`, `output` or `inout` ports as shown on lines (2) and (3).

The port list may be omitted for a module as in this example:

    module main;
    reg a,b,c;
    wire x,y,z;

      mycircuit m1(a,b,c,x,y,z);

    endmodule

This is typically done for top-level modules.

### 4.7 Netlist Modules

Netlist modules are those that are defined as a collection of connected components. The components can be built-in Verilog primitives (such as "`and`" and "`or`"), library modules, or user-defined modules. Here is a simple example of a module for a 1-bit full adder circuit (the same basic circuit as shown in Figure 4.2):

     (1) module ADD(s, co, a, b, ci);
     (2) output s, co;
     (3) input a,b,ci;
     (4) wire w1,w2,w3 ;
     (5)
     (6)   or (co, w1, w2);
     (7)   and (w2, a, b);
     (8)   and (w1, w3, ci);
     (9)   xor (s, w3, ci);
    (10)   xor (w3, a, b);
    (11)
    (12) endmodule

The names "`or`", "`and`" and "`xor`" are built-in Verilog primitives for computing the OR, AND and XOR of one or more signals. The first parameter of each of these primitives is the output signal, and the remaining parameters are the inputs. In gate-level descriptions like this, it is easy to see the mapping between the description and the hardware.

Input ports may be driven by any type of variable, but the outputs of primitives must be a "Net" type variable such as `wire`, `tri` or `wand`.

It is also possible to give names to the instances of each of the gates. We do this by inserting an instance name after the name of the primitive. For example, we could replace the body of the example above with:

     (6)   or g1 (co, w1, w2);
     (7)   and g2 (w2, a, b);
     (8)   and g3 (w1, w3, ci);
     (9)   xor g4 (s, w3, ci);
    (10)   xor g5 (w3, a, b);

In this new body, "`g1`", "`g2`", etc. are the instance names of the gates and can be used to refer to those gates when necessary. You can also specify more than one instance in a single statement. For example, an alternative way of specifying the above design is:

     (6)   or g1 (co, w1, w2);
     (7)   and g2 (w2, a, b), g3 (w1, w3, ci);
     (8)   xor g4 (s, w3, ci), g5 (w3, a, b);

In addition to primitives, netlist modules can also combine other modules. For example, we can connect four of the adders shown above to create a module of a 4-bit adder as shown below:

     (1) module ADD4(s, co, a, b, ci);
     (2) output [3:0] s;
     (3) output co;
     (4) input [3:0] a,b;
     (5) input ci;
     (6) wire c1,c2,c3;
     (7)
     (8)    ADD a1 (s[0], c1, a[0], b[0]);
     (9)    ADD a2 (s[1], c2, a[1], b[1]);
    (10)    ADD a3 (s[2], c3, a[2], b[2]);
    (11)    ADD a4 (s[3], co, a[3], b[3]);
    (12)
    (13) endmodule

In this example, we create four instances of our `ADD` module named `a1` through `a4`. Ports connections are made in the order in which they appear in the port list of the module definition. Alternative, you can explicitly specify the port connections using the syntax:
`.`port`(`net`)`
For example, you could replace line (8) with:

     (8)    ADD a1 (.a(a[0]), .b(b[0]), .s(s[0]), .co(c1));

Since the ports for each connection are explicitly specified, you can list the connections in any order. However, you must either specify no ports or all ports in this manner. You must also ensure that all ports have exactly one connection.

#### 4.7.1 Verilog Primitives

This section will introduce the primitive gates that are supported in TkGate's implementation of Verilog. By default, all primitives are single bit and all inputs and outputs must be single bit. You can declare arrays of primitives by using a bit range after the instance name. For example:

      and a1[3:0] (x, a, b);

will perform a bit-wise AND on the four-bit signals `a` and `b` and drive the four-bit result to `x`. The following subsections describe the various types primitives.

##### Logic Primitives

The logic primitives include `and`, `or`, `xor`, `nand`, `nor` and `xnor`. The first parameter is always the output, and the remaining parameters are the inputs. You can specify anywhere from one to an arbitrary number of inputs. The primitives are defined in terms of their truth tables shown below.

and | 0 | 1 | x | z
0 | 0 | 0 | 0 | 0
1 | 0 | 1 | x | x
x | 0 | x | x | x
z | 0 | x | x | x
or | 0 | 1 | x | z
0 | 0 | 0 | 0 | 0
1 | 0 | 1 | x | x
x | 0 | x | x | x
z | 0 | x | x | x
xor | 0 | 1 | x | z
0 | 0 | 0 | 0 | 0
1 | 0 | 1 | x | x
x | 0 | x | x | x
z | 0 | x | x | x
nand | 0 | 1 | x | z
0 | 0 | 0 | 0 | 0
1 | 0 | 1 | x | x
x | 0 | x | x | x
z | 0 | x | x | x
nor | 0 | 1 | x | z
0 | 0 | 0 | 0 | 0
1 | 0 | 1 | x | x
x | 0 | x | x | x
z | 0 | x | x | x
xnor | 0 | 1 | x | z
0 | 0 | 0 | 0 | 0
1 | 0 | 1 | x | x
x | 0 | x | x | x
z | 0 | x | x | x

##### Buffer Primitives

The buffer primitives include `buf` and `not`. The last parameter of these primitives is the input, and all of the preceding parameters are outputs being driven with the same value. The `buf` primitive simply drives its input to the output, while the `not` primitive drives the compliment logic value. However, if the input is unknown or floating, the output will be unknown for both primitives.

Consider the example:

       buf b1 (w1, w2, w3, a);
       not n1 (w4, w5,  b);

This will drive the value of `a` to `w1`, `w2` and `w3`. The compliment of `b` will be driven to `w4` and `w5`.

##### Conditional Buffer Primitives

The conditional buffer primitives include `bufif1`, `bufif0`, `notif1` and `notif0`. These primitives have exactly three ports as shown below:

       bufif0 b1 (out, in, ctl);
       bufif1 b2 (out, in, ctl);
       notif0 n1 (out, in, ctl);
       notif1 n2 (out, in, ctl);

The first parameter is the output of the primitive, the second parameter is the input, and the third parameter is the control. The `bufif1` and `notif1` gates act like `buf` and `not`, respectively, when the control signal is 1. They output floating when the control line is 0. Conversely, the `bufif0` and `notif0` gates act like `buf` and `not`, respectively, when the control signal is 0. They output floating when the control line is 1. The truth tables for these primitives are shown in the tables below.

| ctl
in | bufif0 | 0 | 1 | x | z
0 | 0 | z | L | L
1 | 1 | z | H | H
x | x | z | x | x
z | x | z | x | x
| ctl
in | bufif1 | 0 | 1 | x | z
0 | z | 0 | L | L
1 | z | 1 | H | H
x | z | x | x | x
z | z | x | x | x
| ctl
in | notif0 | 0 | 1 | x | z
0 | 1 | z | H | H
1 | 0 | z | L | L
x | x | z | x | x
z | x | z | x | x
| ctl
in | notif1 | 0 | 1 | x | z
0 | z | 1 | H | H
1 | z | 0 | L | L
x | z | x | x | x
z | z | x | x | x

##### MOS Transistor Primitives

Transistor primitives model simple nmos and pmos devices. However, TkGate does not do true transistor-level simulation in the sense of Spice and other such tools. Instead, they are simulated in the same way as the gate primitives, driving an output depending on the value of the input and control signals. Examples of these primitives are:

      nmos n (out, in, ctl);
      pmos p (out, in, ctl);

The truth tables for determining the value driven to `out` from the values on the input `in` and the control line (or gate) `ctl` are shown in the table below.

| ctl
in | nmos | 0 | 1 | x | z
0 | z | 0 | L | L
1 | z | 1 | H | H
x | z | x | x | x
z | z | z | z | z
| ctl
in | pmos | 0 | 1 | x | z
0 | 0 | z | L | L
1 | 1 | z | H | H
x | z | z | x | x
z | z | z | z | z

This level of modeling is generally good enough to create CMOS circuits out of nmos and pmos components. For example:

      nmos n1 (out, gnd, a);
      nmos n2 (out, gnd, b);
      pmos p1 (x, vdd, a);
      pmos p2 (out, x, b);

will implement a 2-input OR gate.

#### 4.7.2 Specifying Delay Values

In the examples presented so far, all of the primitives had zero delay. In a real circuit, there is propagation delay over a gate. The delay is specified with the syntax `#`delay. For example, if we add delays to our full adder circuit we get:

     (1) module ADD(s, co, a, b, ci);
     (2) output s, co;
     (3) input a,b,ci;
     (4) wire w1,w2,w3 ;
     (5)
     (6)   or #5 g1 (co, w1, w2);
     (7)   and #5 g2 (w2, a, b);
     (8)   and #5 g3 (w1, w3, ci);
     (9)   xor #7 g4 (s, w3, ci);
    (10)   xor #7 g5 (w3, a, b);
    (11)
    (12) endmodule

The `or` and `and` gates will have delays of 5 time units (or whatever was specified as the units in the ``timescale` directive).

#### 4.7.3 `assign` Statements

Rather than defining complex expression in terms of primitives, you can use an `assign` statement to assign an expression to an output, with much the same behavior as if you defined it in terms of gates. The general syntax is:
`assign` wire `=` expression`;`
The wire must be a net type variable (`wire`, `tri`, `wand`, etc.), but the expression may contain both net and register type variables. The value driven to wire changes whenever the value of the expression changes. You can can also specify a delay value for the `assign` statement using the syntax:
`assign #`delay wire `=` expression`;`
An example of an `assign` statement with a delay is:

       assign #5 x = a & (b + c);

### 4.8 Behavioral Modules

In behavioral models, the design is specified algorithmically, more like a C program. Unlike most C programs, however, Verilog specifications tend to be highly parallel with many threads.

#### 4.8.1 `initial` and `always` Statements

All behavioral Verilog is defined inside an `initial` or `always` statement. Both of these statements create a new parallel thread for each statement occurring in the design. The `initial` statement creates a thread that executes once and terminates, while the `always` statement creates a thread that repeats in an infinite loop. An example of a clock-generator module defined in behavioral Verilog is shown below:

     (1)  module myclock(x);
     (2)  output reg x;
     (3)
     (4)    initial
     (5)       x = 1'b0;
     (6)
     (7)    always
     (8)       #100 x = ~x;
     (9)
    (10)  endmodule

When the simulation starts, both the `initial` statement and the `always` statement begin execution in parallel. The thread started by the `initial` statement sets the output register `x` to 0 as soon as the simulator starts. The `always` thread waits for 100 simulation time steps, then inverts the value if `x`. Since `always` statements repeat, control will go back to the top of the `always` statement, and after another 100 time units, `x` will be inverted again. The result is that `x` will be 0 for the first 100 time units, 1 for time units 100 to 199, 0 again for time units 200 to 299, and so on.

#### 4.8.2 Blocking Assignments

Blocking assignments are assignments that use the `=` operator, and are the most similar to assignments in a C program. Each blocking assignment is executed and the new value assigned to the left-hand side before the next statement is executed. The left-hand side of blocking assignments must be a register type variable.

An example use of blocking assignments is in the module shown below:

     (1)  module foo(z,a,b,c)
     (2)  output reg [15:0] z;
     (3)  input [15:0] a,b,c;
     (4)  reg [15:0] r1,r2;
     (5)
     (6)    always
     (7)      begin
     (8)        r1 = a + b;
     (9)        r2 = r1 *(b + c);
    (10)        #5 z = r2 / r1;
    (11)      end
    (12)
    (13)  endmodule

The statements at Lines (8) and (9) are executed sequentially. The value of `r1` used in Line (9) is the value computed at Line (8). The `#5` at Line (10) cause execution of the thread to be suspended for 5 time units. After the 5 unit delay has elapsed, the expression `r2 / r1` is evaluated and assigned to `z`. Once the statement at Line (10) has completed, execution of the thread goes back to the top and Lines (8) and (9) are executed again.

The delay on Line (10) causes evaluation of the left-hand side to wait until the statement after the delay period has elapsed. If some other thread were to change the values of `r1` or `r2` during the 5 time units Line (10) was delayed, the new values would be used instead. If you wish to ensure that the values at the beginning of the delay period are used, you can use an intra-statement delay such as:

            z = #5 r2 / r1;

This will cause `r2 / r1` to be evaluated immediately, but the statement will delay 5 time units before assigning `z`.

#### 4.8.3 Non-Blocking Assignments

Non-Blocking assignments use the `<=` operator and are executed in parallel. The right-hand side expressions are evaluated immediately, but the assignment is deferred until the end of the current time step. Like with blocking assignments, the left-hand side of non-blocking assignments must also be a register type variable.

An example of using non-blocking assignments to swap the values of two registers are:

     (1)  always
     (2)    begin
     (3)      # 10;
     (4)      a <= b;
     (5)      b <= a;
     (6)    end

The statement at Line (3) is a delay statement. It waits 10 time units before continuing execution. The next two statements at Lines (4) and (5) are executed in parallel. The current values of `b` and `a` are read, then when the next time unit starts, the new values are written to `a` and `b`.

You can specify a delay in non-blocking assignments using a statement such as:

        a <=  #5 b + x;

This statement will evaluate `b + x`, and schedule the assignment of that value to `a` five time units in the future. Execution of statements after this non-blocking assignment will continue immediately.

While you can place the delay before a non-blocking assignment as in:

        #5 a <= b + x;    // A usually incorrect usage of non-blocking assignment

This usage will result in the thread blocking for 5 time units, then executing the non-blocking assignment. It is equivalent to writing:

        #5;
        a <= b + x;

#### 4.8.4 Fully Qualified Path Names

You can reference variables in other modules of your design by using fully qualified path names. Fully qualified path names start with the name of the top level module, followed by the names of the path of instances down to the level in which the variable you wish to reference is. The "`.`" character is used between each part of the name. Consider the following example:

      module top;
        wire [15:0] x;
        reg [15:0] a,b;

        foo g1(x,a,b);

        initial
          begin
            $monitor("x=%h a=%h b=%h",x,a,b);

            #1 a = 16'h45;
            #1 b = 16'h24;
            #1 top.g1.i = 16'h100;
          end
      endmodule

      module foo(x,a,b);
       output [15:0] x;
       input [15:0] a,b;

        reg [15:0] i = 0;

        assign #1 x = a + b + i;
      endmodule

The variable name "`top.g1.i`" used in `top` references the variable `i` in the instance `g1` of module `foo`. When this example is simulated, it produces the output:

    x=x a=45 b=x
    x=x a=45 b=24
    x=69 a=45 b=24
    x=169 a=45 b=24

Fully qualified path names allow any module to access variables of any other module in your design. Normally, they should only be used in simulation scripts and for debugging.

#### 4.8.5 System Tasks

There are a number of system tasks supported in TkGate. They are used somewhat like function calls and are built into the simulator. System tasks begin with a `$`. One useful system task is the `$display` task. It is similar to a `printf()` in a C program. Here is an example of a behavioral description using the `$display` task:

       reg [7:0] x;

       initial
         begin
           x = 8'hf;
           $display("Hello world.  The value of x is %d",x);
         end

Simulating this description will produce the output:

    Hello world.  The value of x is 15

The `$display` task appends a newline to the end of the output. When simulating through the TkGate graphical interface, the output will be directed to the simulator output console. When using the TkGate simulator stand-alone, output will go to standard output. Like C, the `%` symbol is used to denote conversions for output. For example:

        $display("x=%d  x=%o  x=%h  x=%04h",x,x,x,x);

will produce:

    x=15  x=17  x=f  x=000f

Another useful system task is the `$monitor` task. It has the same calling conventions as `$display`, except that instead of displaying immediately, it sets a watch on all the nets that are referenced in the statement. Any time a variable referenced by the `$monitor` task changes value, output will be produced using the rules as in a `$display`. For example, the module:

       module top;
       reg [7:0] x, y, z;

         initial
           $monitor("%t: x=%02h  y=%02h  z=%02h",$time,x,y,z);

         initial
           begin
             x = 8'h42; y = 8'h23; z = 8'hfe;
             #5 x = 8'h94;
             #73 y = 8'h6d;
             #21 z = 8'h88;
           end
        endmodule

will produce the output:

    0: x=42  y=23  z=fe
    5: x=94  y=23  z=fe
    78: x=94  y=6d  z=fe
    99: x=94  y=6d  z=88

The `$monitor` task produces output at most once per simulation time unit. The output is produced at the end of the epoch if the simulator has detected a change on any of the variables references in the `$monitor` task.

You may have noticed that we also used the system task `$time` in this example. This system task returns the current simulation time in simulation time units. You should use the `%t` conversion when printing out time values. The output produced when using the `%t` conversion is influenced by the current ``timescale` in force for the module in which it is used.

These are only a small fraction of the system tasks supported in TkGate. For a complete list of all the system tasks, see Appendix D. List of System Tasks.

#### 4.8.6 Delay Triggering

The delay operator "`#`delay" has already been touched upon in the previous sections. This operator can be used to suspend/delay execution of a thread for a specified period of time. It can be placed at the beginning of a statement, in-line in a assignment statement, or by itself as a pure delay.

If a `timescale` directive has been used, the delay value may be fractional. For example when the module:

     (1)  `timescale 1ns / 100ps
     (2)
     (3)  module top;
     (4)
     (5)    initial
     (6)      begin
     (7)         $display("%t: starting simulation",$time);
     (8)         # 1.5;
     (9)         $display("%t: after delay",$time);
    (10)      end
    (11)
    (12)  endmodule

is simulated, the following output is produced:

    0.0: starting simulation
    1.5: after delay

You can also use a zero delay to ensure that a statement is executed at the end of an epoch. For example:

       initial
         i = 9;

       initial
         i = 7;

       initial
         #0 i = 42;

will set `i` to `42` because the `#0` delay ensures that the `i = 42;` assignment is executed last. If the `#0` were not used, then the value of `i` would be non-deterministic.

#### 4.8.7 Event-Based Triggering

Event-based triggering is another way to introduce blocking into your design. Event-based triggers have the syntax:
`@(` event-expr `)`statement`;`
They cause the execution of the statement to block until the event described by event-expr occurs. An example use of a event-based trigger is in the following example of a D-flip-flop:

     (1)  module dff(q, d, clock);
     (2)  input d, clock;
     (3)  output reg q;
     (4)
     (5)    always @(posedge clock)
     (6)      q = d;
     (7)
     (8)  endmodule

The `@(posedge clock)` expression will cause the execution of the always block to be suspended until the rising edge of the `clock` signal. The `posedge` and `negedge` operators indicate that we should wait for the rising/positive or falling/negative edge of the signal that follows it. If we had instead written Lines (5) and (6) as:

     (5)    always @(clock)
     (6)      q = d;

The design would have loaded `q` with the value of `d` on both the rising and falling edges of the `clock` signal.

You can use the `or` operator to trigger on the change of one or more signals. For example:

     (5)    always @(posedge clock or load)
     (6)      q = d;

would result in the assignment being executed on either the rising edge of `clock` or any change in the value of `load`.

You can also use the event-based trigger with `event` variables. Event variables are declared with the `event` keyword. The `->` operator is used to raise an event on an event variable. The following example declares and uses an event variable:

      (1)   module top;
      (2)      event e;
      (3)
      (4)      initial
      (5)        @ (e) $display($time,": got event");
      (6)
      (7)      initial
      (8)        #24 -> e;
      (9)
      (10)  endmodule

when simulated, this example produces:

    24: got event

The event variable `e` is declared at Line 2. The `initial` statement at Line 4 executes and uses an event trigger to wait for a signal on `e`. A parallel `initial` statement at Line 7 waits for 24 time units, then uses the `->` operator to raise an event on `e`. The raise event operator only has an effect if there are other threads that are blocked waiting for an event.

#### 4.8.8 The `wait` Statement

The `wait` statement block until a condition is true, then executes its statement. The general syntax is:
`wait (` expr `)`statement`;`
The expr is evaluated any time a variable in it changes, and if the expression is not satisfied, it continued to block, otherwise it executes its statement. As an example, consider the simple latch:

     (1)  module latch(q, d, load)
     (2)  input d,load;
     (3)  output reg q;
     (4)
     (5)    always
     (6)        wait (load == 1'b0)
     (7)          #10 q = d;
     (8)
     (9)  endmodule

When the `load` signal becomes zero, the `q` register is loaded with the value of `d` after a delay of 10 time units. It is important to include a delay in here to avoid locking up the simulator. With no delay, the statement would continue executing forever without advancing simulation time. This is because simulation time is advanced only after all statements in the current time period (epoch) have been executed.

#### 4.8.9 Conditional Statements

Conditional statements are similar to C `if` statements and use essentially the same syntax. For example:

        if (load == 1'b0)
          q = d;
        else
          q = q + 1;

will load the value of `d` into `q` if `load` is zero, otherwise it will increment the value of `q`. If the value of the expression is unknown (for example, if `load` had any unknown bits), then the `else` branch will be taken. `if` statements may be nested, and the `else` branch is optional. You may also use a `begin...end` block in the body as in the example:

        if (u > x)
          begin
            u = u - 1;
            x = j + k;
          end

#### 4.8.10 Case Statements

There are three variants of multi-way branching or `case` statements: `case`, `casex` and `casez`. They all have the same basic syntax except for which keyword is used. They are similar in purpose to the C `switch` statement, but have some important differences. An example of a `case` statement is:

         case (r)
            2'b00: u = 3;
            2'b0x, 2'b0z: u = 4;
            2'b10, 2'b11, 2'bx1: u = 5;
            2'bxx: u = 6;
            default: u = 7;
         endcase

This statement will compare `r` against each of the branches in order until a match is found. Comparison is done with case equality (`===`) meaning that there must be an exact bit-by-bit match including any unknown (x) or floating (z) bits. You may also specify more than one value for each branch of the case.

The `casez` statement differs from `case` in that any floating (z) bits in the case values or in the expression are treated as don't cares. You may also use a "?" in the case values in place of "z". The `casex` statement differs in that both floating (z) and unknown (x) bits are treated as don't cares. An example of a `casex` statement is:

         casez (r)
            8'b1101????: u = 3;
            8'b1001????: u = 4;
            8'b00????01: u = 5;
            default: u = 7;
         endcase

Like conditional statements, you may nest `case` and `if` statements and use `begin...end` block in the body of a branch.

Another difference between the Verilog `case`, `casez` and `casex` statements compared to the C `switch` statement is that the case values need not be constants. For example, you can write:

        reg [7:0] r, v1, v2,v3;

        case (r)
           v1: $display("r matched v1");
           (v2+1): $display("r matched v2+1");
           v3: $display("r matched v3");
           default: $display("r didn't match anything");
        endcase

The case expressions are evaluated as the simulator tries `r` against each expression looking for the first match.

#### 4.8.11 Loops

There are four types of looping statements in Verilog that will be described in this section.

##### `while` Loops

`while` loops look and behave similarly to `while` loops in C programs. An example use of a `while` loop is shown below:

       always
         begin
           count = 0;
           while (count < 10)
             #12 count = count + 1;
         end

This description will set `count` to 0, then increment `count` ten times with a 12 epoch delay between each time it is incremented.

##### `for` Loops

`for` loops also look and behave similarly to `for` loops in C programs. An example use of a `for` loop is shown below:

       reg [7:0] r;
       integer i;

       always @(r)
         for (i = 0;i < 8;i = i + 1)
           $display("Bit %d of r is %b.",i,r[i]);

This code would wait or the value of `r` to change, then print out each bit of it individually.

##### `repeat` Loops

`repeat` loops can be used to repeat a statement a specified number of times. For example:

       repeat (10)
         #12 count = count + 1;

would increment `count` ten times with a 12 time unit delay between each increment.

##### `forever` Loops

`forever` loops can be used to repeat a statement indefinitely . For example:

       forever
         #12 count = count + 1;

would increment `count` every 12 time units. Control would never pass to any statements after the `forever` statement.

#### 4.8.12 `fork...join` Blocks

`fork...join` blocks can be used to execute two or more statements in parallel. A new thread is started for each statement in the fork, and the threads are executed in parallel. Execution of the parent thread is suspended until all statements in the `fork` have completed. The statements in the `fork` may be `begin...end` blocks in which case the statements enclosed within each `begin...end` block will be executed sequentially. Here is an example of a module using a `fork...join`.

     (1)  module top;
     (2)    reg [31:0] a,b,c;
     (3)
     (4)    initial
     (5)      begin
     (6)        fork
     (7)          @(a) $display("%t: got a",$time);
     (8)          @(b) $display("%t: got b",$time);
     (9)          @(c) $display("%t: got c",$time);
    (10)        join
    (11)        $display("%t: done with fork",$time);
    (12)      end
    (13)
    (14)    initial
    (15)      begin
    (16)        #1 a = 1;
    (17)        #1 b = 1;
    (18)        #1 c = 1;
    (19)      end
    (20)
    (21)  endmodule

When simulated, this example would produce the output:

    1: got a
    2: got b
    3: got c
    3: done with fork

The three threads at Lines (7), (8) and (9) are started in parallel. Each of those threads immediately suspend waiting for changes in `a`, `b` and `c`, respectively. The `initial` block at Line (14) also begins executing at time 0, then sets `a`, `b` and `c` in order with a 1 time unit delay between each assignment. As each assignment occurs, one of the forks in the `fork...join` sees the change, prints its message and terminates. When all three forks of the `fork...join` have terminated, execution continues in the main thread after the `fork...join` and the "done with fork" message is displayed.

#### 4.8.13 Tasks

Tasks are similar to function calls in C. Tasks are defined in the context of a module. They begin with the `task` keyword, and are followed by the task name, an optional parameter list, a body, and the `endtask` keyword. The body can contain any of the statements that may appear of the behavioral Verilog statements described in this section. Tasks may address both local variables defined within them and variables in the parent module. Here is example of a module that defines and uses a task:

     (1)  module top;
     (2)    reg [15:0] s1,s2;
     (3)
     (4)     task domult(input [15:0] a, input [15:0] b, output [15:0] z);
     (5)       begin
     (6)         #1 z = a * b;
     (7)       end
     (8)     endtask
     (9)
    (10)     initial
    (11)       begin
    (12)         domult(3,5,s1);
    (13)         $display("%t: s1=%d",$time,s1);
    (14)         domult(7,11,s2);
    (15)         $display("%t: s2=%d",$time,s2);
    (16)       end
    (17)
    (18)  endmodule

The task `domul` take two inputs `a` and `b`, delays for one epoch, then stores their product in the output `z`. We make two calls in to `domul` in the main body of the module, assigning values to `s1` and `s2`. When simulated, this module will produce the output:

    1: s1=15
    2: s2=77

Tasks can use `input`, `output` and `inout` ports declared in their parameter list as shown on Line (4) of the example. These ports can either be declared in a port list as shown in the example, or they may be declared in separate declarations as in:

        task domult;
        input [15:0] a, b;
        output [15:0] z;
          begin
            #1 z = a * b;
          end
        endtask

It is also possible to have tasks with no ports as in this example:

     (1)  module myclock(x);
     (2)  output reg x;
     (3)
     (4)    task initialize_clock;
     (5)      begin
     (6)        x = 1'b0;
     (7)      end
     (8)    endtask
     (9)
    (10)    initial
    (11)       initialize_clock();
    (12)
    (13)    always
    (14)       #100 x = ~x;
    (15)
    (16)  endmodule

In this example, the `initialize_clock` task sets the register `x` to 0. By placing all the initialization code in a task, we have made our design more general. If future versions of our module become more complex, we have a place to put any additional initialization code.

Additional local variables can be declared before the `begin...end` block inside the task. For example:

        task printbits(input [7:0] a);
          integer i;

          begin
            $display("Here are the bits in %d:",a);
            for (i = 0;i < 8;i = i + 1)
              $display("   bit %d is %b.",i,a[i]);
          end
        endtask

will print out:

    Here are the bits in 184:
       bit 0 is 0
       bit 1 is 0
       bit 2 is 0
       bit 3 is 1
       bit 4 is 1
       bit 5 is 1
       bit 6 is 0
       bit 7 is 1

when invoked with `printbits(184)`.

One important difference between Verilog tasks, and C functions is that local variables are shared across all invocations of the task. This can cause problems when a task is invoked concurrently on two different threads. For example, consider this module in which `domult` is invoked concurrently in two different threads of a `fork...join` block:

     (1) module top;
     (2)   reg [15:0] s1,s2;
     (3)
     (4)   task domult(input [15:0] a, input [15:0] b, output [15:0] z);
     (5)     begin
     (6)       #1 z = a * b;
     (7)     end
     (8)   endtask
     (9)
    (10)   initial
    (11)     fork
    (12)       begin
    (13)         domult(3,5,s1);
    (14)         $display("%t: s1=%d",$time,s1);
    (15)       end
    (16)       begin
    (17)         domult(7,11,s2);
    (18)         $display("%t: s2=%d",$time,s2);
    (19)       end
    (20)    join
    (21)
    (22)  endmodule

When this module was simulated,the following seemingly incorrect output was produced:

    1: s1=77
    1: s2=77

The problem is that since, the local variables `a` and `b` are shared between the two invocations, which ever invocation gets invoked second, will overwrite those values. In this case, the invocation at Line (17) was invoked second, so by the time Line (6) is called, `a` and `b` have been set to 7 and 11 in both invocations. In general, the values of `a` and `b` are non-deterministic since there is no guarantee as to which thread will execute first. To solve this problem, you can use the `automatic` keyword in the task declaration, writing:

     (4)   automatic task domult(input [15:0] a, input [15:0] b, output [15:0] z);
     (5)     begin
     (6)       #1 z = a * b;
     (7)     end
     (8)   endtask

in place of Lines (4) through (8) above. The `automatic` keyword causes local variables in a task to be private to each invocation at a slight performance penalty to the simulation. When this corrected design is simulated, the simulator output becomes:

    1: s1=15
    1: s2=77

This agrees more with our expectations, although technically, the order in which the two output lines is printed is still non-deterministic.

#### 4.8.14 Functions

Functions are very similar to tasks, but have some additional restrictions. They must

- return a single value,
- use only `input` ports,
- must not contain any delay or event-triggered statements, and
- must not contain any non-blocking assignments.

Unlike tasks, functions can also be used in `assign` statements outside of normal behavioral Verilog blocks. Here is an example of a function definition and invocation:

     (1)  module top;
     (2)    reg [15:0] s1,s2;
     (3)
     (4)     function [15:0] sqaddmult(input [15:0] a, input [15:0] b, input [15:0] c);
     (5)       reg [15:0] temp;
     (5)       begin
     (6)         temp = b + c;
     (7)         sqaddmult = a * temp * temp;
     (8)       end
     (9)     endtask
    (10)
    (11)     initial
    (12)       begin
    (13)         #1 $display("%t: s1=%d",$time,sqaddmult(3,4,5));
    (14)         #1 $display("%t: s2=%d",$time,sqaddmult(6,7,8));
    (15)       end
    (16)
    (17)  endmodule

This function adds `b` and `c`, squares the sum and puts the result into the temporary variable `temp`, then multiplies `temp` by the value of `a`. The return value of the function is indicated by the assignment to `sqaddmult`, the name of the function. The `[15:0]` after the `function` keyword in Line 4 tells us that the return value is 16 bits.

Just as with tasks, you can also use the alternate syntax:

         function [15:0] sqaddmult;
         input [15:0] a, b, c;

to declare the function and its ports. Also just like with tasks, local variables are shared among invocations unless you use the `automatic` keyword before `function`. However, due to a limitation in the TkGate Verilog simulator implementation, you can only use `automatic` to protect against alternate threads accessing the same function, you can not use it to write recursive functions.

One use of functions is to define complex combinational logic in a concise algorithmic manner such as:

     (1)  module mylogic(x,a,b,c);
     (2)  output [15:0] x;
     (3)  input [15:0] a,b,c;
     (4)
     (5)    function foo(input [15:0] a,input [15:0] b,input [15:0] c);
     (6)      begin
     (7)        r1 = (a[7:0] ^ b[7:0] ^ c[7:0]) + (a[15:8] ^ b[15:8] ^ c[15:8]);
     (8)        r2 = (a[7:0] ^ b[15:8] ^ c[7:0]) + (a[15:8] ^ b[7:0] ^ c[15:8]);
     (9)        r3 = (a[7:0] ^ b[7:0] ^ c[15:8]) + (a[15:8] ^ b[15:8] ^ c[7:0]);
    (10)        r4 = (a[7:0] ^ b[15:8] ^ c[15:8]) + (a[15:8] ^ b[7:0] ^ c[7:0])
    (11)        foo = r1 ^ r2 ^ r3 ^ r4;
    (12)      end
    (13)    endfunction
    (14)
    (15)    assign x = foo(a,b,c);
    (16)
    (17)  endmodule

### 4.9 Module Parameters

The `parameter` variable type was introduced in Section 4.3.6. You can also declare module parameters that can be overridden by instantiating modules. Module parameters are declared in a separate list before the port list. This list has the syntax:
`#( .`name1`(`value1`),` .name2`(`value2`),` ...`)`
The names name1, name2, etc. are the names of the module parameters, and the values value1, value2, etc. are the default values of those parameters. As an example, consider this module implementing and AND gate with a parameter `delay` for specifying the delay.

     (1) module AND2 #(.delay(5)) (z, a, b);
     (2) output z;
     (3) input a,b;
     (4)
     (5)   assign #delay z = a & b;
     (6)
     (7) endmodule

The default value for `delay` in this example is 5. When overriding the module parameters in an instantiation, the parameter list is specified after the module name, but before any instance names. For example:

     (1) module ADDER(s, co, a, b, ci);
     (2) output s, co;
     (3) input a,b,ci;
     (4) wire w1,w2,w3 ;
     (5)
     (6)   OR2 #(6) g1 (.a(w1), .b(w2), .z(co));
     (7)   AND2 #(6) g2 (.a(a), .b(b), .z(w2));
     (8)   AND2 #(7) g3 (.a(w3), .b(ci), .z(w1));
     (9)   XOR2 #(8) g4 (.a(w3), .b(ci), .z(s));
    (10)   XOR2 #(8) g5 (.a(a), .b(b), .z(w3));
    (11)
    (12) endmodule

This would create a design where the delay of instance `g2` is 6, and the delay of `g3` is 7. You can also omit the parameter values entirely writing:

          AND2 g2 (.a(a), .b(b), .z(w2));

to use the default values of the parameters.

### 4.10 Specify Blocks

Specify blocks are an alternative way to specify the delay of combinational logic without specifying gate-by-gate delay. They can also be used to specify setup and hold times for registers in your design.

A specify block is delimited by the `specify...endspecify` keywords. Each statement in a specify block is either a path delay statement, or a constraint task used to verify timing constraints.

#### 4.10.1 Path Delay Statements

Path delay statements specify the delay from one or more input ports to one or output ports. The syntax is:
`(`in1`,` in2`,` ...`*>` out1`,` out2`,` ...`) =` value`;` or `(`in1`,` in2`,` ...`=>` out1`,` out2`,` ...`) =` value`;`
where in1, in2, etc. are `input` ports and out1, out2, etc. are `output` ports. These expressions specify a delay of value from each of the input ports to each of the output ports. The Verilog specification differentiates between the `=>` and `*>` versions in that the `=>` only specifies delay for corresponding bits of each port, while the `*>` specifies delay from each bit of each input port to every bit of each output port. However, the TkGate Verilog simulator does not support bit-by-bit delay specifications, so in TkGate, both forms are treated the same as `*>`.

Here is an example of a combinational logic circuit using a `specify` block:

     (1)   module dosomething(a,b,c,x,y,z);
     (2)   input a,b,c;
     (3)   output x,y,z;
     (4)   wire q,r;
     (5)
     (6)     specify
     (7)       (a,b *> x) = 12;
     (8)       (c *> x) = 8;
     (9)       (a *> y) = 11;
     (10)      (c *> y) = 16;
     (11)      (b *> z) = 23;
     (12)      (c *> z) = 18;
     (13)    endspecify
     (14)
     (15)    assign r = q & c;
     (16)    assign x = a ^ b ^ r;
     (17)    assign y = a & c;
     (18)    assign z = c & b;
     (19)    assign q = a & b;
     (20)
     (21)  endmodule

The statement at Line 7 states that any changes on `a` or `b` will be reflected at `x` after 12 time units. Changes on `c` will appear at `x` after 8 time units, and so on.

A path delay statement may also have a condition attached to it using the `if` keyword. For example:

    module XOR(a,b,x);
    input a,b;
    output x;

      specify
        if (a) (a *> x) = 10;
        if (!a) (a *> x) = 21;
        (b *> x) = 12;
      endspecify

      assign x = a ^ b;

    endmodule

This will implement an XOR gate that has a delay of 10 when `a` has a 1 value, and a delay of 21 when `a` has a value of 0. The delay from input `b` is 12, irregardless of the input values. There is no `else` in the `if` clause used with path delay statements, so you must ensure that you cover every possible condition.

#### 4.10.2 Specparam Declarations

You can define parameters for use exclusively within a `specify` block using the `specparam` keyword. You can assign either a constant, or an expression using other `specparam` parameters, or `parameter` variables defined in the module. Here is an example using a `specparam`:

      specify
        specparam ab_delay = 7;
        (a *> b) = ab_delay;
      endspecify

#### 4.10.3 Constraint Tasks

Another use of `specify` blocks is to ensure that certain timing constraints are met. For example, most real hardware latches require that the input data line be held constant for some time period before the clock arrives. This is called "setup" time. There is also often a constraint that the input data line hold its value for some time period after the clock pulse. This is called "hold" time. There may also be width restrictions on the clock used to drive the latch. The example below uses a `specify` block to encode all of these requirements. Each of the statements in the `specify` block will be addressed in turn.

    module latch(ck,data,out);
    input ck,data;
    output out;
    reg out = 1'bx;

      specify
        $setup(data, posedge ck, 10);
        $hold(posedge ck, data, 10);
        $width(posedge ck, 25);
      endspecify

      always @(posedge ck)
        out = data;

    endmodule

##### The `$setup` Check

The `$setup` check has the syntax:
`$setup(`data`,` clock`,` limit `)`
It is used to verify that a setup constraint is satisfied. The data parameter should reference the data line on which you wish to perform the setup check. The clock parameter specifies the clock event for which the data must be set up. The limit parameter specifies the minimum delay time allowed between the data event and the clock event. If this constraint is violated, the TkGate Verilog simulator will issue a warning message, but normal simulation of the circuit will continue.

You can conditionally execute a check using the `&&&` operator in the clock parameter. For example:

        $setup(data, posedge ck &&& enable, 10);

would only perform the setup check if the `enable` signal were asserted.

##### The `$hold` Check

The `$hold` check has the syntax:
`$hold(` clock`,` data`,` limit `)`
It is used to verify that a hold constraint is satisfied. The clock parameter references the clock event which begins the hold period. The data parameter indicates the data signal that must be held constant during the hold period. The limit indicates the time period for which the data line can not change after the clock event. If this constraint is violated, the TkGate Verilog simulator will issue a warning message, but normal simulation of the circuit will continue.

Like with the `$setup` check, you can use the `&&&` operator in the clock parameter to set a condition on when to do the check.

##### The `$width` Check

The `$width` check as the syntax:
`$width(` event`,` limit `)`
It is used to verify that the width of a pulse exceeds a minimum value. The event parameter indicates an event (rising or falling) on the signal that is to be tested. The `posedge` and `negedge` keyword are used to indicate on which edge to start the test. For example:

        $width(posedge ck, 25);

will check that the time the time between the positive/rising edge of `ck`, and the opposite (in this case negative/falling) edge of `ck` is at least 25 time units. If this constraint is violated, the TkGate Verilog simulator will issue a warning message, but normal simulation of the circuit will continue.