Verilog User Defined Primitives

Verilog's built-in primitives, such as and, nand and not, cover the basic gates, but they are too limited for more complex cells like a multiplexer or a flip-flop. Verilog lets you define your own primitives, called User Defined Primitives (UDPs), which describe combinational or sequential behavior with a truth table instead of gates or procedural code.

12 min read | Beginner Level

What You'll Learn

• The rules for declaring a UDP and the symbols used in its table
• How to write a combinational UDP, using a 2:1 mux as the example
• How to write level-sensitive and edge-sensitive sequential UDPs, such as a latch and a flip-flop
• Where UDPs are used in practice, and the common mistakes when writing their tables

A UDP has a few rules that make it different from a module:

• It is declared with primitive ... endprimitive, outside of any module.
• It has exactly one output, which must be the first port in the port list, and can have many inputs. Simulators must support at least 9 inputs for sequential UDPs and 10 for combinational ones.
• All ports are 1-bit scalars. Vectors and inout ports are not allowed.
• The output can only be 0, 1 or x, never z. A z on an input is treated as x.
• The behavior is described in a state table between table and endtable. Any input combination that is not listed in the table produces x.

Verilog UDP Symbols

The table is written with the following symbols:

A transition is written in parentheses, such as (01) or (0?). The symbols -, transitions and edge letters can only be used in sequential UDPs.

Combinational UDP Example

In a combinational UDP, each row of the table lists the values of the inputs, in the same order as in the port list, followed by a colon and the output value. The 2:1 multiplexer below selects a when sel is 0 and b when sel is 1. The ? marks the input that is not selected, because its value does not affect the output.

// Output should always be the first signal in port list
primitive mux (out, sel, a, b);
  output  out;
  input   sel, a, b;

  table
    // sel  a   b     out
       0    1   ?  :  1;
       0    0   ?  :  0;
       1    ?   0  :  0;
       1    ?   1  :  1;
       x    0   0  :  0;
       x    1   1  :  1;
  endtable
endprimitive

The last two rows handle an unknown select: if a and b are equal, the output is known even though sel is not. Any combination missing from the table, such as sel = x with a = 0 and b = 1, gives x.

A UDP is instantiated like a gate primitive. Connections are by position only; named port connections such as .out(out) are not allowed.

module tb;
  reg       sel, a, b;
  reg [2:0] dly;
  wire      out;
  integer   i;

  // Instantiate the UDP - note that UDPs cannot
  // be instantiated with port name connection
  mux u_mux ( out, sel, a, b);

  initial begin
    a <= 0;
    b <= 0;

    $monitor("[T=%0t] a=%0b b=%0b sel=%0b out=%0b", $time, a, b, sel, out);

    // Drive a, b, and sel after different random delays
    for (i = 0; i < 10; i = i + 1) begin
      dly = $random;
      #(dly) a <= $random;
      dly = $random;
      #(dly) b <= $random;
      dly = $random;
      #(dly) sel <= $random;
    end
  end
endmodule

xcelium> run
[T=0] a=0 b=0 sel=x out=0
[T=4] a=1 b=0 sel=x out=x
[T=5] a=1 b=1 sel=x out=1
[T=10] a=1 b=1 sel=1 out=1
[T=15] a=0 b=1 sel=1 out=1
[T=28] a=0 b=0 sel=1 out=0
[T=33] a=0 b=0 sel=0 out=0
[T=38] a=1 b=0 sel=0 out=1
[T=40] a=1 b=1 sel=0 out=1
[T=51] a=1 b=1 sel=1 out=1
[T=54] a=0 b=0 sel=1 out=0
[T=62] a=1 b=0 sel=1 out=0
[T=67] a=1 b=1 sel=1 out=1
[T=72] a=0 b=1 sel=1 out=1
[T=80] a=0 b=1 sel=0 out=0
[T=84] a=0 b=0 sel=0 out=0
[T=85] a=1 b=0 sel=0 out=1
xmsim: *W,RNQUIE: Simulation is complete.

The first three lines show the x handling. sel is not assigned until T=10, so it is x. At T=0 both data inputs are 0, the row x 0 0 : 0 matches, and the output is 0. At T=4, a and b differ, no row matches, and the output becomes x. At T=5 they are equal again, and the output is 1. From T=10 on, out follows b whenever sel is 1 and a whenever sel is 0.

