# 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-2010 by Wilson Snyder.  (Report bugs to
L<http://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 (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.

=head1 SUPPORTED SYSTEMS

Verilator is developed and has primary testing on:

    SuSE 11.1 AMD64 i686-linux-2.6.27, GCC 4.3.2

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

=head1 INSTALLATION

For more details see 
L<http://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 L<http://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
2.0.1 from L<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 SystemPerl or coverage, download and install
Verilog-Perl, L<http://www.veripool.org/verilog-perl>.

=item

If you will be using SystemPerl or coverage, download and install
System-Perl, L<http://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

C<cd> to the Verilator directory containing this README.

=item

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

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; you just point to the tarball.

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

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

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

Finally, if you are configuring Verilator to be part of a RPM or other
distribution package system, you may want to tune the various install
directories and 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 C<make> to compile Verilator.

Type C<make test_c> to check the compilation.

Type C<make test> for a more complete test.  You may get a error about the
Bit::Vector Perl package.  You will need to install it and SystemPerl if
you want all tests to pass.

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 sheme 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<make install>.

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

=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 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

=head1 LIMITATIONS

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