TKGate User Documentation (System Tasks)

## B. List of System Tasks

### B.1 Data Display Tasks

The system tasks described in this section generate output to the console. When simulating through the TkGate interface, the output will go to the simulator output console. When simulating in stand-alone mode with "Verga", output will go to the standard output.

#### B.1.1 $display

Usage: `$display(`arg1`,` arg2`,` ... `);`

This tasks outputs a message to the standard output when running Verga in standalone mode, and to the simulation console when running under TkGate. A newline is appended to the output. It is similar to the `printf()` function used in C.

Unlike the C `printf` function, the first argument is not necessarily a control string. The `$display` function can have from zero up to an arbitrary number of control strings. For example:

         integer r1,r2;

         r1 = 7; r2 = 12;
         $display(r1,r2);

will print:

    7 12

The same output could have been produced with a control string using the statement:

        $display("%d %d",r1,r2);

The general rule is that if an argument is a string, then it is treated as a control string and consumes as many arguments after it as there are conversions (e.g., "`%d`", etc.). If an argument is not a string, its value is printed. The format in which it is printed depends on the variable type. Unsized values are printed in decimal, sized values are printed using the Verilog hexadecimal notation. For example:

         integer r1;
         reg [16:0] r2;

         r1 = 7; r2 = 12;
         $display(r1,r2);

will print

    7 16'hc

When printing constants and expressions, `$display` will use the base specified in any constants. For example `$display(1'o0+r2)` would produce `16'o14`.

