Verilog Timeformat

The `timescale directive sets the time unit and precision of a simulation, but it does not decide how a time value looks when it is printed. That is the job of the system task $timeformat. It controls how the %t format specifier prints time in system tasks such as $display, $monitor, $write and $strobe: in which unit, with how many decimal places, with which suffix and in how wide a field.

9 min read | Beginner Level

What You'll Learn

• The four arguments of $timeformat and the default format of %t
• How the timescale and $timeformat together decide the printed time
• The difference between %t and %0t, and how the minimum field width pads the output
• Common $timeformat mistakes, such as a suffix that does not match the unit

Syntax

$timeformat(<unit_number>, <precision>, <suffix_string>, <minimum field width>);

The most common unit numbers are listed below. Every power of ten in between is valid too, for example -10 for 100 ps or -11 for 10 ps.

The setting is global: one call to $timeformat applies to every %t printed afterwards, in every module of the design, until the next call.

Synthesis result: None. $timeformat and $display are simulation-only system tasks, and synthesis tools ignore them. They are used in testbenches and models to produce readable log files.

Example #1: 1ns/1ps

The testbench below waits for a fractional delay, then prints the same time five times with different $timeformat settings. With a time unit of 1 ns and a precision of 1 ps, the delay #10.512351 is rounded to the nearest picosecond, which is 10.512 ns.

`timescale 1ns/1ps

module tb;
  reg a = 0;

  initial begin

    // Wait for some time - note that because precision is 1/1000 of
    // the main scale (1ns), this delay will be rounded at the 3rd
    // decimal position
    #10.512351;

    // Display current time with default timeformat parameters
    $display("[T=%0t] a=%0b", $realtime, a);

    // Change timeformat parameters and display again
    $timeformat(-9, 2, " ns");
    $display("[T=%0t] a=%0b", $realtime, a);

    // Remove the space in suffix, and extend fractional digits to 5
    $timeformat(-9, 5, "ns");
    $display("[T=%0t] a=%0b", $realtime, a);

    // Here suffix is wrong, it should not be "ns" because we are
    // setting display in "ps" (-12)
    $timeformat(-12, 3, " ns");
    $display("[T=%0t] a=%0b", $realtime, a);

    // Correct the suffix to ps
    $timeformat(-12, 2, " ps");
    $display("[T=%0t] a=%0b", $realtime, a);
  end
endmodule

xcelium> run
[T=10512] a=0
[T=10.51 ns] a=0
[T=10.51200ns] a=0
[T=10512.000 ns] a=0
[T=10512.00 ps] a=0
xmsim: *W,RNQUIE: Simulation is complete.

Line by line:

• Default: $timeformat has not been called, so time is printed in the smallest precision of the design (1 ps) with no decimals and no suffix: 10512.
• (-9, 2, " ns"): the time is converted to ns and printed with 2 decimals, so the third decimal is dropped: 10.51 ns.
• (-9, 5, "ns"): 5 decimals, and the suffix has no space, so it is joined to the number: 10.51200ns.
• (-12, 3, " ns"): the number is now in ps, but the suffix still says ns. The output 10512.000 ns is wrong by a factor of 1000, because $timeformat prints the suffix exactly as written and never checks it.
• (-12, 2, " ps"): number and suffix now agree: 10512.00 ps.

All the examples use %0t. The 0 removes the padding to the minimum field width, which is why no leading spaces appear even though the field width argument is left out.

IEEE 1364 defines $timeformat with all four arguments. Most simulators accept the shorter form used in this example, but passing all four, such as $timeformat(-9, 2, " ns", 10);, works with every tool.

Example #2: 1ns/100ps

This is the same example with a different timescale. Only the first line changes:

`timescale 1ns/100ps

xcelium> run
[T=105] a=0
[T=10.50 ns] a=0
[T=10.50000ns] a=0
[T=10500.000 ns] a=0
[T=10500.00 ps] a=0
xmsim: *W,RNQUIE: Simulation is complete.

With a precision of 100 ps, #10.512351 is rounded to the nearest 0.1 ns, which is 10.5 ns. The default line prints 105 because the default unit is now the smallest precision of the design, 100 ps, and 10.5 ns is 105 of those. The other lines show 10.50 ns, 10.50000 ns and 10500 ps: $timeformat can add as many decimal places as you ask for, but the digits beyond the precision are always zero, because the simulator never stored them.

Example #3: 100ns/1ns

Now the time unit is 100 ns and the precision is 1 ns:

`timescale 100ns/1ns

xcelium> run
[T=1051] a=0
[T=1051.00 ns] a=0
[T=1051.00000ns] a=0
[T=1051000.000 ns] a=0
[T=1051000.00 ps] a=0
xmsim: *W,RNQUIE: Simulation is complete.

The delay #10.512351 now means 10.512351 × 100 ns = 1051.2351 ns, which is rounded to the precision of 1 ns, giving 1051 ns. In the same way, #10 would mean 1000 ns. The default line prints in the precision of 1 ns, so it shows 1051, and the ns and ps lines show the same time with more decimals.

%t vs %0t and the Minimum Field Width

With plain %t, the time is right-aligned in a field of at least the minimum field width, 20 characters by default. With %0t, the padding is removed:

`timescale 1ns/1ps

module tb;
  initial begin
    #10.512;
    $display("[T=%t]",  $realtime);    // Default width of 20
    $display("[T=%0t]", $realtime);    // No padding

    $timeformat(-9, 2, " ns", 10);
    $display("[T=%t]",  $realtime);    // Width of 10
  end
endmodule

[T=               10512]
[T=10512]
[T=  10.51 ns]

The padding is useful in log files: when every time stamp has the same width, the messages after it line up in columns and are easier to scan. %0t is more compact and is common in short messages.

Common Beginner Mistakes

`timescale 1ns/10ps

module tb;
  initial begin
    #3.14159;
    $display("[%0t]", $realtime);
    $timeformat(-9, 1, " ns", 0);
    $display("[%0t]", $realtime);
    $timeformat(-12, 0, " ps", 0);
    $display("[%0t]", $realtime);
  end
endmodule

[314]
[3.1 ns]
[3140 ps]