5. Using the Simulator

5.1 Starting the Simulator

Figure 5.1: Simulator Mode Tab

Figure 5.2: Simulator Mode Module Hierarchy

The simulation will be performed with the designated root module at the top-level. The simulator internally expands any module instances in your circuit. While the simulator is active, the Module Hierarchy View changes to show the hierarchy of module instances as shown in

While the simulator is active you must navigate using either the Module Hierarchy , or by right clicking on a module and using " Open" and " Close". You can not use the Module List view to navigate since TkGate can not tell which instance of a module to open.

5.1.1 Simulator Console

(Click to Enlarge)

Figure 5.2: Simulator Console

The simulator console has four tabs with different pages of information. These four pages are:

Page	Description
	Message Page - This page displays messages from the console. Any output from $display or other system tasks generating output will be displayed here.
	Breakpoint Page - Displays breakpoints that have been set for the simulation and the status of those breakpoints.
	Script Page - Shows the loaded simulation scripts and their status.
	Simulation Control Page - Allows you to set options controlling the simulation such as the number of epochs to advance at a time when stepping through a simulation.

5.1.2 Simulator Control

Button	Description
	Run - Enters continuous simulation mode. The simulation will continue as long as there are events in the event queue. If there are any clock gates in your circuit, this will mean the simulation will continue indefinitely. If the circuit is combinational, the simulation will continue until the circuit reaches quiescence.
	Pause - Causes a continuously running simulation to stop.
	Step - Causes the simulation to advance a fixed number of epochs. The number of epochs to advance can be set on the simulation options menu. You can also invoke this command with the space-bar.
	Clock Step - Causes the simulation to advance to the rising edge of a clock. You can set the number of clock cycles to simulate and the number of epochs past the designated cycle to step (to allow time for registers to change value). The default is to trigger on any clock, but you can designate a specific clock in the simulator options menu. You can also invoke this command with the tab key.
	Stop - Causes the simulation to be terminated and all probes to be deleted.

(Click to Enlarge)

Figure 5.3: Simulator Console Control Page

5.2 Observing the Output

5.2.1 Current Value Display

Figure 5.3: Value Display

There is a slight delay between pressing the mouse button and displaying the value. This is because double clicks on a wire are used to set probes, so the delay must be long enough to determine that the mouse press is not a double click. By default, this delay is 333ms (1/3 of a second), but the delay may be changed through the Simulate Options dialog box.

5.2.2 Scope View

(Click to Enlarge)

Figure 5.4: Scope Window

You can slide the range of time displayed in the scope window by using the scroll bar for coarse changes, or by clicking and dragging in the trace part of the window for fine grain control. To zoom in, you can press the left mouse button while holding the shift key, press the '>' key, or press the button on the toolbar. To zoom out, you can press the right mouse button while holding the shift key, press the '<' key or press the button on the toolbar.

Scope	Description
	0 - Logic 0 or false (1 bit signals only)
	1 - Logic 1 or true (1 bit signals only)
	x - Unknown value
	z - Floating or high impedance
	L - Low (the signal is either floating or zero)
	H - High (the signal is either floating or one)
	Data - Data value on a multi-bit wire.

Figure 5.5: Logic Trace Values

The time-line on the scope window is displayed as a base value shown in the lower left corner, and an offset value shown along the bottom. In the example shown in Figure 5.4, the base value is 50016916ns (i.e., 0.05 simulated seconds). Each tick mark on the x-axis represents an additional 5000ns past the base time value.

The scope includes a cross hair that follows the mouse whenever it is in the scope window to help you correlate events across different traces. You can enable or disable the cross hairs with the button on the toolbar. The scope window toolbar also includes some of the same simulation control and other simulation-related buttons that are on the main TkGate window.

Figure 5.5 shows how the various logic values are displayed in the scope windows. On multi-bit wires, the value of the wire is displayed in hexadecimal, unless the scale is such that there is no room to display the value between when it starts and the next logic transition. In this case, it will first compress the value to a "#", and if there is no room to display that either, no value or symbol will be displayed. The colors used in the scope traces can be configured through the Color Options dialog box.

5.2.3 Printing Scope Traces

Figure 5.6: Print Region Selection

After you chosen a region, push the button on the toolbar of the scope window. This will bring up the Scope Print dialog box having an "Output" and a "Content" page. The "Output" page of this dialog box is the same as the "Output" page of the dialog box used to print circuits.

If you choose the "Save as Encapsulated Postscript" option, the "Content" page will be disabled, and the selected region of the trace will be written as a single Encapsulated Postscript figure suitable for inclusion in a document (e.g., by Latex).

(Click to Enlarge)

Figure 5.7: Scope Print Dialog Box

The "Scale Selection" allows you to set the amount of time to plot per line when generating output. You must be cautious to set this carefully, as too low a setting can result in trace output with a huge number of pages. To help you in setting this value, an estimate of the number of pages needed is displayed next to this selector. The default value for the "Line Length" is one full scale of the scope window at the current zoom setting.

5.3 Controlling the Input

