\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename readme.info
@settitle Verilator Installation
@c %**end of header

@c DESCRIPTION: TexInfo: DOCUMENT source run through texinfo to produce README file
@c Use 'make README' to produce the output file
@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update)

@node Top, Copyright, (dir), (dir)
@chapter Verilator

This is the Verilator Package.

@menu
* Copyright::
* Description::
* Obtaining Distribution::
* Directory Structure::
* Supported Systems::
* Installation::
* Limitations::
@end menu

@node Copyright, Description, Top, Top
@section Copyright

This package is Copyright 2003-2008 by Wilson Snyder @email{wsnyder@@wsnyder.org}.

You may distribute under the terms of either the GNU General Public License
or the Artistic License, as specified in the Perl README file.

This code is provided with no warranty of any kind, and is used entirely at
your own risk.

@node Description, Obtaining Distribution, Copyright, Top
@section Description

Verilator converts synthesizable (not behavioral) Verilog code into C++ or
SystemC code.  It is not a complete simulator, just a translator.

Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
reads the specified Verilog code, lints it, and optionally adds coverage
code.  For C++ format, it outputs .cpp and .h files.  For SystemC format,
it outputs .sp files for the SystemPerl preprocessor available at
http://www.veripool.org.

The resulting files are then compiled with C++.  The user writes a little
C++ wrapper file, which instantiates the top level module.  This is
compiled in C++, and linked with the Verilated files.

The resulting executable will perform the actual simulation.

@node Obtaining Distribution, Directory Structure, Description, Top
@section Obtaining Distribution

The latest version is available at
@uref{http://www.veripool.org/verilator}

Download the latest package from that site, and decompress.
@samp{tar xvzf verilator_version.tgz}

@node Directory Structure, Supported Systems, Obtaining Distribution, Top
@section Directory Structure

The directories after de-taring are as follows:

@itemize @bullet
@item bin/verilator	     => Compiler Wrapper invoked on user Verilog code
@item include/		     => Files that should be in your -I compiler path
@item include/verilated.cpp   => Global routines to link into your simulator
@item include/verilated.h     => Global headers
@item include/verilated.v     => Stub defines for linting
@item include/verilated.mk    => Common makefile
@item src/		     => Translator source code
@item test_v		     => Example Verilog code for other test dirs
@item test_c		     => Example Verilog->C++ conversion
@item test_sc		     => Example Verilog->SystemC conversion
@item test_sp		     => Example Verilog->SystemPerl conversion
@item test_vcs		     => Example Verilog->VCS conversion (test the test)
@item test_verilated	     => Internal tests
@item test_regress	     => Internal tests
@end itemize

@node Supported Systems, Installation, Directory Structure, Top
@section Supported Systems

This version of verilator has been built and tested on:

@itemize @bullet
@item SuSE AMD64 i686-linux-2.6.5
@end itemize

Other users report success with Redhat Linux 2.4, Windows under
Cygwin, HPUX and Solaris.  It should run with minor porting on any
Unix system.

@node Installation, Limitations, Supported Systems, Top
@section Installation

@enumerate
@item
If you will be using SystemC (vs straight C++ output), download
SystemC 2.0.1 from @url{http://www.systemc.org}.  Follow their
installation instructions.  As described in the System-Perl README,
you will need to set SYSTEMC and/or SYSTEMC_KIT to point to this
download.  Also, set SYSTEMC_ARCH to the architecture name you used
with SystemC, generally 'linux' or 'cygwin'.

@item
If you will be using SystemC, download and install Verilog-Perl,
@url{http://search.cpan.org/search?module=Verilog::Language}.

@item
If you will be using SystemC, download and install System-Perl,
@url{http://search.cpan.org/search?module=SystemC::Netlist}.  Note
you'll need to set a @samp{SYSTEMPERL} environment variable to point
to the downloaded kit (not the installed files.)  Also, make sure to
do a @code{make sc_patch}.

@item
@code{cd} to the Verilator directory containing this README.

@item
Type @samp{./configure} to configure Verilator for your system.

If you are configuring Verilator to be part of a RPM or other
distribution package system, you may want to use the --enable-defenv
configure flag.  This will take the current value of VERILATOR_ROOT,
SYSTEMC, SYSTEMC_ARCH, and SYSTEMPERL and build them as defaults into
the executable.

@item
Type @samp{make} to compile Verilator.

On Cygwin (Windows) you may get a error about libperl.a not being
found.  You need to copy your perl libraries as follows.

  @enumerate
  @item
  Type @samp{perl -MExtUtils::Embed -e ldopts}
  @item
  It will show a directory name ending in /CORE.  cd to that directory.
  @item
  @samp{cp libperl5_6_1.a libperl.a}
  @item
  @samp{cp libperl5_6_1.dll libperl.dll}
  @item
  @samp{cp libperl5_6_1.def libperl.def}
  @end enumerate

@item
Type @samp{make test} to check the compilation.

You may get a error about the Bit::Vector perl package.  You will need to install
it if you want the tests to pass.  (Try @samp{make test_c} for a smaller test that
doesn't require it.)

You may get a error about a typedef conflict for uint32_t.  Edit verilated.h to change
the typedef to work, probably to @samp{typedef unsigned long uint32_t;}.

If you get warnings, you might want to edit @samp{include/verilated.mk} to delete the
lines that define VK_CPPFLAGS_WALL.

@item

There is no installation at present; this package runs from the
distribution directory.  Programs should set the environment variable
VERILATOR_ROOT to point to this distribution, then execute
$VERILATOR_ROOT/bin/verilator, which will find the path to all needed
files.

Verilator assumes you did a make in the SystemC kit directory.  If not, you will need
to populate @samp{$SYSTEMC/include} and @samp{$SYSTEMC/lib-linux} appropriately.

If you will be modifying Verilator, you will probably want a second
stable copy of this kit for others to use while you experiment.

@item
Detailed documentation and the man page can be seen by running:

    bin/verilator --help

or reading verilator.txt in the same directory as this README.

@end enumerate

@node Limitations,  , Installation, Top
@section Limitations

See verilator.txt (or execute @samp{bin/verilator --help}) for limitations.