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/
|
/cov_work/
|
||||||
/logs/
|
/logs/
|
||||||
^Makefile$
|
^Makefile$
|
||||||
|
README.html
|
||||||
bin/verilator_bin.*
|
bin/verilator_bin.*
|
||||||
bin/verilator_coverage_bin.*
|
bin/verilator_coverage_bin.*
|
||||||
|
docs/.*\.html$
|
||||||
docs/Makefile$
|
docs/Makefile$
|
||||||
docs/doxygen-doc/.*
|
docs/doxygen-doc/.*
|
||||||
examples/xml_py/copied/
|
examples/xml_py/copied/
|
||||||
|
|||||||
25
Makefile.in
25
Makefile.in
@ -115,8 +115,9 @@ SUBDIRS = src test_regress \
|
|||||||
examples/make_tracing_sc \
|
examples/make_tracing_sc \
|
||||||
examples/make_protect_lib \
|
examples/make_protect_lib \
|
||||||
|
|
||||||
INFOS = README README.html README.pdf \
|
INFOS = verilator.txt verilator.html verilator.pdf
|
||||||
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.
|
# Files that can be generated, but should be up to date for a distribution.
|
||||||
DISTDEP = info Makefile
|
DISTDEP = info Makefile
|
||||||
@ -127,6 +128,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
|
|||||||
Changes \
|
Changes \
|
||||||
LICENSE \
|
LICENSE \
|
||||||
MANIFEST.SKIP \
|
MANIFEST.SKIP \
|
||||||
|
README.adoc \
|
||||||
verilator-config.cmake.in \
|
verilator-config.cmake.in \
|
||||||
verilator-config-version.cmake.in \
|
verilator-config-version.cmake.in \
|
||||||
bin/verilator \
|
bin/verilator \
|
||||||
@ -142,6 +144,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
|
|||||||
docs/TODO \
|
docs/TODO \
|
||||||
docs/doxygen-mainpage \
|
docs/doxygen-mainpage \
|
||||||
docs/doxygen.config \
|
docs/doxygen.config \
|
||||||
|
docs/install.adoc \
|
||||||
docs/internals.adoc \
|
docs/internals.adoc \
|
||||||
docs/verilator_logo.png \
|
docs/verilator_logo.png \
|
||||||
install-sh configure *.pod \
|
install-sh configure *.pod \
|
||||||
@ -281,22 +284,6 @@ verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX)
|
|||||||
pdflatex verilator.tex
|
pdflatex verilator.tex
|
||||||
-rm -f verilator.toc verilator.aux verilator.idx verilator.out
|
-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
|
# 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 \
|
VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg \
|
||||||
verilator_coverage verilator_gantt verilator_includer verilator_profcfunc
|
verilator_coverage verilator_gantt verilator_includer verilator_profcfunc
|
||||||
@ -529,7 +516,7 @@ clean mostlyclean distclean maintainer-clean::
|
|||||||
rm -rf nodist/obj_dir
|
rm -rf nodist/obj_dir
|
||||||
|
|
||||||
distclean maintainer-clean::
|
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 Makefile config.status config.cache config.log TAGS
|
||||||
rm -f verilator_bin* verilator_coverage_bin*
|
rm -f verilator_bin* verilator_coverage_bin*
|
||||||
rm -f bin/verilator_bin* 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
|
Makefile
|
||||||
|
|||||||
@ -23,6 +23,7 @@
|
|||||||
|
|
||||||
#### Start of system configuration section. ####
|
#### Start of system configuration section. ####
|
||||||
|
|
||||||
|
ASCIIDOCTOR = asciidoctor
|
||||||
DOXYGEN = doxygen
|
DOXYGEN = doxygen
|
||||||
|
|
||||||
#### End of system configuration section. ####
|
#### End of system configuration section. ####
|
||||||
@ -33,6 +34,9 @@ DOXYGEN = doxygen
|
|||||||
default:
|
default:
|
||||||
@echo "error: make not supported here, run 'make docs' from Verilator top-level"
|
@echo "error: make not supported here, run 'make docs' from Verilator top-level"
|
||||||
|
|
||||||
|
%.html: %.adoc
|
||||||
|
$(ASCIIDOCTOR) $< -n -o $@
|
||||||
|
|
||||||
clean mostlyclean distclean maintainer-clean::
|
clean mostlyclean distclean maintainer-clean::
|
||||||
rm -f $(SCRIPTS) *.tmp
|
rm -f $(SCRIPTS) *.tmp
|
||||||
rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
|
rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
|
||||||
@ -41,7 +45,7 @@ clean mostlyclean distclean maintainer-clean::
|
|||||||
rm -f *.tex
|
rm -f *.tex
|
||||||
|
|
||||||
distclean maintainer-clean::
|
distclean maintainer-clean::
|
||||||
rm -f *.info* *.1 $(INFOS)
|
rm -f *.info* *.1 *.html *.pdf $(INFOS)
|
||||||
rm -f Makefile
|
rm -f Makefile
|
||||||
|
|
||||||
.PHONY: doxygen
|
.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
|
This file discusses internal and programming details for Verilator. It's a
|
||||||
reference for developers and debugging problems.
|
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
|
== Code Flows
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user