# 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-2015 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 You will need the C<flex> and C<bison> 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. =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_verilated => Internal tests test_regress => Internal tests =head1 LIMITATIONS See verilator.txt (or execute C<bin/verilator --help>) for limitations.