Verilog Compilation/Simulation
==============================

Unlike most Verilog systems, V-System/Plus is a compiled Verilog
system: a design is first compiled, and then simulated. Before you
can compile your design, you must create a library to store the
compilation results. Use VLIB to create a new library. For example,

    vlib work

This creates a library named work. By default, compilation results
are stored in the work library. Verilog and VHDL design units may
be compiled into the same library.

Compilation
-----------

VLOG compiles Verilog source code and stores the resulting compiled
modules and UDPs in the work library. The usage of VLOG is:

Usage: vlog [options] files
Options: -work path      Specify library WORK
         -source         Print the source line with error messages
         -nodebug        Do not put symbolic debugging information into library
         -quiet          Disable 'loading' messages
         -hazards        Enable run-time hazard checking code
         -v path         Specify Verilog source library file
         -y path         Specify Verilog source library directory
         +libext+<suffix> Specify suffix of files in library directory
         +define+<macro_name>[=<macro_text>]  Same as compiler directive
                                              `define macro_name macro_text
         +incdir+<directory>  Search directory for files included with
                              `include "filename"

VLOG compiles the files in the order that they appear on the command
line. Compiler directives encountered in a file persist for all
subsequent files. VLOG compiles one or more design units (modules and UDPs)
at a time, and you may compile all design units or any subset in a single
invocation of VLOG. Also, you may compile design units in any order you
desire because the interface checking among design units is deferred
until the design is loaded by VSIM.

VLOG performs semantic checking as each design unit is compiled, but
these checks do not extend across the boundaries of a design unit
because each design unit is analyzed as an independent unit. The
interfaces among design units are not checked until the design
is loaded and elaborated by VSIM, at which time the following kinds of
checks are performed:

    - Port and parameter associations in instantiations.
    - Hierarchical name references to objects external to the module.
    - Calls to user-defined and built-in system tasks and system
      functions.

Simulation
----------

After compiling the design units, you can proceed to simulate the
design with VSIM. Invoke VSIM with the name of the top-level module,
or with a list of names if there are multiple top-level modules.
For example,

	vsim top1 top2 top3

If you fail to provide a top-level module name, VSIM will present
a dialog box from which you can choose a single top-level module.

Time resolution
---------------

The simulation time resolution is 1 ns by default. You can select
a specific time resolution with the -t option or from the startup
dialog box. For example, to run in picosecond resolution:

    vsim -t ps topmod

