A module is a block of Verilog code that implements a certain functionality. Modules can be embedded within other modules and a higher level module can communicate with its lower level modules using their input and output ports.

Syntax

A module should be enclosed within module and endmodule keywords. Name of the module should be given right after the module keyword and an optional list of ports may be declared as well. Note that ports declared in the list of port declarations cannot be redeclared within the body of the module.

  
  
	module <name> ([port_list]);
		// Contents of the module
	endmodule
	
	// A module can have an empty portlist
	module name;
		// Contents of the module
	endmodule

  

All variable declarations, dataflow statements, functions or tasks and lower module instances if any, must be defined within the module and endmodule keywords. There can be multiple modules with different names in the same file and can be defined in any order.

Example

The module dff represents a D flip flop which has three input ports d, clk, rstn and one output port q. Contents of the module describe how a D flip flop should behave for different combinations of inputs. Here, input d is always assigned to output q at positive edge of clock if rstn is high because it is an active low reset.

  
  
// Module called "dff" has 3 inputs and 1 output port
module dff ( 	input 			d,
							input 			clk,
							input 			rstn,
							output reg	q);
			
	// Contents of the module	
	always @ (posedge clk) begin
		if (!rstn)
			q <= 0;
		else 
			q <= d;
	end
endmodule

  

Hardware Schematic

This module will be converted into the following digital circuit during synthesis.

Note that you cannot have any code written outside a module !

What is the purpose of a module ?

A module represents a design unit that implements certain behavioral characteristics and will get converted into a digital circuit during synthesis. Any combination of inputs can be given to the module and it will provide a corresponding output. This allows the same module to be reused to form bigger modules that implement more complex hardware.

For example, the DFF shown above can be chained to form a shift register.

  
  
module shift_reg ( 	input 	d,
										input  	clk,
										input 	rstn,
										output 	q);
			
	wire [2:0] q_net;
	dff u0 (.d(d), 				.clk(clk), .rstn(rstn), .q(q_net[0]));
	dff u1 (.d(q_net[0]), .clk(clk), .rstn(rstn), .q(q_net[1]));
	dff u2 (.d(q_net[1]), .clk(clk), .rstn(rstn), .q(q_net[2]));
	dff u3 (.d(q_net[2]), .clk(clk), .rstn(rstn), .q(q));
	
endmodule

  

Hardware Schematic

Note that the dff instances are connected together with wires as described by the Verilog RTL module.

Instead of building up from smaller blocks to form bigger design blocks, the reverse can also be done. Consider the breakdown of a simple GPU engine into smaller components such that each can be represented as a module that implements a specific feature. The GPU engine shown below can be divided into five different sub-blocks where each perform a specific functionality. The bus interface unit gets data from outside into the design, which gets processed by another unit to extract instructions. Other units down the line process data provided by previous unit.

Each sub-block can be represented as a module with a certain set of input and output signals for communication with other modules and each sub-block can be further divided into more finer blocks as required.

What are top-level modules ?

A top-level module is one which contains all other modules. A top-level module is not instantiated within any other module.

For example, design modules are normally instantiated within top level testbench modules so that simulation can be run by providing input stimulus. But, the testbench is not instantiated within any other module because it is a block that encapsulates everything else and hence is the top-level module.

Design Top Level

The design code shown below has a top-level module called design. This is because it contains all other sub-modules requried to make the design complete. The submodules can have more nested sub-modules like mod3 inside mod1 and mod4 inside mod2. Anyhow, all these are included into the top level module when mod1 and mod2 are instantiated. So this makes the design complete and is the top-level module for the design.

  
  
	//---------------------------------
	//  Design code
	//---------------------------------
	module mod3 ( [port_list] );
		reg c;
		// Design code
	endmodule
	
	module mod4 ( [port_list] );
		wire a;
		// Design code
	endmodule
	
	module mod1 ( [port_list] );	 	// This module called "mod1" contains two instances
		wire 	y;
	
		mod3 	mod_inst1 ( ... ); 	 		// First instance is of module called "mod3" with name "mod_inst1"
		mod3 	mod_inst2 ( ... );	 		// Second instance is also of module "mod3" with name "mod_inst2"
	endmodule

	module mod2 ( [port_list] ); 		// This module called "mod2" contains two instances
		mod4 	mod_inst1 ( ... );			// First instance is of module called "mod4" with name "mod_inst1"
		mod4 	mod_inst2 ( ... );			// Second instance is also of module "mod4" with name "mod_inst2"
	endmodule
	
	// Top-level module
	module design ( [port_list]); 		// From design perspective, this is the top-level module
		wire 	_net;
		mod1 	mod_inst1 	( ... ); 			// since it contains all other modules and sub-modules
		mod2 	mod_inst2 	( ... );
	endmodule

  

