The problem: a reuse at STAGES = 0

A delay pipeline is written for STAGES = 2. Later, a block that needs no delay reuses it with STAGES = 0. Nothing in the module rejects that value, so the storage range becomes [0:-1], which is two entries, not none. The output reads entry -1, which nothing ever writes.

1
2
3
4
5
6
7

// snippet: the unguarded body, instantiated with STAGES = 0
T stage_q [0:STAGES-1];            // [0:-1]: two entries
always_ff @(posedge clk) begin
  stage_q[0] <= data_i;
  for (int i = 1; i < STAGES; i++) stage_q[i] <= stage_q[i-1];
end
assign data_o = stage_q[STAGES-1]; // stage_q[-1]: never written

Simulated with an 8-bit type and data_i = 5a for four cycles, the two simulators disagree, and neither warns:

Icarus:    STAGES=0: data_i=5a data_o=xx
Verilator: STAGES=0: data_i=5a data_o=00

The bug surfaces far from its cause: X in one simulator, zeros in the other, and whatever the synthesis tool decides in silicon.

The guard

The fix checks the parameter before any storage is declared. An illegal value now stops the build with a message that names the module and the rule.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

module pipeline #(
  parameter type T = logic [31:0],
  parameter int STAGES = 2
) (
  input  logic clk,
  input  T     data_i,
  output T     data_o
);
  if (STAGES < 1) begin : g_bad_stages
    $error("pipeline: STAGES must be at least 1");  // elaboration-time check
    assign data_o = 'x;                              // keeps the bad build well-formed
  end else begin : g_pipeline
    T stage_q [0:STAGES-1];
    always_ff @(posedge clk) begin
      stage_q[0] <= data_i;
      for (int i = 1; i < STAGES; i++) stage_q[i] <= stage_q[i-1];
    end
    assign data_o = stage_q[STAGES-1];
  end
endmodule

• parameter type T passes a whole data type: width, signedness and any packed struct layout travel together.

• if (STAGES < 1) at module scope is a generate-if: it is decided while the design is built, not while it runs.

• $error inside that branch is an elaboration system task, so the build stops before any simulation or synthesis.

• assign data_o = 'x gives the illegal branch a driver, so the only message is the one you wrote.

• g_pipeline holds the real storage, declared only when STAGES is legal.

With STAGES = 0 the same instance now fails to build:

Icarus:
ERROR: pipeline.sv:10: pipeline: STAGES must be at least 1
       During elaboration  Scope: g_bad_stages

Verilator:
%Warning-USERERROR: pipeline.sv:10:5: pipeline: STAGES must be at least 1

Legal and illegal configurations

Test at least the minimum, a normal value and one more. Each row above is one elaboration of the same source.

Rules

• Use localparam for derived values callers must not override.

• Guard zero/one values before $clog2 or part-select expressions.

• Test minimum, non-power-of-two, and normal configurations.

• Do not use defparam; named parameter overrides keep hierarchy ownership visible.

Related topics

• Parameterization and generate

• Functions and tasks