VSIM will issue a warning if any of the Verilog modules have
`timescale directives with a time precision smaller than the
selected simulation time resolution. Note that, unlike many
Verilog simulators, VSIM does not automatically set the
time resolution to the smallest time precision found in the
`timescale directives. Even so, the `timescale directive is
completely implemented in V-System.

Min:Typ:Max expressions
-----------------------

By default, VSIM selects typical delays from the min:typ:max expressions
in the Verilog code. You can explicitly select a delay set by invoking
VSIM with the +mindelays, +typdelays, or +maxdelays switches. For example,
to simulate with maximum delays:

	vsim +maxdelays topmod

Timing check disabling
----------------------

By default, the timing check system tasks ($setup, $hold,...) in specify
blocks are enabled. They can be disabled with the +notimingchecks switch.
For example,

    vsim +notimingchecks topmod

Instantiation bindings
----------------------

Verilog module and UDP instantiations are not bound to specific design
units at compilation time; instead, VSIM dynamically binds them as a
design is loaded. VSIM first looks for designs units in libraries
specified with the -L switch. The libraries are searched in the order
they are presented on the command line. If -L switches are not used,
or if a design unit is not found, then VSIM searches the work library.
For example, to search the libraries "gatelib", "mylib", and "work":

    vsim -L gatelib -L mylib top

Hazard detection
----------------

VSIM can help you find hazards in your Verilog code. As an option, you can
have VSIM notify you when it executes code that depends on an order
of execution that is not guaranteed by the language. This kind of hazard
always involves concurrently executing processes that are simultaneously
accessing a global variable.

You can use this feature to help you write code that ports more easily
among Verilog simulators. VSIM matches the event ordering of Cadence's
Verilog simulator in many, but not all, cases. VSIM's hazard detection
is useful in porting models that rely on Cadence Verilog event ordering.

VSIM detects the following kinds of hazards:

WRITE/WRITE: Two processes writing to the same variable at the same time.

READ/WRITE: One process reading a variable at the same time it is being
	written to by another process. VSIM calls this a READ/WRITE hazard
	if it executed the read first.

WRITE/READ: Same as a READ/WRITE hazard except that VSIM executed the
	write first.

VSIM issues an error message when it detects a hazard. The message pinpoints
the variable and the two processes involved. You can have the simulator
break on the statement where the hazard is detected by setting the
"break on assertion" level to "error".

To enable hazard detection you must invoke VLOG with the -hazards
switch when you compile your source code and you must also invoke
VSIM with the -hazards switch when you simulate.

Limitations:

	- Reads and writes involving bit and part selects of vectors are
	  not considered for hazard detection. The overhead of tracking
	  the overlap between the bit and part selects is too high.

	- A WRITE/WRITE hazard is flagged even if the same value is
	  written by both processes.

	- A WRITE/READ or READ/WRITE hazard is flagged even if the write
	  does not modify the variable's value.

	- Glitches on nets caused by non-guaranteed event ordering are
	  not detected.


VSIM User Interface
===================

VSIM's Graphical User Interface and command line interface are common
to both VHDL and Verilog simulation. All of the GUI windows apply to
VHDL and Verilog, and most VSIM commands also apply to VHDL and Verilog.

Verilog object names in commands
--------------------------------

Because Verilog identifiers are case sensitive, names in VSIM commands
are now case sensitive by default. VHDL identifiers are considered to be
lower case. For example, to examine the value of a Verilog register named
MyRegister, you would type the following VSIM command:

	examine MyRegister

You can turn off case sensitivity by setting the TCL variable
ObjectsCaseSensitive to 0. For example,

	set ObjectsCaseSensitive 0

By default, VSIM requires the '/' character as separators in
hierarchical names. You can use the '.' character instead by
setting the VerilogNaming variable to 1. For example,

	set VerilogNaming 1

In addition, this causes VSIM to display hierarchical names with
the '.' character as separators.

Verilog literals in commands
----------------------------

Verilog style literals are allowed in VSIM commands. You may use either
Verilog or VHDL style literals independent of the type of object
operated on. For example, the following command may modify either a
Verilog or VHDL variable:

	change var 'hff


Verilog Programming Language Interface (PLI)
============================================

PLI applications that use the TF routines should include the "veriuser.h"
file supplied in the V-System installation directory.

PLI applications are dynamically linked to VSIM's PLI routines. A PLI
application must supply a dynamically loadable object with an entry point
named "init_usertfs". This function must call mti_RegisterUserTF for each
entry in the table of user tasks and functions. The name of the
file to load is specified in the vsystem.ini file by the Veriuser entry.
The Veriuser entry must be in the [vsim] section of the file.
For example,

    [vsim]
       .
       .
       .
	Veriuser = hello.so

Here is an example of how to use the PLI:

------------------hello.c-------------------
#include "veriuser.h"

static int hello()
{
	io_printf("Hi there\n");
}

static s_tfcell veriusertfs[] = {
{usertask, 0, 0, 0, hello, 0, "$hello", 0},
{0}
};

void init_usertfs()
{
	p_tfcell usertf;

	for (usertf = veriusertfs; usertf; usertf++) {
		if (usertf->type == 0)
			return;
		mti_RegisterUserTF(usertf);
	}
}
---------------------------------------------

Compile and link on sunos4:

cc -c hello.c
ld -o hello.so hello.o
