Verilog Parameters: Making Modules Configurable

Constants With a Twist

A parameter is a constant - the compiler picks its value and bakes it into the design before simulation starts. The twist is that whoever instantiates the module can change the value. The same module source file can produce circuits of different sizes depending on how callers parameterize it.

That's how you build reusable IP. A FIFO module with WIDTH and DEPTH parameters can serve every team in a company. A counter with a WIDTH parameter is the same source whether it counts to 16 or 4 billion.

Basic Parameter Declaration

module counter #(
    parameter WIDTH = 8
)(
    input  wire             clk,
    input  wire             reset,
    output reg  [WIDTH-1:0] count
);
    always @(posedge clk) begin
        if (reset) count <= 0;
        else       count <= count + 1;
    end
endmodule

module test;
    reg clk = 0;
    reg reset = 1;
    wire [7:0] count8;
    wire [15:0] count16;

    // Default WIDTH = 8
    counter dut8(.clk(clk), .reset(reset), .count(count8));

    // Override WIDTH to 16 for this instance
    counter #(.WIDTH(16)) dut16(.clk(clk), .reset(reset), .count(count16));

    always #5 clk = ~clk;

    initial begin
        #12 reset = 0;
        #40 $display("after 4 clocks: count8=%0d count16=%0d", count8, count16);
        $finish;
    end
endmodule

Three pieces of new syntax:

1. Parameter block: #( parameter WIDTH = 8 ) between the module name and the port list. The default value 8 is what the module uses when nobody overrides.
2. Use site: output reg [WIDTH-1:0] count. The parameter is just a constant - we plug it into the bit range. Same module source produces an 8-bit or 16-bit output depending on WIDTH.
3. Override syntax: counter #(.WIDTH(16)) dut16(...) at instantiation time. The #(...) block goes before the instance name, after the module name. Any parameters you don't mention keep their defaults.

localparam: Internal Constants

There are constants you don't want callers to override. State encodings are the classic case:

module fsm(input wire clk, input wire reset, input wire go, output reg busy);
    // States are an implementation detail; nobody outside should care.
    localparam IDLE    = 2'd0;
    localparam RUNNING = 2'd1;
    localparam DONE    = 2'd2;

    reg [1:0] state;

    always @(posedge clk) begin
        if (reset) state <= IDLE;
        else begin
            case (state)
                IDLE:    if (go) state <= RUNNING;
                RUNNING: state <= DONE;
                DONE:    state <= IDLE;
            endcase
        end
    end

    always @(*) busy = (state != IDLE);
endmodule

module test;
    reg clk = 0;
    reg reset = 1;
    reg go = 0;
    wire busy;

    fsm dut(.clk(clk), .reset(reset), .go(go), .busy(busy));

    always #5 clk = ~clk;

    initial begin
        #12 reset = 0;
        #5  go = 1;
        #10 go = 0;
        #40 $finish;
    end

    always @(posedge clk) $display("t=%0t state=%0d busy=%b", $time, dut.state, busy);
endmodule

localparam makes IDLE, RUNNING, DONE available inside the module but not overrideable from instantiation. That's the right choice - changing what state value means IDLE from outside the module would be terrifying.

Use parameter for things callers should configure (widths, depths, behavior options) and localparam for everything else. A common pattern is to derive localparams from parameters:

parameter WIDTH = 32;
localparam WIDTH_M1 = WIDTH - 1;   // computed once; not overrideable

Parameterized Widths in Practice

The most common use of parameters is to make bus widths flexible. Here's an adder that works at any width:

module adder #(
    parameter WIDTH = 8
)(
    input  wire [WIDTH-1:0] a,
    input  wire [WIDTH-1:0] b,
    output wire [WIDTH:0]   sum    // +1 for carry-out
);
    assign sum = a + b;
endmodule

module test;
    reg  [3:0]  a4, b4;
    wire [4:0]  sum4;
    reg  [15:0] a16, b16;
    wire [16:0] sum16;

    adder #(.WIDTH(4))  small(.a(a4),  .b(b4),  .sum(sum4));
    adder #(.WIDTH(16)) big  (.a(a16), .b(b16), .sum(sum16));

    initial begin
        a4  = 4'd9;       b4  = 4'd8;
        a16 = 16'd60000;  b16 = 16'd10000;
        #1;
        $display("small: %0d + %0d = %0d", a4,  b4,  sum4);
        $display("big  : %0d + %0d = %0d", a16, b16, sum16);
        $finish;
    end
endmodule

One source file, two instances, two different widths, no copy-paste. That's the entire payoff of parameters.

Multiple Parameters, Named Override

For larger modules you'll often have several parameters. Override them by name in any order:

module fifo #(
    parameter WIDTH = 8,
    parameter DEPTH = 16,
    parameter AFULL = DEPTH - 2
)(
    input  wire             clk,
    input  wire             reset,
    // ... ports ...
);
    // ...
endmodule

// At the call site:
fifo #(.WIDTH(32), .DEPTH(1024)) cmd_queue (.clk(clk), .reset(reset), ...);

You don't have to override every parameter; un-mentioned ones keep their defaults. The AFULL default in the example is computed from DEPTH, which means if you override DEPTH, AFULL follows automatically - exactly the kind of dependency localparam would also handle if you didn't want callers to be able to override AFULL independently.

Common Mistakes

Forgetting the # in the override. counter (.WIDTH(16)) dut(...) looks like an override but Verilog reads (.WIDTH(16)) as a port connection. You need counter #(.WIDTH(16)) dut(...).

Using parameters where they aren't constant enough. Parameters resolve at elaboration time, before any signals exist. You can't parameterize on a runtime signal - if the value depends on what an input is doing at simulation time, it's not a parameter, it's logic.

Confusing parameter and localparam in port lists. Only parameter goes in the #(...) block at the top. localparam lives inside the body. The compiler will tell you if you swap them.

What Comes Next

You can now make modules whose size is set at compile time. The next two docs cover the rules for writing literal constants (8'h1F, 4'b1010, 32'd100) and the x and z values that show up when signals are undriven or contended. After that we move to operators - everything you can do with the vectors and parameters you've now seen.