Verilog Functions

A Verilog function is a reusable block of code that takes one or more inputs, computes a result and returns a single value, much like a function in C. Functions run in zero simulation time: they cannot contain delays or wait for events, so they are used for combinational computations that would otherwise be repeated in several places.

12 min read | Beginner Level

What You'll Learn

• How to declare, return a value from and call a Verilog function
• What hardware a function synthesizes into
• The rules functions must follow, and when to use automatic
• How to use recursive and constant functions, and avoid common function bugs

Syntax

function [automatic] [return_type] name ([port_list]);
	[statements]
endfunction

• automatic - Gives every call its own copy of the function's variables, which is required for recursion (optional)
• return_type - A range such as [7:0], or a type such as integer. If left out, the function returns a single bit (optional)
• name - The function name, which also acts as the variable that holds the return value (required)
• port_list - One or more input arguments (at least one required)
• statements - The body; use begin ... end to group several statements

Functions are declared inside a module, outside any always or initial block, and can be called from anywhere in that module.

Function declarations

There are two equivalent ways to declare a function's inputs. In the first, the inputs are declared inside the function body, one declaration per line. In the second, which is more common in newer code, they are declared in a port list after the name, like the ports of a module.

function [7:0] sum;
	input [7:0] a, b;
	begin
		sum = a + b;
	end
endfunction

function [7:0] sum (input [7:0] a, b);
	begin
		sum = a + b;
	end
endfunction

Both versions describe the same function: it takes two 8-bit inputs and returns their 8-bit sum. Since the return type is [7:0], any carry out of bit 7 is dropped.

Returning a value from a function

The function declaration implicitly creates a variable with the same name and width as the function. Assigning a value to that variable sets the return value, and the value it holds when the function ends is what the caller receives.

sum = a + b;

Make sure every path through the function body assigns the return variable. If a path skips the assignment, the function returns whatever the variable held before, which is usually x in simulation and unpredictable logic in hardware.

Verilog uses the function name as the return variable. The return statement that some code uses was added in SystemVerilog and is not part of Verilog.

Calling a function

A function call is an expression, so it can appear anywhere a value is expected: on the right-hand side of an assignment, inside a condition, as an argument of another function, or in a continuous assign statement. The arguments are matched to the inputs in the order they were declared.

reg [7:0] result;
reg [7:0] a, b;

initial begin
	a = 4;
	b = 5;
	#10 result = sum (a, b);    // result becomes 9 at time 10
end

Functions in Synthesizable Design

Functions are fully synthesizable when they follow the rules below. This module converts two 4-bit binary values to Gray code using one function called twice:

module gray_pair (
  input  [3:0] bin_a,
  input  [3:0] bin_b,
  output [3:0] gray_a,
  output [3:0] gray_b
);

  // Binary to Gray: each Gray bit is the XOR of two neighboring binary bits
  function [3:0] bin2gray (input [3:0] b);
    begin
      bin2gray = b ^ (b >> 1);
    end
  endfunction

  // The same function is called twice, for two independent inputs
  assign gray_a = bin2gray(bin_a);
  assign gray_b = bin2gray(bin_b);

endmodule

Synthesis result: A function is not a shared hardware block that calls are routed to. The synthesis tool inlines the function body at every call site, so each call becomes its own copy of the logic. Here, the two calls build two separate sets of three XOR gates (bit 3 of the Gray code is just a wire from bit 3 of the input). See Verilog Binary to Gray for the conversion itself.

PPA Impact: Because every call adds a copy of the logic, a function that contains a multiplier or a wide adder, called in five places, builds five multipliers or adders. If the calls never need to run at the same time, share one instance through a mux instead.

Function rules

Because a function must finish in zero time and return exactly one value, Verilog places these restrictions on it:

• No timing controls: no # delays, no @ event controls and no wait statements
• It can call other functions, but it cannot call a task
• It must have at least one input, and it cannot have output or inout arguments
• It cannot use non-blocking assignments, force/release or assign/deassign
• It cannot trigger named events

When you need delays, timing, or more than one output, use a task instead. See Verilog Task.

Recursive Functions

By default, a Verilog function is static: all calls share one copy of its variables. If a function calls itself, the inner call overwrites the variables the outer call is still using. Declaring the function automatic gives every call its own copy, which makes recursion work.

module tb;
  integer result;

  initial begin
    result = factorial(4);
    $display("factorial(4) = %0d", result);
  end

	function automatic integer factorial (input integer i);
      integer result;   // Local: each call has its own copy because of "automatic"
      begin
        // This function is called within the body of this
        // function with a different argument
        if (i) begin
          result = i * factorial(i-1);
          $display("i=%0d result=%0d", i, result);
        end else
          result = 1;   // Base case: 0! = 1

        factorial = result;   // Set the return value
      end
	endfunction
endmodule

xcelium> run
i=1 result=1
i=2 result=2
i=3 result=6
i=4 result=24
factorial(4) = 24
xmsim: *W,RNQUIE: Simulation is complete

The call factorial(4) calls factorial(3), which calls factorial(2), and so on down to factorial(0), which returns 1 without printing. Each call prints only after the inner call returns, so the lines appear from i=1 upward as the calls unwind.

module fifo #(parameter DEPTH = 16) ( /* ports */ );

  // Number of bits needed to address DEPTH entries
  function integer clog2 (input integer value);
    integer v;
    begin
      v = value - 1;
      for (clog2 = 0; v > 0; clog2 = clog2 + 1)
        v = v >> 1;
    end
  endfunction

  localparam ADDR_W = clog2(DEPTH);   // 4 for DEPTH = 16; computed at elaboration

  reg [ADDR_W-1:0] wr_ptr, rd_ptr;

endmodule

module max4 (
  input  [7:0] a, b, c, d,
  output [7:0] m
);

  // Return the larger of two unsigned 8-bit values
  function [7:0] max2 (input [7:0] x, y);
    begin
      max2 = (x > y) ? x : y;
    end
  endfunction

  // Two first-round comparisons, then one final comparison
  assign m = max2(max2(a, b), max2(c, d));

endmodule