VeniVidiVici
/
verilator
mirror of https://github.com/verilator/verilator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation has been rewritten into a book format.

This commit is contained in:
Wilson Snyder 2021-04-11 18:55:06 -04:00
parent 0d6099b2b7
commit adce7ecf4b
74 changed files with 9186 additions and 6126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Changes
View File

@ -11,6 +11,10 @@ contributors that suggested a given feature are shown in []. Thanks!
Verilator 4.201 devel
==========================
**Major:**
* Documentation has been rewritten into a book format.
**Minor:**
* Add EOFNEWLINE warning when missing a newline at EOF.
@ -169,7 +173,7 @@ Verilator 4.102 2020-10-15
* Support # as a comment in -f files (#2497). [phantom-killua]
* Support 'this' (#2585). [Rafal Kapuscik]
* Support defines for FST tracing (#2592). [Markus Krause]
* Support |=> inside properties (#1292). [Peter Monsson]
* Support non-overapping implication inside properties (#1292). [Peter Monsson]
* Fix timescale with --hierarchical (#2554). [Yutetsu TAKATSUKASA]
* Fix cmake build with --hierarchical (#2560). [Yutetsu TAKATSUKASA]
* Fix -G dropping public indication (#2561). [Andrew Goessling]
@ -195,7 +199,7 @@ Verilator 4.100 2020-09-07
* Support (with limitations) class extern, class extends, virtual class.
* Support $urandom, $urandom_range without stability.
* Support assume property. [Peter Monsson]
* Support |=> inside properties (#1292). [Peter Monsson]
* Support non-overapping implication inside properties (#1292). [Peter Monsson]
* Fix false DECLFILENAME on black-boxed modules (#2430). [Philipp Wagner]
* Fix naming of "id : begin" blocks.
* Fix class constructor error on assignments to const.
@ -401,7 +405,7 @@ Verilator 4.026 2020-01-11
**Minor:**
* Support bounded queues.
* Support implication operator "|->" in assertions. (#2069) [Peter Monsson]
* Support non-overlapping implication operator in assertions. (#2069) [Peter Monsson]
* Support string compare, ato*, etc methods. (#1606) [Yutetsu TAKATSUKASA]
* Support immediate cover statements.
* Ignore `uselib to end-of-line. (#1634) [Frederic Antonin]
@ -1172,7 +1176,7 @@ Verilator 3.866 2014-11-15
* Add public enums. (#833) [Jonathon Donaldson]
* Trace_off now operates on cells. (#826) [Lane Brooks]
* Fix public parameters in unused packages. (#804) [Jonathon Donaldson]
* Fix select when partially out-of-bound. (#823) [Cliffort Wolf]
* Fix select when partially out-of-bound. (#823) [Clifford Wolf]
* Fix generate unrolling with function call. (#830) [Steven Slatter]
* Fix cast-to-size context-determined sizing. (#828) [Geoff Barrett]
* Fix not tracing modules following primitives. (#837) [Jie Xu]
@ -1513,7 +1517,7 @@ Verilator 3.833 2012-04-15
**Minor:**
* Support += and -= in standard for loops. (#463) [Alex Solomatnikov]
* Fix processing unused parametrized modules. (#469) (#470) [Alex Solomatnikov]
* Fix processing unused parameterized modules. (#469) (#470) [Alex Solomatnikov]
* Add SELRANGE as warning instead of error. (#477) [Alex Solomatnikov]
* Add readme.pdf and internal.pdf and doxygen. (#483) [by Jeremy Bennett]
* Fix change detections on arrays. (#364) [John Stevenson, Alex Solomatnikov]
@ -1585,7 +1589,7 @@ Verilator 3.824 2011-10-25
**Minor:**
* Fix "always @ (* )". (#403) (#404) [Walter Lavino]
* Add ASSIGNIN as suppressable error. [Jeremy Bennett]
* Add ASSIGNIN as suppressible error. [Jeremy Bennett]
* Fix 3.823 constructor core dump on Debian. (#401) [Ahmed El-Mahmoudy]
@ -1667,7 +1671,7 @@ Verilator 3.811 2011-02-14
* Report error on duplicated or empty pins. (#321) [Christian Leber]
* Report error on function call output tied to constant. [Bernard Deadman]
* Throw UNUSED/UNDRIVEN only once per net in a parametrized module.
* Throw UNUSED/UNDRIVEN only once per net in a parameterized module.
* Fix internal error on functions called as SV tasks. [Bernard Deadman]
* Fix internal error on non-inlined inout pins. [Jeff Winston]
* Fix false BLKSEQ on non-unrolled for loop indexes. [Jeff Winston]
@ -1970,7 +1974,7 @@ Verilator 3.700 2009-01-08
* Line coverage now aggregates by hierarchy automatically.
Previously this would be done inside SystemPerl, which was slower.
* Minor performance improvements of Verilator compiler runtime.
* Coverage of each parametarized module is counted separately. [Bob Fredieu]
* Coverage of each parameterized module is counted separately. [Bob Fredieu]
* Fix creating parameterized modules when no parameter values are changed.
* Fix certain generate-if cells causing "clone" error. [Stephane Laurent]
* Fix line coverage of public functions. [Soon Koh]
@ -2381,7 +2385,7 @@ Verilator 3.620 2006-10-04 Stable
* Optimize variables set to constants within basic blocks for ~3%.
* Default make no longer makes the docs; if you edit the documentation.
sources, run "make info" to get them.
* Optimize additional boolean identities (a|a = a, etc.)
* Optimize additional Boolean identities (a|a = a, etc.)
* Fix coredump when dotted cross-ref inside task call. [Eugene Weber]
* Fix dotted variables in always sensitivity lists. [Allan Cochrane]

1
MANIFEST.SKIP
View File

@ -42,6 +42,7 @@ docs/.*\.html$
docs/_build/
docs/clang-format.txt$
docs/doxygen-doc/.*
docs/spelling.txt
examples/xml_py/copied/
examples/xml_py/graph.*
sonar-project.properties

49
Makefile.in
View File

@ -51,7 +51,6 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_DATA = @INSTALL_DATA@
MAKEINFO = makeinfo
POD2TEXT = pod2text
POD2LATEXFIX = $(srcdir)/src/pod2latexfix
MKINSTALLDIRS = $(SHELL) $(srcdir)/src/mkinstalldirs
PERL = @PERL@
@ -111,14 +110,14 @@ SUBDIRS = docs src test_regress \
examples/make_protect_lib \
examples/xml_py \
INFOS = verilator.txt verilator.html verilator.pdf
INFOS = 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
DISTFILES_INC = $(INFOS) .gitignore \
DISTFILES1 = $(INFOS) .gitignore \
*.in *.ac \
Artistic \
Changes \
@ -137,9 +136,14 @@ DISTFILES_INC = $(INFOS) .gitignore \
docs/CONTRIBUTING.rst \
docs/CONTRIBUTORS \
docs/Makefile \
docs/_static/verilator_logo.png \
docs/_static/* \
docs/bin/* \
docs/gen/* \
docs/guide/* \
docs/install.rst \
docs/internals.rst \
docs/internals.rst \
docs/verilated.dox \
docs/xml.rst \
install-sh configure *.pod \
include/*.[chv]* \
@ -157,6 +161,8 @@ DISTFILES_INC = $(INFOS) .gitignore \
examples/*/.*ignore examples/*/Makefile* \
examples/*/*.[chv]* examples/*/vl_* \
examples/*/CMakeLists.txt \
DISTFILES2 = \
test_*/.*ignore test_*/Makefile* test_*/*.cpp \
test_*/*.pl test_*/*.v test_*/*.vc test_*/*.vh \
test_regress/*.pl \
@ -195,8 +201,6 @@ INST_PROJ_BIN_FILES = \
bin/verilator_bin_dbg \
bin/verilator_coverage_bin_dbg \
DISTFILES := $(DISTFILES_INC)
EXAMPLES_FIRST = \
examples/make_hello_c \
examples/make_hello_sc \
@ -260,20 +264,14 @@ info: $(INFOS)
%.1: ${srcdir}/bin/%
pod2man $< $@
verilator.txt: ${srcdir}/bin/verilator
$(POD2TEXT) $< $@
verilator.html: ${srcdir}/bin/verilator
pod2html $< >$@
.PHONY: verilator.html
verilator.html:
$(MAKE) -C docs html
# PDF needs DIST variables; but having configure.ac as dependency isn't detected
verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX)
pod2latex --full --out verilator.tex $<
$(PERL) $(POD2LATEXFIX) "$(DISTTITLE)" "${DISTDATE}" < verilator.tex > verilator2.tex
mv verilator2.tex verilator.tex
pdflatex verilator.tex
pdflatex verilator.tex
-rm -f verilator.toc verilator.aux verilator.idx verilator.out
.PHONY: verilator.pdf
verilator.pdf: Makefile
$(MAKE) -C docs verilator.pdf
# 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 \
@ -474,6 +472,10 @@ clang-format:
PY_PROGRAMS = \
examples/xml_py/vl_file_copy \
examples/xml_py/vl_hier_graph \
docs/guide/conf.py \
docs/guide/vl_sphinx_extract \
docs/guide/vl_sphinx_extract \
docs/guide/vl_doxygen_filter \
src/astgen \
src/bisonpre \
src/config_rev \
@ -564,6 +566,7 @@ clean mostlyclean distclean maintainer-clean::
rm -rf test_*/obj_dir
rm -rf nodist/fuzzer/dictionary
rm -rf nodist/obj_dir
rm -rf verilator.txt
distclean maintainer-clean::
rm -f *.info* *.1 $(INFOS) $(INFOS_OLD) $(VL_INST_MAN_FILES)
@ -588,7 +591,8 @@ doxygen:
dist-file-list:
@echo "begin-dist-file-list:"; # Scripts look for this
@echo $(wildcard $(DISTFILES))
@echo $(wildcard $(DISTFILES1))
@echo $(wildcard $(DISTFILES2))
@echo "end-dist-file-list:"; # Scripts look for this
######################################################################
@ -607,7 +611,12 @@ tag:
# Don't depend on DISTFILES because there's no rule for "standards.info*".
dist: $(DISTDEP) maintainer-copy
-rm -fr $(DISTNAME)
for file in $(DISTFILES); do \
for file in $(DISTFILES1); do \
mkdir -p `dirname $(DISTNAME)/$$file` >/dev/null ; \
ln $$file $(DISTNAME)/$$file \
|| { echo copying $$file instead; cp -p $$file $(DISTNAME)/$$file;}; \
done; true;
for file in $(DISTFILES2); do \
mkdir -p `dirname $(DISTNAME)/$$file` >/dev/null ; \
ln $$file $(DISTNAME)/$$file \
|| { echo copying $$file instead; cp -p $$file $(DISTNAME)/$$file;}; \

5411
bin/verilator
View File

File diff suppressed because it is too large Load Diff

137
bin/verilator_coverage
View File

@ -160,122 +160,27 @@ verilator_coverage - Verilator coverage analyzer
Verilator_coverage processes Verilated model-generated coverage reports.
With --annotate, it reads the specified coverage data file and generates
annotated source code with coverage metrics annotated. If multiple
coverage points exist on the same source code line, additional lines will
be inserted to report the additional points.
For documentation see L<https://verilator.org/verilator_doc.html>.
Additional Verilog-XL-style standard arguments specify the search paths
necessary to find the source code that the coverage analysis was performed
on.
=head1 ARGUMENT SUMMARY
To filter those items to be included in coverage, you may read
logs/coverage.dat into an editor and do a M-x keep-lines to include only
those statistics of interest and save to a new .dat file.
<filename> Specify input data filename, default "coverage.dat"
--annotate <output_dir> Directory name for source annotation.
--annotate-all All files should be shown.
--annotate-min <count> Minimum occurrence count for uncovered.
--help Displays this message and version and exits.
--rank Compute relative importance of tests.
--unlink With --write, unlink all inputs
--version Displays program version and exits.
--write <filename> Write aggregate coverage results.
--write-info <filename.info> Write lcov .info.
For Verilog conditions that should never occur, either add a $stop
statement to the appropriate statement block, or see the Verilator
documentation on "// verilator coverage_off" and "coverage_off". This will
remove the coverage points after the model is re-Verilated.
=head1 ARGUMENTS
=over 4
=item I<filename>
Specify input data file. May be repeated to read multiple inputs. If no
data file is specified, by default coverage.dat is read.
=item --annotate I<output_directory>
Specifies the directory name that source files with annotated coverage data
should be written to.
=item --annotate-all
Specifies all files should be shown. By default, only those source files
which have low coverage are written to the output directory.
=item --annotate-min I<count>
Specifies the minimum occurrence count that should be flagged if the
coverage point does not include a specified threshold. Defaults to 10.
=item --help
Displays this message and program version and exits.
=item --rank
Print an experimental report listing the relative importance of each test
in covering all of the coverage points. The report shows "Covered" which
indicates the number of points that test covers; a test is considered to
cover a point if it has a bucket count of at least 1. The "rank" column has
a higher number t indicate the test is more important, and rank 0 means the
test does not need to be run to cover the points. "RankPts" indicates the
number of coverage points this test will contribute to overall coverage if
all tests are run in the order of highest to lowest rank.
=item --unlink
When using --write to combine coverage data, unlink all input files after
the output has been created.
=item --version
Displays program version and exits.
=item --write I<filename>
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in verilator_coverage data format.
This is useful in scripts to combine many sequential runs into one master
coverage file.
=item --write-info I<filename.info>
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in C<lcov> .info format.
This may be used to use C<lcov> to aggregate or generate reports.
The info format loses data compared to the Verilator coverage data format;
the info will all forms of coverage converted to line style coverage, and
if there are multiple coverage points on a single line, the minimum
coverage across those points will be used to report coverage of the line.
=back
=head1 VERILOG ARGUMENTS
The following arguments are compatible with GCC, VCS and most Verilog
programs.
=over 4
=item +libext+I<ext>+I<ext>...
Defines the extensions for Verilog files.
=item +define+I<var>+I<value>
=item -DI<var>=I<value>
Defines the given variable.
=item +incdir+I<dir>
=item -II<dir>
Specifies a directory for finding include files.
=item -f I<file>
Specifies a file containing additional command line arguments.
=item -y I<dir>
Specifies a module search directory.
=back
+libext+I<ext>+I<ext>... Extensions for Verilog files.
+define+I<var>+I<value> Defines the given variable.
-DI<var>=I<value> Defines the given variable.
+incdir+I<dir> Add directory for finding include files.
-II<dir> Add directory for finding include files.
-y I<dir> Specifies module search directory.
=head1 DISTRIBUTION
@ -288,16 +193,14 @@ Artistic License Version 2.0.
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
=head1 AUTHORS
Wilson Snyder <wsnyder@wsnyder.org>
=head1 SEE ALSO
C<verilator>, C<lcov>
L<verilator_coverage --help> which is the source for this document.
and L<https://verilator.org/verilator_doc.html> for detailed documentation.
=cut
######################################################################

2
bin/verilator_difftree
View File

@ -223,6 +223,8 @@ Wilson Snyder <wsnyder@wsnyder.org>
C<verilator>
and L<https://verilator.org/verilator_doc.html> for detailed documentation.
=cut
######################################################################

90
bin/verilator_gantt
View File

@ -535,83 +535,19 @@ verilator_gantt - Create Gantt chart of multi-threaded execution
=head1 SYNOPSIS
Creates a visual representation to help analyze Verilator multithreaded
simulation performance, by showing when each macro-task starts and ends,
and showing when each thread is busy or idle.
Verilator_gantt creates a visual representation to help analyze Verilator
multithreaded simulation performance, by showing when each macro-task
starts and ends, and showing when each thread is busy or idle.
The generated Gantt chart has time on the X-axis. Times shown are to the
scale printed, i.e. a certain about of time for each character width. The
Y-axis shows threads, each thread's execution is shown on one line. That
line shows "[" at the position in time when it executes.
For documentation see L<https://verilator.org/verilator_doc.html>.
Following the "[" is the CPU number the task executed on, followed by zero
or more "-" to make the width of the characters match the scaled execution
time, followed by a "]". If the scale is too small, the CPU number and
mtask number will not be printed. If the scale is very small, a "&"
indicates multiple mtasks started at that time position.
=head1 ARGUMENT SUMMARY
Also creates a value change dump (VCD) format dump file which may be viewed
in a waveform viewer (e.g. C<GTKWave>). See below.
=head1 USAGE
Build with --prof-threads.
Run a sim with +verilator+prof+threads+window 2.
This will create profile_threads.dat.
Then run:
verilator_gantt profile_threads.dat
The report will be printed on standard output, this also generates
profile_threads.vcd
View profile_threads.vcd in a waveform viewer.
=head1 VCD SIGNALS
In waveforms there are the following signals. Most signals the "decimal"
format will remove the leading zeros and make the traces easier to read.
parallelism: The number of mtasks active at this time, for best performance
this will match the thread count. You may want to use an "analog step"
format to view this signal.
cpu#_thread: For the given CPU number, the thread number executing.
mtask#_cpu; For the given mtask id, the CPU it is executing on.
thread#_mtask: For the given thread number, the mtask id executing.
=head1 ARGUMENTS
=over 4
=item I<filename>
The filename to read data from, defaults to "profile_threads.dat".
=item --help
Displays this message and program version and exits.
=item --scale I<n>
On the X-axis of the generated Gantt chart, each character represents this
many time units. (On x86, time units are rdtsc ticks.) Defaults to 0,
which will automatically compute a reasonable scale where no two mtasks
need to fit into same character width's worth of scaled time.
=item --no-vcd
=item --vcd I<filename>
Set output filename for vcd dump, or disable. Default is
verilator_gantt.vcd.
=back
<filename> Filename to read data from, default "profile_threads.dat".
--help Displays this message and program version and exits.
--scale I<n> Number of characters per time step.
--no-vcd Do not create a VCD file.
--vcd <filename> Set output filename for vcd dump, default "verilator_gantt.vcd."
=head1 DISTRIBUTION
@ -624,14 +560,12 @@ Version 2.0.
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
=head1 AUTHORS
Wilson Snyder <wsnyder@wsnyder.org>
=head1 SEE ALSO
C<verilator>
and L<https://verilator.org/verilator_doc.html> for detailed documentation.
=cut
######################################################################

17
bin/verilator_profcfunc
View File

@ -214,15 +214,12 @@ the functions are then transformed, assuming the user used Verilator's
--prof-cfuncs, and a report printed showing the percentage of time, etc,
in each Verilog block.
=head1 ARGUMENTS
For documentation see L<https://verilator.org/verilator_doc.html>.
=over 4
=head1 ARGUMENT SUMMARY
=item --help
Displays this message and program version and exits.
=back
<filename> Input file (gprof.out)
--help Display this help
=head1 DISTRIBUTION
@ -235,14 +232,12 @@ Version 2.0.
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
=head1 AUTHORS
Wilson Snyder <wsnyder@wsnyder.org>
=head1 SEE ALSO
C<verilator>
and L<https://verilator.org/verilator_doc.html> for detailed documentation.
=cut
######################################################################

3
ci/docker/buildenv/README.rst
View File

@ -1,4 +1,3 @@
================================
Verilator Build Docker Container
================================
@ -52,7 +51,7 @@ top of a repository:
Rebuilding
==========
----------
To rebuild the Verilator-buildenv docker image, run:

3
ci/docker/run/README.rst
View File

@ -1,4 +1,3 @@
=====================================
Verilator Executable Docker Container
=====================================
@ -60,7 +59,7 @@ You can also use the container to build Verilator at a specific commit:
Internals
=========
---------
The Dockerfile builds Verilator and removes the tree when completed to
reduce the image size. The entrypoint is set as a wrapper script

9
docs/CONTRIBUTING.rst
View File

@ -1,4 +1,3 @@
=========================
Contributing to Verilator
=========================
@ -9,7 +8,7 @@ contributions flow more efficiently.
Did you find a bug?
===================
-------------------
- Please **Ensure the bug was not already reported** by searching
`Verilator Issues <https://verilator.org/issues>`__.
@ -26,7 +25,7 @@ Did you find a bug?
Did you write a patch that fixes a bug?
=======================================
---------------------------------------
- Please `Open a new issue <https://verilator.org/issues/new>`__.
@ -72,7 +71,7 @@ Did you write a patch that fixes a bug?
Do you have questions?
======================
----------------------
- Please see FAQ section and rest of the `Verilator
manual <https://verilator.org/verilator_doc.html>`__, or `Verilator
@ -83,7 +82,7 @@ Do you have questions?
Code of Conduct
===============
---------------
- Our contributors and participants pledge to make participation in our
project and our community a positive experience for everyone. We follow

61
docs/Makefile
View File

@ -5,24 +5,25 @@
#
# Code available from: https://verilator.org
#
#*****************************************************************************
#
# Copyright 2003-2021 by Wilson Snyder. This program 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.
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
#
#****************************************************************************/
######################################################################
#
# This file is intended only to be called from the top-level Verilator Makefile.
#### Start of system configuration section. ####
DOXYGEN = doxygen
RST2HTML = rst2html
PYTHON3 = python3
DOXYGEN = doxygen
SPHINXOPTS ?= -c guide
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
#### End of system configuration section. ####
######################################################################
.SUFFIXES:
@ -30,9 +31,49 @@ RST2HTML = rst2html
default:
@echo "error: make not supported here, run 'make docs' from Verilator top-level"
######################################################################
# Intermediate rules
vl-extract: ../bin/verilator ../Changes
mkdir -p _build/gen
$(PYTHON3) bin/vl_sphinx_extract ../bin/verilator
sed 's/`/\&96;/g' < ../Changes > _build/gen/Changes
######################################################################
# HTML
htmled:
$(MAKE) vl-extract
$(MAKE) html
$(PYTHON3) bin/vl_sphinx_fix _build
server: htmled
cd _build/html && $(PYTHON3) -m http.server
%.html: %.rst
$(RST2HTML) $< $@
######################################################################
# PDF
.PHONY: verilator.pdf
verilator.pdf: pdf
pdf:
$(MAKE) vl-extract
$(MAKE) latex
$(PYTHON3) bin/vl_sphinx_fix _build
$(MAKE) -C _build/latex
cp _build/latex/verilator.pdf ..
######################################################################
html latex clean linkcheck spelling::
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
clean mostlyclean distclean maintainer-clean::
rm -f $(SCRIPTS) *.tmp
rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
@ -42,9 +83,3 @@ clean mostlyclean distclean maintainer-clean::
distclean maintainer-clean::
rm -f *.info* *.1 *.html *.pdf $(INFOS)
rm -f Makefile
.PHONY: doxygen
doxygen:
$(DOXYGEN) doxygen.config

BIN
docs/_static/fig_gantt_min.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
docs/_static/verilator_192_150_min.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

BIN
docs/_static/verilator_32x32_min.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 KiB

63
docs/bin/vl_sphinx_extract Executable file
View File

@ -0,0 +1,63 @@
#!/usr/bin/env python3
# pylint: disable=C0112,C0114,C0116,C0301,R0903
# -*- Python -*- See copyright, etc below
######################################################################
import argparse
import re
#######################################################################
class VlSphinxExtract:
debug = 0
SkipBasenames = {}
def process(self, filename):
with open(filename) as fhr:
fhw = None
for line in fhr:
# =for VL_SPHINX_EXTRACT "file_to_write_to"
match = re.search(r'VL_SPHINX_EXTRACT +"([^"]+)"', line)
if match:
outname = match.group(1)
print("Writing %s" % outname)
fhw = open(outname, "w")
fhw.write(
".. comment: generated by vl_sphinx_extract from " +
filename + "\n")
fhw.write(".. code-block::\n")
elif re.match(r'^[=a-zA-Z0-9_]', line):
fhw = None
elif fhw:
fhw.write(line)
#######################################################################
parser = argparse.ArgumentParser(
allow_abbrev=False,
formatter_class=argparse.RawDescriptionHelpFormatter,
description="""Read a file and extract documentation data.""",
epilog=
""" Copyright 2021-2021 by Wilson Snyder. This package 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.
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
parser.add_argument('--debug',
action='store_const',
const=9,
help='enable debug')
parser.add_argument('path', help='path to extract from')
Args = parser.parse_args()
o = VlSphinxExtract()
o.debug = Args.debug
o.process(Args.path)
######################################################################
# Local Variables:
# compile-command: "./vl_sphinx_extract --debug ../../bin/verilator"
# End:

79
docs/bin/vl_sphinx_fix Executable file
View File

@ -0,0 +1,79 @@
#!/usr/bin/env python3
# pylint: disable=C0112,C0114,C0116,C0301,R0903
# -*- Python -*- See copyright, etc below
######################################################################
import argparse
import os
import re
#######################################################################
class VlSphinxFix:
debug = 0
SkipBasenames = {}
def process(self, path):
if os.path.isdir(path):
for basefile in os.listdir(path):
file = os.path.join(path, basefile)
if ((basefile != ".") and (basefile != "..")
and basefile not in self.SkipBasenames
and not os.path.islink(file)):
self.process(file)
elif re.search(r'\.(html|tex)$', path):
self._edit(path)
def _edit(self, filename):
is_html = re.search(r'\.(html)$', filename)
with open(filename) as fhr:
origfile = fhr.read()
wholefile = origfile
# Option doesn't like spaces, so we use
# :option:`/*verilator&32;metacomment*/`
wholefile = re.sub(r'verilator-32-', r'verilator-', wholefile)
if is_html:
wholefile = re.sub(r'&amp;32;', r'&nbsp;', wholefile)
wholefile = re.sub(r'&amp;96;', r'`', wholefile)
else:
wholefile = re.sub(r'&amp;32;', r' ', wholefile)
wholefile = re.sub(r'&amp;96;', r'`', wholefile)
if wholefile != origfile:
if self.debug:
print("Edit %s" % filename)
tempname = filename + ".tmp"
with open(tempname, "w") as fhw:
fhw.write(wholefile)
os.rename(tempname, filename)
#######################################################################
parser = argparse.ArgumentParser(
allow_abbrev=False,
formatter_class=argparse.RawDescriptionHelpFormatter,
description="""Post-process Sphinx HTML.""",
epilog=
""" Copyright 2021-2021 by Wilson Snyder. This package 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.
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
parser.add_argument('--debug',
action='store_const',
const=9,
help='enable debug')
parser.add_argument('path', help='path to edit')
Args = parser.parse_args()
o = VlSphinxFix()
o.debug = Args.debug
o.process(Args.path)
######################################################################
# Local Variables:
# compile-command: "./vl_sphinx_fix --debug _build"
# End:

4
docs/gen/ex_USERERROR_faulty.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block:: sv
$error("User elaboration-time error");

4
docs/gen/ex_USERERROR_msg.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block::
%Warning-USERERROR: example.v:1:7 User elaboration-time error

4
docs/gen/ex_USERFATAL_faulty.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block:: sv
$fatal(0, "User elaboration-time fatal");

4
docs/gen/ex_USERFATAL_msg.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block::
%Warning-USERFATAL: example.v:1:7 User elaboration-time fatal

4
docs/gen/ex_USERINFO_faulty.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block:: sv
$info("User elaboration-time info");

4
docs/gen/ex_USERINFO_msg.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block::
-Info: example.v:1:7 User elaboration-time info

4
docs/gen/ex_USERWARN_faulty.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block:: sv
$warning("User elaboration-time warning");

4
docs/gen/ex_USERWARN_msg.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_assert_comp_bad
.. code-block::
%Warning-USERWARN: example.v:1:7 User elaboration-time warning

8
docs/gen/ex_VARHIDDEN_faulty.rst Normal file
View File

@ -0,0 +1,8 @@
.. comment: generated by t_var_bad_hide_docs
.. code-block:: sv
:linenos:
:emphasize-lines: 2
module t;
integer t; //<--- Warning ('t' hidden by module 't')
endmodule

5
docs/gen/ex_VARHIDDEN_msg.rst Normal file
View File

@ -0,0 +1,5 @@
.. comment: generated by t_var_bad_hide_docs
.. code-block::
%Warning-VARHIDDEN: example.v:2:12 Declaration of signal hides declaration in upper scope: 't'
example.v:1:8 ... Location of original declaration

8
docs/gen/ex_WIDTH_1_faulty.rst Normal file
View File

@ -0,0 +1,8 @@
.. comment: generated by t_lint_width_docs_bad
.. code-block:: sv
:linenos:
:emphasize-lines: 3
int array[5];
bit [1:0] rd_addr;
wire int rd_value = array[rd_addr]; //<--- Warning

5
docs/gen/ex_WIDTH_1_fixed.rst Normal file
View File

@ -0,0 +1,5 @@
.. comment: generated by t_lint_width_docs_bad
.. code-block:: sv
:emphasize-lines: 1
wire int rd_value = array[{1'b0, rd_addr}]; //<--- Fixed

4
docs/gen/ex_WIDTH_1_msg.rst Normal file
View File

@ -0,0 +1,4 @@
.. comment: generated by t_lint_width_docs_bad
.. code-block::
%Warning-WIDTH: example.v:3:29 Bit extraction of array[4:0] requires 3 bit index, not 2 bits.

16
docs/guide/changes.rst Normal file
View File

@ -0,0 +1,16 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
****************
Revision History
****************
.. COMMENT above header must use ### so there is an extra level of headers
here so the index won't show the huge list of revisions when clicking on
"Revision History" in the sidebar.
Changes are contained in the :file:`Changes` file of the distribution, and
also summarized below. To subscribe to new versions see `Verilator
Announcements <https://github.com/verilator/verilator-announce>`_.
.. include:: ../_build/gen/Changes

221
docs/guide/conf.py Normal file
View File

@ -0,0 +1,221 @@
# pylint: disable=E402
#
# Configuration file for Verilator's Sphinx documentation builder.
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
#
# This file only contains overridden options. For a full list:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
#
# ----------------------------------------------------------------------
# -- Path setup
from datetime import datetime
import os
import re
import shutil
import sys
sys.path.insert(0, os.path.abspath('./_ext'))
import sphinx_rtd_theme
def get_vlt_version():
filename = "../../src/config_rev.h"
with open(filename) as fh:
for line in fh:
match = re.search(r'= "([a-z0-9.]+)', line)
if match:
return match.group(1)
return "unknown"
# ----------------------------------------------------------------------
# -- Project information
project = 'Verilator'
copyright = '2021 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
author = 'Wilson Snyder'
# The master toctree document.
master_doc = "guide/index"
version = get_vlt_version()
release = get_vlt_version()
rst_prolog = """
.. role:: vlopt(option)
"""
# ----------------------------------------------------------------------
# -- General configuration
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
# To install:
# sudo install enchant
# sudo pip3 install sphinx sphinx_rtd_theme breathe sphinxcontrib-spelling
# We keep this list empty for now to avoid needing dependencies
extensions = []
# extensions = ['breathe', 'sphinxcontrib.spelling']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
'_build', 'Thumbs.db', '.DS_Store', 'internals.rst', 'xml.rst'
]
# Warn about refs
nitpicky = True
nitpicky_ignore = []
# Number figures for referencing
numfig = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = [".rst"]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# Date format to ISO
today_fmt = datetime.now().strftime("%F")
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# TODO could use this for internals<->guide references
# intersphinx_mapping = { 'sphinx': ('https://sphinx-doc.org/', None), }
# ----------------------------------------------------------------------
# -- Options for HTML output
# html_baseurl =
html_domain_indices = False
html_logo = "../_static/verilator_192_150_min.png"
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_theme_options = {
'analytics_id': 'G-D27B0C9QEB',
'logo_only': True,
'style_nav_header_background': "#45acf8", # Default is #2980B9
# 'canonical_url':
}
html_context = {
'display_github': True,
'github_user': 'verilator',
'github_repo': 'verilator',
'github_version': 'master/docs/user/',
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['../_static']
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
html_use_index = False
html_favicon = "../_static/verilator_32x32_min.png"
# Custom sidebar templates, maps document names to template names.
# html_sidebars
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# ----------------------------------------------------------------------
# -- Options for Latex output
latex_logo = "../_static/verilator_logo.png"
latex_elements = {
'extraclassoptions': 'openany,oneside',
'papersize': 'letterpaper',
'makeindex': '',
'printindex': '',
# 'pointsize': '10pt',
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
# latex_documents = [
# (
# master_doc,
# "Verilog-to-Routing.tex",
# "Verilog-to-Routing Documentation",
# "VTR Developers",
# "manual",
# ),
# ]
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
latex_domain_indices = False
# ----------------------------------------------------------------------
# -- Options for manual page output
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
# man_pages = [(master_doc, "verilog-to-routing", "Verilog-to-Routing Documentation", [author], 1)]
# If true, show URL addresses after external links.
# man_show_urls = False
# ----------------------------------------------------------------------
# -- Options for spelling
spelling_word_list_filename = ['spelling.txt']
spelling_ignore_contributor_names = True
# ----------------------------------------------------------------------
# -- Options for doxygen
#if shutil.which("doxygen"):
# breathe_projects = {
# "verilated": "../_build/doxygen/verilated/xml",
# }
# breathe_default_project = "verilated"
#
# if not os.environ.get("SKIP_DOXYGEN", None) == "True":
# for prjname, prjdir in breathe_projects.items():
# print("Generating doxygen files for {}...".format(prjname))
# os.makedirs(prjdir, exist_ok=True)
# cmd = "cd ../_doxygen && doxygen {}.dox".format(prjname)
# subprocess.call(cmd, shell=True)
# else:
# for prjname, prjdir in breathe_projects.items():
# assert os.path.exists(prjdir) == True, "Regenerate doxygen XML for {}".format(prjname)
breathe_projects = {"verilated": "_build/doxygen/verilated/xml/"}
breathe_default_project = "verilated"
breathe_default_members = ('members')

451
docs/guide/connecting.rst Normal file
View File

@ -0,0 +1,451 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Connecting:
******************************
Connecting to Verilated Models
******************************
.. _Connecting to C++:
Connecting to C++
=================
Verilator creates a :file:`{prefix}.h` and :file:`{prefix}.cpp` file for
the top level module, together with additional .h and .cpp files for
internals. See the :file:`examples` directory in the kit for examples. See
:ref:`Files Read/Written` for information on all the files it writes.
After the model is created, there will be a :file:`{prefix}.mk` file that
may be used with Make to produce a :file:`{prefix}__ALL.a` file with all
required objects in it.
The user must write a C++ wrapper and main loop for the simulation, to link
with the Verilated model. Here is a simple example:
.. code-block:: C++
#include <verilated.h> // Defines common routines
#include <iostream> // Need std::cout
#include "Vtop.h" // From Verilating "top.v"
Vtop *top; // Instantiation of module
vluint64_t main_time = 0; // Current simulation time
// This is a 64-bit integer to reduce wrap over issues and
// allow modulus. This is in units of the timeprecision
// used in Verilog (or from --timescale-override)
double sc_time_stamp() { // Called by $time in Verilog
return main_time; // converts to double, to match
// what SystemC does
}
int main(int argc, char** argv) {
Verilated::commandArgs(argc, argv); // Remember args
top = new Vtop; // Create instance
top->reset_l = 0; // Set some inputs
while (!Verilated::gotFinish()) {
if (main_time > 10) {
top->reset_l = 1; // Deassert reset
}
if ((main_time % 10) == 1) {
top->clk = 1; // Toggle clock
}
if ((main_time % 10) == 6) {
top->clk = 0;
}
top->eval(); // Evaluate model
cout << top->out << endl; // Read a output
main_time++; // Time passes...
}
top->final(); // Done simulating
// // (Though this example doesn't get here)
delete top;
}
Note signals are read and written as member variables of the model. You
call the :code:`eval()` method to evaluate the model. When the simulation
is complete call the :code:`final()` method to execute any SystemVerilog
final blocks, and complete any assertions. See :ref:`Evaluation Loop`.
Connecting to SystemC
=====================
Verilator will convert the top level module to a SC_MODULE. This module
will attach directly into a SystemC netlist as an instantiation.
The SC_MODULE gets the same pinout as the Verilog module, with the
following type conversions: Pins of a single bit become bool. Pins 2-32
bits wide become uint32_t's. Pins 33-64 bits wide become sc_bv's or
vluint64_t's depending on the :vlopt:`--no-pins64` option. Wider pins
become sc_bv's. (Uints simulate the fastest so are used where possible.)
Lower modules are not pure SystemC code. This is a feature, as using the
SystemC pin interconnect scheme everywhere would reduce performance by an
order of magnitude.
Direct Programming Interface (DPI)
==================================
Verilator supports SystemVerilog Direct Programming Interface import and
export statements. Only the SystemVerilog form ("DPI-C") is supported, not
the original Synopsys-only DPI.
DPI Example
-----------
In the SYSTEMC example above, if you wanted to import C++ functions into
Verilog, put in our.v:
.. code-block::
import "DPI-C" function int add (input int a, input int b);
initial begin
$display("%x + %x = %x", 1, 2, add(1,2));
endtask
Then after Verilating, Verilator will create a file Vour__Dpi.h with the
prototype to call this function:
.. code-block:: C++
extern int add(int a, int b);
From the sc_main.cpp file (or another .cpp file passed to the Verilator
command line, or the link), you'd then:
.. code-block:: C++
#include "svdpi.h"
#include "Vour__Dpi.h"
int add(int a, int b) { return a+b; }
DPI System Task/Functions
-------------------------
Verilator extends the DPI format to allow using the same scheme to
efficiently add system functions. Simply use a dollar-sign prefixed system
function name for the import, but note it must be escaped.
.. code-block:: sv
export "DPI-C" function integer \$myRand;
initial $display("myRand=%d", $myRand());
Going the other direction, you can export Verilog tasks so they can be
called from C++:
.. code-block:: sv
export "DPI-C" task publicSetBool;
task publicSetBool;
input bit in_bool;
var_bool = in_bool;
endtask
Then after Verilating, Verilator will create a file Vour__Dpi.h with the
prototype to call this function:
.. code-block:: C++
extern void publicSetBool(svBit in_bool);
From the sc_main.cpp file, you'd then:
.. code-block:: C++
#include "Vour__Dpi.h"
publicSetBool(value);
Or, alternatively, call the function under the design class. This isn't
DPI compatible but is easier to read and better supports multiple designs.
.. code-block:: C++
#include "Vour__Dpi.h"
Vour::publicSetBool(value);
// or top->publicSetBool(value);
Note that if the DPI task or function accesses any register or net within
the RTL, it will require a scope to be set. This can be done using the
standard functions within svdpi.h, after the module is instantiated, but
before the task(s) and/or function(s) are called.
For example, if the top level module is instantiated with the name "dut"
and the name references within tasks are all hierarchical (dotted) names
with respect to that top level module, then the scope could be set with
.. code-block:: C++
#include "svdpi.h"
...
svSetScope(svGetScopeFromName("TOP.dut"));
(Remember that Verilator adds a "TOP" to the top of the module hierarchy.)
Scope can also be set from within a DPI imported C function that has been
called from Verilog by querying the scope of that function. See the
sections on DPI Context Functions and DPI Header Isolation below and the
comments within the svdpi.h header for more information.
DPI Imports that access signals
-------------------------------
If a DPI import accesses a signal through the VPI Verilator will not be
able to know what variables are accessed and may schedule the code
inappropriately. Ideally pass the values as inputs/outputs so the VPI is
not required. Alternatively a workaround is to use a non-inlined task as a
wrapper:
.. code-block::
logic din;
// This DPI function will read "din"
import "DPI-C" context function void dpi_that_accesses_din();
always @(...)
dpi_din_args(din);
task dpi_din_args(input din);
/* verilator no_inline_task */
dpi_that_accesses_din();
endtask
DPI Display Functions
---------------------
Verilator allows writing $display like functions using this syntax:
.. code-block::
import "DPI-C" function void
\$my_display(input string formatted /*verilator sformat*/ );
The :option:`/*verilator&32;sformat*/` metacomment indicates that this
function accepts a $display like format specifier followed by any number of
arguments to satisfy the format.
DPI Context Functions
---------------------
Verilator supports IEEE DPI Context Functions. Context imports pass the
simulator context, including calling scope name, and filename and line
number to the C code. For example, in Verilog:
.. code-block::
import "DPI-C" context function int dpic_line();
initial $display("This is line %d, again, line %d\n", `line, dpic_line());
This will call C++ code which may then use the svGet\* functions to read
information, in this case the line number of the Verilog statement that
invoked the dpic_line function:
.. code-block:: C++
int dpic_line() {
// Get a scope: svScope scope = svGetScope();
const char* scopenamep = svGetNameFromScope(scope);
assert(scopenamep);
const char* filenamep = "";
int lineno = 0;
if (svGetCallerInfo(&filenamep, &lineno)) {
printf("dpic_line called from scope %s on line %d\n",
scopenamep, lineno);
return lineno;
} else {
return 0;
}
}
See the IEEE Standard for more information.
DPI Header Isolation
--------------------
Verilator places the IEEE standard header files such as svdpi.h into a
separate include directory, vltstd (VeriLaTor STandarD). When compiling
most applications $VERILATOR_ROOT/include/vltstd would be in the include
path along with the normal $VERILATOR_ROOT/include. However, when
compiling Verilated models into other simulators which have their own
svdpi.h and similar standard files with different contents, the vltstd
directory should not be included to prevent picking up incompatible
definitions.
Public Functions
----------------
Instead of DPI exporting, there's also Verilator public functions, which
are slightly faster, but less compatible.
Verification Procedural Interface (VPI)
=======================================
Verilator supports a limited subset of the VPI. This subset allows
inspection, examination, value change callbacks, and depositing of values
to public signals only.
VPI is enabled with the Verilator :vlopt:`--vpi` option.
To access signals via the VPI, Verilator must be told exactly which signals
are to be accessed. This is done using the Verilator public pragmas
documented below.
Verilator has an important difference from an event based simulator; signal
values that are changed by the VPI will not immediately propagate their
values, instead the top level header file's :code:`eval()` method must be
called. Normally this would be part of the normal evaluation (i.e. the
next clock edge), not as part of the value change. This makes the
performance of VPI routines extremely fast compared to event based
simulators, but can confuse some test-benches that expect immediate
propagation.
Note the VPI by its specified implementation will always be much slower
than accessing the Verilator values by direct reference
(structure->module->signame), as the VPI accessors perform lookup in
functions at simulation runtime requiring at best hundreds of instructions,
while the direct references are evaluated by the compiler and result in
only a couple of instructions.
For signal callbacks to work the main loop of the program must call
:code:`VerilatedVpi::callValueCbs()`.
.. _VPI Example:
VPI Example
-----------
In the below example, we have readme marked read-only, and writeme which if
written from outside the model will have the same semantics as if it
changed on the specified clock edge.
.. code-block:: bash
cat >our.v <<'EOF'
module our (input clk);
reg readme /*verilator public_flat_rd*/;
reg writeme /*verilator public_flat_rw @(posedge clk) */;
initial $finish;
endmodule
EOF
There are many online tutorials and books on the VPI, but an example that
accesses the above signal "readme" would be:
.. code-block:: bash
cat >sim_main.cpp <<'<<EOF'
#include "Vour.h"
#include "verilated.h"
#include "verilated_vpi.h" // Required to get definitions
vluint64_t main_time = 0; // See comments in first example
double sc_time_stamp() { return main_time; }
void read_and_check() {
vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
if (!vh1) vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found");
const char* name = vpi_get_str(vpiName, vh1);
printf("Module name: %s\n", name); // Prints "readme"
s_vpi_value v;
v.format = vpiIntVal;
vpi_get_value(vh1, &v);
printf("Value of v: %d\n", v.value.integer); // Prints "readme"
}
int main(int argc, char** argv, char** env) {
Verilated::commandArgs(argc, argv);
Vour* top = new Vour;
Verilated::internalsDump(); // See scopes to help debug
while (!Verilated::gotFinish()) {
top->eval();
VerilatedVpi::callValueCbs(); // For signal callbacks
read_and_check();
}
delete top;
return 0;
}
EOF
.. _Evaluation Loop:
Wrappers and Model Evaluation Loop
==================================
When using SystemC, evaluation of the Verilated model is managed by the
SystemC kernel, and for the most part can be ignored. When using C++, the
user must call :code:`eval()`, or :code:`eval_step()` and
:code:`eval_end_step()`.
1. When there is a single design instantiated at the C++ level that needs
to evaluate within a given context, call :code:`designp->eval()`.
2. When there are multiple designs instantiated at the C++ level that need
to evaluate within a context, call :code:`first_designp->eval_step()` then
:code:`->eval_step()` on all other designs. Then call
:code:`->eval_end_step()` on the first design then all other designs. If
there is only a single design, you would call :code:`eval_step()` then
:code:`eval_end_step()`; in fact :code:`eval()` described above is just a
wrapper which calls these two functions.
When :code:`eval()` (or :code:`eval_step()`) is called Verilator looks for
changes in clock signals and evaluates related sequential always blocks,
such as computing always_ff @ (posedge...) outputs. Then Verilator
evaluates combinatorial logic.
Note combinatorial logic is not computed before sequential always blocks
are computed (for speed reasons). Therefore it is best to set any non-clock
inputs up with a separate :code:`eval()` call before changing clocks.
Alternatively, if all always_ff statements use only the posedge of clocks,
or all inputs go directly to always_ff statements, as is typical, then you
can change non-clock inputs on the negative edge of the input clock, which
will be faster as there will be fewer :code:`eval()` calls.
For more information on evaluation, see :file:`docs/internals.rst` in the
distribution.
Verilated and VerilatedContext
==============================
Multiple Verilated models may be part of the same simulation context, that
is share a VPI interface, sense of time, and common settings. This common
simulation context information is stored in a ``VerilatedContext``
structure. If a ``VerilatedContext`` is not created prior to creating a
model, a default global one is created automatically.
The ``Verilated::`` methods, including the ``Verilated::commandArgs`` call
shown above, simply call VerilatedContext methods using the default global
VerilatedContext. (Technically they operate on the last one used by a
given thread.) If you are using multiple simulation contexts you should
not use the Verilated:: methods, and instead always use VerilatedContext
methods called on the appropriate VerilatedContext object.
For methods available under Verilated and VerilatedContext see
:file:`include/verilated.h` in the distribution.

68
docs/guide/contributing.rst Normal file
View File

@ -0,0 +1,68 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*******************************
Contributing and Reporting Bugs
*******************************
Announcements
=============
To get notified of new releases and other important announcements, go to
`Verilator announcement repository
<https://github.com/verilator/verilator-announce>`__ and follow the
instructions there.
Reporting Bugs
==============
First, check the :ref:`Language Limitations` section.
Next, try the :vlopt:`--debug` option. This will enable additional
internal assertions, and may help identify the problem.
Finally, reduce your code to the smallest possible routine that exhibits
the bug. Even better, create a test in the :file:`test_regress/t`
directory, as follows:
.. code-block:: bash
cd test_regress
cp -p t/t_EXAMPLE.pl t/t_BUG.pl
cp -p t/t_EXAMPLE.v t/t_BUG.v
There are many hints on how to write a good test in the
:file:`test_regress/driver.pl` documentation which can be seen by running:
.. code-block:: bash
cd $VERILATOR_ROOT # Need the original distribution kit
test_regress/driver.pl --help
Edit :file:`t/t_BUG.pl` to suit your example; you can do anything you want
in the Verilog code there; just make sure it retains the single clk input
and no outputs. Now, the following should fail:
.. code-block:: bash
cd $VERILATOR_ROOT # Need the original distribution kit
cd test_regress
t/t_BUG.pl # Run on Verilator
t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
t/t_BUG.pl --vcs # Run on VCS simulator
t/t_BUG.pl --nc|--iv|--ghdl # Likewise on other simulators
The test driver accepts a number of options, many of which mirror the main
Verilator options. For example the previous test could have been run with
debugging enabled. The full set of test options can be seen by running
:command:`driver.pl --help` as shown above.
Finally, report the bug at `Verilator Issues
<https://verilator.org/issues>`_. The bug will become publicly visible; if
this is unacceptable, mail the bug report to ``wsnyder@wsnyder.org``.
.. Contributing
.. ============
.. include:: ../CONTRIBUTING.rst

155
docs/guide/contributors.rst Normal file
View File

@ -0,0 +1,155 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
************************
Contributors and Origins
************************
Authors
=======
When possible, please instead report bugs at `Verilator Issues
<https://verilator.org/issues>`_.
Primary author is Wilson Snyder <wsnyder@wsnyder.org>.
Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
Contributors
============
Many people have provided ideas and other assistance with Verilator.
Verilator is receiving major development support from the `CHIPS Alliance
<https://chipsalliance.org>`_.
Previous major corporate sponsors of Verilator, by providing significant
contributions of time or funds included include: Atmel Corporation, Cavium
Inc., Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd.,
Hicamp Systems, Intel Corporation, Mindspeed Technologies Inc., MicroTune
Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus Networks Inc.,
and SiCortex Inc.
The people who have contributed major functionality are: Byron Bradley,
Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Geza Lore, Todd
Strader, Stefan Wallentowitz, Paul Wasson, Jie Xu, and Wilson Snyder.
Major testers included Jeff Dutton, Jonathon Donaldson, Ralf Karge, David
Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov, Sebastien Van
Cauwenberghe, Gene Weber, and Clifford Wolf.
Some of the people who have provided ideas, and feedback for Verilator
include: David Addison, Nikana Anastasiadis, Vasu Arasanipalai, Jens Arm,
Tariq B. Ahmad, Sharad Bagri, Matthew Ballance, Andrew Bardsley, Matthew
Barr, Geoff Barrett, Kaleb Barrett, Julius Baxter, Jeremy Bennett, Michael
Berman, Jean Berniolles, Victor Besyakov, Moinak Bhattacharyya, Krzysztof
Bieganski, David Binderman, Piotr Binkowski, Johan Bjork, David Black,
Tymoteusz Blazejczyk, Daniel Bone, Morten Borup Petersen, Gregg Bouchard,
Christopher Boumenot, Nick Bowler, Byron Bradley, Bryan Brady, Charlie
Brej, J Briquet, Lane Brooks, John Brownlee, Jeff Bush, Lawrence Butcher,
Tony Bybell, Iru Cai, Ted Campbell, Chris Candler, Lauren Carlson, Donal
Casey, Alex Chadwick, Terry Chen, Yi-Chung Chen, Enzo Chi, Robert A. Clark,
Ryan Clarke, Allan Cochrane, John Coiner, Gianfranco Costamagna, Sean
Cross, George Cuan, Joe DErrico, Lukasz Dalek, Gunter Dannoritzer, Ashutosh
Das, Maarten De Braekeleer, Bernard Deadman, Alberto Del Rio, John Demme,
Mike Denio, John Deroo, Philip Derrick, John Dickol, Ruben Diez, Danny
Ding, Jacko Dirks, Ivan Djordjevic, Jonathon Donaldson, Sebastian Dressler,
Alex Duller, Jeff Dutton, Tomas Dzetkulic, Richard E George, Edgar
E. Iglesias, Usuario Eda, Charles Eddleston, Chandan Egbert, Jan Egil Ruud,
Joe Eiler, Ahmed El-Mahmoudy, Trevor Elbourne, Mats Engstrom, Charles Eric
LaForest, Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Udi Finkelstein,
Brian Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi, Benjamin Gartner,
Christian Gelinek, Peter Gerst, Glen Gibb, Michael Gielda, Barbara Gigerl,
Shankar Giri, Dan Gisselquist, Petr Gladkikh, Sam Gladstone, Andrew
Goessling, Amir Gonnen, Chitlesh Goorah, Tomasz Gorochowik, Kai Gossner,
Sergi Granell, Al Grant, Alexander Grobman, Xuan Guo, Driss Hafdi, Neil
Hamilton, James Hanlon, Oyvind Harboe, Jannis Harder, Junji Hashimoto,
Thomas Hawkins, Mitch Hayenga, Harald Heckmann, Robert Henry, Stephen
Henry, David Hewson, Jamey Hicks, Joel Holdsworth, Andrew Holme, Hiroki
Honda, Alex Hornung, Pierre-Henri Horrein, David Horton, Peter Horvath, Jae
Hossell, Kuoping Hsu, Alan Hunter, James Hutchinson, Anderson Ignacio da
Silva, Jamie Iles, Thomas J Whatson, Ben Jackson, Mark Jackson Pulver,
Shareef Jalloq, Marlon James, Krzysztof Jankowski, HyungKi Jeong, Iztok
Jeras, James Johnson, Christophe Joly, Franck Jullien, James Jung, Mike
Kagen, Arthur Kahlich, Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi,
Kanad Kanhere, Patricio Kaplan, Pieter Kapsenberg, Rafal Kapuscik, Ralf
Karge, Dan Katz, Sol Katzman, Ian Kennedy, Michael Killough, Jonathan
Kimmitt, Olof Kindgren, Kevin Kiningham, Dan Kirkham, Sobhan Klnv, Gernot
Koch, Jack Koenig, Soon Koh, Nathan Kohagen, Steve Kolecki, Brett Koonce,
Will Korteland, Wojciech Koszek, Varun Koyyalagunta, Markus Krause, David
Kravitz, Roland Kruse, Andreas Kuster, Sergey Kvachonok, Ed Lander, Steve
Lang, Stephane Laurent, Walter Lavino, Christian Leber, Larry Lee, Igor
Lesik, John Li, Eivind Liland, Charlie Lind, Andrew Ling, Jiuyang Liu, Paul
Liu, Derek Lockhart, Jake Longo, Geza Lore, Arthur Low, Stefan Ludwig, Dan
Lussier, Fred Ma, Duraid Madina, Odd Magne Reitan, Affe Mao, Julien
Margetts, Mark Marshall, Alfonso Martinez, Unai Martinez-Corral, Yves
Mathieu, Patrick Maupin, Conor McCullough, Jason McMullan, Elliot Mednick,
Wim Michiels, Miodrag Milanovic, Peter Monsson, Sean Moore, Dennis
Muhlestein, John Murphy, Matt Myers, Nathan Myers, Richard Myers, Dimitris
Nalbantis, Peter Nelson, Bob Newgard, Paul Nitza, Yossi Nivin, Pete Nixon,
Lisa Noack, Mark Nodine, Kuba Ober, Andreas Olofsson, Baltazar Ortiz,
Aleksander Osman, Don Owen, James Pallister, Vassilis Papaefstathiou, Brad
Parker, Dan Petrisko, Maciej Piechotka, David Pierce, Cody Piersall,
Dominic Plunkett, David Poole, Mike Popoloski, Roman Popov, Rich Porter,
Niranjan Prabhu, Usha Priyadharshini, Prateek Puri, Marshal Qiao, Nandu
Raj, Danilo Ramos, Chris Randall, Anton Rapp, Josh Redford, Frederic
Requin, Dustin Richmond, Samuel Riedel, Eric Rippey, Oleg Rodionov, Ludwig
Rogiers, Paul Rolfe, Arjen Roodselaar, Tobias Rosenkranz, Huang Rui, Denis
Rystsov, John Sanguinetti, Galen Seitz, Joseph Shaker, Salman Sheikh, Yu
Sheng Lin, Hao Shi, Mike Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Fan
Shupei, Rodney Sinclair, Steven Slatter, Brian Small, Garrett Smith, Tim
Snyder, Wilson Snyder, Maciej Sobkowski, Stan Sokorac, Alex Solomatnikov,
Wei Song, Art Stamness, David Stanford, John Stevenson, Pete Stevenson,
Patrick Stewart, Rob Stoddard, Todd Strader, John Stroebel, Sven Stucki,
Howard Su, Emerson Suguimoto, Gene Sullivan, Wai Sum Mong, Qingyao Sun,
Renga Sundararajan, Rupert Swarbrick, Yutetsu Takatsukasa, Thierry Tambe,
Drew Taussig, Peter Tengstrand, Wesley Terpstra, Rui Terra, Stefan Thiede,
Gary Thomas, Ian Thompson, Kevin Thompson, Mike Thyer, Hans Tichelaar,
Viktor Tomov, Steve Tong, Alex Torregrosa, Michael Tresidder, David Turner,
Neil Turton, Cong Van Nguyen, Hans Van Antwerpen, Jan Van Winkel, Sebastien
Van Cauwenberghe, Laurens van Dam, Leendert van Doorn, Srini Vemuri, Yuri
Victorovich, Bogdan Vukobratovic, Holger Waechtler, Philipp Wagner, Stefan
Wallentowitz, Shawn Wang, Paul Wasson, Greg Waters, Thomas Watts, Eugene
Weber, David Welch, Martin Whitaker, Marco Widmer, Leon Wildman, Daniel
Wilkerson, Gerald Williams, Trevor Williams, Jeff Winston, Joshua Wise,
Clifford Wolf, Tobias Wolfel, Johan Wouters, Paul Wright, Junyi Xi, Ding
Xiaoliang, Jie Xu, Mandy Xu, Yinan Xu, Luke Yang, Amir Yazdanbakhsh, and
Keyi Zhang.
Thanks to them, and all those we've missed including above, or wished to
remain anonymous.
Historical Origins
==================
Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group at
Digital Equipment Corporation. The Verilog code that was converted to C
was then merged with a C based CPU model of the Alpha processor and
simulated in a C based environment called CCLI.
In 1995 Verilator started being used also for Multimedia and Network
Processor development inside Digital. Duane Galbi took over active
development of Verilator, and added several performance enhancements. CCLI
was still being used as the shell.
In 1998, through the efforts of existing DECies, mainly Duane Galbi,
Digital graciously agreed to release the source code. (Subject to the code
not being resold, which is compatible with the GNU Public License.)
In 2001, Wilson Snyder took the kit, and added a SystemC mode, and called
it Verilator2. This was the first packaged public release.
In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator from
scratch in C++. This added many optimizations, yielding about a 2-5x
performance gain.
In 2009, major SystemVerilog and DPI language support was added.
In 2018, Verilator 4.000 was released with multithreaded support.
In 2019, Verilator joined the `CHIPS Alliance
<https://chipsalliance.org>`_.
Currently, various language features and performance enhancements are added
as the need arises. Verilator is now about 3x faster than in 2002, and is
faster than most (if not every) other simulator.

19
docs/guide/copyright.rst Normal file
View File

@ -0,0 +1,19 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*********
Copyright
*********
The latest version of Verilator is available from `https://verilator.org
<https://verilator.org>`_.
Copyright 2003-2021 by Wilson Snyder. This program is free software; you
can redistribute it and/or modify the Verilator internals under the terms
of either the GNU Lesser General Public License Version 3 or the Perl
Artistic License Version 2.0.
All Verilog and C++/SystemC code quoted within this documentation file are
released as Creative Commons Public Domain (CC0). Many example files and
test files are likewise released under CC0 into effectively the Public
Domain as described in the files themselves.

28
docs/guide/deprecations.rst Normal file
View File

@ -0,0 +1,28 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Deprecations
============
The following deprecated items are scheduled for future removal:
C++11 compiler support
Verilator currently requires C++11 or newer compilers. Verilator will
require C++14 or newer compilers for both compiling Verilator and
compiling Verilated models no sooner than January 2022.
No-Relative-Cfuncs Option
The :vlopt:`--no-relative-cfuncs` option is not be required by any C++11
compliant compiler and is planned for removal no sooner than July 2021.
Inhibit-Sim Option
The :vlopt:`--inhibit-sim` option is planned for removal no sooner than
July 2021.
Configuration File -msg
The :vlopt:`lint_off` "-msg" option has been replaced with the "-rule"
option. "-msg" is planned for removal no sooner than January 2021.
XML locations
The XML "fl" attribute has been replaced with the "loc" attribute. "fl"
is planned for removal no sooner than January 2021.

93
docs/guide/environment.rst Normal file
View File

@ -0,0 +1,93 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Environment
===========
This section describes the environment variables used by Verilator and
associated programs.
.. option:: LD_LIBRARY_PATH
A generic Linux/OS variable specifying what directories have shared
object (.so) files. This path should include SystemC and any other
shared objects needed at simulation runtime.
.. option:: MAKE
Names the executable of the make command invoked when using the
:vlopt:`--build` option. Some operating systems may require "gmake" to
this variable to launch GNU make. If this variable is not specified,
"make" is used.
.. option:: OBJCACHE
Optionally specifies a caching or distribution program to place in front
of all runs of the C++ compiler. For example, "ccache". If using
:command:`distcc` or :command:`icecc`/:command:`icecream`, they would
generally be run under :command:`ccache`; see the documentation for
those programs. If OBJCACHE is not set, and at configure time ccache
was present, ccache will be used as a default.
.. option:: SYSTEMC
Deprecated. Used only if :option:`SYSTEMC_INCLUDE` or
:option:`SYSTEMC_LIBDIR` is not set. If set, specifies the directory
containing the SystemC distribution. If not specified, it will come
from a default optionally specified at configure time (before Verilator
was compiled).
.. option:: SYSTEMC_ARCH
Deprecated. Used only if :option:`SYSTEMC_LIBDIR` is not set.
Specifies the architecture name used by the SystemC kit. This is the
part after the dash in the "lib-{...}" directory name created by a
:command:`make` in the SystemC distribution. If not set, Verilator will
try to intuit the proper setting, or use the default optionally
specified at configure time (before Verilator was compiled).
.. option:: SYSTEMC_CXX_FLAGS
Specifies additional flags that are required to be passed to GCC when
building the SystemC model. System 2.3.0 may need this set to
"-pthread".
.. option:: SYSTEMC_INCLUDE
If set, specifies the directory containing the systemc.h header file. If
not specified, it will come from a default optionally specified at
configure time (before Verilator was compiled), or computed from
SYSTEMC/include.
.. option:: SYSTEMC_LIBDIR
If set, specifies the directory containing the libsystemc.a library. If
not specified, it will come from a default optionally specified at
configure time (before Verilator was compiled), or computed from
SYSTEMC/lib-SYSTEMC_ARCH.
.. option:: VERILATOR_BIN
If set, specifies an alternative name of the ``verilator`` binary. May
be used for debugging and selecting between multiple operating system
builds.
.. option:: VERILATOR_COVERAGE_BIN
If set, specifies an alternative name of the ``verilator_coverage``
binary. May be used for debugging and selecting between multiple
operating system builds.
.. option:: VERILATOR_GDB
If set, the command to run when using the :vlopt:`--gdb` option, such as
"ddd". If not specified, it will use "gdb".
.. option:: VERILATOR_ROOT
Specifies the directory containing the distribution kit. This is used
to find the executable, Perl library, and include files. If not
specified, it will come from a default optionally specified at configure
time (before Verilator was compiled). It should not be specified if
using a pre-compiled Verilator package as the hard-coded value should be
correct. See :ref:`Installation`.

92
docs/guide/example_cc.rst Normal file
View File

@ -0,0 +1,92 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Example C++ Execution:
Example C++ Execution
=====================
We'll compile this example into C++. For an extended and commented version
of what this C++ code is doing, see
:file:`examples/make_tracing_c/sim_main.cpp` in the distribution.
.. include:: example_common_install.rst
Now, let's create an example Verilog, and C++ wrapper file:
.. code-block:: bash
mkdir test_our
cd test_our
cat >our.v <<'EOF'
module our;
initial begin $display("Hello World"); $finish; end
endmodule
EOF
cat >sim_main.cpp <<'EOF'
#include "Vour.h"
#include "verilated.h"
int main(int argc, char** argv, char** env) {
VerilatedContext* contextp = new VerilatedContext;
contextp->commandArgs(argc, argv);
Vour* top = new Vour{contextp};
while (!contextp->gotFinish()) { top->eval(); }
delete top;
delete contextp;
return 0;
}
EOF
Now we run Verilator on our little example.
.. code-block:: bash
verilator -Wall --cc --exe --build sim_main.cpp our.v
Breaking this command down:
#. :vlopt:`-Wall` so Verilator has stronger lint warnings
enabled.
#. :vlopt:`--cc` to get C++ output (versus e.g. SystemC
or only linting).
#. :vlopt:`--exe`, along with our :command:`sim_main.cpp` wrapper file, so
the build will create an executable instead of only a library.
#. :vlopt:`--build` so Verilator will call make itself. This is we don't
need to manually call make as a separate step. You can also write your
own compile rules, and run make yourself as we show in :ref:`Example
SystemC Execution`.)
#. An finally, :command:`our.v` which is our SystemVerilog design file.
Once Verilator completes we can see the generated C++ code under the
:file:`obj_dir` directory.
.. code-block:: bash
ls -l obj_dir
(See :ref:`Files Read/Written` for descriptions of some of the files that
were created.)
And now we run it:
.. code-block:: bash
obj_dir/Vour
And we get as output:
.. code-block:: bash
Hello World
- our.v:2: Verilog $finish
Really, you're better off using a Makefile to run the steps for you so when
your source changes it will automatically run all of the appropriate steps.
To aid this Verilator can create a makefile dependency file. For examples
that do this see the :file:`examples` directory in the distribution.

18
docs/guide/example_common_install.rst Normal file
View File

@ -0,0 +1,18 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
First you need Verilator installed, see :ref:`Installation`. In brief, if
you installed Verilator using the package manager of your operating system,
or did a :command:`make install` to place Verilator into your default path,
you do not need anything special in your environment, and should not have
VERILATOR_ROOT set. However, if you installed Verilator from sources and
want to run Verilator out of where you compiled Verilator, you need to
point to the kit:
.. code-block:: bash
# See above; don't do this if using an OS-distributed Verilator
export VERILATOR_ROOT=/path/to/where/verilator/was/installed
export PATH=$VERILATOR_ROOT/bin:$PATH

40
docs/guide/example_dist.rst Normal file
View File

@ -0,0 +1,40 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Examples in the Distribution:
Examples in the Distribution
============================
See the ``examples/`` directory that is part of the distribution, and
is installed (in a OS-specific place, often in e.g.
``/usr/local/share/verilator/examples``). These examples include:
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
To run an example copy the example to a new directory and run it.
::
cp -rp {path_to}/examples/make_hello_c make_hello_c
cd make_hello_c
make

73
docs/guide/example_sc.rst Normal file
View File

@ -0,0 +1,73 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Example SystemC Execution:
Example SystemC Execution
=========================
This is an example similar to the :ref:`Example C++ Execution`, but using
SystemC. We'll also explicitly run make.
.. include:: example_common_install.rst
Now, let's create an example Verilog, and SystemC wrapper file:
.. code-block:: bash
mkdir test_our_sc
cd test_our_sc
cat >our.v <<'EOF'
module our (clk);
input clk; // Clock is required to get initial activation
always @(posedge clk)
begin $display("Hello World"); $finish; end
endmodule
EOF
cat >sc_main.cpp <<'EOF'
#include "Vour.h"
int sc_main(int argc, char** argv) {
Verilated::commandArgs(argc, argv);
sc_clock clk{"clk", 10, SC_NS, 0.5, 3, SC_NS, true};
Vour* top = new Vour{"top"};
top->clk(clk);
while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
delete top;
return 0;
}
EOF
Now we run Verilator on our little example:
.. code-block:: bash
verilator -Wall --sc --exe sc_main.cpp our.v
This example does not use --build, therefore we need to explicitly compile
it:
.. code-block:: bash
make -j -C obj_dir -f Vour.mk Vour
And now we run it:
.. code-block:: bash
obj_dir/Vour
And we get, after the SystemC banner, the same output as the C++ example:
.. code-block:: bash
SystemC 2.3.3-Accellera
Hello World
- our.v:4: Verilog $finish
Really, you're better off using a Makefile to run the steps for you so when
your source changes it will automatically run all of the appropriate steps.
For examples that do this see the :file:`examples` directory in the
distribution.

22
docs/guide/examples.rst Normal file
View File

@ -0,0 +1,22 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Examples:
========
Examples
========
This section covers the following examples:
* :ref:`Example C++ Execution`
* :ref:`Example SystemC Execution`
* :ref:`Examples in the Distribution`
.. toctree::
:maxdepth: 1
:hidden:
example_cc.rst
example_sc.rst
example_dist.rst

89
docs/guide/exe_sim.rst Normal file
View File

@ -0,0 +1,89 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Simulation Runtime Arguments:
Simulation Runtime Arguments
============================
The following are the arguments that may be passed to a Verilated
executable, provided that executable calls
:code:`Verilated::commandArgs()`.
All simulation runtime arguments begin with "+verilator", so that the
user's executable may skip over all "+verilator" arguments when parsing its
command line.
Summary:
.. include:: ../_build/gen/args_verilated.rst
.. option:: +verilator+debug
Enable simulation runtime debugging. Equivalent to
:vlopt:`+verilator+debugi+4 <+verilator+debugi+\<value\>>`.
.. option:: +verilator+debugi+<value>
Enable simulation runtime debugging at the provided level.
.. option:: +verilator+error+limit+<value>
Set number of non-fatal errors (e.g. assertion failures) before exiting
simulation runtime. Also affects number of $stop calls needed before
exit. Defaults to 1.
.. option:: +verilator+help
Display help and exit.
.. option:: +verilator+prof+threads+file+<filename>
When a model was Verilated using :vlopt:`--prof-threads`, sets the
simulation runtime filename to dump to. Defaults to
:file:`profile_threads.dat`.
.. option:: +verilator+prof+threads+start+<value>
When a model was Verilated using :vlopt:`--prof-threads`, the simulation
runtime will wait until $time is at this value (expressed in units of
the time precision), then start the profiling warmup, then
capturing. Generally this should be set to some time that is well within
the normal operation of the simulation, i.e. outside of reset. If 0, the
dump is disabled. Defaults to 1.
.. option:: +verilator+prof+threads+window+<value>
When a model was Verilated using :vlopt:`--prof-threads`, after $time
reaches :vlopt:`+verilator+prof+threads+start+\<value\>`, Verilator will
warm up the profiling for this number of eval() calls, then will capture
the profiling of this number of eval() calls. Defaults to 2, which
makes sense for a single-clock-domain module where it's typical to want
to capture one posedge eval() and one negedge eval().
.. option:: +verilator+rand+reset+<value>
When a model was Verilated using :vlopt:`--x-initial unique
<--x-initial>`, sets the simulation runtime initialization technique. 0
= Reset to zeros. 1 = Reset to all-ones. 2 = Randomize. See
:ref:`Unknown States`.
.. option:: +verilator+seed+<value>
For $random and :vlopt:`--x-initial unique <--x-initial>`, set the
simulation runtime random seed value. If zero or not specified picks a
value from the system random number generator.
.. option:: +verilator+noassert
Disable assert checking per runtime argument. This is the same as
calling :code:`Verilated::assertOn(false)` in the model.
.. option:: +verilator+V
Shows the verbose version, including configuration information.
.. option:: +verilator+version
Displays program version and exits.

1623
docs/guide/exe_verilator.rst Normal file
View File

File diff suppressed because it is too large Load Diff

114
docs/guide/exe_verilator_coverage.rst Normal file
View File

@ -0,0 +1,114 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator_coverage
==================
Verilator_coverage processes Verilated model-generated coverage reports.
With --annotate, it reads the specified coverage data file and generates
annotated source code with coverage metrics annotated. If multiple
coverage points exist on the same source code line, additional lines will
be inserted to report the additional points.
Additional Verilog-XL-style standard arguments specify the search paths
necessary to find the source code that the coverage analysis was performed
on.
To filter those items to be included in coverage, you may read
logs/coverage.dat into an editor and do a M-x keep-lines to include only
those statistics of interest and save to a new .dat file.
For Verilog conditions that should never occur, either add a $stop
statement to the appropriate statement block, or see
:option:`/*verilator&32;coverage_off*/`. This will remove the coverage
points after the model is re-Verilated.
For an overview of use of verilator_coverage, see :ref:`Coverage Analysis`.
verilator_coverage Example Usage
--------------------------------
..
verilator_coverage --help
verilator_coverage --version
verilator_coverage --annotate <obj>
verilator_coverage -write merged.dat -read <datafiles>...
verilator_coverage -write-info merged.info -read <datafiles>...
verilator_coverage Arguments
----------------------------
.. program:: verilator_coverage
.. option:: <filename>
Specifies the input coverage data file. Multiple filenames may be provided
to read multiple inputs. If no data file is specified, by default
"coverage.dat" will be read.
.. option:: --annotate <output_directory>
Specifies the directory name that source files with annotated coverage data
should be written to.
.. option:: --annotate-all
Specifies all files should be shown. By default, only those source files
which have low coverage are written to the output directory.
.. option:: --annotate-min <count>
Specifies if the coverage point does not include the count number of
coverage hits, then the coverage point will be considered above the
threashold, and the coverage report will put a "%" to indicate the coverage
is not sufficient. Defaults to 10.
.. option:: --help
Displays a help summary, the program version, and exits.
.. option:: --rank
Prints an experimental report listing the relative importance of each test
in covering all of the coverage points. The report shows "Covered" which
indicates the number of points that test covers; a test is considered to
cover a point if it has a bucket count of at least 1. The "rank" column has
a higher number t indicate the test is more important, and rank 0 means the
test does not need to be run to cover the points. "RankPts" indicates the
number of coverage points this test will contribute to overall coverage if
all tests are run in the order of highest to lowest rank.
.. option:: --unlink
With :option:`--write`, unlink all input files after the output
has been successfully created.
.. option:: --version
Displays program version and exits.
.. option:: --write <filename>
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in verilator_coverage data format.
This is useful for use in scripts to combine many coverage data files
(likely generated from random test runs) into one master coverage file.
.. option:: --write-info <filename.info>
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in :command:`lcov` .info format.
This may be used to feed into :command:`lcov` to aggregate or generate
reports.
The info format loses data compared to the Verilator coverage data format;
the info will all forms of coverage converted to line style coverage, and
if there are multiple coverage points on a single line, the minimum
coverage across those points will be used to report coverage of the line.

76
docs/guide/exe_verilator_gantt.rst Normal file
View File

@ -0,0 +1,76 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator_gantt
===============
Verilator_gantt creates a visual representation to help analyze Verilator
multithreaded simulation performance, by showing when each macro-task
starts and ends, and showing when each thread is busy or idle.
For an overview of use of verilator_gantt, see :ref:`Profiling`.
Gantt Chart Contents
--------------------
The generated Gantt chart has time on the X-axis. Times shown are to the
scale printed, i.e. a certain about of time for each character width. The
Y-axis shows threads, each thread's execution is shown on one line. That
line shows "[" at the position in time when it executes.
Following the "[" is the CPU number the task executed on, followed by zero
or more "-" to make the width of the characters match the scaled execution
time, followed by a "]". If the scale is too small, the CPU number and
mtask number will not be printed. If the scale is very small, a "&"
indicates multiple mtasks started at that time position.
Also creates a value change dump (VCD) format dump file which may be viewed
in a waveform viewer (e.g. C<GTKWave>). See below.
Gantt Chart VCD Signals
-----------------------
In waveforms there are the following signals. Most signals the "decimal"
format will remove the leading zeros and make the traces easier to read.
parallelism
The number of mtasks active at this time, for best performance this will
match the thread count. You may want to use an "analog step" format to
view this signal.
cpu#_thread
For the given CPU number, the thread number executing.
mtask#_cpu
For the given mtask id, the CPU it is executing on.
thread#_mtask
For the given thread number, the mtask id executing.
verilator_gantt Arguments
-------------------------
.. program:: verilator_gantt
.. option:: <filename>
The filename to read data from, defaults to "profile_threads.dat".
.. option:: --help
Displays a help summary, the program version, and exits.
.. option:: --scale <n>
Sets the number of time units per character on the X-axis of the generated
Gantt chart. (On x86, time units are rdtsc ticks.) Defaults to 0, which
will automatically compute a reasonable scale where no two mtasks need to
fit into same character width's worth of scaled time.
.. option:: --no-vcd
Disables creating a .vcd file.
.. option:: --vcd <filename>
Sets the output filename for vcd dump. Default is "verilator_gantt.vcd".

25
docs/guide/exe_verilator_profcfuncs.rst Normal file
View File

@ -0,0 +1,25 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator_profcfuncs
====================
Verilator_profcfunc reads a profile report created by gprof. The names of
the functions are then transformed, assuming the user used Verilator's
--prof-cfuncs, and a report printed showing the percentage of time, etc, in
each Verilog block.
For an overview of use of verilator_profcfuncs, see :ref:`Profiling`.
verilator_profcfuncs Arguments
------------------------------
.. program:: verilator_profcfuncs
.. option:: <filename>
The :command:`gprof`-generated filename to read data from. Typically "gprof.out".
.. option:: --help
Displays a help summary, the program version, and exits.

19
docs/guide/executables.rst Normal file
View File

@ -0,0 +1,19 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*********************************
Executable and Argument Reference
*********************************
This section describes the executables that are part of Verilator, and the
options to each executable.
.. toctree::
:maxdepth: 1
:hidden:
exe_verilator.rst
exe_verilator_coverage.rst
exe_verilator_gantt.rst
exe_verilator_profcfuncs.rst
exe_sim.rst

492
docs/guide/extensions.rst Normal file
View File

@ -0,0 +1,492 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*******************
Language Extensions
*******************
The following additional constructs are the extensions Verilator supports
on top of standard Verilog code. Using these features outside of comments
or "`ifdef`"'s may break other tools.
.. option:: `__FILE__
The :option:`\`__FILE__` define expands to the current filename as a
string, like C++'s __FILE__. This Verilator feature added in 2006 was
incorporated into the IEEE 1800-2009 standard.
.. option:: `__LINE__
The :option:`\`__LINE__` define expands to the current filename as a
string, like C++'s __LINE__. This Verilator feature added in 2006 was
incorporated into the IEEE 1800-2009 standard.
.. option:: `error [string]
This will report an error when encountered, like C++'s #error.
.. option:: $c([string], ...);
The string will be embedded directly in the output C++ code at the point
where the surrounding Verilog code is compiled. It may either be a
standalone statement (with a trailing ; in the string), or a function
that returns up to a 32-bit number (without a trailing ;). This can be
used to call C++ functions from your Verilog code.
String arguments will be put directly into the output C++ code.
Expression arguments will have the code to evaluate the expression
inserted. Thus to call a C++ function, :code:`$c("func(",a,")")` will
result in :code:`func(a)` in the output C++ code. For input arguments,
rather than hard-coding variable names in the string
:code:`$c("func(a)")`, instead pass the variable as an expression
::code:`$c("func(",a,")")`. This will allow the call to work inside
Verilog functions where the variable is flattened out, and also enable
other optimizations.
If you will be reading or writing any Verilog variables inside the C++
functions, the Verilog signals must be declared with
:option:`/*verilator&32;public*/` metacomments.
You may also append an arbitrary number to $c, generally the width of
the output; :code:`signal_32_bits = $c32("...");`. This allows for
compatibility with other simulators which require a differently named
PLI function name for each different output width.
.. option:: $display, $write, $fdisplay, $fwrite, $sformat, $swrite
Format arguments may use C fprintf sizes after the % escape. Per the
Verilog standard, %x prints a number with the natural width, and %0x
prints a number with minimum width. Verilator extends this so %5x
prints 5 digits per the C standard (this is unspecified in Verilog, but
was incorporated into the 1800-2009).
.. option:: `coverage_block_off
Specifies the entire begin/end block should be ignored for coverage
analysis. Must be inside a code block, e.g. within a begin/end pair.
Same as :option:`coverage_block_off` in :ref:`Configuration Files`.
.. option:: `systemc_header
Take remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the output .h file's header. Must be placed as a module
item, e.g. directly inside a module/endmodule pair. Despite the name of
this macro, this also works in pure C++ code.
.. option:: `systemc_ctor
Take remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class constructor. Must be placed as a module
item, e.g. directly inside a module/endmodule pair. Despite the name of
this macro, this also works in pure C++ code.
.. option:: `systemc_dtor
Take remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class destructor. Must be placed as a module
item, e.g. directly inside a module/endmodule pair. Despite the name of
this macro, this also works in pure C++ code.
.. option:: `systemc_interface
Take remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class interface. Must be placed as a module item,
e.g. directly inside a module/endmodule pair. Despite the name of this
macro, this also works in pure C++ code.
.. option:: `systemc_imp_header
Take remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the header of all files for this C++ class implementation.
Must be placed as a module item, e.g. directly inside a module/endmodule
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `systemc_implementation
Take remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into a single file of the C++ class implementation. Must be
placed as a module item, e.g. directly inside a module/endmodule
pair. Despite the name of this macro, this also works in pure C++ code.
If you will be reading or writing any Verilog variables in the C++
functions, the Verilog signals must be declared with a
:option:`/*verilator&32;public*/` metacomment. See also the public task
feature; writing an accessor may result in cleaner code.
.. option:: `SYSTEMVERILOG
The SYSTEMVERILOG, SV_COV_START and related standard defines are set by
default when :vlopt:`--language <--language>` is "1800-\*".
.. option:: `VERILATOR
.. option:: `verilator
.. option:: `verilator3
The VERILATOR, verilator and verilator3 defines are set by default so
you may "\`ifdef" around tool specific constructs.
.. option:: `verilator_config
Take remaining text up to the next :option:`\`verilog` mode switch and
treat it as Verilator configuration commands. See :ref:`Configuration Files`.
.. option:: `verilog
Switch back to processing Verilog code after a
:option:`\`systemc_... <\`systemc_header>` mode switch. The Verilog
code returns to the last language mode specified with
"\`begin_keywords", or SystemVerilog if none was specified.
.. option:: /*verilator&32;clock_enable*/
Used after a signal declaration to indicate the signal is used to gate a
clock, and the user takes responsibility for insuring there are no races
related to it. (Typically by adding a latch, and running static timing
analysis.) For example:
.. code-block:: sv
reg enable_r /*verilator clock_enable*/;
wire gated_clk = clk & enable_r;
always_ff @(posedge clk)
enable_r <= enable_early;
The clock_enable attribute will cause the clock gate to be ignored in
the scheduling algorithm, sometimes required for correct clock behavior,
and always improving performance. It's also a good idea to enable the
:option:`IMPERFECTSCH` warning, to ensure all clock enables are properly
recognized.
Same as :option:`clock_enable` configuration file option.
.. option:: /*verilator&32;clocker*/
.. option:: /*verilator&32;no_clocker*/
Used after a signal declaration to indicate the signal is used as clock
or not. This information is used by Verilator to mark the signal as
clocker and propagate the clocker attribute automatically to derived
signals. See :vlopt:`--clk`.
Same as :option:`clocker` and :option:`no_clocker` in configuration
files.
.. option:: /*verilator&32;coverage_block_off*/
Specifies the entire begin/end block should be ignored for coverage
analysis purposes.
Same as :option:`coverage_block_off` configuration file option.
.. option:: /*verilator&32;coverage_off*/
Specifies that following lines of code should have coverage disabled.
Often used to ignore an entire module for coverage analysis purposes.
.. option:: /*verilator&32;coverage_on*/
Specifies that following lines of code should have coverage re-enabled
(if appropriate :vlopt:`--coverage` flags are passed) after being
disabled earlier with :option:`/*verilator&32;coverage_off*/`.
.. _verilator_hier_block:
.. option:: /*verilator&32;hier_block*/
Specifies that the module is a unit of hierarchical Verilation. This
metacomment must be between :code:`module module_name(...);` and
:code:`endmodule`. The module will not be inlined nor uniquified for
each instance in hierarchical Verilation. Note that the metacomment is
ignored unless the :vlopt:`--hierarchical` option is specified.
See :ref:`Hierarchical Verilation`.
.. option:: /*verilator&32;inline_module*/
Specifies the module the comment appears in may be inlined into any
modules that use this module. This is useful to speed up simulation
runtime. Note if using :vlopt:`--public` that signals under inlined
submodules will be named :code:`{submodule}__DOT__{subsignal}` as C++
does not allow "." in signal names.
Same as :option:`inline` configuration file option.
.. option:: /*verilator&32;isolate_assignments*/
Used after a signal declaration to indicate the assignments to this
signal in any blocks should be isolated into new blocks. When there is
a large combinatorial block that is resulting in an ``UNOPTFLAT``
warning, attaching this to the signal causing a false loop may clear up
the problem.
IE, with the following:
.. code-block:: sv
reg splitme /* verilator isolate_assignments*/;
// Note the placement of the semicolon above
always_comb begin
if (....) begin
splitme = ....;
other assignments
end
end
Verilator will internally split the block that assigns to "splitme" into
two blocks:
It would then internally break it into (sort of):
.. code-block:: sv
// All assignments excluding those to splitme
always_comb begin
if (....) begin
other assignments
end
end
// All assignments to splitme
always_comb begin
if (....) begin
splitme = ....;
end
end
Same as :option:`isolate_assignments` configuration file option.
.. option:: /*verilator&32;lint_off <msg>*/
Disable the specified warning message for any warnings following the
comment.
.. option:: /*verilator&32;lint_on <msg>*/
Re-enable the specified warning message for any warnings following the
comment.
.. option:: /*verilator&32;lint_restore*/
After a :code:`/*verilator&32;lint_save*/`, pop the stack containing lint
message state. Often this is useful at the bottom of include files.
.. option:: /*verilator&32;lint_save*/
Push the current state of what lint messages are turned on or turned off
to a stack. Later meta-comments may then lint_on or lint_off specific
messages, then return to the earlier message state by using
:code:`/*verilator&32;lint_restore*/`. For example:
.. code-block:: sv
// verilator lint_save
// verilator lint_off WIDTH
... // code needing WIDTH turned off
// verilator lint_restore
If WIDTH was on before the lint_off, it will now be restored to on, and
if it was off before the lint_off it will remain off.
.. option:: /*verilator&32;no_inline_module*/
Specifies the module the comment appears in should not be inlined into
any modules that use this module.
Same as :option:`no_inline` configuration file option.
.. option:: /*verilator&32;no_inline_task*/
Used in a function or task variable definition section to specify the
function or task should not be inlined into where it is used. This may
reduce the size of the final executable when a task is used a very large
number of times. For this flag to work, the task and tasks below it
must be pure; they cannot reference any variables outside the task
itself.
Same as :option:`no_inline` configuration file option.
.. option:: /*verilator&32;public*/ (on parameter)
Used after a parameter declaration to indicate the emitted C code should
have the parameter values visible. Due to C++ language restrictions,
this may only be used on 64-bit or narrower integral enumerations.
.. code-block:: sv
parameter [2:0] PARAM /*verilator public*/ = 2'b0;
.. option:: /*verilator&32;public*/ (on typedef enum)
Used after an enum typedef declaration to indicate the emitted C code
should have the enum values visible. Due to C++ language restrictions,
this may only be used on 64-bit or narrower integral enumerations.
.. code-block:: sv
typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
.. option:: /*verilator&32;public*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
the signal should be declared so that C code may read or write the value
of the signal. This will also declare this module public, otherwise use
:code:`/*verilator&32;public_flat*/`.
Instead of using public variables, consider instead making a DPI or
public function that accesses the variable. This is nicer as it
provides an obvious entry point that is also compatible across
simulators.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;public*/ (on task/function)
Used inside the declaration section of a function or task declaration to
indicate the function or task should be made into a C++ function, public
to outside callers. Public tasks will be declared as a void C++
function, public functions will get the appropriate non-void (bool,
uint32_t, etc) return type. Any input arguments will become C++
arguments to the function. Any output arguments will become C++
reference arguments. Any local registers/integers will become function
automatic variables on the stack.
Wide variables over 64 bits cannot be function returns, to avoid
exposing complexities. However, wide variables can be input/outputs;
they will be passed as references to an array of 32-bit numbers.
Generally, only the values of stored state (flops) should be written, as
the model will NOT notice changes made to variables in these functions.
(Same as when a signal is declared public.)
You may want to use DPI exports instead, as it's compatible with other
simulators.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;public_flat*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
the signal should be declared so that C code may read or write the value
of the signal. This will not declare this module public, which means
the name of the signal or path to it may change based upon the module
inlining which takes place.
Same as :option:`public_flat` configuration file option.
.. option:: /*verilator&32;public_flat_rd*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
the signal should be declared public_flat (see above), but read-only.
Same as :option:`public_flat_rd` configuration file option.
.. option:: /*verilator&32;public_flat_rw @(<edge_list>)*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
the signal should be declared public_flat_rd (see above), and also
writable, where writes should be considered to have the timing specified
by the given sensitivity edge list. Set for all variables, ports and
wires using the :vlopt:`--public-flat-rw` option.
Same as :option:`public_flat_rw` configuration file option.
.. option:: /*verilator&32;public_module*/
Used after a module statement to indicate the module should not be
inlined (unless specifically requested) so that C code may access the
module. Verilator automatically sets this attribute when the module
contains any public signals or \`systemc_ directives. Also set for all
modules when using the :vlopt:`--public` option.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;sc_clock*/
Deprecated and ignored. Previously used after an input declaration to
indicate the signal should be declared in SystemC as a sc_clock instead
of a bool. This was needed in SystemC 1.1 and 1.2 only; versions 2.0
and later do not require clock pins to be sc_clocks and this is no
longer needed and is ignored.
.. option:: /*verilator&32;sc_bv*/
Used after a port declaration. It sets the port to be of
:code:`sc_bv<{width}>` type, instead of bool, vluint32_t or vluint64_t.
This may be useful if the port width is parameterized and the
instantiating C++ code wants to always have a sc_bv so it can accept any
width. In general you should avoid using this attribute when not
necessary as with increasing usage of sc_bv the performance decreases
significantly.
Same as :option:`sc_bv` configuration file option.
.. option:: /*verilator&32;sformat*/
Attached to the final argument of type "input string" of a function or
task to indicate the function or task should pass all remaining
arguments through $sformatf. This allows creation of DPI functions with
$display like behavior. See the :file:`test_regress/t/t_dpi_display.v`
file for an example.
Same as :option:`sformat` configuration file option.
.. option:: /*verilator&32;split_var*/
Attached to a variable or a net declaration to break the variable into
multiple pieces typically to resolve ``UNOPTFLAT`` performance issues.
Typically the variables to attach this to are recommended by Verilator
itself, see :option:`UNOPTFLAT`.
For example, Verilator will internally convert a variable with the
metacomment such as:
.. code-block:: sv
logic [7:0] x [0:1] /*verilator split_var*/;
To:
.. code-block:: sv
logic [7:0] x__BRA__0__KET__ /*verilator split_var*/;
logic [7:0] x__BRA__1__KET__ /*verilator split_var*/;
Note that the generated packed variables retain the split_var
metacomment because they may be split into further smaller pieces
according to the access patterns.
This only supports unpacked arrays, packed arrays, and packed structs of
integer types (reg, logic, bit, byte, int...); otherwise if a split was
requested but cannot occur a SPLITVAR warning is issued. Splitting
large arrays may slow down the Verilation speed, so use this only on
variables that require it.
Same as :option:`split_var` configuration file option.
.. option:: /*verilator&32;tag <text...>*/
Attached after a variable or structure member to indicate opaque (to
Verilator) text that should be passed through to the XML output as a tag,
for use by downstream applications.
.. option:: /*verilator&32;tracing_off*/
Disable waveform tracing for all future signals that are declared in
this module, or instances below this module. Often this is placed just
after a primitive's module statement, so that the entire module and
instances below it are not traced.
.. option:: /*verilator&32;tracing_on*/
Re-enable waveform tracing for all future signals or instances that are
declared.

495
docs/guide/faq.rst Normal file
View File

@ -0,0 +1,495 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
******************************
FAQ/Frequently Asked Questions
******************************
.. Extra heading level here so sidebar index looks nice
Questions
=========
Can I contribute?
"""""""""""""""""
Please contribute! Just submit a pull request, or raise an issue to
discuss if looking for something to help on. For more information see our
contributor agreement.
How widely is Verilator used?
"""""""""""""""""""""""""""""
Verilator is used by many of the largest silicon design companies, large
organizations such as CERN, and even by college student projects.
Verilator is one of the "big 4" simulators, meaning one of the 4 main
SystemVerilog simulators available, namely the closed-source products Synopsys
VCS (tm), Mentor Questa/ModelSim (tm), Cadence
Xcelium/Incisive/NC-Verilog/NC-Sim (tm), and the open-source Verilator.
The three closed-source offerings are often collectively called the "big 3"
simulators.
Does Verilator run under Windows?
"""""""""""""""""""""""""""""""""
Yes, using Cygwin. Verilated output also compiles under Microsoft Visual
C++, but this is not tested every release.
Can you provide binaries?
"""""""""""""""""""""""""
You can install Verilator via the system package manager (apt, yum, etc.)
on many Linux distributions, including Debian, Ubuntu, SuSE, RedHat, and
others. These packages are provided by the Linux distributions and
generally will lag the version of the mainline Verilator repository. If no
binary package is available for your distribution, how about you set one
up?
How can it be faster than (name-a-big-3-closed-source-simulator)?
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Generally, the implied part of the question is "... with all of the
manpower they can put into developing it."
Most simulators have to be compliant with the complete IEEE 1364 (Verilog)
and IEEE 1800 (SystemVerilog) standards, meaning they have to be event
driven. This prevents them from being able to reorder blocks and make
netlist-style optimizations, which are where most of the gains come from.
You should not be scared by non-compliance. Your synthesis tool isn't
compliant with the whole standard to start with, so your simulator need not
be either. Verilator is closer to the synthesis interpretation, so this is
a good thing for getting working silicon.
Will Verilator output remain under my own license/copyright?
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Yes, it's just like using GCC on your programs; this is why Verilator uses
the "GNU **Lesser** Public License Version 3" instead of the more typical
"GNU Public License". See the licenses for details, but in brief, if you
change Verilator itself or the header files Verilator includes, you must
make the source code available under the GNU Lesser Public License.
However, Verilator output (the Verilated code) only "include"s the licensed
files, and so you are **not** required to open-source release any output
from Verilator.
You also have the option of using the Perl Artistic License, which again
does not require you to release your Verilog or generated code, and also
allows you to modify Verilator for internal use without distributing the
modified version. But please contribute back to the community!
One limit is that you cannot under either license release a closed-source
Verilog simulation product incorporating Verilator. That is you can have a
commercial product, but must make the source code available.
As is standard with Open Source, contributions back to Verilator will be
placed under the Verilator copyright and LGPL/Artistic license. Small test
cases will be released into the public domain so they can be used anywhere,
and large tests under the LGPL/Artistic, unless requested otherwise.
Why is running Verilator (to create a model) so slow?
"""""""""""""""""""""""""""""""""""""""""""""""""""""
Verilator may require more memory than the resulting simulator will
require, as Verilator internally creates all of the state of the resulting
generated simulator in order to optimize it. If it takes more than a few
minutes or so (and you're not using :vlopt:`--debug` since debug mode is
disk bound), see if your machine is paging; most likely you need to run it
on a machine with more memory. Very large designs are known to have topped
64 GB resident set size. Alternatively, see :ref:`Hierarchical Verilation`.
How do I generate waveforms (traces) in C++?
""""""""""""""""""""""""""""""""""""""""""""
See also the next question for tracing in SystemC mode.
A. Pass the :vlopt:`--trace` option to Verilator, and in your top level C
code, call ``Verilated::traceEverOn(true)``. Then you may use
``$dumpfile`` and ``$dumpvars`` to enable traces, same as with any
Verilog simulator. See ``examples/make_tracing_c`` in the distribution.
B. Or, for finer-grained control, or C++ files with multiple Verilated
modules you may also create the trace purely from C++. Create a
VerilatedVcdC object, and in your main loop call
``trace_object->dump(time)`` every time step, and finally call
``trace_object->close()``.
.. code-block:: C++
:emphasize-lines: 1,5-8,12
#include "verilated_vcd_c.h"
...
int main(int argc, char** argv, char** env) {
...
Verilated::traceEverOn(true);
VerilatedVcdC* tfp = new VerilatedVcdC;
topp->trace(tfp, 99); // Trace 99 levels of hierarchy
tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
...
while (Verilated::time() < sim_time && !Verilated::gotFinish()) {
Verilated::timeInc(1);
tfp->dump(main_time);
}
tfp->close();
}
You also need to compile :file:`verilated_vcd_c.cpp` and add it to your
link, preferably by adding the dependencies in your Makefile's
:code:`$(VK_GLOBAL_OBJS)` link rule. This is done for you if using the
Verilator :vlopt:`--exe` option.
you can call :code:`trace_object->trace()` on multiple Verilated objects
with the same trace file if you want all data to land in the same output
file.
How do I generate waveforms (traces) in SystemC?
""""""""""""""""""""""""""""""""""""""""""""""""
A. Pass the :vlopt:`--trace` option to Verilator, and in your top level
:code:`sc_main()`, call :code:`Verilated::traceEverOn(true)`. Then you
may use :code:`$dumpfile` and code:`$dumpvars` to enable traces, same as
with any Verilog simulator, see the non-SystemC example in
:file:`examples/make_tracing_c`. This will trace only the module
containing the :code:`$dumpvar`.
B. Or, you may create a trace purely from SystemC, which may trace all
Verilated designs in the SystemC model. Create a VerilatedVcdSc object
as you would create a normal SystemC trace file. For an example, see
the call to ``VerilatedVcdSc`` in the
:file:`examples/make_tracing_sc/sc_main.cpp` file of the distribution,
and below.
C. Alternatively you may use the C++ trace mechanism described in the
previous question, note the timescale and timeprecision will be
inherited from your SystemC settings.
.. code-block:: C++
:emphasize-lines: 1,5-8
#include "verilated_vcd_sc.h"
...
int main(int argc, char** argv, char** env) {
...
Verilated::traceEverOn(true);
VerilatedVcdSc* tfp = new VerilatedVcdSc;
topp->trace(tfp, 99); // Trace 99 levels of hierarchy
tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
...
sc_start(1);
...
tfp->close();
}
You also need to compile :file:`verilated_vcd_sc.cpp` and
:file:`verilated_vcd_c.cpp` and add them to your link, preferably by adding
the dependencies in your Makefile's :code:`$(VK_GLOBAL_OBJS)` link rule.
This is done for you if using the Verilator :vlopt:`--exe` option.
You can call :code:`->trace()` on multiple Verilated objects with the same
trace file if you want all data to land in the same output file.
When using SystemC 2.3, the SystemC library must have been built with the
experimental simulation phase callback based tracing disabled. This is
disabled by default when building SystemC with its configure based build
system, but when building SystemC with CMake, you must pass
``-DENABLE_PHASE_CALLBACKS_TRACING=OFF`` to disable this feature.
How do I generate FST waveforms (traces) in C++ or SystemC?
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
FST is a trace file format developed by GTKWave. Verilator provides basic
FST support. To dump traces in FST format, add the :vlopt:`--trace-fst`
option to Verilator and either A. use :code:`$dumpfile & $dumpvars` in
Verilog as described in the VCD example above,
Or, in C++ change the include described in the VCD example above:
.. code-block:: C++
#include "verilated_fst_c.h"
VerilatedFstC* tfp = new VerilatedFstC;
Or, in SystemC change the include described in the VCD example above:
.. code-block:: C++
#include "verilated_fst_sc.h"
VerilatedFstC* tfp = new VerilatedFstSc;
Note that currently supporting both FST and VCD in a single simulation is
impossible, but such requirement should be rare. You can however ifdef
around the trace format in your C++ main loop, and select VCD or FST at
build time, should you require.
How do I view waveforms (aka dumps or traces)?
""""""""""""""""""""""""""""""""""""""""""""""
Verilator creates standard VCD (Value Change Dump) and FST files. VCD
files are viewable with the open source GTKWave (recommended) or Dinotrace
(legacy) programs, or any of the many closed-source offerings; FST is
supported only by GTKWave.
How do I speed up writing large waveform (trace) files?
"""""""""""""""""""""""""""""""""""""""""""""""""""""""
A. Instead of calling ``VerilatedVcdC->open`` or ``$dumpvars`` at the
beginning of time, delay calling it until the time stamp where you want
tracing to begin.
B. Add the :option:`/*verilator&32;tracing_off*/` metacomment to any very
low level modules you never want to trace (such as perhaps library
cells).
C. Use the :vlopt:`--trace-depth` option to limit the depth of tracing, for
example :vlopt:`--trace-depth 1 <--trace-depth>` to see only the top
level signals.
D. You can also consider using FST tracing instead of VCD. FST dumps are a
fraction of the size of the equivalent VCD. FST tracing can be slower
than VCD tracing, but it might be the only option if the VCD file size
is prohibitively large.
E. Be sure you write your trace files to a local solid-state drive, instead
of to a network drive. Network drives are generally far slower.
Where is the translate_off command? (How do I ignore a construct?)
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Translate on/off pragmas are generally a bad idea, as it's easy to have
mismatched pairs, and you can't see what another tool sees by just
preprocessing the code. Instead, use the preprocessor; Verilator defines
the ``\`VERILATOR`` define for you, so just wrap the code in an ifndef
region:
.. code-block:: sv
:emphasize-lines: 1
`ifndef VERILATOR
Something_Verilator_Dislikes;
`endif
Most synthesis tools similarly define SYNTHESIS for you.
Why do I get "unexpected 'do'" or "unexpected 'bit'" errors?
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The words \ ``do``\ , \ ``bit``\ , \ ``ref``\ , \ ``return``\ , and others
are reserved keywords in SystemVerilog. Older Verilog code might use these
as identifiers. You should change your code to not use them to ensure it
works with newer tools. Alternatively, surround them by the Verilog
2005/SystemVerilog begin_keywords pragma to indicate Verilog 2001 code.
.. code-block:: sv
:emphasize-lines: 1
`begin_keywords "1364-2001"
integer bit; initial bit = 1;
`end_keywords
If you want the whole design to be parsed as Verilog 2001, see the
:vlopt:`--default-language` option.
How do I prevent my assertions from firing during reset?
""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Call :code:`Verilated::assertOn(false)` before you first call the model,
then turn it back on after reset. It defaults to true. When false, all
assertions controlled by :vlopt:`--assert` are disabled.
Why do I get "undefined reference to sc_time_stamp()?
"""""""""""""""""""""""""""""""""""""""""""""""""""""
In Verilator 4.200 and later, using the timeInc function is recommended
instead. See the :ref:`Connecting to C++` examples. Some linkers (MSVC++)
still require :code:`sc_time_stamp()` to be defined, either define this
with :code:`double sc_time_stamp() { return 0; }` or compile the Verilated
code with :code:`-CFLAGS -DVL_TIME_CONTEXT`.
Prior to Verilator 4.200, the :code:`sc_time_stamp()` function needs to be
defined in C++ (non SystemC) to return the current simulation time.
Why do I get "undefined reference to \`VL_RAND_RESET_I' or \`Verilated::...'"?
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
You need to link your compiled Verilated code against the
:code:`verilated.cpp` file found in the include directory of the Verilator
kit. This is one target in the ``$(VK_GLOBAL_OBJS)`` make variable, which
should be part of your Makefile's link rule. If you use :vlopt:`--exe`,
this is done for you.
Is the PLI supported?
"""""""""""""""""""""
Only somewhat. More specifically, the common PLI-ish calls $display,
$finish, $stop, $time, $write are converted to C++ equivalents. You can
also use the "import DPI" SystemVerilog feature to call C code (see the
chapter above). There is also limited VPI access to public signals.
If you want something more complex, since Verilator emits standard C++
code, you can simply write your own C++ routines that can access and modify
signal values without needing any PLI interface code, and call it with
$c("{any_c++_statement}").
See the :ref:`Connecting` section.
How do I make a Verilog module that contain a C++ object?
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
You need to add the object to the structure that Verilator creates, then
use $c to call a method inside your object. The
:file:`test_regress/t/t_extend_class` files in the distribution show an
example of how to do this.
How do I get faster build times?
""""""""""""""""""""""""""""""""
* When running make, pass the make variable VM_PARALLEL_BUILDS=1 so that
builds occur in parallel. Note this is now set by default if an output
file was large enough to be split due to the :vlopt:`--output-split`
option.
* Verilator emits any infrequently executed "cold" routines into separate
__Slow.cpp files. This can accelerate compilation as optimization can be
disabled on these routines. See the OPT_FAST and OPT_SLOW make variables
and :ref:`Benchmarking & Optimization`.
* Use a recent compiler. Newer compilers tend to be faster.
* Compile in parallel on many machines and use caching; see the web for the
ccache, distcc and icecream packages. ccache will skip GCC runs between
identical source builds, even across different users. If ccache was
installed when Verilator was built it is used, or see OBJCACHE
environment variable to override this. Also see the
:vlopt:`--output-split` option.
* To reduce the compile time of classes that use a Verilated module (e.g. a
top CPP file) you may wish to add a
:option:`/*verilator&32;no_inline_module*/` metacomment to your top level
module. This will decrease the amount of code in the model's Verilated
class, improving compile times of any instantiating top level C++ code,
at a relatively small cost of execution performance.
* Use :ref:`hierarchical verilation`.
Why do so many files need to recompile when I add a signal?
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Adding a new signal requires the symbol table to be recompiled. Verilator
uses one large symbol table, as that results in 2-3 less assembly
instructions for each signal access. This makes the execution time 10-15%
faster, but can result in more compilations when something changes.
How do I access Verilog functions/tasks in C?
"""""""""""""""""""""""""""""""""""""""""""""
Use the SystemVerilog Direct Programming Interface. You write a Verilog
function or task with input/outputs that match what you want to call in
with C. Then mark that function as a DPI export function. See the DPI
chapter in the IEEE Standard.
How do I access C++ functions/tasks in Verilog?
"""""""""""""""""""""""""""""""""""""""""""""""
Use the SystemVerilog Direct Programming Interface. You write a Verilog
function or task with input/outputs that match what you want to call in
with C. Then mark that function as a DPI import function. See the DPI
chapter in the IEEE Standard.
How do I access signals in C?
"""""""""""""""""""""""""""""
The best thing to do is to make a SystemVerilog "export DPI" task or
function that accesses that signal, as described in the DPI chapter in the
manual and DPI tutorials on the web. This will allow Verilator to better
optimize the model and should be portable across simulators.
If you really want raw access to the signals, declare the signals you will
be accessing with a :option:`/*verilator&32;public*/` metacomment before
the closing semicolon. Then scope into the C++ class to read the value of
the signal, as you would any other member variable.
Signals are the smallest of 8-bit unsigned chars (equivalent to uint8_t),
16-bit unsigned shorts (uint16_t), 32-bit unsigned longs (uint32_t), or
64-bit unsigned long longs (uint64_t) that fits the width of the signal.
Generally, you can use just uint32_t's for 1 to 32 bits, or vluint64_t for
1 to 64 bits, and the compiler will properly up-convert smaller entities.
Note even signed ports are declared as unsigned; you must sign extend
yourself to the appropriate signal width.
Signals wider than 64 bits are stored as an array of 32-bit uint32_t's.
Thus to read bits 31:0, access signal[0], and for bits 63:32, access
signal[1]. Unused bits (for example bit numbers 65-96 of a 65-bit vector)
will always be zero. If you change the value you must make sure to pack
zeros in the unused bits or core-dumps may result, because Verilator strips
array bound checks where it believes them to be unnecessary to improve
performance.
In the SYSTEMC example above, if you had in our.v:
.. code-block:: sv
input clk /*verilator public*/;
// Note the placement of the semicolon above
From the sc_main.cpp file, you'd then:
.. code-block:: C++
#include "Vour.h"
#include "Vour_our.h"
cout << "clock is " << top->our->clk << endl;
In this example, clk is a bool you can read or set as any other variable.
The value of normal signals may be set, though clocks shouldn't be changed
by your code or you'll get strange results.
Should a module be in Verilog or SystemC?
"""""""""""""""""""""""""""""""""""""""""
Sometimes there is a block that just interconnects instances, and have a
choice as to if you write it in Verilog or SystemC. Everything else being
equal, best performance is when Verilator sees all of the design. So, look
at the hierarchy of your design, labeling instances as to if they are
SystemC or Verilog. Then:
* A module with only SystemC instances below must be SystemC.
* A module with a mix of Verilog and SystemC instances below must be
SystemC. (As Verilator cannot connect to lower-level SystemC instances.)
* A module with only Verilog instances below can be either, but for best
performance should be Verilog. (The exception is if you have a design
that is instantiated many times; in this case Verilating one of the lower
modules and instantiating that Verilated instances multiple times into a
SystemC module *may* be faster.)

141
docs/guide/files.rst Normal file
View File

@ -0,0 +1,141 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*****
Files
*****
.. _Files in the Distribution:
Files in the Git Tree
=====================
The following is a summary of the files in the Git Tree (distribution) of
Verilator:
::
Changes => Version history
README.rst => This document
bin/verilator => Compiler wrapper invoked to Verilate code
docs/ => Additional documentation
examples/ => Examples (see manual for descriptions)
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
.. _Files Read/Written:
Files Read/Written
==================
All output files are placed in the output directory specified with the
:vlopt:`--Mdir` option, or "obj_dir" if not specified.
Verilator creates the following files in the output directory:
For --cc/--sc, it creates:
.. list-table::
* - *{prefix}*\ .cmake
- CMake include script for compiling (from --make cmake)
* - *{prefix}*\ .mk
- Make include file for compiling (from --make gmake)
* - *{prefix}*\ _classes.mk
- Make include file with class names (from --make gmake)
* - *{prefix}*\ _hier.mk
- Make file for hierarchy blocks (from --make gmake)
* - *{prefix|*\ _hierMkArgs.f
- Arguments for hierarchical Verilation (from --make gmake)
* - *{prefix}*\ _hierCMakeArgs.f
- Arguments for hierarchical Verilation (from --make cmake)
* - *{prefix}*\ .cpp
- Top level C++ file
* - *{prefix}{__n}*\ .cpp
- Additional top C++ files (from --output-split)
* - *{prefix}*\ .h
- Top level header
* - *{prefix}*\ __Slow\ *{__n}*\ .cpp
- Infrequent cold routines
* - *{prefix}*\ __Dpi.cpp
- DPI import and export wrappers (from --dpi)
* - *{prefix}*\ __Dpi.h
- DPI import and export declarations (from --dpi)
* - *{prefix}*\ __Inlines.h
- Inline support functions
* - *{prefix}*\ __Syms.cpp
- Global symbol table C++
* - *{prefix}*\ __Syms.h
- Global symbol table header
* - *{prefix}*\ __Trace{__n}*\ .cpp
- Wave file generation code (from --trace)
* - *{prefix}*\ __Trace__Slow{__n}*\ .cpp
- Wave file generation code (from --trace)
* - *{prefix}{each_verilog_module}*\ .cpp
- Lower level internal C++ files
* - *{prefix}{each_verilog_module}*\ .h
- Lower level internal header files
* - *{prefix}{each_verilog_module}{__n}*\ .cpp
- Additional lower C++ files (from --output-split)
For --hierarchy mode, it creates:
.. list-table::
* - V\ *{hier_block}*\ /
- Directory to Verilate each hierarchy block (from --hierarchy)
* - *{prefix}*\ __hierVer.d
- Make dependencies of the top module (from --hierarchy)
* - *{prefix}*\ __hier.dir
- Directory to store .dot, .vpp, .tree of top module (from --hierarchy)
In certain debug and other modes, it also creates:
.. list-table::
* - *{prefix}*\ .xml
- XML tree information (from --xml)
* - *{prefix}*\ __cdc.txt
- Clock Domain Crossing checks (from --cdc)
* - *{prefix}*\ __stats.txt
- Statistics (from --stats)
* - *{prefix}*\ __idmap.txt
- Symbol demangling (from --protect-ids)
* - *{prefix}*\ __ver.d
- Make dependencies (from -MMD)
* - *{prefix}*\ __verFiles.dat
- Timestamps (from --skip-identical)
* - *{prefix}{misc}*\ .dot
- Debugging graph files (from --debug)
* - *{prefix}{misc}*\ .tree
- Debugging files (from --debug)
* - {mod_prefix}_{each_verilog_module}*{__n}*\ .vpp
- Pre-processed verilog (from --debug)
After running Make, the C++ compiler may produce the following:
.. list-table::
* - verilated{misc}*\ .d
- Intermediate dependencies
* - verilated{misc}*\ .o
- Intermediate objects
* - {mod_prefix}{misc}*\ .d
- Intermediate dependencies
* - {mod_prefix}{misc}*\ .o
- Intermediate objects
* - *{prefix}*\
- Final executable (from --exe)
* - *{prefix}*\ __ALL.a
- Library of all Verilated objects
* - *{prefix}*\ __ALL.cpp
- Include of all code for single compile
* - *{prefix}{misc}*\ .d
- Intermediate dependencies
* - *{prefix}{misc}*\ .o
- Intermediate objects

37
docs/guide/index.rst Normal file
View File

@ -0,0 +1,37 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. toctree::
:maxdepth: 2
:caption: Getting Started
overview.rst
examples.rst
install.rst
.. toctree::
:maxdepth: 2
:caption: User's Guide
verilating.rst
connecting.rst
simulating.rst
contributing.rst
faq.rst
.. toctree::
:maxdepth: 1
:caption: Reference Guide
languages.rst
extensions.rst
executables.rst
warnings.rst
files.rst
environment.rst
deprecations.rst
contributors.rst
changes.rst
copyright.rst

321
docs/guide/install.rst Normal file
View File

@ -0,0 +1,321 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Installation:
************
Installation
************
This section discusses how to install Verilator.
.. _Package Manager Quick Install:
Package Manager Quick Install
=============================
Using a distribution's package manager is the easiest way to get
started. (Note packages are unlikely to have the most recent version, so
:ref:`Git Install`, might be a better alternative.) To install as a
package:
::
apt-get install verilator # On Ubuntu
.. _Git Install:
Git Quick Install
=================
Installing Verilator from Git provides the most flexibility. For additional
options and details see :ref:`Detailed Build Instructions` below.
In brief, to install from git:
::
# Prerequisites:
#sudo apt-get install git perl python3 make autoconf g++ flex bison ccache
#sudo apt-get install libgoogle-perftools-dev numactl perl-doc
#sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)
#sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error)
#sudo apt-get install zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error)
git clone https://github.com/verilator/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 # Configure and create Makefile
make -j # Build Verilator itself
sudo make install
.. _Detailed Build Instructions:
Detailed Build Instructions
===========================
This section describes details of the build process, and assumes you are
building from Git. For using a pre-built binary for your Linux
distribution, see instead :ref:`Package Manager Quick Install`.
OS Requirements
---------------
Verilator is developed and has primary testing on Ubuntu, with additional
testing on FreeBSD and Apple OS-X. Versions have also built on Redhat
Linux, 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 using MSVC++.
Install Prerequisites
---------------------
To build or run Verilator you need these standard packages:
::
sudo apt-get install git perl python3 make
sudo apt-get install g++ # Alternatively, clang
sudo apt-get install libgz # Non-Ubuntu (ignore if gives error)
sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)
sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error)
sudo apt-get install zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error)
To build or run the following are optional but should be installed for good
performance:
::
sudo apt-get install ccache # If present at build, needed for run
sudo apt-get install libgoogle-perftools-dev numactl perl-doc
To build Verilator you will need to install these packages; these do not
need to be present to run Verilator:
::
sudo apt-get install git autoconf flex bison
Those developing Verilator itself may also want these (see internals.rst):
::
sudo apt-get install gdb graphviz cmake clang clang-format gprof lcov
sudo pip3 install sphinx sphinx_rtd_theme breathe
cpan install Pod::Perldoc
cpan install Parallel::Forker
Install SystemC
^^^^^^^^^^^^^^^
If you will be using SystemC (vs straight C++ output), download `SystemC
<https://www.accellera.org/downloads/standards/systemc>`__. Follow their
installation instructions. You will need to set the
:option:`SYSTEMC_INCLUDE` environment variable to point to the include
directory with ``systemc.h`` in it, and set the :option:`SYSTEMC_LIBDIR`
environment variable to point to the directory with ``libsystemc.a`` in it.
Install GTKWave
^^^^^^^^^^^^^^^
To make use of Verilator FST tracing you will want `GTKwave
<http://gtkwave.sourceforge.net/>`__ installed, however this is not
required at Verilator build time.
Obtain Sources
--------------
Get the sources from the git repository: (You need do this only once,
ever.)
::
git clone https://github.com/verilator/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 Verilator onto your system. Verilator will be compiling
the current value of the environment variables :option:`VERILATOR_ROOT`,
:option:`SYSTEMC_INCLUDE`, and :option:`SYSTEMC_LIBDIR` as defaults into
the executable, so they must be correct before configuring.
These are the installation 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 :option:`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 specific location
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You may eventually be installing onto a project/company-wide "CAD" tools
disk that may support multiple versions of every tool. Tell configure the
eventual destination directory name. We recommend the destination location
include 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 `modulecmd
<http://modules.sourceforge.net/>`__, 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
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 your ``$PATH`` environment variable.
4. Install System Globally
^^^^^^^^^^^^^^^^^^^^^^^^^^
The final option is to eventually install Verilator globally, using
configure's default system paths:
::
unset VERILATOR_ROOT # if your shell is bash
unsetenv VERILATOR_ROOT # if your shell is csh
./configure
Then after installing (below) the binaries should be in a location that is
already in your ``$PATH`` environment variable.
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 install option other than the `1. Run-in-Place from
VERILATOR_ROOT <#_1_run_in_place_from_verilator_root>`__ scheme, install
the files:
::
make install
.. Docker Build Environment
.. include:: ../../ci/docker/buildenv/README.rst
.. Docker Run Environment
.. include:: ../../ci/docker/run/README.rst

477
docs/guide/languages.rst Normal file
View File

@ -0,0 +1,477 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
***************
Input Languages
***************
This section describes the languages Verilator takes as input. See also
:ref:`Configuration Files`.
Language Standard Support
=========================
Verilog 2001 (IEEE 1364-2001) Support
-------------------------------------
Verilator supports most Verilog 2001 language features. This includes
signed numbers, "always @\*", generate statements, multidimensional arrays,
localparam, and C-style declarations inside port lists.
Verilog 2005 (IEEE 1364-2005) Support
-------------------------------------
Verilator supports most Verilog 2005 language features. This includes the
\`begin_keywords and \`end_keywords compiler directives, $clog2, and the
uwire keyword.
SystemVerilog 2005 (IEEE 1800-2005) Support
-------------------------------------------
Verilator supports ==? and !=? operators, ++ and -- in some contexts,
$bits, $countbits, $countones, $error, $fatal, $info, $isunknown, $onehot,
$onehot0, $unit, $warning, always_comb, always_ff, always_latch, bit, byte,
chandle, const, do-while, enum, export, final, import, int, interface,
logic, longint, modport, package, program, shortint, struct, time, typedef,
union, var, void, priority case/if, and unique case/if.
It also supports .name and .\* interconnection.
Verilator partially supports concurrent assert and cover statements; see
the enclosed coverage tests for the syntax which is allowed.
Verilator has limited support for class and related object-oriented
constructs.
SystemVerilog 2012 (IEEE 1800-2012) Support
-------------------------------------------
Verilator implements a full SystemVerilog-compliant preprocessor, including
function call-like preprocessor defines, default define arguments,
\`__FILE__, \`__LINE__ and \`undefineall.
SystemVerilog 2017 (IEEE 1800-2017) Support
-------------------------------------------
Verilator supports the 2017 "for" loop constructs, and several minor
cleanups IEEE made in 1800-2017.
Verilog AMS Support
-------------------
Verilator implements a very small subset of Verilog AMS (Verilog Analog and
Mixed-Signal Extensions) with the subset corresponding to those VMS
keywords with near equivalents in the Verilog 2005 or SystemVerilog 2009
languages.
AMS parsing is enabled with :vlopt:`--language VAMS <--language>` or
:vlopt:`--language 1800+VAMS <--language>`.
At present Verilator implements ceil, exp, floor, ln, log, pow, sqrt,
string, and wreal.
Synthesis Directive Assertion Support
-------------------------------------
With the :vlopt:`--assert` option, Verilator reads any :code:`//synopsys
full_case` or :code:`//synopsys parallel_case` directives. The same
applies to any :code:`//ambit synthesis`, :code:`//cadence` or
:code:`//pragma` directives of the same form.
When these synthesis directives are discovered, Verilator will either
formally prove the directive to be true, or failing that, will insert the
appropriate code to detect failing cases at simulation runtime and print an
"Assertion failed" error message.
Verilator likewise also asserts any "unique" or "priority" SystemVerilog
keywords on case statement, as well as "unique" on if statements. However,
"priority if" is currently simply ignored.
.. _Language Limitations:
Language Limitations
====================
This section describes the language limitations of Verilator. Many of these
restrictions are by intent.
Synthesis Subset
----------------
Verilator supports the Synthesis subset with other verification constructs
being added over time. Verilator also simulates events as Synopsys's Design
Compiler would; namely given a block of the form:
.. code-block:: sv
always @(x) y = x & z;
This will recompute y when there is even a potential for change in x or a
change in z, that is when the flops computing x or z evaluate (which is
what Design Compiler will synthesize.) A compliant simulator would only
calculate y if x changes. We recommend using always_comb to make the code
run the same everywhere. Also avoid putting $displays in combo blocks, as
they may print multiple times when not desired, even on compliant
simulators as event ordering is not specified.
Signal Naming
-------------
To avoid conflicts with C symbol naming, any character in a signal name
that is not alphanumeric nor a single underscore will be replaced by __0hh
where hh is the hex code of the character. To avoid conflicts with
Verilator's internal symbols, any double underscore are replaced with
___05F (5F is the hex code of an underscore.)
Bind
----
sVerilator only supports bind to a target module name, not to an
instance path.
Class
-----
Verilator class support is limited but in active development. Verilator
supports members, and methods. Verilator does not support class static
members, class extend, or class parameters.
Dotted cross-hierarchy references
---------------------------------
Verilator supports dotted references to variables, functions and tasks in
different modules. The portion before the dot must have a constant value;
for example a[2].b is acceptable, while a[x].b is generally not.
References into generated and arrayed instances use the instance names
specified in the Verilog standard; arrayed instances are named
``{instanceName}[{instanceNumber}]`` in Verilog, which becomes
``{instanceName}__BRA__{instanceNumber}__KET__`` inside the generated C++
code.
Latches
-------
Verilator is optimized for edge sensitive (flop based) designs. It will
attempt to do the correct thing for latches, but most performance
optimizations will be disabled around the latch.
Structures and Unions
---------------------
Presently Verilator only supports packed structs and packed unions. Rand
and randc tags on members are simply ignored. All structures and unions
are represented as a single vector, which means that generating one member
of a structure from blocking, and another from non-blocking assignments is
unsupported.
Time
----
All delays (#) are ignored, as they are in synthesis.
.. _Unknown States:
Unknown States
--------------
Verilator is mostly a two state simulator, not a four state simulator.
However, it has two features which uncover most initialization bugs
(including many that a four state simulator will miss.)
Identity comparisons (=== or !==) are converted to standard ==/!= when
neither side is a constant. This may make the expression yield a different
result compared to a four state simulator. An === comparison to X will
always be false, so that Verilog code which checks for uninitialized logic
will not fire.
Assigning X to a variable will actually assign a constant value as
determined by the :vlopt:`--x-assign` option. This allows runtime
randomization, thus if the value is actually used, the random value should
cause downstream errors. Integers also get randomized, even though the
Verilog 2001 specification says they initialize to zero. Note however that
randomization happens at initialization time and hence during a single
simulation run, the same constant (but random) value will be used every
time the assignment is executed.
All variables, depending on :vlopt:`--x-initial` setting, are typically
randomly initialized using a function. By running several random
simulation runs you can determine that reset is working correctly. On the
first run, have the function initialize variables to zero. On the second,
have it initialize variables to one. On the third and following runs have
it initialize them randomly. If the results match, reset works. (Note
this is what the hardware will really do.) In practice, just setting all
variables to one at startup finds most problems (since typically control
signals are active-high).
:vlopt:`--x-assign` applies to variables explicitly initialized or assigned
an X. Uninitialized clocks are initialized to zero, while all other state
holding variables are initialized to a random value. Event driven
simulators will generally trigger an edge on a transition from X to 1
(posedge) or X to 0 (negedge). However, by default, since clocks are
initialized to zero, Verilator will not trigger an initial negedge. Some
code (particularly for reset) may rely on X->0 triggering an edge. The
:vlopt:`--x-initial-edge` option enables this behavior. Comparing runs with
and without this option will find such problems.
Tri/Inout
---------
Verilator converts some simple tristate structures into two state. Pullup,
pulldown, bufif0, bufif1, notif0, notif1, pmos, nmos, tri0 and tri1 are
also supported. Simple comparisons with :code:`=== 1'bz` are also
supported.
An assignment of the form:
.. code-block:: sv
inout driver;
wire driver = (enable) ? output_value : 1'bz;
Will be converted to:
.. code-block:: sv
input driver; // Value being driven in from "external" drivers
output driver__en; // True if driven from this module
output driver__out; // Value being driven from this module
External logic will be needed to combine these signals with any external
drivers.
Tristate drivers are not supported inside functions and tasks; an inout
there will be considered a two state variable that is read and written
instead of a four state variable.
Functions & Tasks
-----------------
All functions and tasks will be inlined (will not become functions in C.)
The only support provided is for simple statements in tasks (which may
affect global variables).
Recursive functions and tasks are not supported. All inputs and outputs
are automatic, as if they had the Verilog 2001 "automatic" keyword
prepended. (If you don't know what this means, Verilator will do what you
probably expect, what C does. The default behavior of Verilog is
different.)
Generated Clocks
----------------
Verilator attempts to deal with generated and gated clocks correctly,
however some cases cause problems in the scheduling algorithm which is
optimized for performance. The safest option is to have all clocks as
primary inputs to the model, or wires directly attached to primary inputs.
For proper behavior clock enables may also need the
:option:`/*verilator&32;clock_enable*/` metacomment.
Gate Primitives
---------------
The 2-state gate primitives (and, buf, nand, nor, not, or, xnor, xor) are
directly converted to behavioral equivalents. The 3-state and MOS gate
primitives are not supported. Tables are not supported.
Specify blocks
--------------
All specify blocks and timing checks are ignored. All min:typ:max delays
use the typical value.
Array Initialization
--------------------
When initializing a large array, you need to use non-delayed assignments.
Verilator will tell you when this needs to be fixed; see the BLKLOOPINIT
error for more information.
Array Out of Bounds
-------------------
Writing a memory element that is outside the bounds specified for the array
may cause a different memory element inside the array to be written
instead. For power-of-2 sized arrays, Verilator will give a width warning
and the address. For non-power-of-2-sizes arrays, index 0 will be written.
Reading a memory element that is outside the bounds specified for the array
will give a width warning and wrap around the power-of-2 size. For
non-power-of-2 sizes, it will return a unspecified constant of the
appropriate width.
Assertions
----------
Verilator is beginning to add support for assertions. Verilator currently
only converts assertions to simple :code:`if (...) error` statements, and
coverage statements to increment the line counters described in the
coverage section.
Verilator does not support SEREs yet. All assertion and coverage
statements must be simple expressions that complete in one cycle.
Encrypted Verilog
-----------------
Open source simulators like Verilator are unable to use encrypted RTL
(i.e. IEEE P1735). Talk to your IP vendor about delivering IP blocks via
Verilator's :vlopt:`--protect-lib` feature.
Language Keyword Limitations
============================
This section describes specific limitations for each language keyword.
.. Hack to get long definition list:
.. |cmdslong1| replace:: \`__FILE__, \`__LINE__, \`begin_keywords,
\`begin_keywords, \`begin_keywords, \`begin_keywords, \`begin_keywords,
\`define, \`else, \`elsif, \`end_keywords, \`endif, \`error, \`ifdef,
\`ifndef, \`include, \`line, \`systemc_ctor, \`systemc_dtor,
\`systemc_header, \`systemc_imp_header, \`systemc_implementation,
\`systemc_interface, \`undef, \`verilog
|cmdslong1|
Fully supported.
.. Hack to get long definition list:
.. |cmdslong2| replace:: always, always_comb, always_ff, always_latch, and,
assign, begin, buf, byte, case, casex, casez, default, defparam,
do-while, else, end, endcase, endfunction, endgenerate, endmodule,
endspecify, endtask, final, for, function, generate, genvar, if,
initial, inout, input, int, integer, localparam, logic, longint,
macromodule, module, nand, negedge, nor, not, or, output, parameter,
posedge, reg, scalared, shortint, signed, supply0, supply1, task, time,
tri, typedef, var, vectored, while, wire, xnor, xor
|cmdslong2|
Generally supported.
++, -- operators
Increment/decrement can only be used as standalone statements or in
certain limited cases.
'{} operator
Assignment patterns with order based, default, constant integer (array)
or member identifier (struct/union) keys are supported. Data type keys
and keys which are computed from a constant expression are not supported.
\`uselib
Uselib, a vendor specific library specification method, is ignored along
with anything following it until the end of that line.
cast operator
Casting is supported only between simple scalar types, signed and
unsigned, not arrays nor structs.
chandle
Treated as a "longint"; does not yet warn about operations that are
specified as illegal on chandles.
disable
Disable statements may be used only if the block being disabled is a
block the disable statement itself is inside. This was commonly used to
provide loop break and continue functionality before SystemVerilog added
the break and continue keywords.
inside
Inside expressions may not include unpacked array traversal or $ as an
upper bound. Case inside and case matches are also unsupported.
interface
Interfaces and modports, including with generated data types are
supported. Generate blocks around modports are not supported, nor are
virtual interfaces nor unnamed interfaces.
shortreal
Short floating point (shortreal) numbers are converted to real. Most
other simulators either do not support float, or convert likewise.
specify specparam
All specify blocks and timing checks are ignored.
uwire
Verilator does not perform warning checking on uwires, it treats the
uwire keyword as if it were the normal wire keyword.
$bits, $countbits, $countones, $finish, $isunknown, $onehot, $onehot0, $signed, $stime, $stop, $time, $unsigned,
Generally supported.
$dump/$dumpports and related
$dumpfile or $dumpports will create a VCD or FST file (which is based on
the :vlopt:`--trace` option given when the model was Verilated). This
will take effect starting at the next eval() call. If you have multiple
Verilated designs under the same C model, then this will dump signals
only from the design containing the $dumpvars.
$dumpvars and $dumpports module identifier is ignored; the traced
instances will always start at the top of the design. The levels argument
is also ignored, use tracing_on/tracing_off pragmas instead.
$dumpportson/$dumpportsoff/$dumpportsall/$dumpportslimit filename
argument is ignored, only a single trace file may be active at once.
$dumpall/$dumpportsall, $dumpon/$dumpportson, $dumpoff/$dumpportsoff, and
$dumplimit/$dumpportlimit are currently ignored.
$error, $fatal, $info, $warning.
Generally supported.
$exit, $finish, $stop
The rarely used optional parameter to $finish and $stop is ignored. $exit
is aliased to $finish.
$fopen, $fclose, $fdisplay, $ferror, $feof, $fflush, $fgetc, $fgets, $fscanf, $fwrite, $fscanf, $sscanf
Generally supported.
$fullskew, $hold, $nochange, $period, $recovery, $recrem, $removal, $setup, $setuphold, $skew, $timeskew, $width
All specify blocks and timing checks are ignored.
$random, $urandom, $urandom_range
Use :vlopt:`+verilator+seed+\<value\>` runtime option to set the seed if
there is no $random nor $urandom optional argument to set the seed.
There is one random seed per C thread, not per module for $random, nor
per object for random stability of $urandom/$urandom_range.
$readmemb, $readmemh
Read memory commands are supported. Note Verilator and the Verilog
specification does not include support for readmem to multi-dimensional
arrays.
$test$plusargs, $value$plusargs
Supported, but the instantiating C++/SystemC wrapper must call
.. code-block:: C++
Verilated::commandArgs(argc, argv);
to register the command line before calling $test$plusargs or
$value$plusargs.

55
docs/guide/overview.rst Normal file
View File

@ -0,0 +1,55 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
********
Overview
********
Welcome to Verilator!
The Verilator package converts Verilog [#]_ and SystemVerilog [#]_ hardware
description language (HDL) designs into a C++ or SystemC model that after
compiling can be executed. Verilator is not a traditional simulator, but a
compiler.
Verilator is typically used as follows:
1. The :command:`verilator` executable is invoked with parameters similar
to GCC, or other simulators such as Cadence Verilog-XL/NC-Verilog, or
Synopsys VCS. Verilator reads the specified SystemVerilog code, lints it,
optionally adds coverage and waveform tracing support, and compiles the
design into a source level multithreaded C++ or SystemC "model". The
resulting model's C++ or SystemC code is output as .cpp and .h files. This
is referred to as "Verilating" and the process is "to Verilate"; the output
is a "Verilated" model.
2. For simulation, a small user written C++ wrapper file is required, the
"wrapper". This wrapper defines the C++ standard function "main()" which
instantiates the Verilated model as a C++/SystemC object.
3. The user C++ wrapper, the files created by Verilator, a "runtime
library" provided by Verilator, and if applicable SystemC libraries are
then compiled using a C++ compiler to create a simulation executable.
4. The resulting executable will perform the actual simulation, during
"simulation runtime".
5. If appropriately enabled, the executable may also generate waveform
traces of the design that may be viewed. It may also create coverage
analysis data for post-analysis.
The best place to get started is to try the :ref:`Examples`.
.. [#] Verilog is defined by the `Institute of Electrical and Electronics
Engineers (IEEE) Standard for Verilog Hardware Description
Language`, Std. 1364, released in 1995, 2001, and 2005. The
Verilator documentation uses the shorthand e.g. "IEEE 1394-2005" to
refer to the e.g. 2005 version of this standard.
.. [#] SystemVerilog is defined by the `Institute of Electrical and
Electronics Engineers (IEEE) Standard for SystemVerilog - Unified
Hardware Design, Specification, and Verification Language`, Standard
1800, released in 2005, 2009, 2012, and 2017. The Verilator
documentation uses the shorthand e.g. "IEEE 1800-2017" to refer to
the e.g. 2017 version of this standard.

352
docs/guide/simulating.rst Normal file
View File

@ -0,0 +1,352 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _Simulating:
************************************
Simulating (Verilated-Model Runtime)
************************************
This section describes items related to simulating, that using a Verilated
model's executable. For the runtime arguments to a simulated model, see
:ref:`Simulation Runtime Arguments`.
.. _Benchmarking & Optimization:
Benchmarking & Optimization
===========================
For best performance, run Verilator with the :vlopt:`-O3`
:vlopt:`--x-assign fast <--x-assign>` :vlopt:`--x-initial fast
<--x-initial>` :vlopt:`--noassert <--assert>` options. The :vlopt:`-O3`
option will require longer time to run Verilator, and :vlopt:`--x-assign
fast <--x-assign>` :vlopt:`--x-initial fast <--x-assign>` may increase the
risk of reset bugs in trade for performance; see the above documentation
for these options.
If using Verilated multithreaded, use ``numactl`` to ensure you are using
non-conflicting hardware resources. See :ref:`Multithreading`.
Minor Verilog code changes can also give big wins. You should not have any
UNOPTFLAT warnings from Verilator. Fixing these warnings can result in
huge improvements; one user fixed their one UNOPTFLAT warning by making a
simple change to a clock latch used to gate clocks and gained a 60%
performance improvement.
Beyond that, the performance of a Verilated model depends mostly on your
C++ compiler and size of your CPU's caches. Experience shows that large
models are often limited by the size of the instruction cache, and as such
reducing code size if possible can be beneficial.
The supplied $VERILATOR_ROOT/include/verilated.mk file uses the OPT,
OPT_FAST, OPT_SLOW and OPT_GLOBAL variables to control optimization. You
can set these when compiling the output of Verilator with Make, for
example:
.. code-block:: bash
make OPT_FAST="-Os -march=native" -f Vour.mk Vour__ALL.a
OPT_FAST specifies optimization options for those parts of the model that
are on the fast path. This is mostly code that is executed every
cycle. OPT_SLOW applies to slow-path code, which executes rarely, often
only once at the beginning or end of simulation. Note that OPT_SLOW is
ignored if VM_PARALLEL_BUILDS is not 1, in which case all generated code
will be compiled in a single compilation unit using OPT_FAST. See also the
Verilator :vlopt:`--output-split` option. The OPT_GLOBAL variable applies
to common code in the runtime library used by Verilated models (shipped in
$VERILATOR_ROOT/include). Additional C++ files passed on the verilator
command line use OPT_FAST. The OPT variable applies to all compilation
units in addition to the specific "OPT" variables described above.
You can also use the :vlopt:`-CFLAGS` and/or :vlopt:`-LDFLAGS` options on
the verilator command line to pass arguments directly to the compiler or
linker.
The default values of the "OPT" variables are chosen to yield good
simulation speed with reasonable C++ compilation times. To this end,
OPT_FAST is set to "-Os" by default. Higher optimization such as "-O2" or
"-O3" may help (though often they provide only a very small performance
benefit), but compile times may be excessively large even with medium sized
designs. Compilation times can be improved at the expense of simulation
speed by reducing optimization, for example with OPT_FAST="-O0". Often good
simulation speed can be achieved with OPT_FAST="-O1 -fstrict-aliasing" but
with improved compilation times. Files controlled by OPT_SLOW have little
effect on performance and therefore OPT_SLOW is empty by default
(equivalent to "-O0") for improved compilation speed. In common use-cases
there should be little benefit in changing OPT_SLOW. OPT_GLOBAL is set to
"-Os" by default and there should rarely be a need to change it. As the
runtime library is small in comparison to a lot of Verilated models,
disabling optimization on the runtime library should not have a serious
effect on overall compilation time, but may have detrimental effect on
simulation speed, especially with tracing. In addition to the above, for
best results use OPT="-march=native", the latest Clang compiler (about 10%
faster than GCC), and link statically.
Generally the answer to which optimization level gives the best user
experience depends on the use case and some experimentation can pay
dividends. For a speedy debug cycle during development, especially on large
designs where C++ compilation speed can dominate, consider using lower
optimization to get to an executable faster. For throughput oriented use
cases, for example regressions, it is usually worth spending extra
compilation time to reduce total CPU time.
If you will be running many simulations on a single model, you can
investigate profile guided optimization. With GCC, using GCC's
"-fprofile-arcs", then GCC's "-fbranch-probabilities" will yield another
15% or so.
Modern compilers also support link-time optimization (LTO), which can help
especially if you link in DPI code. To enable LTO on GCC, pass "-flto" in
both compilation and link. Note LTO may cause excessive compile times on
large designs.
Unfortunately, using the optimizer with SystemC files can result in
compilation taking several minutes. (The SystemC libraries have many little
inlined functions that drive the compiler nuts.)
If you are using your own makefiles, you may want to compile the Verilated
code with ``--MAKEFLAGS -DVL_INLINE_OPT=inline``. This will inline
functions, however this requires that all cpp files be compiled in a single
compiler run.
You may uncover further tuning possibilities by profiling the Verilog code.
See :ref:`profiling`.
When done optimizing, please let the author know the results. We like to
keep tabs on how Verilator compares, and may be able to suggest additional
improvements.
.. _Coverage Analysis:
Coverage Analysis
=================
Verilator supports adding code to the Verilated model to support
SystemVerilog code coverage. With :vlopt:`--coverage`, Verilator enables
all forms of coverage:
* :ref:`User Coverage`
* :ref:`Line Coverage`
* :ref:`Toggle Coverage`
When a model with coverage is executed, it will create a coverage file for
collection and later analysis, see :ref:`Coverage Collection`.
.. _User Coverage:
Functional Coverage
-------------------
With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
translate functional coverage points which the user has inserted manually
into the SystemVerilog design, into the Verilated model.
Currently, all functional coverage points are specified using SystemVerilog
assertion syntax which must be separately enabled with :vlopt:`--assert`.
For example, the following SystemVerilog statement will add a coverage
point, under the coverage name "DefaultClock":
.. code-block:: sv
DefaultClock: cover property (@(posedge clk) cyc==3);
.. _Line Coverage:
Line Coverage
-------------
With :vlopt:`--coverage` or :vlopt:`--coverage-line`, Verilator will
automatically add coverage analysis at each code flow change point (e.g. at
branches). At each such branch a unique counter is incremented. At the
end of a test, the counters along with the filename and line number
corresponding to each counter are written into the coverage file.
Verilator automatically disables coverage of branches that have a $stop in
them, as it is assumed $stop branches contain an error check that should
not occur. A :option:`/*verilator&32;coverage_block_off*/` metacomment
will perform a similar function on any code in that block or below, or
:option:`/*verilator&32;coverage_off*/` and
:option:`/*verilator&32;coverage_on*/` will disable and enable coverage
respectively around a block of code.
Verilator may over-count combinatorial (non-clocked) blocks when those
blocks receive signals which have had the UNOPTFLAT warning disabled; for
most accurate results do not disable this warning when using coverage.
.. _Toggle Coverage:
Toggle Coverage
---------------
With :vlopt:`--coverage` or :vlopt:`--coverage-toggle`, Verilator will
automatically add toggle coverage analysis into the Verilated model.
Every bit of every signal in a module has a counter inserted. The counter
will increment on every edge change of the corresponding bit.
Signals that are part of tasks or begin/end blocks are considered local
variables and are not covered. Signals that begin with underscores (see
:vlopt:`--coverage-underscore`), are integers, or are very wide (>256 bits
total storage across all dimensions, see :vlopt:`--coverage-max-width`) are
also not covered.
Hierarchy is compressed, such that if a module is instantiated multiple
times, coverage will be summed for that bit across **all** instantiations
of that module with the same parameter set. A module instantiated with
different parameter values is considered a different module, and will get
counted separately.
Verilator makes a minimally-intelligent decision about what clock domain
the signal goes to, and only looks for edges in that clock domain. This
means that edges may be ignored if it is known that the edge could never be
seen by the receiving logic. This algorithm may improve in the future.
The net result is coverage may be lower than what would be seen by looking
at traces, but the coverage is a more accurate representation of the
quality of stimulus into the design.
There may be edges counted near time zero while the model stabilizes. It's
a good practice to zero all coverage just before releasing reset to prevent
counting such behavior.
A :option:`/*verilator&32;coverage_off*/`
:option:`/*verilator&32;coverage_on*/` metacomment pair can be used around
signals that do not need toggle analysis, such as RAMs and register files.
.. _Coverage Collection:
Coverage Collection
-------------------
When any coverage flag was used to Verilate, Verilator will add appropriate
coverage point insertions into the model and collect the coverage data.
To get the coverage data from the model, in the user wrapper code,
typically at the end once a test passes, call
:code:`Verilated::coveragep()->write` with an argument of the filename for
the coverage data file to write coverage data to (typically
"logs/coverage.dat").
Run each of your tests in different directories, potentially in parallel.
Each test will create a :file:`logs/coverage.dat` file.
After running all of the tests, execute the :command:`verilator_coverage`
command, passing arguments pointing to the filenames of all of the
individual coverage files. :command:`verilator_coverage` will reads the
:file:`logs/coverage.dat` file(s), and create an annotated source code
listing showing code coverage details.
:command:`verilator_coverage` may also be used for test grading, that is
computing which tests are important to fully cover the design.
For an example, see the :file:`examples/make_tracing_c/logs` directory.
Grep for lines starting with '%' to see what lines Verilator believes need
more coverage.
Additional options of :command:`verilator_coverage` allow for merging of
coverage data files or other transformations.
Info files can be written by verilator_coverage for import to
:command:`lcov`. This enables use of :command:`genhtml` for HTML reports
and importing reports to sites such as `https://codecov.io
<https://codecov.io>`_.
.. _Profiling:
Code Profiling
==============
The Verilated model may be code-profiled using GCC or Clang's C++ profiling
mechanism. Verilator provides additional flags to help map the resulting
C++ profiling results back to the original Verilog code responsible for the
profiled C++ code functions.
To use profiling:
#. Use Verilator's :vlopt:`--prof-cfuncs`.
#. Use Verilator's :vlopt:`-CFLAGS "-g -pg" <-CFLAGS>` to pass the
profiling flags through to GCC/Clang.
#. Build and run the simulation model.
#. The model will create gmon.out.
#. Run :command:`gprof` to see where in the C++ code the time is spent.
#. Run the gprof output through the :command:`verilator_profcfunc` program
and it will tell you what Verilog line numbers on which most of the time
is being spent.
.. _Thread Profiling:
Thread Profiling
================
When using multithreaded mode (:vlopt:`--threads`), it is useful to see
statistics and visualize how well the multiple CPUs are being utilized.
With the :vlopt:`--prof-threads` option, Verilator will:
* Add code to the Verilated model to record the start and end time of each
macro-task across a number of calls to eval. (What is a macro-task? See
the Verilator internals document (:file:`docs/internals.rst` in the
distribution.)
* Add code to save profiling data in non-human-friendly form to the file
specified with :vlopt:`+verilator+prof+threads+file+\<filename\>`.
The :command:`verilator_gantt` program may then be run to transform the
saved profiling file into a nicer visual format and produce some related
statistics.
.. figure:: ../_static/fig_gantt_min.png
Example verilator_gantt output, as viewed with GTKWave.
The parallelism shows the number of CPUs being used at a given moment.
The cpu_thread section shows which thread is executing on each of the physical CPUs.
The thread_mtask section shows which macro-task is running on a given thread.
For more information see :command:`verilator_gantt`.
.. _Save/Restore:
Save/Restore
============
The intermediate state of a Verilated model may be saved, so that it may
later be restored.
To enable this feature, use :vlopt:`--savable`. There are limitations in
what language features are supported along with :vlopt:`--savable`; if you
attempt to use an unsupported feature Verilator will throw an error.
To use save/restore, the user wrapper code must create a VerilatedSerialize
or VerilatedDeserialze object then calling the :code:`<<` or :code:`>>`
operators on the generated model and any other data the process needs
saved/restored. These functions are not thread safe, and are typically
called only by a main thread.
For example:
.. code-block:: C++
void save_model(const char* filenamep) {
VerilatedSave os;
os.open(filenamep);
os << main_time; // user code must save the timestamp, etc
os << *topp;
}
void restore_model(const char* filenamep) {
VerilatedRestore os;
os.open(filenamep);
os >> main_time;
os >> *topp;
}

482
docs/guide/verilating.rst Normal file
View File

@ -0,0 +1,482 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
**********
Verilating
**********
Verilator may be used in five major ways:
* With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate
the design into C++ or SystemC code respectively. See :ref:`C++ and
SystemC Generation`.
* With the :vlopt:`--lint-only` option, Verilator will lint the design to
check for warnings but will not typically create any output files.
* With the :vlopt:`--xml-only` option, Verilator will create XML output
that may be used to feed into other user-designed tools. See
:file:`docs/xml.rst` in the distribution.
* With the :vlopt:`-E` option, Verilator will preprocess the code according
to IEEE preprocessing rules, and write the output to standard out. This
is useful to feed other tools, and to debug how "\`define" statements are
expanded.
.. _C++ and SystemC Generation:
C++ and SystemC Generation
==========================
Verilator will translate a SystemVerilog design into C++ with the
:vlopt:`--cc` option, or into SystemC with the :vlopt:`--sc` option.
When using these options:
#. Verilator reads the input Verilog code, determines all "top modules" that
is modules or programs that are not used as instances under other cells.
If :vlopt:`--top-module` is used, then that determines the top module and
all other top modules are removed, otherwise a :vlopt:`MULTITOP` warning
is given.
#. Verilator writes the C++/SystemC code to output files into the
:vlopt:`--Mdir` option-specified directory, or defaults to "obj_dir".
The prefix is set with :vlopt:`--prefix`, or defaults to the name of the
top module.
#. If :vlopt:`--exe` is used, Verilator creates makefiles to generate a
simulation executable, otherwise it creates makefiles to generate an
archive (.a) containing the objects.
#. If :vlopt:`--build` option was used, it calls :ref:`GNU Make` or
:ref:`CMake` to build the model.
Once a model is built it is then typically run, see :ref:`Simulating`.
.. _Hierarchical Verilation:
Hierarchical Verilation
=======================
Large designs may take long (e.g. 10+ minutes) and huge memory (e.g. 100+
GB) to Verilate. In hierarchical mode, the user manually selects some
large lower-level hierarchy blocks to separate from the larger design. For
example a core may be the hierarchy block, and separated out of a
multi-core SoC.
Verilator is run in hierarchical mode on the whole SoC. Verilator will
make two models, one for the CPU hierarchy block, and one for the SoC. The
Verialted code for the SoC will automatically call the CPU Verilated model.
The current hierarchical Verilation is based on protect-lib. Each hierarchy
block is Verilated to a protect-lib. User modules of the hierarchy blocks
will see a tiny wrapper generated by protect-lib instead of the actual
design.
Usage
-----
Users need to mark one or more moderate size module as hierarchy block(s).
There are two ways to mark a module:
* Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code.
* Add a :option:`hier_block` line in a the :ref:`Configuration Files`.
Then pass the :vlopt:`--hierarchical` option to Verilator
Compilation is the same as when not using hierarchical mode.
.. code-block:: bash
make -C obj_dir -f Vtop_module_name.mk
Limitations
-----------
Hierarchy blocks have some limitations including:
* The hierarchy block cannot be accessed using dot (.) from upper module(s)
or other hierarchy blocks.
* Signals in the block cannot be traced.
* Modport cannot be used at the hierarchical block boundary.
* The simulation speed is likely to not be as fast as flat Verilation, in
which all modules are globally scheduled.
* Generated clocks may not work correctly if they are generated in the
hierarchical model and pass up into another hierarchical model or the top
module.
But, the following usage is supported:
* Nested hierarchy blocks. A hierarchy block may instantiate other
hierarchy blocks.
* Parameterized hierarchy block. Parameters of a hierarchy block can be
overridden using :code:`#(.param_name(value))` construct.
.. _Overlapping Verilation and Compilation:
Overlapping Verilation and Compilation
--------------------------------------
Verilator needs to run 2 + *N* times in hierarchical Verilation, where *N*
is the number of hierarchy blocks. One of the two is for the top module
which refers wrappers of all other hierarchy blocks. The second one of the
two is the initial run that searches modules marked with
:option:`/*verilator&32;hier_block*/` metacomment and creates a plan and
write in :file:`{prefix}_hier.mk`. This initial run internally invokes
other *N* + 1 runs, so you don't have to care about these *N* + 1 times of
run. The additional *N* is the Verilator run for each hierarchical block.
If ::vlopt:`-j {jobs} <-j>` option is specified, Verilation for hierarchy
blocks runs in parallel.
If :vlopt:`--build` option is specified, C++ compilation also runs as soon
as a hierarchy block is Verilated. C++ compilation and Verilation for other
hierarchy blocks run simultaneously.
Cross Compilation
=================
Verilator supports cross-compiling Verilated code. This is generally used
to run Verilator on a Linux system and produce C++ code that is then compiled
on Windows.
Cross compilation involves up to three different OSes. The build system is
where you configured and compiled Verilator, the host system where you run
Verilator, and the target system where you compile the Verilated code and
run the simulation.
Currently, Verilator requires the build and host system type to be the
same, though the target system type may be different. To support this,
:command:`./configure` and make Verilator on the build system. Then, run
Verilator on the host system. Finally, the output of Verilator may be
compiled on the different target system.
To support this, none of the files that Verilator produces will reference
any configure generated build-system specific files, such as
:file:`config.h` (which is renamed in Verilator to :file:`config_build.h`
to reduce confusion.) The disadvantage of this approach is that
:file:`include/verilatedos.h` must self-detect the requirements of the
target system, rather than using configure.
The target system may also require edits to the Makefiles, the simple
Makefiles produced by Verilator presume the target system is the same type
as the build system.
.. _Multithreading:
Multithreading
==============
Verilator supports multithreaded simulation models.
With :vlopt:`--no-threads`, the default, the model is not thread safe, and
any use of more than one thread calling into one or even different
Verilated models may result in unpredictable behavior. This gives the
highest single thread performance.
With :vlopt:`--threads 1 <--threads>`, the generated model is single
threaded, however the support libraries are multithread safe. This allows
different instantiations of model(s) to potentially each be run under a
different thread. All threading is the responsibility of the user's C++
testbench.
With :vlopt:`--threads {N} <--threads>`, where N is at least 2, the
generated model will be designed to run in parallel on N threads. The
thread calling eval() provides one of those threads, and the generated
model will create and manage the other N-1 threads. It's the client's
responsibility not to oversubscribe the available CPU cores. Under CPU
oversubscription, the Verilated model should not livelock nor deadlock,
however, you can expect performance to be far worse than it would be with
proper ratio of threads and CPU cores.
The remainder of this section describe behavior with :vlopt:`--threads 1
<--threads>` or :vlopt:`--threads {N} <--threads>` (not
:vlopt:`--no-threads`).
:code:`VL_THREADED` is defined in the C++ code when compiling a threaded
Verilated module, causing the Verilated support classes become threadsafe.
The thread used for constructing a model must be the same thread that calls
:code:`eval()` into the model, this is called the "eval thread". The thread
used to perform certain global operations such as saving and tracing must
be done by a "main thread". In most cases the eval thread and main thread
are the same thread (i.e. the user's top C++ testbench runs on a single
thread), but this is not required.
The :vlopt:`--trace-threads` options can be used to produce trace dumps
using multiple threads. If :vlopt:`--trace-threads` is set without
:vlopt:`--threads`, then :vlopt:`--trace-threads` will imply
:vlopt:`--threads 1 <--threads>`, i.e.: the support libraries will be
thread safe.
With :vlopt:`--trace-threads 0 <--trace-threads>`, trace dumps are produced
on the main thread. This again gives the highest single thread performance.
With :vlopt:`--trace-threads {N} <--trace-threads>`, where N is at least 1,
N additional threads will be created and managed by the trace files (e.g.:
VerilatedVcdC or VerilatedFstC), to generate the trace dump. The main
thread will be released to proceed with execution as soon as possible,
though some blocking of the main thread is still necessary while capturing
the trace. Different trace formats can utilize a various number of
threads. See the :vlopt:`--trace-threads` option.
When running a multithreaded model, the default Linux task scheduler often
works against the model, by assuming threads are short lived, and thus
often schedules threads using multiple hyperthreads within the same
physical core. For best performance use the :command:`numactl` program to
(when the threading count fits) select unique physical cores on the same
socket. The same applies for :vlopt:`--trace-threads` as well.
As an example, if a model was Verilated with :vlopt:`--threads 4
<--threads>`, we consult:
.. code-block:: bash
egrep 'processor|physical id|core id' /proc/cpuinfo
To select cores 0, 1, 2, and 3 that are all located on the same socket (0)
but different physical cores. (Also useful is :command:`numactl
--hardware`, or :command:`lscpu` but those doesn't show Hyperthreading
cores.) Then we execute:
.. code-block:: bash
numactl -m 0 -C 0,1,2,3 -- verilated_executable_name
This will limit memory to socket 0, and threads to cores 0, 1, 2, 3,
(presumably on socket 0) optimizing performance. Of course this must be
adjusted if you want another simulator using e.g. socket 1, or if you
Verilated with a different number of threads. To see what CPUs are
actually used, use :vlopt:`--prof-threads`.
Multithreaded Verilog and Library Support
-----------------------------------------
$display/$stop/$finish are delayed until the end of an eval() call in order
to maintain ordering between threads. This may result in additional tasks
completing after the $stop or $finish.
If using :vlopt:`--coverage`, the coverage routines are fully thread safe.
If using the DPI, Verilator assumes pure DPI imports are thread safe,
balancing performance versus safety. See :vlopt:`--threads-dpi`.
If using :vlopt:`--savable`, the save/restore classes are not multithreaded
and must be called only by the eval thread.
If using :vlopt:`--sc`, the SystemC kernel is not thread safe, therefore
the eval thread and main thread must be the same.
If using :vlopt:`--trace`, the tracing classes must be constructed and
called from the main thread.
If using :vlopt:`--vpi`, since SystemVerilog VPI was not architected by
IEEE to be multithreaded, Verilator requires all VPI calls are only made
from the main thread.
.. _GNU Make:
GNU Make
========
Verilator defaults to creating GNU Make makefiles for the model. Verilator
will call make automatically when the :vlopt:'--build' option is used.
If calling Verilator from a makefile, the :vlopt:'-MMD' option will create
a dependency file which will allow Make to only run Verilator if input
Verilog files change.
.. _CMake:
CMake
=====
Verilator can be run using CMake, which takes care of both running
Verilator and compiling the output. There is a CMake example in the
examples/ directory. The following is a minimal CMakeLists.txt that would
build the code listed in :ref:`Example C++ Execution`
.. code-block:: CMake
project(cmake_example)
find_package(verilator HINTS $ENV{VERILATOR_ROOT})
add_executable(Vour sim_main.cpp)
verilate(Vour SOURCES our.v)
:code:`find_package` will automatically find an installed copy of
Verilator, or use a local build if VERILATOR_ROOT is set.
It is recommended to use CMake >= 3.12 and the Ninja generator, though
other combinations should work. To build with CMake, change to the folder
containing CMakeLists.txt and run:
.. code-block:: bash
mkdir build
cd build
cmake -GNinja ..
ninja
Or to build with your system default generator:
.. code-block:: bash
mkdir build
cd build
cmake ..
cmake --build .
If you're building the example you should have an executable to run:
.. code-block:: bash
./Vour
The package sets the CMake variables verilator_FOUND, VERILATOR_ROOT and
VERILATOR_BIN to the appropriate values, and also creates a verilate()
function. verilate() will automatically create custom commands to run
Verilator and add the generated C++ sources to the target specified.
Verilate in CMake
-----------------
.. code-block:: CMake
verilate(target SOURCES source ... [TOP_MODULE top] [PREFIX name]
[TRACE] [TRACE_FST] [SYSTEMC] [COVERAGE]
[INCLUDE_DIRS dir ...] [OPT_SLOW ...] [OPT_FAST ...]
[OPT_GLOBAL ..] [DIRECTORY dir] [VERILATOR_ARGS ...])
Lowercase and ... should be replaced with arguments, the uppercase parts
delimit the arguments and can be passed in any order, or left out entirely
if optional.
verilate(target ...) can be called multiple times to add other Verilog
modules to an executable or library target.
When generating Verilated SystemC sources, you should also include the
SystemC include directories and link to the SystemC libraries.
.. describe:: target
Name of a target created by add_executable or add_library.
.. describe:: COVERAGE
Optional. Enables coverage if present, equivalent to "VERILATOR_ARGS
--coverage"
.. describe:: DIRECTORY
Optional. Set the verilator output directory. It is preferable to use
the default, which will avoid collisions with other files.
.. describe:: INCLUDE_DIRS
Optional. Sets directories that Verilator searches (same as -y).
.. describe:: OPT_SLOW
Optional. Set compiler options for the slow path. You may want to reduce
the optimization level to improve compile times with large designs.
.. describe:: OPT_FAST
Optional. Set compiler options for the fast path.
.. describe:: OPT_GLOBAL
Optional. Set compiler options for the common runtime library used by
Verilated models.
.. describe:: PREFIX
Optional. Sets the Verilator output prefix. Defaults to the name of the
first source file with a "V" prepended. Must be unique in each call to
verilate(), so this is necessary if you build a module multiple times
with different parameters. Must be a valid C++ identifier, i.e. contains
no white space and only characters A-Z, a-z, 0-9 or _.
.. describe:: SOURCES
List of Verilog files to Verilate. Must have at least one file.
.. describe:: SYSTEMC
Optional. Enables SystemC mode, defaults to C++ if not specified.
When using Accellera's SystemC with CMake support, a CMake target is
available that simplifies the SystemC steps. This will only work if the
SystemC installation can be found by CMake. This can be configured by
setting the CMAKE_PREFIX_PATH variable during CMake configuration.
Don't forget to set the same C++ standard for the Verilated sources as
the SystemC library. This can be specified using the SYSTEMC_CXX_FLAGS
environment variable.
.. describe:: TOP_MODULE
Optional. Sets the name of the top module. Defaults to the name of the
first file in the SOURCES array.
.. describe:: TRACE
Optional. Enables VCD tracing if present, equivalent to "VERILATOR_ARGS
--trace".
.. describe:: TRACE_FST
Optional. Enables FST tracing if present, equivalent to "VERILATOR_ARGS
--trace-fst".
.. describe:: VERILATOR_ARGS
Optional. Extra arguments to Verilator. Do not specify :vlopt:`--Mdir`
or :vlopt:`--prefix` here, use DIRECTORY or PREFIX.
SystemC Link in CMake
---------------------
Verilator's CMake support provides a convenience function to automatically
find and link to the SystemC library. It can be used as:
.. code-block:: CMake
verilator_link_systemc(target)
where target is the name of your target.
The search paths can be configured by setting some variables:
.. describe:: SYSTEMC_INCLUDE
Sets the direct path to the SystemC includes.
.. describe:: SYSTEMC_LIBDIR
Sets the direct path to the SystemC libraries.
.. describe:: SYSTEMC_ROOT
Sets the installation prefix of an installed SystemC library.
.. describe:: SYSTEMC
Sets the installation prefix of an installed SystemC library. (Same as
SYSTEMC_ROOT).

1585
docs/guide/warnings.rst Normal file
View File

File diff suppressed because it is too large Load Diff

397
docs/install.rst
View File

@ -1,397 +0,0 @@
|Logo|
======================
Verilator Installation
======================
.. contents::
:depth: 3
Introduction
============
This discusses how to install Verilator. For more general information
please see `verilator.org <https://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 <#_running_verilator>`__.
Docker
------
Verilator is available in pre-built Docker containers. See
https://github.com/verilator/verilator/blob/master/ci/docker/run/README.rst
Git
---
Installing Verilator with Git provides the most flexibility. For
additional options and details see the additional sections below. In
brief:
::
# 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 https://github.com/verilator/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 <#_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 <#_install_from_a_package_manager>`__.
OS Requirements
---------------
Verilator is developed and has primary testing on Ubuntu, with additional
testing on FreeBSD and Apple OS-X. Versions have also built on Redhat
Linux, 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 or run Verilator you need these standard packages:
::
sudo apt-get install perl python3 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)
To build or run the following are optional but should be installed for good
performance:
::
sudo apt-get install ccache # If present at build, needed for run
sudo apt-get install libgoogle-perftools-dev numactl perl-doc
To build Verilator you will need to install these packages; these do not
need to be present to run Verilator:
::
sudo apt-get install git autoconf flex bison
Those developing Verilator itself may also want these (see internals.rst):
::
sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
cpan install Pod::Perldoc
cpan install Parallel::Forker
Install SystemC
~~~~~~~~~~~~~~~
If you will be using SystemC (vs straight C++ output), download `SystemC
<https://www.accellera.org/downloads/standards/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 `GTKwave
<http://gtkwave.sourceforge.net/>`__ 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 `Verilator Downloads
<https://www.veripool.org/projects/verilator/wiki/Download>`__; 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 https://github.com/verilator/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 `modulecmd
<http://modules.sourceforge.net/>`__, 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
<#_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 `Verilator manual (HTML)
<https://verilator.org/verilator_doc.html>`__, or `Verilator manual (PDF)
<https://verilator.org/verilator_doc.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, go to `Verilator announcement repository
<https://github.com/verilator/verilator-announce>`__ and follow the
instructions there.
Directory Structure
===================
Some relevant files and directories in this package are as follows:
::
Changes => Version history
README.rst => 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 `Verilator manual
(HTML) <https://verilator.org/verilator_doc.html>`__, or `Verilator
manual (PDF) <https://verilator.org/verilator_doc.pdf>`__.
License
=======
Copyright 2008-2021 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.
.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png

59
docs/internals.rst
View File

@ -1,8 +1,8 @@
|Logo|
===================
*******************
Verilator Internals
===================
*******************
.. contents::
:depth: 3
@ -81,7 +81,7 @@ Key Classes Used in the Verilator Flow
``AstNode``
~~~~~~~~~~~
^^^^^^^^^^^
The AST is represented at the top level by the class ``AstNode``. This
abstract class has derived classes for the individual components (e.g.
@ -115,7 +115,7 @@ pointer to the ``AstNode`` currently being processed.
``AstNVisitor``
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
The passes are implemented by AST visitor classes. These are implemented by
subclasses of the abstract class, ``AstNVisitor``. Each pass creates an
@ -124,7 +124,7 @@ the pass.
``V3Graph``
~~~~~~~~~~~
^^^^^^^^^^^
A number of passes use graph algorithms, and the class ``V3Graph`` is
provided to represent those graphs. Graphs are directed, and algorithms are
@ -134,7 +134,7 @@ documentation of this class.
``V3GraphVertex``
~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^
``V3GraphVertex`` is the base class for vertices in a graph. Vertices have
an associated ``fanout``, ``color`` and ``rank``, which may be used in
@ -156,7 +156,7 @@ in the form:
``V3GraphEdge``
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
``V3GraphEdge`` is the base class for directed edges between pairs of
vertices. Edges have an associated ``weight`` and may also be made
@ -171,7 +171,7 @@ used in dot output. Typically users provided derived classes from
``V3GraphAlg``
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^
This is the base class for graph algorithms. It implements a ``bool``
method, ``followEdge`` which algorithms can use to decide whether an edge
@ -204,7 +204,7 @@ synchronization cost is not prohibitive with so few nodes.
Partitioning
~~~~~~~~~~~~
^^^^^^^^^^^^
Our partitioner is similar to the one Vivek Sarkar described in his 1989
paper *Partitioning and Scheduling Parallel Programs for Multiprocessors*.
@ -213,7 +213,7 @@ Let's define some terms:
Par Factor
~~~~~~~~~~
^^^^^^^^^^
The available parallelism or "par-factor" of a DAG is the total cost to
execute all nodes, divided by the cost to execute the longest critical path
@ -223,7 +223,7 @@ synchronization are zero.
Macro Task
~~~~~~~~~~
^^^^^^^^^^
When the partitioner coarsens the graph, it combines nodes together. Each
fine-grained node represents an atomic "task"; combined nodes in the
@ -235,7 +235,7 @@ ends.)
Edge Contraction
~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^
Verilator's partitioner, like Sarkar's, primarily relies on "edge
contraction" to coarsen the graph. It starts with one macro-task per atomic
@ -243,7 +243,7 @@ task and iteratively combines pairs of edge-connected macro-tasks.
Local Critical Path
~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^
Each node in the graph has a "local" critical path. That's the critical
path from the start of the graph to the start of the node, plus the node's
@ -263,7 +263,8 @@ it's not guaranteed to produce the best partition (which Sarkar proves is
NP-hard).
Estimating Logic Costs ~~~~~~~~~~~~~~~~~~~~~~
Estimating Logic Costs
^^^^^^^^^^^^^^^^^^^^^^
To compute the cost of any given path through the graph, Verilator
estimates an execution cost for each task. Each macro-task has an execution
@ -284,7 +285,7 @@ runtime costs estimates. This is an area to improve.
Scheduling Macro-Tasks at Runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After coarsening the graph, we must schedule the macro-tasks for
runtime. Sarkar describes two options: you can dynamically schedule tasks
@ -306,7 +307,7 @@ fragmentation.
Locating Variables for Best Spatial Locality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After scheduling all code, we attempt to locate variables in memory such
that variables accessed by a single macro-task are close together in
@ -339,11 +340,11 @@ locality in serial mode; that is a possible area for improvement.)
Improving Multithreaded Performance Further (a TODO list)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Wave Scheduling
^^^^^^^^^^^^^^^
"""""""""""""""
To allow the Verilated model to run in parallel with the testbench, it
might be nice to support "wave" scheduling, in which work on a cycle begins
@ -355,7 +356,7 @@ however, it's probably the best bet for hiding testbench latency.
Efficient Dynamic Scheduling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
""""""""""""""""""""""""""""
To scale to more than a few threads, we may revisit a fully dynamic
scheduler. For large (>16 core) systems it might make sense to dedicate an
@ -365,7 +366,7 @@ would not be prohibitive.
Static Scheduling with Runtime Repack
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"""""""""""""""""""""""""""""""""""""
We could modify the static scheduling approach by gathering actual
macro-task execution times at run time, and dynamically re-packing the
@ -377,7 +378,7 @@ or nonuniform competing memory traffic or whatever.
Clock Domain Balancing
^^^^^^^^^^^^^^^^^^^^^^
""""""""""""""""""""""
Right now Verilator makes no attempt to balance clock domains across
macro-tasks. For a multi-domain model, that could lead to bad gantt chart
@ -385,7 +386,7 @@ fragmentation. This could be improved if it's a real problem in practice.
Other Forms of MTask Balancing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
""""""""""""""""""""""""""""""
The largest source of runtime overhead is idle CPUs, which happens due to
variance between our predicted runtime for each MTask and its actual
@ -406,7 +407,7 @@ option to scramble things.
Performance Regression
^^^^^^^^^^^^^^^^^^^^^^
""""""""""""""""""""""
It would be nice if we had a regression of large designs, with some
diversity of design styles, to test on both single- and multi-threaded
@ -415,7 +416,7 @@ evaluate the optimizations while minimizing the impact of parasitic noise.
Per-Instance Classes
^^^^^^^^^^^^^^^^^^^^
""""""""""""""""""""
If we have multiple instances of the same module, and they partition
differently (likely; we make no attempt to partition them the same) then
@ -631,7 +632,7 @@ and takes an argument type ``AstNode*``.
Caution on Using Iterators When Child Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visitors often replace one node with another node; V3Width and V3Const
are major examples. A visitor which is the parent of such a replacement
@ -700,7 +701,7 @@ that type (if it is of class ``SOMETYPE``, or a derived class of
as that is faster.)
.. _Testing
.. _Testing:
Testing
=======
@ -1152,9 +1153,9 @@ Generally what would you do to add a new feature?
4. If a new Ast type is needed, add it to V3AstNodes.h. Follow the
convention described above about the AstNode type hierarchy.
5. Now you can run "test_regress/t/t_{new testcase}.pl --debug" and it'll
5. Now you can run "test_regress/t/t_<newtestcase>.pl --debug" and it'll
probably fail but you'll see a
test_regress/obj_dir/t_{newtestcase}/*.tree file which you can examine
"test_regress/obj_dir/t_<newtestcase>/*.tree" file which you can examine
to see if the parsing worked. See also the sections above on debugging.
6. Modify the later visitor functions to process the new feature as needed.
@ -1179,8 +1180,6 @@ Verilator ideally would support all of IEEE, and has the goal to get close
to full support. However the following IEEE sections and features are not
anticipated to be ever implemented for the reasons indicated.
.. list-table::
IEEE 1800-2017 3.3 recursive modules
Little/no tool support, and arguably not a good practice.
IEEE 1800-2017 6.12 "shortreal"

850
docs/spelling.txt Normal file
View File

@ -0,0 +1,850 @@
ABCp
Accellera
Affe
Aleksander
Ami
Amir
Anastasiadis
Antonin
Antwerpen
Arasanipalai
Arjen
Asciidoc
Ashutosh
Atmel
Aurelien
Bagri
Baltazar
Bardsley
Benchmarking
Berman
Bhagavatula
Bhattacharyya
Binderman
Bleiweiss
Bogdan
Bouchard
Boumenot
Brej
Briquet
Brownlee
Buckenmaier
Bybell
CMake
Cai
Cavium
Cfuncs
Chandan
Chitlesh
Christophe
Cochrane
Cuan
Cygwin
DErrico
Da
Danilo
Dannoritzer
Das
Dcache
Deadman
Debacker
Defparams
Denio
Deprecations
Deroo
Dickol
Diez
Dimitris
Dinotrace
Djordjevic
Dobbie
Dockerfile
Donal
Doorn
Doxygen
Dressler
Duraid
Dutton
Dzetkulic
Eda
Eddleston
Egbert
Egil
Eiler
Eivind
El
Elbourne
Embecosm
Engstrom
Enzo
Eugen
Fabrizio
Fekete
Ferrandi
Flachs
Foletto
Forker
Francillon
Fredieu
GTKWave
Galbi
Gantt
Gartner
Gelinek
Geoff
Gernot
Gerst
Gielda
Gigerl
Gileadi
Giri
Gisselquist
Gladkikh
Goessling
Gonnen
Goorah
Gossner
Grobman
Gunter
Guo
Hao
Harboe
Hashimoto
Hayenga
Hewson
Hicamp
Hiroki
Holdsworth
Holme
Homebrew
Hornung
Hossell
Hsu
Hyperthreading
Iles
Inlines
Inout
Iru
Iztok
Jacko
Jae
Jalloq
Jankowski
Jannis
Jens
Jeras
Jiuyang
Joly
Jullien
Junji
Junyi
Kaalia
Kagen
Kahlich
Kahn
Kai
Kamendje
Kandadi
Kaplan
Karge
Katz
Katzman
Keren
Keyi
Kimmitt
Kindgren
Kirkham
Klnv
Koenig
Koh
Kolecki
Koonce
Korteland
Koszek
Kravitz
Krolnik
Kruse
Kumashikar
Kuoping
Kurachi
Laeufer
Laurens
Lavino
Leber
Leendert
Lesik
Liland
Liu
Lockhart
Longo
Lussier
MMD
MODDUP
MTasks
Madina
Magne
Mahesh
Mahmoudy
Makefile
Makefiles
Matveyenko
Maupin
Mdir
Mednick
Michiels
Microsystems
Milanovic
MinW
Mindspeed
Miodrag
ModelSim
Modport
Moinak
Mong
Muhlestein
Multithreaded
Multithreading
NOUNOPTFLAT
Nalbantis
Narayan
Nauticus
Newgard
Nikana
Niranjan
Nitza
Noack
Nodine
Oleg
Olof
Olofsson
Oyvind
PLI
Patricio
Petr
Piechotka
Piersall
Plunkett
Popov
Prabhat
Prabhu
Prateek
Pre
Preprocess
Priyadharshini
Pullup
Pulver
Puri
Questa
Ralf
Rapp
Redhat
Reitan
Renga
Requin
Rodionov
Rolfe
Roodselaar
Runtime
Ruud
Rystsov
STandarD
Salman
Sanguinetti
Sanjay
Scharrer
Seitz
Shankar
Shanshan
Sharad
Shareef
Sheng
Shi
Shinkarovsky
Shirakawa
Shuba
Slatter
SoC
Sobhan
Sokorac
Solaris
Solomatnikov
Srini
Stamness
Stephane
Stoddard
Stroebel
Strouble
Stucki
Su
Suguimoto
Sundararajan
Suse
Syms
Synopsys
SystemC
SystemVerilog
Takatsukasa
Tambe
Tariq
Tengstrand
Terpstra
Thiede
Thierry
Thyer
Tichelaar
Tomov
Topa
Tota
Tresidder
Tri
Tristate
Turton
UNOPTFLAT
Ubixum
Uints
Undefines
Unsized
Uselib
Usha
Usuario
VERILATOR
Vasu
Vdly
Vemumtab
Vemuri
Veriable
Verialted
Verilate
Verilated
Verilating
Verilation
Verilator
Verilog
Viktor
Vm
Vukobratovic
Wai
Wasson
Welch
Werror
Wfuture
Whatson
Wildman
Wim
Wno
Wojciech
Wolfel
Wouters
Wpedantic
Wwarn
XSim
Xcelium
Xiaoliang
Xuan
Xuanqi
Yazdanbakhsh
Yi
Yinan
Yosys
Yu
Zhang
abirkmanis
accessor
accessors
agrobman
al
ala
andit
ar
architected
args
arrarys
assertOn
async
ato
atoi
autoconf
autoflush
bXXXX
backend
backslashed
backtrace
backtraces
basename
bbox
biguint
biops
bitstoreal
blackbox
bokke
brancoliticus
buf
bufif
buildenv
bv
bvs
callValueCbs
casex
casez
casted
cb
ccache
cdc
ceil
celldefine
cerr
cfunc
cfuncs
chandle
chandles
changeDetect
chenguokai
clk
clocker
cmake
cmos
combinational
combinatorial
commandArgsPlusMatch
compilable
concat
concats
config
const
coredump
countbits
countones
cout
cpp
cpu
ctor
ctrace
cutable
cygwin
dM
da
dat
datadir
datafiles
ddd
deassign
debugi
defenv
defname
defparam
demangling
der
desassign
destructor
detections
dev
devel
dir
displayb
distcc
doxygen
dpiGetContext
dpic
dsvf
dtor
dumpall
dumpfile
dumplimit
dumpoff
dumpon
dumpportlimit
dumpports
dumpportsall
dumpportslimit
dumpportsoff
dumpportson
dumpvars
dut
dx
elab
elsif
endcase
endcelldefine
endfunction
endgenerate
endian
endif
endmodule
endprotect
endspecify
endtask
engr
entrypoint
enum
enums
env
envvar
eof
erroring
et
eval
exe
executables
expr
extern
fanin
fasttrace
fbranch
fclose
fdisplay
feedthrus
feof
ferror
fflush
fgetc
fgets
filesystem
filt
flto
flushCall
fopen
foreach
fprintf
fprofile
fread
frewind
fs
fscanf
fseek
fsiegle
fst
fstrict
ftell
fullskew
func
funcs
fwrite
gantt
gcc
gdb
genblk
genvar
genvars
getenv
getline
gmake
gmon
gotFinish
gprof
gtkwave
hdr
hdzhangdoc
hh
hier
hierCMakeArgs
hierMkArgs
hierVer
hx
hyperthreads
icecream
idmap
ifdef
ifdefed
iff
ifndef
impot
incdir
includer
inferfaces
inhibitSim
initializer
initializers
inits
inlined
inlining
inout
inouts
inserted
instantiation
instantiations
iostream
ish
isunbounded
isunknown
killua
lang
lcov
ld
len
libext
libgoogle
libsystemc
libtcmalloc
linkers
linter
linux
liu
livelock
ln
loc
localparam
localparams
logicals
longint
lsb
lvalue
lxt
macromodule
makefile
makefiles
manpages
metacomment
metacomments
mis
misconnected
misconversion
missized
mk
mno
modport
modports
msg
msvc
mtask
mtasks
mulithreaded
mult
multidim
multiinterfaces
multiline
multipling
multithread
multithreaded
multithreading
mutexes
mux
mysignal
namespace
nand
nanduraj
nasties
negedge
negedges
netlist
netlists
nettype
nmos
noassert
nochange
noconfig
nol
nonblocking
noprivate
noreturn
notif
nullptr
onehot
ooo
oprofile
oversubscription
param
parameterized
params
parens
pc
pdf
perf
perftools
picoChip
pinout
plusargs
pmos
poping
portbind
portlists
posedge
posix
postfix
pragma
pragmas
pre
precisions
predefines
prepend
prepended
preprocess
preprocessed
preprocessing
preprocessor
prerelease
prev
printf
printtimescale
profcfunc
profcfuncs
prototyptes
ps
pthread
pulldown
pulldowns
pullup
pvalue
pwd
qrq
radix
randc
rarr
rdtsc
reStructuredText
readme
readmem
readmemb
readmemh
realpath
realtime
recoding
recrem
redeclaring
regs
reloop
resetall
respecified
rr
rst
runtime
runtimes
rw
sVerilator
sc
scalared
sccanf
seg
setuphold
sformat
sformatf
shortint
shortreal
signame
sp
specparam
splitme
spp
sqrt
srcdir
srcfile
sscanf
stderr
stdin
stdout
stime
stmts
strcasecmp
stringification
stringified
stringify
struct
structs
subcell
subcells
subexpressions
submodule
submodules
sv
svBitVal
svBitVecVal
svGet
svLogicVal
svdpi
swrite
sys
systemc
testbench
threadsafe
threashold
timeInc
timeformat
timeprecision
timeskew
timeunit
tinshark
tm
tolower
toolchain
topcell
toplevel
toupper
traceEverOn
tran
treei
tri
tristate
tristates
trunc
txt
typ
typedef
typedefed
typedefs
typename
uint
un
undef
undefineall
undriven
ungetc
uniquified
unistd
unlink
unlinked
unopt
unoptflat
unoptimizable
unroller
unsized
unsup
untyped
urandom
uselib
uwire
uwires
vc
vcd
vcddiff
vcoverage
vec
ver
verFiles
verible
verilate
verilated
verilator
verilog
verilogmod
verimake
vl
vlopt
vlt
vltstd
vluint
vpi
vpiLeftRange
vpiModule
vpiSize
vpiSuppressVal
vpiTimeUnit
vpiType
vpm
vpp
warmup
waveforms
whitespace
widthed
wreal
writeb
writeme
writemem
writememb
writememh
xin
xml
xnor
xout
xuejiazidi
yanx
yurivict
zdave

42
docs/verilated.dox Normal file
View File

@ -0,0 +1,42 @@
PROJECT_NAME = "Verilog to Routing - ABC"
INPUT = ../../include
OUTPUT_DIRECTORY = _build/doxygen/verilated
EXTRACT_ALL = NO
EXTRACT_LOCAL_CLASSES = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES
FULL_PATH_NAMES = NO
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
HIDE_FRIEND_COMPOUNDS = YES
HIDE_IN_BODY_DOCS = YES
HIDE_UNDOC_CLASSES = YES
HIDE_UNDOC_MEMBERS = YES
INTERNAL_DOCS = NO
OPTIMIZE_OUTPUT_FOR_C = NO
RECURSIVE = NO
SHOW_INCLUDE_FILES = NO
WARN_IF_UNDOCUMENTED = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = \
"DOXYGEN=1" \
"VL_ATTR_NORETURN=" \
"VL_ATTR_PRINTF()=" \
"VL_ATTR_WEAK=" \
"VL_GUARDED_BY()=" \
"VL_MT_SAFE=" \
"VL_MT_SAFE_EXCLUDES()=" \
"VL_MT_SAFE_POSTINIT=" \
"VL_MT_UNSAFE=" \
"VL_MT_UNSAFE_ONE=" \
"VL_NOT_FINAL=" \
"VL_PURE=" \
"VL_REQUIRES()=" \
"VL_THREAD_LOCAL=" \
"__restrict=" \

4
docs/xml.rst
View File

@ -1,8 +1,8 @@
|Logo|
===========================
***************************
Verilator XML Output Format
===========================
***************************
Introduction
============

36
src/pod2latexfix
View File

@ -1,36 +0,0 @@
#!/usr/bin/env perl
######################################################################
#
# Copyright 2002-2021 by Wilson Snyder. This program 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.
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
#
######################################################################
# DESCRIPTION: Edits pod2latex output
use warnings;
my $Opt_DistTitle = $ARGV[0] or die "%Error: No disttitle specified,";
my $Opt_DistDate = $ARGV[1] or die "%Error: No distdate specified,";
my $header =
("\\usepackage[left=1.0in,right=1.0in,top=1.0in,bottom=1.0in]{geometry}\n"
."\\usepackage[pdftex,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,colorlinks=true,linkcolor=blue]{hyperref}\n"
."\\usepackage{fancyhdr} \\pagestyle{fancy}\n"
."\\usepackage{graphicx}\n"
."\n"
."\\setlength{\\parindent}{0pt} \\setlength{\\parskip}{\\baselineskip}\n"
."\n"
."\\title{\\includegraphics[width=6cm]{docs/_static/verilator_logo.png}\\\\ ${Opt_DistTitle}}\n"
."\\date{${Opt_DistDate}}\n"
."\\author{https:\/\/verilator.org}\n"
."\\lhead[${Opt_DistTitle}]{${Opt_DistTitle}}\n"
);
foreach my $line (<STDIN>) {
$line =~ s/(\\begin\{document\})/${header}$1/;
$line =~ s/(\\tableofcontents)/\\begin\{titlepage\} \\maketitle \\end\{titlepage\}\n$1/;
print "$line";
}

68
test_regress/driver.pl
View File

@ -2388,6 +2388,74 @@ sub file_sed {
$self->write_wholefile($outfilename, $contents);
}
sub extract {
my $self = (ref $_[0]? shift : $Self);
my %param = (#in =>,
#out =>
regexp => qr/.*/,
lineno_adjust => -9999,
lines => undef, #'#, #-#',
@_);
my $temp_fn = $param{out};
$temp_fn =~ s!.*/!!g;
$temp_fn = $self->{obj_dir} . "/" . $temp_fn;
my @out;
my $emph = "";
my $lineno = 0;
my $lineno_out = 0;
{
my $fh = IO::File->new("<$param{in}") or die "%Error: $! $param{in},";
while (defined(my $line = $fh->getline)) {
++$lineno;
if ($line =~ /$param{regexp}/
&& _lineno_match($lineno, $param{lines})) {
if ($line =~ m!t/[A-Za-z0-9_]+.v:(\d+):(\d+):!) {
my $lineno = $1;
my $col = $2;
$lineno += $param{lineno_adjust};
$lineno = 1 if $lineno < 1;
$line =~ s!t/[A-Za-z0-9_]+.v:(\d+):(\d+):!example.v:${lineno}:${col}!;
}
push @out, " " . $line;
++$lineno_out;
if ($line =~ /<--/) {
$emph .= "," if $emph;
$emph .= $lineno_out;
}
}
}
}
{
my $fhw = IO::File->new(">$temp_fn") or die "%Error: $! $temp_fn,";
my $lang = "";
$lang = " sv" if $param{in} =~ /\.s?vh?$/;
$fhw->print(".. comment: generated by " . $self->{name} . "\n");
$fhw->print(".. code-block::${lang}\n");
$fhw->print(" :linenos:\n") if $lang && $#out > 0;
$fhw->print(" :emphasize-lines: ${emph}\n") if $emph;
$fhw->print("\n");
foreach my $line (@out) {
$fhw->print($line);
}
}
$self->files_identical($temp_fn, $param{out});
}
sub _lineno_match {
my $lineno = shift;
my $lines = shift;
return 1 if !defined $lines;
if ($lines =~ /^(\d+)$/) {
return $1 == $lineno;
} elsif ($lines =~ /^(\d+)-(\d+)$/) {
return $1 <= $lineno && $2 >= $lineno;
}
return 0;
}
#######################################################################
#######################################################################
#######################################################################

40
test_regress/t/t_assert_comp_bad.pl
View File

@ -18,5 +18,45 @@ compile(
expect_filename => $Self->{golden_filename},
);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_USERWARN_faulty.rst",
regexp => qr/\$warn.*User/);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_USERERROR_faulty.rst",
regexp => qr/\$error.*User/);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_USERINFO_faulty.rst",
regexp => qr/\$info.*User/);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_USERFATAL_faulty.rst",
regexp => qr/\$fatal.*User/);
extract(
in => $Self->{golden_filename},
out => "../docs/gen/ex_USERWARN_msg.rst",
regexp => qr/USERWARN:.* User/);
extract(
in => $Self->{golden_filename},
out => "../docs/gen/ex_USERERROR_msg.rst",
regexp => qr/USERERROR:.* User/);
extract(
in => $Self->{golden_filename},
out => "../docs/gen/ex_USERINFO_msg.rst",
regexp => qr/-Info:.* User/);
extract(
in => $Self->{golden_filename},
out => "../docs/gen/ex_USERFATAL_msg.rst",
regexp => qr/USERFATAL/);
ok(1);
1;

6
test_regress/t/t_lint_width_docs_bad.out Normal file
View File

@ -0,0 +1,6 @@
%Warning-WIDTH: t/t_lint_width_docs_bad.v:10:29: Bit extraction of array[4:0] requires 3 bit index, not 2 bits.
: ... In instance t
10 | wire int rd_value = array[rd_addr];
| ^
... Use "/* verilator lint_off WIDTH */" and lint_on around source to disable this message.
%Error: Exiting due to

36
test_regress/t/t_lint_width_docs_bad.pl Executable file
View File

@ -0,0 +1,36 @@
#!/usr/bin/env perl
if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
# DESCRIPTION: Verilator: Verilog Test driver/expect definition
#
# Copyright 2003 by Wilson Snyder. This program 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.
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
scenarios(linter => 1);
lint(
verilator_flags2 => ["--lint-only"],
fails => $Self->{vlt_all},
expect_filename => $Self->{golden_filename},
);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_WIDTH_1_faulty.rst",
lines => "8-10");
extract(
in => $Self->{golden_filename},
out => "../docs/gen/ex_WIDTH_1_msg.rst",
lineno_adjust => -7,
regexp => qr/Warning-WIDTH/);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_WIDTH_1_fixed.rst",
lines => "18");
ok(1);
1;

19
test_regress/t/t_lint_width_docs_bad.v Normal file
View File

@ -0,0 +1,19 @@
// DESCRIPTION: Verilator: Verilog Test module
//
// This file ONLY is placed under the Creative Commons Public Domain, for
// any use, without warranty, 2009 by Wilson Snyder.
// SPDX-License-Identifier: CC0-1.0
module t;
int array[5];
bit [1:0] rd_addr;
wire int rd_value = array[rd_addr]; //<--- Warning
ok ok();
endmodule
module ok;
int array[5];
bit [1:0] rd_addr;
wire int rd_value = array[{1'b0, rd_addr}]; //<--- Fixed
endmodule;

8
test_regress/t/t_var_bad_hide_docs.out Normal file
View File

@ -0,0 +1,8 @@
%Warning-VARHIDDEN: t/t_var_bad_hide_docs.v:8:12: Declaration of signal hides declaration in upper scope: 't'
8 | integer t;
| ^
t/t_var_bad_hide_docs.v:7:8: ... Location of original declaration
7 | module t;
| ^
... Use "/* verilator lint_off VARHIDDEN */" and lint_on around source to disable this message.
%Error: Exiting due to

31
test_regress/t/t_var_bad_hide_docs.pl Executable file
View File

@ -0,0 +1,31 @@
#!/usr/bin/env perl
if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
# DESCRIPTION: Verilator: Verilog Test driver/expect definition
#
# Copyright 2003 by Wilson Snyder. This program 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.
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
scenarios(linter => 1);
lint(
verilator_flags2 => ["--lint-only -Wwarn-VARHIDDEN"],
fails => $Self->{vlt_all},
expect_filename => $Self->{golden_filename},
);
extract(
in => $Self->{top_filename},
out => "../docs/gen/ex_VARHIDDEN_faulty.rst",
regexp => qr/(module t|integer|endmodule)/);
extract(
in => $Self->{golden_filename},
out => "../docs/gen/ex_VARHIDDEN_msg.rst",
lineno_adjust => -6,
regexp => qr/(var_bad_hide)/);
ok(1);
1;

9
test_regress/t/t_var_bad_hide_docs.v Normal file
View File

@ -0,0 +1,9 @@
// DESCRIPTION: Verilator: Verilog Test module
//
// This file ONLY is placed under the Creative Commons Public Domain, for
// any use, without warranty, 2009 by Wilson Snyder.
// SPDX-License-Identifier: CC0-1.0
module t;
integer t; //<--- Warning ('t' hidden by module 't')
endmodule

19
test_regress/t/t_width_docs_bad.v Normal file
View File

@ -0,0 +1,19 @@
// DESCRIPTION: Verilator: Verilog Test module
//
// This file ONLY is placed under the Creative Commons Public Domain, for
// any use, without warranty, 2009 by Wilson Snyder.
// SPDX-License-Identifier: CC0-1.0
module t;
int array[5];
bit [1:0] rd_addr;
wire int rd_value = read_array[rd_addr]; //<--- Warning
ok ok();
endmodule
module ok;
int array[5];
bit [1:0] rd_addr;
wire int rd_value = read_array[{1'b0, rd_addr}]; //<--- Fixed
endmodule;