5.3.1 Switches and Dip Switches

Figure 5.8: Dip Value
Dialog Box



Figure 5.9
TTY Device

5.3.2 TTYs

5.4 Setting Breakpoints

(Click to Enlarge)

Figure 5.10: Simulator Console Breakpoint Page

Breakpoints will be activated for any non-zero value of their condition expression. When one of the registered breakpoints is activated, the simulation will stop, and a symbol will appear in the "S" column of the breakpoint. Breakpoints are only triggered on transitions. If you press the button to resume the simulation, the simulation will continue until the breakpoint expression makes a new transition to a non-zero value.

The "ID" column of the breakpoint list indicates an identifying number for the breakpoint. The column labeled "S" indicates the state of the breakpoint. The state is indicated by one of the following symbols:

State	Description
	Error - There is an error such as a syntax error or undefined variable error in the breakpoint expression.
	Go - The breakpoint is active, but has not been tripped.
	Stop - The breakpoint has tripped, and simulation is stopped at this breakpoint.
	Disabled - The breakpoint has been temporarily disabled.
	Stand By - The breakpoint is ready and will be active when the simulator starts.

The "Value" column shows the current value of the breakpoint expression. If the expression is binary, the value will be a 1 or 0, but if it is a multi-bit expression, then it could be an arbitrary value.

There are two buttons to "Enable" and "Disable" a breakpoint. While a breakpoint is disabled, the breakpoint will remain in the breakpoint list, but its value will be ignored until you re-enable it.

5.5 Initializing Memories

@100
e1 f0 0 0 e1 e0 0 0
81 0 0 0 12 1 bd 0

@200
e 1 e1 d0 dc 7 85 0

130/ 2 0 ed 0 60 6 62 6
138/ ed 0 5e 6 1 0 85 0
140/ 81 0 0 0 26 4 69 f0

@memory memory.m1
@100
e1 f0 0 0 e1 e0 0 0
81 0 0 0 12 1 bd 0

@memory memory.m2
@100
62 65 61 6b 20 69 73 0a

@100
10 x 8x 3e z9 3a zx 9x

In many cases, memory files are initialized to act as microstores or to contain machine instructions for a user designed processor. In these cases, it is very tedious and error prone to explicitly specify the contents of the memory. For this reason, TkGate includes a tool, gmac, for compiling microcode and macrocode to TkGate-compatible memory files. Complete documentation on Gmac is given in a later section of this document.

5.6 Simulation Scripts

(Click to Enlarge)

Figure 5.11: Simulator Console Script Manager Page

Simulator script files use Verilog syntax. This section will give some simple examples of how to write scripts. More detailed information on Verilog format can be found in the chapter on Verilog Modules.

5.6.1 Loading Simulator Scripts

You can also arrange for simulation scripts to be automatically executed when you start the simulator by adding one or more simulation scripts in the circuit options dialog box.

The "S" column next to each simulator script indicates the state of the script. The state is one of the following:

State	Description
	Error - There is an error such as a syntax error or undefined variable error in the script.
	Go - The script is active and running.
	Stop - The script has completed executing.
	Disabled - Execution of the script is disabled.
	Stand By - The script is ready and will execute when the simulator is started.

5.6.2 Simulator Script Format

Most scripts are defined as a Verilog initial block. For example:

  initial
    begin
      $readmemh("test.mem");    // Load memory file "test.mem".
      $tkg$probe(a, b, c);      // Place probes on the signals a, b and c.
      repeat (5)                // Advance the simulator 5 steps of the
        @ (posedge clock);      //    clock named 'clock'.
      # 10;                     // Advance the simulator 10 epochs.
      $stop;                    // Stop the simulator and put it in "pause" mode.
    end

You can also define local variables in a simulator script. For example:

  integer i;

  initial
    begin
      for (i = 0;i < 10;i = i + 1)        // Loop ten times
        begin
          @ (posedge clock);              // Advance to rising edge of "clock".
          $display("%t: x=%h",$time,x);   // Print time and value of x signal.
        end
      $stop;                              // Pause the simulator.
    end

5.6.3 Setting Signal Values

Figure 5.12: Full Adder Circuit

  initial
    begin
      $tkg$probe(a,b,ci,s,co);
      ci = 0; a = 0; b = 0;
      #50 ci = 0; a = 0; b = 0;
      #50 ci = 0; a = 0; b = 1;
      #50 ci = 0; a = 1; b = 0;
      #50 ci = 0; a = 1; b = 1;
      #50 ci = 1; a = 0; b = 0;
      #50 ci = 1; a = 0; b = 1;
      #50 ci = 1; a = 1; b = 0;
      #50 ci = 1; a = 1; b = 1;
    end

    top.memctl.ttyreg = 8'h