You can get greater control of the output using control strings with conversions. Strings are enclosed by the double quote character (`"`). Use a backslash (`\`) before a double quote to output the double quote itself and use `\\` to output a single backslash character. In addition, you can use "`\n`" to insert extra newlines into the output.

The conversions supported in Verga are (case is ignored):

Conversion | Description
--- | ---
`%%` | Output a single percent character.
`%m` | Output the name of the current module instance.
`%t` | Output a simulation time value. The raw simulation time in epochs is converted to the units specified in any ``timescale` declaration for the current module. If a precision smaller than the units is specified, then the time value will be output with a decimal point and the appropriate number of digits after the decimal point.
`%d` | Output a value in decimal format.
`%b` | Output a value in binary format.
`%h` | Output a value in hexadecimal format.
`%o` | Output a value in octal format.
`%c` | Output the character with the specified ASCII value.
`%s` | Output the value as a string.
`%f` | Output the value in floating point format.
`%g` | Output the value in floating point format while minimizing the number of characters needed.

The binary, hexadecimal and octal conversions output the raw number without the leading radix and bit-size indication. For example,

       $display("%h",8'h1e);

will output only "`1e`".

Like the C `printf()`, you can specify a number of spaces with the conversion. For example `%4h` will output a hexadecimal value in a four character field, padding with spaces if necessary. If you use leading zero as in `%04h`, then Verga will pad the output with zeros if necessary (e.g., "`16'h2e`" will be output as "`002e`").

As a final example including multiple control strings, consider the statement:

       $display(9," a=%d b=%d ",42, 77, 12,13," c=%d d=%d ",5,9, 88);

This will produce:

    9 a=42 b=77 12 13 c=6 d=9 88

#### B.1.2 $monitor

Usage: `$monitor(`arg1`,` arg2`,` ... `);`

The `$monitor` task formats the output from its arguments in exactly the same way as the `$display` task. The difference is that instead of outputting the text immediately, it places a watch on all variables referenced in the statement and outputs its message any time a variable changes. This can be used to generate a trace of any variable changes.

As an example, consider this module:

       module top;

         reg [15:0] a,b,c;

         initial
           $monitor("%t: a=16'h%04h  b=16'h%04h  c=16'h%04h",$time,a,b,c);

         initial
           begin
             #1 a = 'h4ef; b = 'h6def;
             #1 c = 'h84ff;
             #5 b = 42;

           end

       endmodule

When simulated, it will produce the following output:

    1: a=16'h04ef  b=16'h6def  c=16'hxxxx
    2: a=16'h04ef  b=16'h6def  c=16'h84ff
    7: a=16'h04ef  b=16'h002a  c=16'h84ff

Each time any of the variables `a`, `b` or `c` change, the `$monitor` task will output the stored line. In this example, we set `a` and `b` after one time step. The value of `c` was printed as `16'hxxxx` because it is still uninitialized. One time step later, we set `c`, then five time steps later we set `b`. This results in output from `$monitor` at times steps 1, 2 and 7.

Only one `$monitor` may be active at a time. If you call `$monitor` more than once, only the last call will remain in effect.

#### B.1.3 $monitoroff

Usage: `$monitoroff;`

This task temporarily disables a `$monitor` that has been placed. The monitor remains registered, but all output from it is disabled.

#### B.1.4 $monitoron

Usage: `$monitoron;`

This task re-enables a `$monitor` that has been disabled by `$monitoroff`.

#### B.1.5 $strobe

Usage: `$strobe(`arg1`,` arg2`,` ... `);`

The `$strobe` task formats the output from its arguments in exactly the same way as the `$display` task. The primary difference is that instead of outputting the message immediately, it waits until the end of the time step and does the output with the values at that time. It can be used when you want to ensure that you are outputting the final value of a variable for the time step. As an example, consider the module:

     (1)    module top;
     (2)     reg [15:0] a, b, c;
     (3)
     (4)     initial
     (5)       begin
     (6)         a = 4; b = 7; c = a + b;
     (7)         $strobe("%t: strobe a=%d b=%d c=%d",$time,a,b,c);
     (8)         $display("%t: display a=%d b=%d c=%d",$time,a,b,c);
     (9)         a = c*b;
     (10)        c = a + 9;
     (11)        #1 b = a + 99;
     (12)      end
     (13)
     (14)  endmodule

when this module is simulated, the following output is produced:

    0: display a=4 b=7 c=11
    0: strobe a=77 b=7 c=86

This `$display` tasks output the values as they are when `$display` is called, but `$strobe` waits until the end of the time step at Line 11 before it generates its output.

#### B.1.6 $write

Usage: `$write(`arg1`,` arg2`,` ... `);`

The `$strobe` task formats the output from its arguments in exactly the same way as the `$display` task. The only difference is that it does not append a newline. Use this task when you want to use multiple `$write` statements to construct a line of output. You can use a `\n` in a string to generate a newline.

### B.2 File Tasks

The tasks described in this section allow Verilog descriptions to open and write to files.

#### B.2.1 $fopen

Usage: descriptor`= $fopen(`file-name`);`

The `$open` task opens the specified file and returns a descriptor. The descriptor should be declared as an `integer`. Files are always open for writing, so any file you specify will be overwritten. You may have at most 31 files open at once. Below is an example, of how to use `$open` to open a file.

      integer d;

      initial
        begin
          d = $fopen("myfile.log");
          ...

You may use the bit-wise OR operator "`|`" to combine two or more descriptors. This will cause an write operations on that descriptor to output to all of the files combined in this way. You may also OR in the value "1" to include output to the console. For example, given the statements:

        d1 = $fopen("myfile1.log");
        d2 = $fopen("myfile2.log");
        d = d1 | d2 | 1;

writing to `d` will cause that output to be written to `myfile1.log`, `myfile2.log` and the standard output.

#### B.2.2 $fclose

Usage: `$fclose(`descriptor`);`

Closes the file or files referenced by the descriptor. If descriptor has been formed by ORing together two or more descriptors, all of the referenced files will be closed.

#### B.2.3 $fdisplay, $fmonitor, $fstrobe and $fwrite

Usage: `$fdisplay(`descriptor`,` arg1`,` arg2`,` ... `);`
Usage: `$fmonitor(`descriptor`,` arg1`,` arg2`,` ... `);`
Usage: `$fstrobe(`descriptor`,` arg1`,` arg2`,` ... `);`
Usage: `$write(`descriptor`,` arg1`,` arg2`,` ... `);`

These tasks operate in exactly the same way as their counter-parts without the leading "`f`", except that they take a descriptor as the first argument and write their output to the file (or files) referenced by that descriptor.

### B.3 Timing Check Tasks

The timing check tasks may only be used in the context of a `specify...endspecify` block. They are described briefly here, but more information on their use can be found in Section 4.10.3 Constraint Tasks.

#### B.3.1 $hold

Usage: `$hold(` clock`,` data`,` limit `);`

The `$hold` task generates a warning message when a hold-time constraint is not satisfied. clock specifies a clock event after which a data line must be held constant. data specifies the data signal that must not change for the hold period, and limit specifies the time periods for which changes in data are forbidden. The `$hold` task may only be used in a `specify` block.

#### B.3.2 $setup

Usage: `$setup(`data`,` clock`,` limit `);`

The `$setup` task generates a warning message when a setup-time constraint is not satisfied. data specifies the data signal that must not change for the setup period. clock specifies a clock event that ends the setup period, and limit specifies the length of the setup period. If the clock event occurs less than limit time steps from the last change of data, a warning message is generated. The `$setup` task may only be used in a `specify` block.

#### B.3.3 $width

Usage: `$width(` event`,` limit `);`

The `$width` task generates a warning message when a pulse width is shorter than a specified limit. event specifies the the leading edge of the pulse that is to be tested. Use the `posedge` or `negedge` keyword to indicate which edge is to be tested. limit is the minimum allowable pulse width. If the opposite transition is detected in fewer than limit time steps, then warning message will be generated. The `$width` task may only be used in a `specify` block.

### B.4 Simulation Information/Control and Miscellaneous Tasks

The tasks described in this section can be used to control the simulation, get information about the simulation, and do other miscellaneous tasks.

#### B.4.1 $finish

Usage: `$finish;`

This task terminates the simulation. If called while running Verga in stand-along mode, Verga will terminate immediately. If called from a description running under the TkGate, the simulator will terminate, and TkGate will revert to edit mode.

#### B.4.2 $stop

Usage: `$stop;`

This task suspends the simulation and puts it into pause mode. If called while running Verga in stand-along mode, it will have the same effect as `$finish`, terminating the simulation immediately. If called from a description running under the TkGate, the simulator will enter paused mode allowing you to examine the values of variables before unpausing the simulation.

#### B.4.3 $time

Usage: variable`= $time;`

This task returns the current simulation time. When assigning it to a variable, that variable should be declared as a `time` variable. This is normally a 64-bit integer. One of the most useful places to use `$time` is in conjunction with a `$display` or `$monitor` task to show the simulation time at which the output is produced. When using `$time` in this way, you should use the `%t` conversion in the control string.

#### B.4.4 $stime

Usage: variable`= $stime;`

This task returns the low 32 bits of the current simulation time. You may assign it to an `integer` variable.

#### B.4.5 $random

Usage: variable`= $random;`
Usage: `$random(`seed`);`

When called without an argument, this task returns a random number. When called with an argument, that argument is used as the seed value for the random number generator.

### B.5 Memory Tasks

These tasks can be used to save and load the contents of a memory to or from a file.

#### B.5.1 $readmemb and $readmemh

Usage: `$readmemb(`file`);`
Usage: `$readmemb(`file`,` memory`);`
Usage: `$readmemb(`file`,` memory`,` start`);`
Usage: `$readmemb(`file`,` memory`,` start`,` stop`);`
Usage: `$readmemh(`file`);`
Usage: `$readmemh(`file`,` memory`);`
Usage: `$readmemh(`file`,` memory`,` start`);`
Usage: `$readmemh(`file`,` memory`,` start`,` stop`);`

These tasks initialize one or more memories in a design from the contents of a file. The forms ending in "`b`" assume binary formatted data, while the forms ending in "`h`" assume hexadecimal formatted data. If only a file name is specified, then the name(s) of the memories to be initialized must be encoded in the file. If a memory is specified, than the file is loaded into that memory. You may also specify a start and stop address.

The file should contain a space separated list of values for the memory. The unknown (x) and floating (z) values may also be used in one or more bits. There are also several special control lines beginning with "`@`" that can be used to specify the memory, the address, or the radix of the file. An example of a memory file is shown below:

    @memory top.m
    @0
    3 4 9 16 25
    36 49 64 81

    @C
    100 x x 99 z 12 x8 z12

    @100
    4 3 9x x x11

    @1000000
    12 13 14 z 19 20 x x x 30 31

The `@memory top.m` specifies the name of the memory to be loaded. It should be a fully qualified path name. The `@0` line indicates that the following data is to be load beginning at address 0, the `@C` line indicates data to be loaded beginning at address hexadecimal `C`, and so forth. You can also use a line such as:

    @radix 8

To change the radix for data in the file to binary (2), octal (8), decimal (10) or hexadecimal (16).

#### B.5.2 $writememb and $writememh

Usage: `$writememb(`file`);`
Usage: `$writememb(`file`,` memory`);`
Usage: `$writememb(`file`,` memory`,` start`);`
Usage: `$writememb(`file`,` memory`,` start`,` stop`);`
Usage: `$writememh(`file`);`
Usage: `$writememh(`file`,` memory`);`
Usage: `$writememh(`file`,` memory`,` start`);`
Usage: `$writememh(`file`,` memory`,` start`,` stop`);`

These tasks write the contents of one or more memories to a file. The forms ending in "`b`" write the data in binary, while the forms ending in "`h`" write the data in hexadecimal. The files written are of a format suitable for being read by the `$readmemb` and `$readmemh` tasks. If only a file name is given, the contents of all memories in the design will be written. If a memory name is given, only the contents of that memory will be saved. You can also specify a start and stop address to save a portion of a memory. If there are large regions of uninitialized values in a memory, those values will not be explicitly saved. Only memory pages in which data has been stored will be saved to the file.

### B.6 TkGate-Specific Tasks

These tasks are tasks that are not part of the normal Verilog specification, but are specific to TkGate descriptions. These tasks all begin with the `$tkg` prefix. Most of these tasks are only useful when running a simulation under the TkGate GUI.

#### B.6.1 $tkg$command

Usage: `$tkg$command(`arg1`,` arg2`,` ... `);`

When the simulator is running under the TkGate GUI, TkGate and the simulator communicate over a pipe. This task writes a command from the simulator to TkGate directly on that pipe. The arguments are combined into a string in the same way as for `$display`, and the resulting string is feed directly to the TkGate GUI. When running Verga directly, this task performs identically to `$display`.

This task is subject to security settings set through the TkGate Security Options dialog box.

#### B.6.2 $tkg$exec

Usage: `$tkg$exec(`arg1`,` arg2`,` ... `);`

This task executes a Tcl/Tk command in the context of the TkGate GUI. It can be used to control a Virtual Peripheral Device (VPD), although its use for this purpose is currently discouraged. The `$tkg$post`, `$tkg$send` and `$tkg$recv` tasks are now the preferred tasks to use for interacting with VPDs.

When executing this task, the arguments are combined into a string in the same way as for `$display`, and the resulting string is sent to the TkGate GUI to be executed as a Tcl/Tk command. The command will only be executed if it is enabled through the TkGate Security Options dialog box. There are three possible security settings: fully enabled, enabled for registered functions, and disabled. When enabled only for registered functions, only Tcl commands that have been registered by a VPD on loading can be executed. Furthermore, the "[" and "]" characters are not allowed in the string. For more information on how to use this task in designing VPDs, see the section on Creating Virtual Peripheral Devices.

If running Verga directly, this task will simply print the simulator command requesting a Tcl/Tk command to be executed.

#### B.6.3 $tkg$post

Usage: `$tkg$post(`name`,` id`);`

This task is used to start/post a Virtual Peripheral Device (VPD). The name argument specifies the name of the VPD. The id argument specifies the name of a unique identifier for this instance of the VPD. Normally, the string `"%m"` should be specified as the id. The `"%m"` will be replaced with the instance name of the calling module in the same way that `"%m"` is expanded in the `$display` task. For more information on how to use this task in designing VPDs, see the section on Creating Virtual Peripheral Devices.

If running Verga directly, this task will simply print the simulator command requesting a VPD to be posted.

#### B.6.4 $tkg$probe

Usage: `$tkg$probe(`signal1`,` signal2`,` ...`);`

This task is used to set a probe on a signal or signals. You can list an arbitrary number of signals specified either with their local names, or with fully qualified path names. This task will cause the TkGate GUI to display the probed signals in the logic analyzer window and begin displaying value changes on those signals. You can use this task in a simulator script to setup the signals you want to probe at the beginning of a simulation.

If running Verga directly, this task will simply print the simulator command requesting a probe to be set, and print value changes on that signal until the probe is removed with and `$unprobe`.

If running Verga directly, this task will simply print the simulator command setting a probe and reporting the values on the probed signals.

#### B.6.5 $tkg$recv

Usage: value`= $tkg$recv(`channel`);`

The `$tkg$recv` task is used receive value on a channel from a Virtual Peripheral Device (VPD). A channel is essentially a queue that can be read to or written from either from the Tcl/Tk side of a VPD, or the Verilog side. The `$tkg$recv` task dequeues and returns the next value in the queue. If the queue is empty, the task blocks until a value is placed on the queue.

The channel name is an arbitrary string. Channels are dynamically created when referenced by a `$tkg$recv` or `$tkg$send` task. When used for communicating with a VPD, the channel name should be constructed from the VPD instance name (the same name used as the id in `$tkg$post`), followed by a "." character and a local name. This convention ensures that each instance of a VPD has its own set of channels to use. You can use `"%m"` in place of the instance name which will be replaced with the instance name for the current module.

For more information on how to use this task in designing VPDs, see the section on Creating Virtual Peripheral Devices.

While this task is primarily intended to be used for communication with VPDs, you can use it in conjunction with the `$tkg$send` task to send values from one Verilog thread to another.

#### B.6.6 $tkg$reportbreak

Usage: `$tkg$reportbreak(`id`,` value`);`

This task pauses the simulation and sends a command indicating that a breakpoint has fired. id is the name of the breakpoint, and value is the value that has caused the break. This task is primarily used for TkGate testing purposes.

#### B.6.7 $tkg$send

Usage: `$tkg$send(`channel`,` value`);`

The `$tkg$send` task is used send a value on a channel from the Verilog description to a Virtual Peripheral Device (VPD). A channel is essentially a queue that can be read to or written from either from the Tcl/Tk side of a VPD, or the Verilog side. The `$tkg$send` task enqueues a value on the queue for the specified channel.

The channel name is an arbitrary string. Channels are dynamically created when referenced by a `$tkg$recv` or `$tkg$send` task. When used for communicating with a VPD, the channel name should be constructed from the VPD instance name (the same name used as the id in `$tkg$post`), followed by a "." character and a local name. This convention ensures that each instance of a VPD has its own set of channels to use. You can use `"%m"` in place of the instance name which will be replaced with the instance name for the current module.

For more information on how to use this task in designing VPDs, see the section on Creating Virtual Peripheral Devices.

While this task is primarily intended to be used for communication with VPDs, you can use it in conjunction with the `$tkg$recv` task to send values from one Verilog thread to another.

#### B.6.8 $tkg$systime

Usage: value`= $tkg$systime;`

This task returns the current system time as a 64-bit `time` value with the number of milliseconds since January 1, 1970.

#### B.6.9 $tkg$unprobe

Usage: `$tkg$unprobe(`signal1`,` signal2`,` ...`);`

This task removes one or more probes set either with the `$probe` system task, or manually through the TkGate GUI.

#### B.6.10 $tkg$wait

Usage: `$tkg$wait(`value`);`

This task will block the calling thread for the specified number of milliseconds. The simulation itself will continue, and all other threads will advance normally (unless the calling thread is the only unblocked thread). As an example, consider the code fragment:

       always
         begin
           $tkg$wait(1000)
           $display("Hello World");
         end

This will cause the message "Hello World" to be printed once per second.

#### B.6.11 $tkg$waituntil

Usage: `$tkg$waituntil(`value`);`

This task blocks a thread in the same way as `$tkg$wait` until a specified absolute time. The `$tkg$systime` task should be used to get a reference time to be used with `$tkg$waituntil`. If the time specified by value is less than the current time, `$tkg$waituntil` will return immediately and do nothing. This task can be used to create real time clocks. For example, the following module generates a clock signals that oscillates once per second:

    module realclock(z);
    output reg z;
    time t;

      initial
        z = 1'b0;

      initial
        begin
          t = $tkg$systime;
          forever
            begin
              t = t + 500;
              $tkg$waituntil(t);
    	  z = ~z;
            end
        end

    endmodule

The advantage of using `$tkg$waituntil` instead of `$tkg$wait` to generate the clock signal is to avoid drift. If `$tkg$wait` were used instead, there would be additional real time delay as the simulation was running between calls to `$tkg$wait`. This small error would accumulate over time causing the number of oscillations to diverge from the proper value over a long time period.

Real time clocks such as this can be used to create real-time simulations of devices such as digital clocks, or other simulation using LEDs where you wish to run them synchronized with real time.

#### B.6.12 $tkg$zoom

Usage: `$tkg$zoom(`factor`);`

This task sets the zoom level in the TkGate scope window reletive to the default zoom factor. The factor parameter is an integer representing the zoom factor. A factor of 0 sets the default zoom factor. Negative values represent the number of zoom-out steps (showing more time on the x-axis), and positive values represent the number of zoom-in steps (showing less time on the x-axis).