# 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-2009 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

This version of verilator has been built and tested on:

    SuSE 11.1 AMD64 i686-linux-2.6.27, GCC 4.3.2

Other users report success with Redhat Linux, Windows under Cygwin, Windows
under MinGW, Macs, HPUX and Solaris.  It should run with minor porting on
any Linix-ish platform.

=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 SystemC, download and install Verilog-Perl,
L<http://www.veripool.org/verilog-perl>.

=item

If you will be using SystemC, 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

Type C<./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 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

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