5.6.5 Using Scripts for Test Vector Generation

  reg tempCout;                                    // Declare 1-bit variable for carry out
  reg [31:0] tempS;                                // Declare 32-bit variable for sum
  integer i;                                       // Declare index variable

  initial
    begin
      $random($tkg$systime);                       // Use system clock to set random seed
      for (i = 0;i < 10000; i = i + 1)             // Loop 10,000 times
        begin
          a = $random;                             // Pick random value for A
          b = $random;                             // Pick random value for B
          cin = $random;                           // Pick random value for carry-in

          # 50;                                    // Step 50 epochs

          tempCout = (33'h0 + a + b + cin) >> 32;  // Get correct carry out value
          tempS = a + b + cin;                     // Get correct sum value

          //
          // If output from the design is not as expected, print an error message
          // and stop the simulator. 
          //
          if ({cout,s} != {tempCout,tempS})
            begin
              $display("error: got 31'h%h + 31'h%h + 31'h%h = {1'h%h, 31'h%h}",a,b,cin,cout,s);
              $display(" -- should have gotten {1'h%h, 31'h%h}", tempCout, tempS);
              $stop;
            end
        end

      $display("test completed.");
      $stop;
    end

(Click to Enlarge)

Figure 5.13: Simulator Error List

Figure 5.14: Error Location Cross-hairs

In the example shown here, the module "ADD32" had an internal port name of "a", but the name "A" was erroneously used on the interface. The first error message indicates that the external port name "A" does not have a corresponding port inside, and the second error message indicates that the internal port "a", does not have a corresponding port on the outside.

5.8 Gate Delay Files

Each gate delay file should contain one or more technology blocks having the form:

technology cmos {
  ...
}

primitive mux {
  delay<I-Z> = (2*(num(S)+1) + 2*num(I)) + 2*(inv(I) || inv(Z)); 
  delay<S-Z> = (2*(num(S)+1) + 2*num(I));
  area = bits(Z)*((2*(num(S)+1) + 2*num(I)) + 2*inv(I)); 
}

Function	Description
num(p)	Normally, "p" specifies a group of related ports in which case this function returns the number of ports in the group. For example, on an n-input AND gate with inputs I1 through In, the expression num(I) would return n.
bits(p)	Returns the number of bits on the specified port. If "p" represents a group of ports, the highest bit-width of the group is returned.
inv(p)	When "p" is specific port, a 1 is returned if there is an inverter on the port, 0 otherwise. When "p" specifies a group of ports, the number of ports with inverters is returned.
log(expr)	Returns the ceiling of the base-2 log of an expression.

It is also possible to write procedural delay/area definitions. For example, consider the parameter specification for the "and" primitive.

primitive and {
  delay<I-Z> = {
    if ((inv(I) == num(I)))     // Determine if an inverter is necessary.  An
      d = inv(Z);               //   inverter is not required if the output is
    else if ((inv(I) == 0))     //   inverting and all inputs are non-inverting
      d = !inv(Z);              //   (i.e., it is an AND gate), or if all inputs
    else                        //   are inverting and the output is non-inverting
      d = 1;                    //   (i.e., it is a NOR gate). 

    if (num(I) == 1) {          // If one input, treat this as a reduction gate    
      return 2*bits(I0) + 2*d;  //   one Tr. delay per bit plus inverter delay.    
    } else {                    // If multiple inputs, treat this as a normal gate 
      return 2*num(I) + 2*d;    //   one Tr. delay per input plus inverter delay.  
    }
  }

  area = {
    if ((inv(I) == num(I)))     // Estimate number of inverters required.  If all
      d = inv(Z);               //   inputs are inverted, an inverter is required
    else if ((inv(I) == 0))     //   iff the output is inverted.  If all inputs
      d = !inv(Z);              //   are non-inverted, an inverter is required iff
    else                        //   the output is non-inverted.  Otherwise we need
      d = inv(I);               //   an inverter for each inverted input.

    if (num(I) == 1) {          // If one input, treat this as a reduction gate    
      a = 2*bits(I0) + 2*d;	//   one Tr. per bit plus inverter Trs.    
    } else {			// If multiple inputs, treat this as a normal gate 
      a = 2*num(I) + 2*d;	//   one Tr. per input plus inverter Trs.  
    }
    return bits(Z)*a;           // Multiply by number of bit slices.
  }
}

A technology block need not specify every single primitive type. For example, suppose we have a technology definition for CMOS which includes a definition for a buffer as shown here:

technology CMOS {
  primitive buf {
    delay<I-Z> = 2 + 2*(inv(I) == inv(Z));
    area = bits(Z)*(2 + 2*(inv(I) == inv(Z)));
  }
  ...rest of CMOS definition...
}

/*
 * A high-power buffer with half the delay and double the area/power.
 */
technology HP_CMOS {
  primitive buf {
    delay<I-Z> =  1 + (inv(I) == inv(Z));
    area = 2*bits(Z)*(2 + 2*(inv(I) == inv(Z)));
  }
}

If you assign the technology type HP_CMOS to any gates for which there is no primitive definition, delay values from the technology "default" will be used.

The table below lists all of the primitive gates for which delay may be specified and their delay parameters. The default values given are the values for a "basic" gate created from the "Make" with no changes to the number of inputs, input/output inverters, or bit widths of any of the ports.