forked from github/verilator
Rewrite README and install.adoc
This commit is contained in:
Wilson Snyder
parent
8043a9c666
commit
7ef620dc64
@ -30,8 +30,10 @@
|
||||
/cov_work/
|
||||
/logs/
|
||||
^Makefile$
|
||||
README.html
|
||||
bin/verilator_bin.*
|
||||
bin/verilator_coverage_bin.*
|
||||
docs/.*\.html$
|
||||
docs/Makefile$
|
||||
docs/doxygen-doc/.*
|
||||
examples/xml_py/copied/
|
||||
|
||||
25
Makefile.in
25
Makefile.in
@ -115,8 +115,9 @@ SUBDIRS = src test_regress \
|
||||
examples/make_tracing_sc \
|
||||
examples/make_protect_lib \
|
||||
|
||||
INFOS = README README.html README.pdf \
|
||||
verilator.txt verilator.html verilator.pdf
|
||||
INFOS = verilator.txt verilator.html verilator.pdf
|
||||
|
||||
INFOS_OLD = README README.html README.pdf
|
||||
|
||||
# Files that can be generated, but should be up to date for a distribution.
|
||||
DISTDEP = info Makefile
|
||||
@ -127,6 +128,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
|
||||
Changes \
|
||||
LICENSE \
|
||||
MANIFEST.SKIP \
|
||||
README.adoc \
|
||||
verilator-config.cmake.in \
|
||||
verilator-config-version.cmake.in \
|
||||
bin/verilator \
|
||||
@ -142,6 +144,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
|
||||
docs/TODO \
|
||||
docs/doxygen-mainpage \
|
||||
docs/doxygen.config \
|
||||
docs/install.adoc \
|
||||
docs/internals.adoc \
|
||||
docs/verilator_logo.png \
|
||||
install-sh configure *.pod \
|
||||
@ -281,22 +284,6 @@ verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX)
|
||||
pdflatex verilator.tex
|
||||
-rm -f verilator.toc verilator.aux verilator.idx verilator.out
|
||||
|
||||
README: README.pod
|
||||
-rm -f $@
|
||||
$(POD2TEXT) --loose $< > $@
|
||||
|
||||
README.html: README.pod
|
||||
pod2html $< >$@
|
||||
|
||||
# PDF needs DIST variables; but having configure.ac as dependency isn't detected
|
||||
README.pdf: README.pod Makefile $(POD2LATEXFIX)
|
||||
pod2latex --full --out README.tex $<
|
||||
$(PERL) $(POD2LATEXFIX) "$(DISTTITLE) README File" "${DISTDATE}" < README.tex > README2.tex
|
||||
mv README2.tex README.tex
|
||||
pdflatex README.tex
|
||||
pdflatex README.tex
|
||||
-rm -f README.toc README.aux README.idx README.out
|
||||
|
||||
# See uninstall also - don't put wildcards in this variable, it might uninstall other stuff
|
||||
VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg \
|
||||
verilator_coverage verilator_gantt verilator_includer verilator_profcfunc
|
||||
@ -529,7 +516,7 @@ clean mostlyclean distclean maintainer-clean::
|
||||
rm -rf nodist/obj_dir
|
||||
|
||||
distclean maintainer-clean::
|
||||
rm -f *.info* *.1 $(INFOS) $(VL_INST_MAN_FILES)
|
||||
rm -f *.info* *.1 $(INFOS) $(INFOS_OLD) $(VL_INST_MAN_FILES)
|
||||
rm -f Makefile config.status config.cache config.log TAGS
|
||||
rm -f verilator_bin* verilator_coverage_bin*
|
||||
rm -f bin/verilator_bin* bin/verilator_coverage_bin*
|
||||
|
||||
140
README.adoc
Normal file
140
README.adoc
Normal file
@ -0,0 +1,140 @@
|
||||
// Github doesn't render images unless absolute URL
|
||||
:!toc:
|
||||
|
||||
ifdef::env-github[]
|
||||
image:https://img.shields.io/badge/License-LGPL%20v3-blue.svg[license LGPLv3,link=https://www.gnu.org/licenses/lgpl-3.0]
|
||||
image:https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg[license Artistic-2.0,link=https://opensource.org/licenses/Artistic-2.0]
|
||||
image:https://api.codacy.com/project/badge/Grade/ff998fdaa6f64b9a95eb5f342ee6bf4d[Code Quality,link=https://www.codacy.com/manual/wsnyder/verilator]
|
||||
image:https://travis-ci.com/verilator/verilator.svg?branch=master[Build Status (Travis CI),link=https://travis-ci.com/verilator/verilator]
|
||||
endif::[]
|
||||
|
||||
ifdef::env-github[]
|
||||
:link_verilator_contributing: link:docs/CONTRIBUTING.adoc
|
||||
:link_verilator_install: link:docs/install.adoc
|
||||
endif::[]
|
||||
ifndef::env-github[]
|
||||
:link_verilator_contributing: link:docs/CONTRIBUTING.adoc
|
||||
:link_verilator_install: https://verilator.org/install
|
||||
endif::[]
|
||||
|
||||
== Welcome to Verilator
|
||||
|
||||
[cols="a,a",indent=0,frame="none"]
|
||||
|===
|
||||
^.^| *Welcome to Verilator, the fastest free Verilog HDL simulator.*
|
||||
+++ <br/> +++ • Accepts synthesizable Verilog or SystemVerilog
|
||||
+++ <br/> +++ • Performs lint code-quality checks
|
||||
+++ <br/> +++ • Compiles into multithreaded {cpp}, SystemC, or (soon) {cpp}-under-Python
|
||||
+++ <br/> +++ • Creates XML to front-end your own tools
|
||||
<.^|image:https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200]
|
||||
|
||||
>.^|image:https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png[,388,178]
|
||||
^.^| *Fast*
|
||||
+++ <br/> +++ • Outperforms many commercial simulators
|
||||
+++ <br/> +++ • Single- and multi-threaded output models
|
||||
|
||||
^.^| *Widely Used*
|
||||
+++ <br/> +++ • Wide industry and academic deployment
|
||||
+++ <br/> +++ • Out-of-the-box support from Arm, and RISC-V vendor IP
|
||||
<.^|image:https://www.veripool.org/img/verilator_usage_400x200-min.png[,400,200]
|
||||
|
||||
>.^|image:https://www.veripool.org/img/chips_alliance_logo_225x75-min.png[CHIPS Alliance,link=https://chipsalliance.org]
|
||||
image:https://www.veripool.org/img/osi_logo_125x125-min.png[,125,125]
|
||||
^.^| *Community Driven & Openly Licensed*
|
||||
+++ <br/> +++ • Guided by the https://chipsalliance.org/[CHIPS Alliance] and https://www.linuxfoundation.org/[Linux Foundation]
|
||||
+++ <br/> +++ • Open, and free as in both speech and beer
|
||||
+++ <br/> +++ • More simulation for your verification budget
|
||||
|===
|
||||
|
||||
== What Verilator Does
|
||||
|
||||
Verilator is invoked with parameters similar to GCC or Synopsys's VCS. It
|
||||
"Verilates" the specified synthesizable Verilog or SystemVerilog code by
|
||||
reading it, performing lint checks, and optionally inserting assertion
|
||||
checks and coverage-analysis points. It outputs single- or multi-threaded
|
||||
.cpp and .h files, the "Verilated" code.
|
||||
|
||||
The user writes a little {cpp}/SystemC wrapper file, which instantiates the
|
||||
"Verilated" model of the user's top level module. These {cpp}/SystemC
|
||||
files are then compiled by a {cpp} compiler (gcc/clang/MSVC++). The
|
||||
resulting executable performs the design simulation. Verilator also
|
||||
supports linking its generated libraries, optionally encrypted, into other
|
||||
simulators.
|
||||
|
||||
Verilator may not be the best choice if you are expecting a full featured
|
||||
replacement for NC-Verilog, VCS or another commercial Verilog simulator, or
|
||||
if you are looking for a behavioral Verilog simulator e.g. for a quick
|
||||
class project (we recommend http://iverilog.icarus.com[Icarus Verilog] for
|
||||
this.) However, if you are looking for a path to migrate synthesizable
|
||||
Verilog to {cpp} or SystemC, and your team is comfortable writing just a
|
||||
touch of {cpp} code, Verilator is the tool for you.
|
||||
|
||||
== Performance
|
||||
|
||||
Verilator does not simply convert Verilog HDL to {cpp} or SystemC. Rather
|
||||
than only translate, Verilator compiles your code into a much faster
|
||||
optimized and optionally thread-partitioned model, which is in turn wrapped
|
||||
inside a {cpp}/SystemC/Python module. The results are a compiled Verilog
|
||||
model that executes even on a single-thread over 10x faster than standalone
|
||||
SystemC, and on a single thread is about 100 times faster than interpreted
|
||||
Verilog simulators such as http://iverilog.icarus.com[Icarus
|
||||
Verilog]. Another 2-10x speedup might be gained from multithreading
|
||||
(yielding 200-1000x total over interpreted simulators).
|
||||
|
||||
Verilator has typically similar or better performance versus the commercial
|
||||
Verilog simulators (Carbon Design Systems Carbonator, Modelsim, Cadence
|
||||
Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic CVer/CVC). But,
|
||||
Verilator is free, so you can spend on computes rather than licenses. Thus
|
||||
Verilator gives you more cycles/dollar than anything else available.
|
||||
|
||||
For more information on how Verilator stacks up to some of the other
|
||||
commercial and free Verilog simulators, see the
|
||||
https://www.veripool.org/verilog_sim_benchmarks.html[Verilog Simulator
|
||||
Benchmarks]. (If you benchmark Verilator, please see the notes in the
|
||||
https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)], and also
|
||||
if possible post on the forums the results; there may be additional tweaks
|
||||
possible.)
|
||||
|
||||
== Installation
|
||||
|
||||
== Documentation
|
||||
|
||||
For more information:
|
||||
|
||||
* {link_verilator_install}[Verilator installation and package directory
|
||||
structure].
|
||||
|
||||
* https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
|
||||
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
|
||||
|
||||
* https://verilator.org/forum[Verilator forum].
|
||||
|
||||
== Community Supported
|
||||
|
||||
Verilator is a community project, guided by the
|
||||
https://chipsalliance.org/[CHIPS Alliance] under the
|
||||
https://www.linuxfoundation.org/[Linux Foundation].
|
||||
|
||||
We appreciate and welcome your contributions in whatever form; please see
|
||||
{link_verilator_contributing}[Contributing to Verilator]. Thanks to our
|
||||
https://verilator.org/verilator_doc.html#CONTRIBUTORS[Contributors and
|
||||
Sponsors].
|
||||
|
||||
== Related Projects
|
||||
|
||||
* http://gtkwave.sourceforge.net/[GTKwave] - Waveform viewer for Verilator
|
||||
traces.
|
||||
|
||||
* http://iverilog.icarus.com[Icarus Verilog] - Icarus is a full featured
|
||||
interpreted Verilog simulator. If Verilator does not support your needs,
|
||||
perhaps Icarus may.
|
||||
|
||||
== Open License
|
||||
|
||||
Verilator is Copyright 2003-2019 by Wilson Snyder. (Report bugs to
|
||||
https://verilator.org/issues[Verilator Issues].)
|
||||
|
||||
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.)
|
||||
297
README.pod
297
README.pod
@ -1,297 +0,0 @@
|
||||
# DESCRIPTION: DOCUMENT source run through perl to produce README file
|
||||
# Use 'make README' to produce the output file
|
||||
|
||||
=pod
|
||||
|
||||
=begin html
|
||||
|
||||
<a href="https://www.gnu.org/licenses/lgpl-3.0"><img src="https://img.shields.io/badge/License-LGPL%20v3-blue.svg"></a>
|
||||
<a href="https://opensource.org/licenses/Artistic-2.0"><img src="https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg"></a>
|
||||
<a href="https://www.codacy.com/manual/wsnyder/verilator"><img src="https://api.codacy.com/project/badge/Grade/ff998fdaa6f64b9a95eb5f342ee6bf4d"></a>
|
||||
<a href="https://travis-ci.com/verilator/verilator"><img src="https://travis-ci.com/verilator/verilator.svg?branch=master"></a>
|
||||
|
||||
=end html
|
||||
|
||||
=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 Linux-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 bison # 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 installing 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/make_hello_c => Example GNU-make simple Verilog->C++ conversion
|
||||
examples/make_hello_sc => Example GNU-make simple Verilog->SystemC conversion
|
||||
examples/make_tracing_c => Example GNU-make Verilog->C++ with tracing
|
||||
examples/make_tracing_sc => Example GNU-make Verilog->SystemC with tracing
|
||||
examples/make_protect_lib => Example using --protect-lib
|
||||
examples/cmake_hello_c => Example building make_hello_c with CMake
|
||||
examples/cmake_hello_sc => Example building make_hello_sc with CMake
|
||||
examples/cmake_tracing_c => Example building make_tracing_c with CMake
|
||||
examples/cmake_tracing_sc => Example building make_tracing_sc with CMake
|
||||
examples/cmake_protect_lib => Example building make_protect_lib with CMake
|
||||
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.
|
||||
3
docs/.gitignore
vendored
3
docs/.gitignore
vendored
@ -1 +1,4 @@
|
||||
*.1
|
||||
*.html
|
||||
*.pdf
|
||||
Makefile
|
||||
|
||||
@ -23,6 +23,7 @@
|
||||
|
||||
#### Start of system configuration section. ####
|
||||
|
||||
ASCIIDOCTOR = asciidoctor
|
||||
DOXYGEN = doxygen
|
||||
|
||||
#### End of system configuration section. ####
|
||||
@ -33,6 +34,9 @@ DOXYGEN = doxygen
|
||||
default:
|
||||
@echo "error: make not supported here, run 'make docs' from Verilator top-level"
|
||||
|
||||
%.html: %.adoc
|
||||
$(ASCIIDOCTOR) $< -n -o $@
|
||||
|
||||
clean mostlyclean distclean maintainer-clean::
|
||||
rm -f $(SCRIPTS) *.tmp
|
||||
rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
|
||||
@ -41,7 +45,7 @@ clean mostlyclean distclean maintainer-clean::
|
||||
rm -f *.tex
|
||||
|
||||
distclean maintainer-clean::
|
||||
rm -f *.info* *.1 $(INFOS)
|
||||
rm -f *.info* *.1 *.html *.pdf $(INFOS)
|
||||
rm -f Makefile
|
||||
|
||||
.PHONY: doxygen
|
||||
|
||||
294
docs/install.adoc
Normal file
294
docs/install.adoc
Normal file
@ -0,0 +1,294 @@
|
||||
= Verilator Installation
|
||||
:toc: right
|
||||
|
||||
// Github doesn't render unless absolute URL
|
||||
image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
|
||||
|
||||
== Introduction
|
||||
|
||||
This discusses how to install Verilator. For more general information
|
||||
please see http://verilator.org[verilator.org].
|
||||
|
||||
== Quick-start
|
||||
|
||||
=== Install From a Package Manager
|
||||
|
||||
Using a distribution's package manager is the easiest way to get
|
||||
started. (Note packages are unlikely to have the most recent version, so
|
||||
Git, below, maybe a better alternative.) To install as a package:
|
||||
|
||||
apt-get install verilator
|
||||
|
||||
If this works, skip down to <<Running Verilator>>.
|
||||
|
||||
=== Git
|
||||
|
||||
Alternatively, installing Verilator with Git provides the most flexibility.
|
||||
For additional options and details see the additional sections below. In
|
||||
brief:
|
||||
|
||||
// Also update README
|
||||
....
|
||||
# Prerequisites:
|
||||
#sudo apt-get install git make autoconf g++ flex bison
|
||||
#sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)
|
||||
#sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error)
|
||||
|
||||
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
|
||||
|
||||
# Every time you need to build:
|
||||
unsetenv VERILATOR_ROOT # For csh; ignore error if on bash
|
||||
unset VERILATOR_ROOT # For bash
|
||||
cd verilator
|
||||
git pull # Make sure git repository is up-to-date
|
||||
git tag # See what versions exist
|
||||
#git checkout master # Use development branch (e.g. recent bug fixes)
|
||||
#git checkout stable # Use most recent stable release
|
||||
#git checkout v{version} # Switch to specified release version
|
||||
|
||||
autoconf # Create ./configure script
|
||||
./configure
|
||||
make
|
||||
sudo make install
|
||||
# Now see "man verilator" or online verilator.pdf's for the example tutorials
|
||||
....
|
||||
|
||||
If this works, skip down to <<Running Verilator>>.
|
||||
|
||||
== Detailed Build Instructions
|
||||
|
||||
This section describes details of the build process, and assumes you are
|
||||
building from Git or a tarball. For using a pre-built binary for your
|
||||
Linux distribution, see instead <<Install From a Package Manager>>.
|
||||
|
||||
=== OS Requirements
|
||||
|
||||
Verilator is developed and has primary testing on Ubuntu. Versions have
|
||||
also built on Redhat Linux, Apple OS-X, HPUX and Solaris. It should run
|
||||
with minor porting on any GNU/Linux-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++.
|
||||
|
||||
=== Install Prerequisites
|
||||
|
||||
To build Verilator you will need to install some standard packages:
|
||||
|
||||
sudo apt-get install git
|
||||
sudo apt-get install autoconf
|
||||
sudo apt-get install flex bison
|
||||
|
||||
Additionally, to build or run Verilator you need these standard packages:
|
||||
|
||||
sudo apt-get install perl python3
|
||||
sudo apt-get install make
|
||||
sudo apt-get install g++ # Alternatively, clang
|
||||
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)
|
||||
|
||||
Those developing Verilator may also want these (see internals.adoc):
|
||||
|
||||
sudo apt-get install gdb asciidoctor graphviz
|
||||
cpan install Pod::Perldoc
|
||||
cpan install Unix::Processors
|
||||
|
||||
==== Install SystemC
|
||||
|
||||
If you will be using SystemC (vs straight C++ output), download
|
||||
http://www.systemc.org[SystemC]. 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.)
|
||||
|
||||
==== Install GTKWave
|
||||
|
||||
To make use of Verilator FST tracing you will want
|
||||
http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not
|
||||
required at Verilator build time.
|
||||
|
||||
=== Obtain Sources
|
||||
|
||||
You may use Git or a tarball for the sources. Git is the supported option.
|
||||
(If using a historical build that uses a tarball, tarballs are obtained
|
||||
from https://www.veripool.org/projects/verilator/wiki/Download[Verilator
|
||||
Downloads]; we presume you know how to use it, and is not described here.)
|
||||
|
||||
Get the sources from the repository: (You need do this only once, ever.)
|
||||
|
||||
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
|
||||
|
||||
Enter the checkout and determine what version/branch to use:
|
||||
|
||||
cd verilator
|
||||
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
|
||||
|
||||
=== Auto Configure
|
||||
|
||||
Create the configuration script:
|
||||
|
||||
autoconf # Create ./configure script
|
||||
|
||||
=== Eventual Installation Options
|
||||
|
||||
Before configuring the build, you have to decide how you're going to
|
||||
eventually install the kit. Verilator will be compiling the current value
|
||||
of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults
|
||||
into the executable, so they must be correct before configuring.
|
||||
|
||||
These are the options:
|
||||
|
||||
==== 1. Run-in-Place from VERILATOR_ROOT
|
||||
|
||||
Our personal favorite is to always run Verilator in-place from its Git
|
||||
directory. This allows the easiest experimentation and upgrading, and
|
||||
allows many versions of Verilator to co-exist on a system.
|
||||
|
||||
export VERILATOR_ROOT=`pwd` # if your shell is bash
|
||||
setenv VERILATOR_ROOT `pwd` # if your shell is csh
|
||||
./configure
|
||||
# Running will use files from $VERILATOR_ROOT, so no install needed
|
||||
|
||||
Note after installing (below steps), a calling program or shell must 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.
|
||||
|
||||
==== 2. Install into a CAD Disk
|
||||
|
||||
You may eventually be installing onto a project/company-wide "CAD" tools
|
||||
disk that may support multiple versions of every tool. Target the build to
|
||||
a destination directory name that includes the Verilator version name:
|
||||
|
||||
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
|
||||
http://modules.sourceforge.net/[modulecmd], you'll want a module file like
|
||||
the following:
|
||||
|
||||
.modulecmd's verilator/version file
|
||||
----
|
||||
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
|
||||
----
|
||||
|
||||
==== 3. Install into a Specific Path
|
||||
|
||||
You may eventually install Verilator 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`.
|
||||
|
||||
==== 4. Install System Globally
|
||||
|
||||
The final option is to eventually install Verilator 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`.
|
||||
|
||||
=== Configure
|
||||
|
||||
The command to configure the package was described in the previous step.
|
||||
Developers should configure to have more complete developer tests.
|
||||
Additional packages may be required for these tests.
|
||||
|
||||
export VERILATOR_AUTHOR_SITE=1 # Put in your .bashrc
|
||||
./configure --enable-longtests ...above options...
|
||||
|
||||
=== Compile
|
||||
|
||||
Compile Verilator:
|
||||
|
||||
make -j
|
||||
|
||||
=== Test
|
||||
|
||||
Check the compilation by running self-tests:
|
||||
|
||||
make test
|
||||
|
||||
=== Install
|
||||
|
||||
If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
|
||||
install to the OS-standard place:
|
||||
|
||||
make install
|
||||
|
||||
== Running Verilator
|
||||
|
||||
To run Verilator, see the example sections in the
|
||||
https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
|
||||
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
|
||||
|
||||
Also see the `examples/` directory that is part of the kit, and is installed
|
||||
(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
|
||||
|
||||
cd examples/make_hello_c
|
||||
make
|
||||
|
||||
Note if you did a `make install` above you should not have `VERILATOR_ROOT`
|
||||
set in your environment; it is built into the executable.
|
||||
|
||||
== Announcements
|
||||
|
||||
To get notified of new releases, login to
|
||||
http://www.veripool.org[Veripool], and click the "watch" button near the
|
||||
top right under http://www.veripool.org/projects/verilator/news[Verilator
|
||||
News].
|
||||
|
||||
== Directory Structure
|
||||
|
||||
Some relevant files and directories in this package are as follows:
|
||||
|
||||
Changes => Version history
|
||||
README.adoc => This document
|
||||
bin/verilator => Compiler wrapper invoked to Verilate code
|
||||
docs/ => Additional documentation
|
||||
examples/make_hello_c => Example GNU-make simple Verilog->C++ conversion
|
||||
examples/make_hello_sc => Example GNU-make simple Verilog->SystemC conversion
|
||||
examples/make_tracing_c => Example GNU-make Verilog->C++ with tracing
|
||||
examples/make_tracing_sc => Example GNU-make Verilog->SystemC with tracing
|
||||
examples/make_protect_lib => Example using --protect-lib
|
||||
examples/cmake_hello_c => Example building make_hello_c with CMake
|
||||
examples/cmake_hello_sc => Example building make_hello_sc with CMake
|
||||
examples/cmake_tracing_c => Example building make_tracing_c with CMake
|
||||
examples/cmake_tracing_sc => Example building make_tracing_sc with CMake
|
||||
examples/cmake_protect_lib => Example building make_protect_lib with CMake
|
||||
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
|
||||
src/ => Translator source code
|
||||
test_regress => Internal tests
|
||||
|
||||
For files created after a design is Verilated, see the
|
||||
https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
|
||||
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
|
||||
|
||||
== License
|
||||
|
||||
Copyright 2008-2019 by Wilson Snyder. 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.
|
||||
@ -9,7 +9,7 @@ image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role=
|
||||
This file discusses internal and programming details for Verilator. It's a
|
||||
reference for developers and debugging problems.
|
||||
|
||||
See also the Verilator internals presentation at http://www.veripool.org.
|
||||
See also the Verilator internals presentation at https://www.veripool.org.
|
||||
|
||||
== Code Flows
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user