Sequential UDP Example

A sequential UDP has a memory: its output depends on the inputs and on the current value of the output. Its table therefore has an extra field for the current state, between the inputs and the next output:

// inputs  :  current state  :  next state

The output of a sequential UDP must also be declared as a reg. Its starting value can be set with an initial statement inside the primitive, such as initial q = 0;; without it, the output starts as x. Sequential UDPs are either level-sensitive or edge-sensitive.

Level-Sensitive UDPs

A level-sensitive UDP reacts to the current values of its inputs, like a latch. In the D latch below, q follows d while clk is 1. While clk is 0, the - in the output column means that q keeps its current value.

primitive d_latch (q, clk, d);
  output  q;
  input   clk, d;
  reg     q;

  table
    // clk  d     q     q+
       1    1  :  ?  :  1;
       1    0  :  ?  :  0;
       0    ?  :  ?  :  -;
  endtable
endprimitive

module tb;
  reg       clk, d;
  reg [1:0] dly;
  wire      q;
  integer   i;

  d_latch u_latch (q, clk, d);

  always #10 clk = ~clk;

  initial begin
    clk = 0;

    $monitor ("[T=%0t] clk=%0b d=%0b q=%0b", $time, clk, d, q);

    #10;  // To see the effect of X

    for (i = 0; i < 50; i = i+1) begin
      dly = $random;
      #(dly) d <= $random;
    end

    #20 $finish;
  end
endmodule

xcelium> run
[T=0] clk=0 d=x q=x
[T=10] clk=1 d=1 q=1
[T=13] clk=1 d=0 q=0
[T=14] clk=1 d=1 q=1
[T=17] clk=1 d=0 q=0
[T=20] clk=0 d=1 q=0
[T=28] clk=0 d=0 q=0
[T=30] clk=1 d=1 q=1
[T=38] clk=1 d=0 q=0
[T=39] clk=1 d=1 q=1
[T=40] clk=0 d=1 q=1
[T=42] clk=0 d=0 q=1
[T=47] clk=0 d=1 q=1
[T=50] clk=1 d=0 q=0
[T=55] clk=1 d=1 q=1
[T=59] clk=1 d=0 q=0
[T=60] clk=0 d=0 q=0
[T=61] clk=0 d=1 q=0
[T=64] clk=0 d=0 q=0
[T=67] clk=0 d=1 q=0
[T=70] clk=1 d=0 q=0
[T=73] clk=1 d=1 q=1
[T=74] clk=1 d=0 q=0
[T=77] clk=1 d=1 q=1
[T=79] clk=1 d=0 q=0
[T=80] clk=0 d=0 q=0
[T=84] clk=0 d=1 q=0
[T=86] clk=0 d=0 q=0
[T=87] clk=0 d=1 q=0
[T=90] clk=1 d=1 q=1
[T=91] clk=1 d=0 q=0
[T=100] clk=0 d=0 q=0
[T=110] clk=1 d=0 q=0
Simulation complete via $finish(1) at time 111 NS + 0

While clk is 1, every change of d appears on q immediately, for example at T=13, 14 and 17. While clk is 0, from T=40 to T=50, d changes but q holds 1. At T=20, clk falls in the same time step in which d changes to 1; the clock change is processed first, so the latch is already closed and q keeps 0.

Edge-Sensitive UDPs

An edge-sensitive UDP reacts to a transition on an input, written as (ab) or with an edge letter. The D flip-flop below loads d on the rising edge of clk and ignores everything else. Each row can contain at most one transition.

primitive d_flop (q, clk, d);
  output  q;
  input   clk, d;
  reg     q;

  table
    // clk     d       q     q+
    // obtain output on rising edge of clk
       (01)    0    :  ?  :  0;
       (01)    1    :  ?  :  1;
       (0?)    1    :  1  :  1;
       (0?)    0    :  0  :  0;

    // ignore negative edge of clk
       (?0)    ?    :  ?  :  -;

    // ignore data changes on steady clk
       ?       (??) :  ?  :  -;
  endtable
endprimitive

The rows (0?) 1 : 1 : 1 and (0?) 0 : 0 : 0 reduce x pessimism: if clk goes from 0 to x, it may or may not be a rising edge, but when d already equals q, the result is the same either way, so q can stay known instead of becoming x.