Testbench Top Level

The testbench module contains stimulus to check functionality of the design and is primarily used for functional verification using simulation tools. Hence the design is instantiated and called d0 inside the testbench module. From a simulator perspective, testbench is the top level module.

  
  
	//-----------------------------------------------------------
	// Testbench code
	// From simulation perspective, this is the top-level module
	// because 'design' is instantiated within this module
	//-----------------------------------------------------------
	module testbench; 												
		design d0 ( [port_list_connections] ); 	
		
		// Rest of the testbench code
	endmodule

  

Hierarchical Names

A hierarchical structure is formed when modules can be instantiated inside one another, and hence the top level module is called the root. Since each lower module instantiations within a given module is required to have different identifier names, there will not be any ambiguity in accessing signals. A hierarchical name is constructed by a list of these identifiers separated by dots . for each level of the hierarchy. Any signal can be accessed within any module using the hierarchical path to that particular signal.

  
  
	// Take the example shown above in top level modules
	design.mod_inst1 					// Access to module instance mod_inst1
	design.mod_inst1.y 					// Access signal "y" inside mod_inst1
	design.mod_inst2.mod_inst2.a		// Access signal "a" within mod4 module
	
	testbench.d0._net; 					// Top level signal _net within design module accessed from testbench

  

Hardware behavior cannot be implemented without conditional statements and other ways to control the flow of logic. Verilog has a set of control flow blocks and mechanisms to achieve the same.

if-else-if

This conditional statement is used to make a decision about whether certain statements should be executed or not. This is very similar to the if-else-if statements in C. If the expression evaluates to true, then the first statement will be executed. If the expression evaluates to false and if an else part exists, the else part will be executed.

Read more: Verilog Control Blocks

Placing values onto nets and variables are called assignments. There are three basic forms:

• Procedural
• Continuous
• Procedural continuous

Legal LHS values

An assignment has two parts - right-hand side (RHS) and left-hand side (LHS) with an equal symbol (=) or a less than-equal symbol (<=) in between.

The RHS can contain any expression that evaluates to a final value while the LHS indicates a net or a variable to which the value in RHS is being assigned.

  
  
module tb;
	reg clk;
	wire a, b, c, d, e, f;
	reg  z, y;
	
	// clk is on the LHS and the not of clk forms RHS
	always #10 clk = ~clk;
	
	// y is the LHS and the constant 1 is RHS
	assign y = 1; 
	
	// f is the LHS, and the expression of a,b,d,e forms the RHS
	assign f = (a | b) ^ (d & e);

	always @ (posedge clk) begin
		// z is the LHS, and the expression of a,b,c,d forms the RHS
		z <= a + b + c + d;
	end
	
	initial begin
		// Variable names on the left form LHS while 0 is RHS
		a <= 0; b <= 0; c <= 0; d <= 0; e <= 0;
		clk <= 0;
	end
endmodule

  

Procedural Assignment

Procedural assignments occur within procedures such as always, initial, task and functions and are used to place values onto variables. The variable will hold the value until the next assignment to the same variable.

The value will be placed onto the variable when the simulation executes this statement at some point during simulation time. This can be controlled and modified the way we want by the use of control flow statements such as if-else-if, case statement and looping mechanisms.

  
  
	reg [7:0]  data;
	integer    count;
	real       period;
	
	initial begin
		data = 8'h3e;
		period = 4.23;
		count = 0;
	end
	
	always @ (posedge clk) 
		count++;

  

Variable declaration assignment

