mirror of
https://github.com/verilator/verilator.git
synced 2024-12-29 10:47:34 +00:00
283 lines
9.1 KiB
Plaintext
283 lines
9.1 KiB
Plaintext
# DESCRIPTION: DOCUMENT source run through perl to produce README file
|
|
# Use 'make README' to produce the output file
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
Welcome to Verilator. This is the Verilator package's README file.
|
|
|
|
This document describes how to initially install Verilator. For more
|
|
general information please see L<http://verilator.org>.
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Verilator is a simulator which "Verilates" synthesizable (generally not
|
|
behavioral) Verilog code into "Verilated" C++ or SystemC code.
|
|
|
|
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 all the options above, plus
|
|
MSVC++ 2008 and newer.
|
|
|
|
=head1 INSTALLATION
|
|
|
|
The following are detailed installation instructions.
|
|
Alternatively, for a quick summary please see
|
|
L<http://www.veripool.org/projects/verilator/wiki/Installing>.
|
|
|
|
=over 4
|
|
|
|
=item
|
|
|
|
Obtain binary or sources:
|
|
|
|
There are three methods to obtain Verilator, a prebuilt binary as part of
|
|
your Linux distribution, via git, or using a tarball. If you will be
|
|
modifying Verilator, you should use the "git" method as it will let you
|
|
track changes and hopefully contribute in the future.
|
|
|
|
=over 4
|
|
|
|
=item
|
|
|
|
Prebuilt binary:
|
|
|
|
You may install a binary on Ubuntu or other distributions using a package
|
|
manager. This is unlikely to be the most recent version.
|
|
|
|
apt-get install verilator
|
|
|
|
You may now skip the remaining installation steps.
|
|
|
|
=item
|
|
|
|
Git:
|
|
|
|
Get the sources from the repository.
|
|
|
|
git clone http://git.veripool.org/git/verilator # Only first time
|
|
## Note the URL above is not a page you can see with a browser, it's for git only
|
|
|
|
=item
|
|
|
|
Tarball:
|
|
|
|
Get a recent tarball package from L<http://www.veripool.org/verilator>.
|
|
Click the "Download" tab, scroll down to the latest package
|
|
(i.e. verilator-#.###.tgz), download it, and decompress with:
|
|
|
|
tar xvzf verilator_#-###.tgz
|
|
|
|
=back
|
|
|
|
=item
|
|
|
|
Install prerequisites:
|
|
|
|
=over 4
|
|
|
|
=item
|
|
|
|
To use Verilator you will need the C<perl>, C<make> (or C<gmake>), and
|
|
C<g++> (or C<clang>) packages. To compile Verilator in addition to the above you need the C<flex>,
|
|
C<bison> and C<texi2html> packages installed.
|
|
|
|
sudo apt-get install git make autoconf g++ flex bisonz # First time prerequisites
|
|
sudo apt-get install libgz # Non-Ubuntu (ignore if gives error)
|
|
sudo apt-get install libfl2 libfl-dev zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error)
|
|
|
|
=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 FST tracing you will need the C<gtkwave> and C<libgz> (and on
|
|
Ubuntu C<zlibc> C<zlib1g> C<zlib1g-dev>) packages installed.
|
|
|
|
=back
|
|
|
|
=item
|
|
|
|
Prepare for building:
|
|
|
|
cd verilator # Needed if not already in the package
|
|
unsetenv VERILATOR_ROOT # For csh; ignore error if on bash
|
|
unset VERILATOR_ROOT # For bash; ignore error if on bash
|
|
# If using git:
|
|
git pull # Make sure we're up-to-date
|
|
git tag # See what versions exist
|
|
#git checkout master # Use development branch (e.g. recent bug fix)
|
|
#git checkout stable # Use most recent release
|
|
#git checkout v{version} # Switch to specified release version
|
|
#
|
|
autoconf # Create ./configure script
|
|
|
|
=item
|
|
|
|
Installation Choices
|
|
|
|
You 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 its git directory.
|
|
This allows the easiest experimentation and upgrading, and allows many
|
|
versions of Verilator to co-exist on a system. To run you point to the
|
|
program's files, no install is needed.
|
|
|
|
export VERILATOR_ROOT=`pwd` # if your shell is bash
|
|
setenv VERILATOR_ROOT `pwd` # if your shell is csh
|
|
./configure
|
|
|
|
Note after installing (below steps), a calling program should set the
|
|
environment variable VERILATOR_ROOT to point to this git directory, then
|
|
execute $VERILATOR_ROOT/bin/verilator, which will find the path to all
|
|
needed files.
|
|
|
|
=item 2.
|
|
|
|
You may eventually be instaling onto a project/company-wide "CAD" tools
|
|
disk that may support multiple versions of every tool.
|
|
|
|
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_//"`
|
|
|
|
Note after installing (below steps), if you use C<modulecmd>, 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 eventually 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
|
|
|
|
Then after installing (below) the binary directories should already be in
|
|
your PATH.
|
|
|
|
=item 4.
|
|
|
|
Finally, you may eventually install it into a specific installation prefix,
|
|
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 (below steps) you will need to add /opt/verilator-VERSION/bin to
|
|
PATH.
|
|
|
|
=back
|
|
|
|
Note all of the options above did:
|
|
|
|
./configure ... some options ...
|
|
|
|
Add to this line C<--enable-longtests> for more complete developer tests.
|
|
Additional packages may be required for these tests.
|
|
|
|
=item
|
|
|
|
Type C<make> to compile Verilator.
|
|
|
|
=item
|
|
|
|
Type C<make test> to check the compilation.
|
|
|
|
=item
|
|
|
|
If you used the prefix scheme, now do a C<make install>.
|
|
|
|
=item
|
|
|
|
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.pdf in the same directory as this README.
|
|
|
|
or see L<https://www.veripool.org/ftp/verilator_doc.pdf> (which is the most
|
|
recent version and thus may differ in some respects from the version you installed).
|
|
|
|
=head1 PACKAGE DIRECTORY STRUCTURE
|
|
|
|
The directories in the package directory are as follows:
|
|
|
|
Changes => Version history
|
|
bin/verilator => Compiler Wrapper invoked to Verilate code
|
|
docs/ => Additional documentation
|
|
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
|
|
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.mk => Common Makefile
|
|
include/verilated.v => Stub defines for linting
|
|
src/ => Translator source code
|
|
test_regress => Internal tests
|
|
verilator.pdf => Primary documentation
|
|
verilator.txt => Primary documentation (text)
|
|
|
|
For files created after Verilation, see the manual.
|
|
|
|
=head1 DISTRIBUTION
|
|
|
|
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.
|