module tb;
  reg       clk, d;
  reg [1:0] dly;
  wire      q;
  integer   i;

  d_flop u_flop (q, clk, d);

  always #10 clk = ~clk;

  initial begin
    clk = 0;

    $monitor ("[T=%0t] clk=%0b d=%0b q=%0b", $time, clk, d, q);

    #10;  // To see the effect of X

    for (i = 0; i < 20; i = i+1) begin
      dly = $random;
      repeat(dly) @(posedge clk);
      d <= $random;
    end

    #20 $finish;
  end
endmodule

xcelium> run
[T=0] clk=0 d=x q=x
[T=10] clk=1 d=1 q=x
[T=20] clk=0 d=1 q=x
[T=30] clk=1 d=1 q=1
[T=40] clk=0 d=1 q=1
[T=50] clk=1 d=1 q=1
[T=60] clk=0 d=1 q=1
[T=70] clk=1 d=0 q=1
[T=80] clk=0 d=0 q=1
[T=90] clk=1 d=1 q=0
[T=100] clk=0 d=1 q=0
[T=110] clk=1 d=1 q=1
[T=120] clk=0 d=1 q=1
[T=130] clk=1 d=1 q=1
[T=140] clk=0 d=1 q=1
[T=150] clk=1 d=0 q=1
[T=160] clk=0 d=0 q=1
[T=170] clk=1 d=0 q=0
[T=180] clk=0 d=0 q=0
[T=190] clk=1 d=0 q=0
[T=200] clk=0 d=0 q=0
[T=210] clk=1 d=1 q=0
[T=220] clk=0 d=1 q=0
[T=230] clk=1 d=1 q=1
[T=240] clk=0 d=1 q=1
[T=250] clk=1 d=1 q=1
[T=260] clk=0 d=1 q=1
[T=270] clk=1 d=1 q=1
[T=280] clk=0 d=1 q=1
[T=290] clk=1 d=1 q=1
[T=300] clk=0 d=1 q=1
[T=310] clk=1 d=1 q=1
[T=320] clk=0 d=1 q=1
[T=330] clk=1 d=1 q=1
[T=340] clk=0 d=1 q=1
[T=350] clk=1 d=1 q=1
[T=360] clk=0 d=1 q=1
[T=370] clk=1 d=0 q=1
[T=380] clk=0 d=0 q=1
[T=390] clk=1 d=0 q=0
[T=400] clk=0 d=0 q=0
[T=410] clk=1 d=1 q=0
[T=420] clk=0 d=1 q=0
[T=430] clk=1 d=1 q=1
[T=440] clk=0 d=1 q=1
[T=450] clk=1 d=1 q=1
[T=460] clk=0 d=1 q=1
[T=470] clk=1 d=1 q=1
[T=480] clk=0 d=1 q=1
Simulation complete via $finish(1) at time 490 NS + 0

The testbench changes d with a nonblocking assignment right after a rising edge, so the flip-flop always samples the old value of d, and q follows d one clock cycle later. For example, d becomes 0 at T=70, and q becomes 0 at the next rising edge, T=90. At T=10, d was still x when the clock rose, no row matched, and q stayed x until the edge at T=30.

When a table contains both level-sensitive and edge-sensitive rows, the level-sensitive rows take priority. This is how an asynchronous reset is added to a flip-flop: a row such as 0 ? ? : ? : 0; for an active-low reset input overrides any clock edge.

Synthesis result: Most synthesis tools do not accept UDPs. A UDP describes behavior as a table for simulation, and synthesis needs RTL or library cells instead. Write synthesizable designs with always blocks and assign, which infer the same mux, latch and flip-flop.

Common Beginner Mistakes

primitive t_flop (q, clk, t);
  output q;
  input  clk, t;
  reg    q;

  initial q = 0;

  table
    // clk    t      q     q+
       (01)   0   :  ?  :  -;     // Hold
       (01)   1   :  0  :  1;     // Toggle 0 -> 1
       (01)   1   :  1  :  0;     // Toggle 1 -> 0
       (?0)   ?   :  ?  :  -;     // Ignore falling edge
       ?      (??) : ?  :  -;     // Ignore changes of t
  endtable
endprimitive