An initial value can be placed onto a variable at the time of its declaration as shown next. The assignment does not have a duration and holds the value until the next assignment to the same variable happens. Note that variable declaration assignments to an array are not allowed.

  
  
	module my_block;
		reg [31:0] data = 32'hdead_cafe;
	
		initial begin
			#20  data = 32'h1234_5678;    // data will have dead_cafe from time 0 to time 20
			                              // At time 20, data will get 12345678
		end
	endmodule

  

  
  
	reg [3:0] a = 4'b4;
	
	// is equivalent to 
	
	reg [3:0] a;
	initial a = 4'b4;

  

If the variable is initialized during declaration and at time 0 in an initial block as shown below, the order of evaluation is not guaranteed, and hence can have either 8'h05 or 8'hee.

  
  
	module my_block;
		reg [7:0]  addr = 8'h05;
		
		initial 
			addr = 8'hee;
	endmodule

  

  
  
	reg [3:0] array [3:0] = 0;           // illegal
	integer i = 0, j;                    // declares two integers i,j and i is assigned 0
	real r2 = 4.5, r3 = 8;               // declares two real numbers r2,r3 and are assigned 4.5, 8 resp.
	time startTime = 40;                 // declares time variable with initial value 40

  

Procedural blocks and assignments will be covered in more detail in a later section.

Continuous Assignment

Click here for a step-by-step simulation example !

This is used to assign values onto scalar and vector nets and happens whenever there is a change in the RHS. It provides a way to model combinational logic without specifying an interconnection of gates and makes it easier to drive the net with logical expressions.

  
  
    // Example model of an AND gate
	wire  a, b, c;
	
	assign a = b & c;

  

Whenever b or c changes its value, then the whole expression in RHS will be evaluated and a will be updated with the new value.

Net declaration assignment

This allows us to place a continuous assignment on the same statement that declares the net. Note that because a net can be declared only once, only one declaration assignment is possible for a net.

  
  
	wire  penable = 1;

  

Procedural Continuous Assignment

These are procedural statements that allow expressions to be continuously assigned to nets or variables and are of two types.

• assign ... deassign
• force ... release

assign deassign

This will override all procedural assignments to a variable and is deactivated by using the same signal with deassign. The value of the variable will remain same until the variable gets a new value through a procedural or procedural continuous assignment. The LHS of an assign statement cannot be a bit-select, part-select or an array reference but can be a variable or a concatenation of variables.

  
  
	reg q;
	
	initial begin
		assign q = 0;
		#10 deassign q;
	end

  

force release

These are similar to the assign - deassign statements but can also be applied to nets and variables. The LHS can be a bit-select of a net, part-select of a net, variable or a net but cannot be the reference to an array and bit/part select of a variable. The force statment will override all other assignments made to the variable until it is released using the release keyword.

  
  
	reg o, a, b;
	
	initial begin
		force o = a & b;
		...
		release o;
	end

  

Parameters are Verilog constructs that allow a module to be reused with a different specification. For example, a 4-bit adder can be parameterized to accept a value for the number of bits and new parameter values can be passed in during module instantiation. So, an N-bit adder can become a 4-bit, 8-bit or 16-bit adder. They are like arguments to a function that are passed in during a function call.

  
  
	parameter MSB = 7;                  // MSB is a parameter with a constant value 7
	parameter REAL = 4.5;               // REAL holds a real number
	
	parameter FIFO_DEPTH = 256, 
	          MAX_WIDTH = 32;           // Declares two parameters
	          
	parameter [7:0] f_const = 2'b3;     // 2 bit value is converted to 8 bits; 8'b3

  

Parameters are basically constants and hence it's illegal to modify their value at runtime. It is illegal to redeclare a name that is already used by a net, variable or another parameter.

There are two major types of parameters, module and specify and both accepts a range specification. But, they are normally made as wide as the value to be stored requires them to be and hence a range specification is not necessary.

Module parameters

Module parameters can be used to override parameter definitions within a module and this makes the module have a different set of parameters at compile time. A parameter can be modified with the defparam statement or in the module instance statement. It is a common practice to use uppercase letters in names for the parameter to make them instantly noticeable.

