verilator/README

1 Verilator
***********

This is the Verilator Package.

1.1 Copyright
=============

This package is Copyright 2003-2007 by Wilson Snyder
<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.

1.2 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://veripool.com.

   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.

1.3 Obtaining Distribution
==========================

The latest version is available at `http://veripool.com/verilator.htm'

   Download the latest package from that site, and decompress.  `gunzip
verilator_version.tar.gz ; tar xvf verilator_version.tar'

1.4 Directory Structure
=======================

The directories after de-taring are as follows:

   * bin/verilator	     => Compiler Wrapper invoked on user Verilog code

   * include/		     => Files that should be in your -I compiler
     path

   * include/verilated.cpp   => Global routines to link into your
     simulator

   * include/verilated.h     => Global headers

   * include/verilated.v     => Stub defines for linting

   * include/verilated.mk    => Common makefile

   * src/		     => Translator source code

   * test_v		     => Example Verilog code for other test dirs

   * test_c		     => Example Verilog->C++ conversion

   * test_sc		     => Example Verilog->SystemC conversion

   * test_sp		     => Example Verilog->SystemPerl conversion

   * test_vcs		     => Example Verilog->VCS conversion (test the
     test)

   * test_verilated	     => Internal tests

   * test_regress	     => Internal tests

1.5 Supported Systems
=====================

This version of verilator has been built and tested on:

   * SuSE AMD64 i686-linux-2.6.5

   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.

1.6 Installation
================

  1. If you will be using SystemC (vs straight C++ output), download
     SystemC 2.0.1 from `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'.

  2. If you will be using SystemC, download and install Verilog-Perl,
     `http://search.cpan.org/search?module=Verilog::Language'.

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

  4. `cd' to the Verilator directory containing this README.

  5. Type `./configure' to configure Verilator for your system.

  6. Type `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.

       1.   Type `perl -MExtUtils::Embed -e ldopts'

       2.   It will show a directory name ending in /CORE.  cd to that
          directory.

       3.   `cp libperl5_6_1.a libperl.a'

       4.   `cp libperl5_6_1.dll libperl.dll'

       5.   `cp libperl5_6_1.def libperl.def'

  7. Type `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 `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 `typedef
     unsigned long uint32_t;'.

     If you get warnings, you might want to edit `include/verilated.mk'
     to delete the lines that define VK_CPPFLAGS_WALL.

  8.  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 `$SYSTEMC/include' and
     `$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.

  9. 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.


1.7 Limitations
===============

See verilator.txt (or execute `bin/verilator --help') for limitations.