DESCRIPTION: DOCUMENT source run through perl to produce README file

Use 'make README' to produce the output file

=pod

=head1 NAME

This is the Verilator Package README file.

=head1 DISTRIBUTION

This package is Copyright 2003-2013 by Wilson Snyder. (Report bugs to Lhttp://www.veripool.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.

=head1 DESCRIPTION

Verilator converts synthesizable (generally 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 .cpp and .h files using the standard SystemC headers.

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.

=head1 SUPPORTED SYSTEMS

Verilator is developed and has primary testing on Ubuntu. Versions have also built on Redhat Linux, Macs OS-X, HPUX and Solaris. It should run with minor porting on any Linix-ish platform. Verilator also works on Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator itself) compiles under MSVC++ 2008 and newer.

=head1 INSTALLATION

For more details see Lhttp://www.veripool.org/projects/verilator/wiki/Installing.

If you will be modifying Verilator, you should use the "git" method as it will let you track changes.

=over 4

=item

The latest version is available at Lhttp://www.veripool.org/verilator.

Download the latest package from that site, and decompress.

tar xvzf verilator_version.tgz

=item

If you will be using SystemC (vs straight C++ output), download SystemC from Lhttp://www.systemc.org. Follow their installation instructions. You will need to set SYSTEMC_INCLUDE to point to the include directory with systemc.h in it, and SYSTEMC_LIBDIR to points to the directory with libsystemc.a in it. (Older installations may set SYSTEMC and SYSTEMC_ARCH instead.)

=item

If you will be using SystemPerl or coverage, download and install System-Perl, Lhttp://www.veripool.org/systemperl. Note you'll need to set a C<SYSTEMPERL> environment variable to point to the downloaded kit. Optionally also set C<SYSTEMPERL_INCLUDE> to point to the installed headers.

=item

You will need the C and C packages installed.

=item

C to the Verilator directory containing this README.

=item

You now have to decide how you're going to eventually install the kit.

Note Verilator builds the current value of VERILATOR_ROOT, SYSTEMC_INCLUDE, SYSTEMC_LIBDIR, SYSTEMPERL, and SYSTEMPERL_INCLUDE as defaults into the executable, so try to have them correct before configuring.

=over 4

=item 1.

Our personal favorite is to always run Verilator from the kit directory. This allows the easiest experimentation and upgrading. It's also how most EDA tools operate; to run you point to the tarball, no install is needed.

export VERILATOR_ROOT=`pwd`   # if your shell is bash
setenv VERILATOR_ROOT `pwd`   # if your shell is csh
./configure

=item 2.

To install globally onto a "cad" disk with multiple versions of every tool, and add it to path using Modules/modulecmd:

unset VERILATOR_ROOT      # if your shell is bash
unsetenv VERILATOR_ROOT   # if your shell is csh
# For the tarball, use the version number instead of git describe
./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`

After installing you'll want a module file like the following:

set install_root /CAD_DISK/verilator/{version-number-used-above}
setenv VERILATOR_ROOT $install_root
prepend-path PATH $install_root/bin
prepend-path MANPATH $install_root/man

=item 3.

The next option is to install it globally, using the normal system paths:

unset VERILATOR_ROOT      # if your shell is bash
unsetenv VERILATOR_ROOT   # if your shell is csh
./configure

=item 4.

Alternatively you can configure a prefix that install will populate, as most GNU tools support:

unset VERILATOR_ROOT      # if your shell is bash
unsetenv VERILATOR_ROOT   # if your shell is csh
./configure --prefix /opt/verilator-VERSION

Then after installing you will need to add /opt/verilator-VERSION/bin to PATH.

=back

=item

Type C to compile Verilator.

Type C to check the compilation.

Configure with C<--enable-longtests> for more complete developer tests. Additional packages may be required for these tests.

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;}.

=item

If you used the VERILATOR_ROOT scheme you're done. 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.

If you used the prefix scheme, now do a C. To run verilator, have the verilator binary directory in your PATH (this should already be true if using the default configure), and make sure VERILATOR_ROOT is not set.

=back

=head1 USAGE DOCUMENTATION

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.

=head1 DIRECTORY STRUCTURE

The directories in the kit after de-taring are as follows:

bin/verilator               => Compiler Wrapper invoked to Verilate 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

=head1 LIMITATIONS

See verilator.txt (or execute C<bin/verilator --help>) for limitations.