The module shown below uses parameters to specify the bus width, data width and the depth of FIFO within the design, and can be overriden with new values when the module is instantiated or by using defparam statements.

  
  
	// Verilog 1995 style port declaration
	module design_ip  ( addr,  
	                    wdata,
	                    write,
	                    sel,
	                    rdata);
	                    
	     parameter  BUS_WIDTH    = 32, 
	                DATA_WIDTH   = 64,
	                FIFO_DEPTH   = 512;
	                
	     input addr;
	     input wdata;
	     input write;
	     input sel;
	     output rdata;
	     
	     wire [BUS_WIDTH-1:0] addr;
	     wire [DATA_WIDTH-1:0] wdata;
	     reg  [DATA_WIDTH-1:0] rdata;
	     
	     reg [7:0] fifo [FIFO_DEPTH];
	                
	     // Design code goes here ...
	endmodule

  

In the new ANSI style of Verilog port declaration, you may declare parameters as show below.

  
  
module design_ip 
	#(parameter BUS_WIDTH=32, 
		parameter DATA_WIDTH=64) (	
		
		input [BUS_WIDTH-1:0] addr,
   	// Other port declarations
   );

  

Overriding parameters

Parameters can be overridden with new values during module instantiation. The first part instantiates the module called design_ip by the name d0 where new parameters are passed in within #( ). The second part uses a Verilog construct called defparam to set the new parameter values. The first method is the most commonly used way to pass new parameters in RTL designs. The second method is commonly used in testbench simulations to quickly update the design parameters without having to reinstantiate the module.

  
  
module tb;
	
	  // Module instantiation override
		design_ip  #(BUS_WIDTH = 64, DATA_WIDTH = 128) d0 ( [port list]);
		
		// Use of defparam to override
		defparam d0.FIFO_DEPTH = 128;
		
endmodule

  

Example

The module counter has two parameters N and DOWN declared to have a default value of 2 and 0 respectively. N controls the number of bits in the output effectively controlling the width of the counter. By default it is a 2-bit counter. Parameter DOWN controls whether the counter should increment or decrement. By default, the counter will decrement because the parameter is set to 0.

2-bit up-counter

  
  
module counter
  #( 	parameter N = 2,
   		parameter DOWN = 0)
   		
  ( input 							clk,
    input 							rstn,
    input 							en,
   	output 	reg [N-1:0] out);
  
  always @ (posedge clk) begin
    if (!rstn) begin
      out <= 0;
    end else begin
      if (en)
        if (DOWN)
          out <= out - 1;
        else
          	out <= out + 1;
      else
         out <= out;     
    end
  end
endmodule

  

The module counter is instantiated with N as 2 even though it is not required because the default value is anyway 2. DOWN is not passed in during module instantiation and hence takes the default value of 0 making it an up-counter.

  
  
module design_top (    input clk,
                input rstn,
                input en,
                output [1:0] out);

    counter #(.N(2)) u0 (	.clk(clk),
                          .rstn(rstn),
                          .en(en));
endmodule

  

See that default parameters are used to implement the counter where N equals two making it a 2-bit counter and DOWN equals zero making it an up-counter. The output from counter is left unconnected at the top level.

4-bit down-counter

In this case, the module counter is instantiated with N as 4 making it a 4-bit counter. DOWN is passed a value of 1 during module instantiation and hence an down-counter is implemented.

  
  
module design_top (    input clk,
                input rstn,
                input en,
                output [3:0] out);

    counter #(.N(4), .DOWN(1)) 
    		u1 (	.clk(clk),
              .rstn(rstn),
              .en(en));
endmodule

  

Specify parameters

These are primarily used for providing timing and delay values and are declared using the specparam keyword. It is allowed to be used both within the specify block and the main module body.

  
  
	// Use of specify block
	specify
		specparam  t_rise = 200, t_fall = 150;
		specparam  clk_to_q = 70, d_to_q = 100;
	endspecify
	
	// Within main module
	module  my_block ( ... );
	 	specparam  dhold = 2.0;
	 	specparam  ddly  = 1.5;
	 	
	 	parameter  WIDTH = 32;
	endmodule

  

Difference between specify and module parameters