\documentstyle[rep11,fullpage,program]{report}
\pagenumbering{roman}
\title{Fintronic Verilog Analyzer - User's Guide}
\author{Fintronic USA Inc. \\
        Suite 205, 1360 Willow Rd.\\
        Menlo Park, California 94025}
\date{\today}

\begin{document}
\maketitle

\tableofcontents
\pagenumbering{arabic}

\chapter{Introduction}
This document describes an analyzer for the Verilog Hardware Description
Language developed at Fintronic USA. The analyzer is based on the
Verilog Hardware Description Language Reference Manual published
by Open Verilog International (OVI).

  The analyzer takes as input one or more Verilog source files and checks 
them for correctness. This includes:
\begin{enumerate}
\item{Syntactic checking - These checks catch parse errors and ensure that 
the source files conform to the language syntax.}
\item{Semantic checking - These checks catch all the non parse errors. E.g.
ensuring that all identifiers used in the source files are declared,
 all identifiers
used in expressions are legal rvalues, all identifiers on the lhs of assignments
are legal lvalues, all parameter expressions are constants, a real expression
is not used as an array index etc.}
\end{enumerate}

  In addition to catching all errors in the source files the analyzer produces
a number of warning messages about potential user errors. E.g. negative 
delay expressions, delay expressions that contain x or z, 
mismatches between types and widths of lhs and rhs of assignments, 
connection of a real expression to the terminal of a gate etc.
Warning messages can be selectively suppressed based on options.

  An option is provided to print the symbol table corresponding to the
the Verilog design. The symbol table contains the declaration of
every object in the Verilog design. This is useful in case parameter
overrides modify the declaration of an identifier in two different 
instances of the same module.
E.g. a parameter override may not only change the value of the overridden 
parameter but may also change the widths of all objects whose width 
is defined in terms of that parameter.

  The analyzer also produces a binary intermediate format (IMF) which is an
internal representation of the information contained in the source files.
It is faster and easier to process the IMF as opposed to operating directly
on the source files. The IMF can be used by tools like translators, 
code generators, systhesis tools, pretty printers etc. to inquire about 
the information in the Verilog design. A procedural interface to the IMF
if provided through a set of access functions. These functions can
extract information from and modify the IMF. The IMF and it's access
functions are described in the Fintronic Verilog Intermediate Format document.

\chapter{Operation of the analyzer}
The analysis is performed in 3 phases:
\begin{enumerate}
\item{Analysis of modules/primitives}
\item{Analysis of module/primitive instantiations}
\item{Analysis of the design hierarchy}
\end{enumerate}
These phases are performed in order listed above. One or more errors in
a particular phase cause the subsequent phases to be skipped 
until the user corrects all the errors encountered in that phase.
\section{Phase 1: Analysis of modules/primitives}
  This phase catches syntax errors and 
  ensures that the source files conform to the syntax of the language as
  described in Appendix A of the Verilog HDL manual published by OVI.

  This phase also processes each module/primitive declared in the source
files and performs all the semantic checks that can be performed by looking at 
that module/primitive alone. It uses the default values of parameters
when performing these checks. Some checks that cannot be performed in this
phase are: checking hierarchical names
(\verb+<+scope\verb+>+.\verb+<+scope\verb+>+...\verb+<+name\verb+>+) 
that are referenced in the
current module but are declared in another module,
checking instantiations of other modules that are made in the current 
module etc.

   This phase also searches library files/directories for any 
modules/primitives that were instantiated in the source files but not
declared in the source files. Modules/primitives that are brought in 
from library files/directories are also analyzed in a similar way.

\section{Phase 2: Analysis of module/primitive instantiations}
This phase checks the module/primitive instantiations within
each module. Some of the checks include ensuring that the instantiated
module exists, the number of port expressions specified in the instantiation
matches the number of ports of the instantiated module/primitive etc.
This phase also uses the default values of parameters when performing these
checks.

\section{Phase 3: Analysis of the design hierarchy}
This phase checks for the correctness of the design hierarchy.
All hierarchical names \\
(\verb+<+scope\verb+>+.\verb+<+scope\verb+>+...\verb+<+name\verb+>+)
that are external to a
module (used in the module but declared in another module) 
are checked in this phase. 
Instances of modules whose parameters are overridden 
are also rechecked in this phase. Note that only the portions of the 
module instance that are affected by parameter overrides are rechecked.
This phase uses the overridden values (if any) of parameters.

\chapter{Using the analyzer}
\section{Options}
The analyzer should be used as follows:

\begin{verbatim}
va <option or source file name> <option or source file name> ... 

The legal options are:
-cf <file>  : take command line information from the specified command file
-id <dir>   : search for include files in the specified include directory
-ld <dir>   : search for undeclared modules in the specified library directory
-lf <file>  : search for undeclared modules in the specified library file
-le <str>   : use the specified string as the file extension when searching for
              undeclared modules in library directories
-lsm <str>  : the specified string describes the library search mechanism to 
              use, it must be one of d (default), o (order) or r (rescan)
-ustf       : suppress warning messages about unknown system tasks/functions
-ind        : suppress warning messages about implicit net declarations
-ubd        : suppress warning messages about objects used before they are 
              declared
-ncd        : suppress warning messages about non constant delay expressions
-rd         : suppress warning messages about delay expressions of type real
-nd         : suppress warning messages about negative delay expressions
-xzd        : suppress warning messages about delay expressions that contain 
              x's or z's
-tc         : suppress warning messages about type conversions performed on 
              expression operands
-tmarg      : suppress warning messages about type mismatches between actual 
              and formal arguments of tasks/functions
-wmarg      : suppress warning messages about width mismatches between actual 
              and formal arguments of tasks/functions
-twmarg     : same as "-tmarg -wmarg"
-tmgate     : suppress warning messages about type mismatches between gate 
              terminals and the expressions connected to them
-wmgate     : suppress warning messages about width mismatches between gate
              terminals and the expressions connected to them
-twmgate    : same as "-tmgate -wmgate"
-tmport     : suppress warning messages about type mismatches between 
              module/primitive ports and the expressions connected to them
-wmport     : suppress warning messages about width mismatches between 
              module/primitive ports and the expressions connected to them
-twmport    : same as "-tmport -wmport"
-tmass      : suppress warning messages about type mismatches between the lhs 
              and rhs of assignments
-wmass      : suppress warning messages about width mismatches between the lhs 
              and rhs of assignments
-twmass     : same as "-tmass -wmass"
-tmcel      : suppress warning messages about type mismatches between case 
              expressions and case labels
-wmcel      : suppress warning messages about width mismatches between case 
              expressions and case labels
-twmcel     : same as "-tmcel -wmcel"
-tm         : same as "-tmarg -tmgate -tmport -tmass -tmcel"
-wm         : same as "-wmarg -wmgate -wmport -wmass -wmcel"
-twm        : same as "-twmarg -twmgate -twmport -twmass -twmcel"
-a          : suppress all warning messages
-min        : use the min component in min:typ:max expressions for analysis
-typ        : use the typ component in min:typ:max expressions for analysis, 
              this is also the default
-max        : use the max component in min:typ:max expressions for analysis
-des <str>  : use the specified string as the name of the design
-ao         : perform syntax and semantic analysis only, do not generate 
              code and data for simulation
-stb        : print the symbol table (in file stb.out)
-vpp        : print the result of the preprocessor (in file vpp.out)
-ifb        : print the intermediate format in binary (in file ifb.out)
-ifa        : print the intermediate format in ascii (in file ifa.out)
-is n:a:c:s : n, a, c and s are positive integers indicating the initial sizes 
              of the node, attribute, char and string arrays respectively. 
              a, c and s are optional

\end{verbatim}

\section{Examples of usage}
\begin{verbatim}
   va test.v
\end{verbatim}
Run the analyzer on the file test.v, use default values of all options.

\begin{verbatim}
   va -a -stb cpu.vlog mem.vlog -lf /usr/lib/lib.v -lf /usr/john/mylib.v
   -ld /usr/lib -le .v -le .v2 -lsm r
\end{verbatim}
Run the analyzer on the files cpu.vlog and mem.vlog, 
suppress all warnings and print the symbol table.
Search for undeclared modules in the library files /usr/lib/lib.v
and /usr/john/mylib.v and the library directory /usr/lib.
Use ".v" and ".v2" as the extension for files opened in 
library directories and search the libraries
using the rescan algorithm.

\section{Types of values}
Verilog has 3 different types of values
\begin{enumerate}
\item{real - E.g. 1.0, 5.65, -99.32, 0.999 etc.}
\item{unsigned - E.g. 1'b1, 8'hff, 'habc, 2'bx1, 6'bzzzzzz etc.}
\item{signed - E.g. 1, 5, -99, 0 etc.}
\end{enumerate}

The warning messages pertaining to type mismatches refer to these
types. E.g. in the declaration reg [0:7] r, r is a register of width 8 
the type of its value is unsigned. 
the value of all real variables is of type real,
The value of all reg, net and time variables is of type unsigned
and the value of all integer variables is of type signed. Each bit
of a unsigned or signed value can be 0, 1, X or Z.

   Unsigned arithmetic is performed on unsigned values, whereas
signed arithmetic is performed on values of type signed. 
Whenever one of the operands of an expression (e.g. +, -, \verb+<+,
 == etc) is of 
type real the other one is converted to type real if it is not 
already of type real. When converting a value of type unsigned or type 
signed to type real, x's and z's in the value are treated as 0's.
If neither operand is real but at least one is
of type unsigned the other operand is converted to type unsigned 
if it is already not already of type unsigned.

\chapter{Unsupported features}
\section {Macro modules}
The current version of the analyzer treats macro modules exactly
the same as ordinary modules. Macro module instances are not expanded
within the instantiating module but create a new scope of their own 
just like module instances. 
Macro modules will be supported in a future release.

\section{Some compiler directives}
The following compiler directives are not supported yet:
\begin{verbatim}
   `protect, `endprotect, `protected, `endprotected,
   `remove_gatenames, `remove_netnames
\end{verbatim}

They will be supported in a future release.

\chapter{Installation}
To install the software create a directory where the software is to be 
installed, cd to that direcrory, insert the tape in the tape drive and untar
the contents of the tape. E.g.
\begin{verbatim}
   mkdir /u1/fin_vlog
   cd /u1/fin_vlog
   tar xvf <name of tape drive e.g. /dev/rst0> 
\end{verbatim}

The tape consists of 9 files.
\begin{enumerate}
\item{A README file that contains installation instructions, 
  instructions on how to use the analyzer and a description of 
  the contents of all the files.}
\item{The Verilog analyzer itself (va)}
\item{A key file called fintronc.key which enables the user to run the analyzer on specific hosts until a specific time}
\item{A Verilog example that fails in the first phase of analysis (bad1.v).}
\item{A Verilog example that fails in the second phase of analysis (bad2.v).}
\item{A Verilog example that fails in the third phase of analysis (bad3.v).}
\item{A good Verilog example (good.v).}
\item{The user's guide in latex (users\verb+_+guide.tex).}
\item{The user's guide in postscript (users\verb+_+guide.ps).}
\end{enumerate}

In order to use the analyzer the user must set the environment variable 
FIN\_LICENSE\_PATH to the directory that contains the key file fintronc.key.
\begin{verbatim}
   e.g. setenv FIN_LICENSE_PATH /u1/fin_vlog
\end{verbatim}

\chapter{Contacting Fintronic USA}
Questions or comments about the analyzer can be
reported via email, fax, phone or regular mail to 
Bob Sahai.

\begin{verbatim}
Email   : sahai@fintronic.com

Fax     : (415)-325-4908
 
Phone   : (415)-325-4474 Ext 204
          (415)-325-4757 Ext 204

Address : Fintronic USA, Inc.
          1360 Willow Road, Suite 205
          Menlo Park, CA 94025
        
\end{verbatim}

\end{document}
  
