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

This is the Verilator Package.

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

This package is Copyright 2003-2009 by Wilson Snyder
<wsnyder@wsnyder.org>.

   Verilator is free software; you can redistribute it and/or modify it
under the terms of either the GNU 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.

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://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.

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

The latest version is available at `http://www.veripool.org/verilator'

   Download the latest package from that site, and decompress.  `tar
xvzf verilator_version.tgz'

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.  Optionally also set `SYSTEMPERL_INCLUDE' to
     point to the installed headers.

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

  5. Type `./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.

  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.

