# 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

http://www.veripool.org/verilator

This package is Copyright 2003-2019 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 (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
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
from L<http://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

To use Verilator you will need the C<perl>, C<make> (or C<gmake>), and
C<g++> (or C<clang>) packages.

To use Verilator FST tracing you will need the C<gtkwave> and C<libgz> (on
Ubuntu C<zlibc> C<zlib1g> C<zlib1g-dev>) packages installed.

To compile Verilator in addition to the above you need the C<flex>,
C<bison> and C<texi2html> packages installed.

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

Note Verilator builds the current value of VERILATOR_ROOT, SYSTEMC_INCLUDE,
and SYSTEMC_LIBDIR 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}
    unsetenv VERILATOR_ROOT
    prepend-path PATH $install_root/bin
    prepend-path MANPATH $install_root/man
    prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig

=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<make> to compile Verilator.

Type C<make test> 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<make install>.  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.

You may now wish to consult the examples directory. Type C<make> inside any
example directory to run the example.

=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
    examples/hello_world_c      => Example simple Verilog->C++ conversion
    examples/hello_world_sc     => Example simple Verilog->SystemC conversion
    examples/tracing_c          => Example Verilog->C++ with tracing
    examples/tracing_sc         => Example Verilog->SystemC with tracing
    test_regress                => Internal tests

=head1 LIMITATIONS

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