\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-2009 by Wilson Snyder @email{wsnyder@@wsnyder.org}.

Verilator is free software; you can redistribute it and/or modify it
under the terms of either the GNU Lesser General Public License
Version 3 or the Perl Artistic License Version 2.0.  (See the
documentation for more details.)

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

@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.  Optionally also set @samp{SYSTEMPERL_INCLUDE}
to point to the installed headers.

@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, SYSTEMPERL, and SYSTEMPERL_INCLUDE 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.