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

Merge from master for release.

This commit is contained in:
Wilson Snyder 2021-04-24 10:40:13 -04:00
parent f0d664530d 15f7741eaf
commit aac4b7090a
553 changed files with 24522 additions and 13294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.clang-format
View File

@ -20,7 +20,7 @@ AlwaysBreakBeforeMultilineStrings: false
AlwaysBreakTemplateDeclarations: false
BinPackArguments: true
BinPackParameters: true
BraceWrapping:
BraceWrapping:
AfterClass: false
AfterControlStatement: false
AfterEnum: false
@ -55,12 +55,12 @@ DerivePointerAlignment: false
DisableFormat: false
ExperimentalAutoDetectBinPacking: false
FixNamespaceComments: true
ForEachMacros:
ForEachMacros:
- foreach
- Q_FOREACH
- BOOST_FOREACH
IncludeBlocks: Preserve
IncludeCategories:
IncludeCategories:
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
Priority: 2
- Regex: '^(<|"(gtest|gmock|isl|json)/)'

1
.gitattributes vendored
View File

@ -1,4 +1,5 @@
*.v linguist-language=SystemVerilog
*.vh linguist-language=SystemVerilog
*.sv linguist-language=SystemVerilog
Changes linguist-language=reStructuredText
nodist linguist-detectable=false

27
.github/workflows/coverage.yml vendored
View File

@ -23,13 +23,15 @@ jobs:
runs-on: ubuntu-20.04
env:
CI_BUILD_STAGE_NAME: build
CI_RUNS_ON: ${{ matrix.os }}
CACHE_KEY: ${{ matrix.os }}-${{ matrix.compiler.cc }}-coverage
CI_RUNS_ON: ubuntu-20.04
CACHE_KEY: ubuntu-20.04-${{ matrix.compiler.cc }}-coverage
steps:
- uses: actions/checkout@v2
- name: Checkout
uses: actions/checkout@v2
- uses: actions/cache@v2
- name: Cache
uses: actions/cache@v2
env:
cache-name: ccache
with:
@ -37,15 +39,14 @@ jobs:
key: ${{ env.CACHE_KEY }}-${{ env.cache-name }}-${{ github.sha }}
restore-keys: coverage-${{ env.cache-name }}
- name: Install dependencies for build
- name: Install packages for build
env:
CI_BUILD_STAGE_NAME: build
run: ./ci/ci-install.bash
- name: Build Verilator
- name: Build
run: |
./ci/ci-script.bash
tar cvzf verilator-${CI_COMMIT}-coverage.tgz bin src/obj*/*.o src/obj*/*.gcno
- uses: actions/upload-artifact@v2
@ -74,17 +75,19 @@ jobs:
- 9
include:
- { test: dist, num: '' }
name: test-${{ matrix.test }}${{ matrix.num }}
runs-on: ubuntu-20.04
name: test-${{ matrix.test }}${{ matrix.num }}
env:
CI_BUILD_STAGE_NAME: test
CI_RUNS_ON: ${{ matrix.os }}
CACHE_KEY: ${{ matrix.os }}-${{ matrix.compiler.cc }}-coverage
CI_RUNS_ON: ubuntu-20.04
CACHE_KEY: ubuntu-20.04-${{ matrix.compiler.cc }}-coverage
steps:
- uses: actions/checkout@v2
- name: Checkout
uses: actions/checkout@v2
- uses: actions/cache@v2
- name: Cache
uses: actions/cache@v2
env:
cache-name: ccache
with:

2
.gitignore vendored
View File

@ -36,4 +36,6 @@ verilator_coverage_bin*
verilator.pc
verilator-config.cmake
verilator-config-version.cmake
**/__pycache__/*
**/_build/*
**/obj_dir/*

5755
Changes
View File

File diff suppressed because it is too large Load Diff

4
MANIFEST.SKIP
View File

@ -19,6 +19,7 @@
.*\.1
\.codacy\.yml
\.travis\.yml
/_build/
/build/
/obj_dbg/
/obj_dir/
@ -38,9 +39,10 @@ README.html
bin/verilator_bin.*
bin/verilator_coverage_bin.*
docs/.*\.html$
docs/Makefile$
docs/_build/
docs/clang-format.txt$
docs/doxygen-doc/.*
docs/spelling.txt
examples/xml_py/copied/
examples/xml_py/graph.*
sonar-project.properties

64
Makefile.in
View File

@ -51,10 +51,12 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_DATA = @INSTALL_DATA@
MAKEINFO = makeinfo
POD2TEXT = pod2text
POD2LATEXFIX = $(srcdir)/src/pod2latexfix
MKINSTALLDIRS = $(SHELL) $(srcdir)/src/mkinstalldirs
PERL = @PERL@
# Version (for docs/guide/conf.py)
PACKAGE_VERSION_NUMBER = @PACKAGE_VERSION_NUMBER@
# Destination prefix for RPMs
DESTDIR =
@ -111,14 +113,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 \
@ -136,13 +138,18 @@ DISTFILES_INC = $(INFOS) .gitignore \
docs/.gitignore \
docs/CONTRIBUTING.rst \
docs/CONTRIBUTORS \
docs/Makefile.in \
docs/TODO \
docs/doxygen-mainpage \
docs/doxygen.config \
docs/Makefile \
docs/_static/*.png \
docs/_static/css/* \
docs/bin/* \
docs/gen/* \
docs/guide/*.py \
docs/guide/*.rst \
docs/guide/figures/* \
docs/install.rst \
docs/internals.rst \
docs/verilator_logo.png \
docs/internals.rst \
docs/verilated.dox \
docs/xml.rst \
install-sh configure *.pod \
include/*.[chv]* \
@ -160,6 +167,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 \
@ -198,8 +207,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 \
@ -263,20 +270,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 \
@ -477,6 +478,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 \
@ -508,8 +513,8 @@ PYLINT = pylint
PYLINT_FLAGS = --disable=R0801
lint-py:
$(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
$(PYLINT) $(PYLINT_FLAGS) $(PY_PROGRAMS)
-$(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
-$(PYLINT) $(PYLINT_FLAGS) $(PY_PROGRAMS)
format-pl-exec:
-chmod a+x test_regress/t/*.pl
@ -567,6 +572,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)
@ -591,7 +597,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
######################################################################
@ -610,7 +617,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;}; \

27
README.rst
View File

@ -23,15 +23,15 @@ Welcome to Verilator
* Compiles into multithreaded C++, or SystemC
* Creates XML to front-end your own tools
- |Logo|
* - |verilator multithreaded performance bg min|
* - |verilator multithreaded performance|
- **Fast**
* Outperforms many commercial simulators
* Single- and multi-threaded output models
* - **Widely Used**
* Wide industry and academic deployment
* Out-of-the-box support from Arm, and RISC-V vendor IP
- |verilator usage 400x200 min|
* - |verilator community 400x125 min|
- |verilator usage|
* - |verilator community|
- **Community Driven & Openly Licensed**
* Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
* Open, and free as in both speech and beer
@ -40,7 +40,7 @@ Welcome to Verilator
* Commercial support contracts
* Design support contracts
* Enhancement contracts
- |verilator support 400x125 min|
- |verilator support|
What Verilator Does
@ -85,15 +85,6 @@ Modelsim, Cadence Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic
CVer/CVC). But, Verilator is open-sourced, so you can spend on computes
rather than licenses. Thus Verilator gives you the best cycles/dollar.
For more information on how Verilator stacks up to some of the other
closed-sourced and open-sourced Verilog simulators, see the `Verilog
Simulator Benchmarks
<https://www.veripool.org/verilog_sim_benchmarks.html>`_. (If you
benchmark Verilator, please see the notes in the `Verilator manual (PDF)
<https://verilator.org/verilator_doc.pdf>`_, and also if possible post on
the forums the results; there may be additional tweaks possible.)
Installation & Documentation
============================
@ -123,7 +114,7 @@ We appreciate and welcome your contributions in whatever form; please see
`Contributing to Verilator
<https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst>`_.
Thanks to our `Contributors and Sponsors
<https://verilator.org/verilator_doc.html#CONTRIBUTORS>`_.
<https://verilator.org/guide/latest/contributors.html>`_.
Verilator also supports and encourages commercial support models and
organizations; please see `Verilator Commercial Support
@ -154,7 +145,7 @@ Perl Artistic License Version 2.0. See the documentation for more details.
.. _Icarus Verilog: http://iverilog.icarus.com
.. _Linux Foundation: https://www.linuxfoundation.org
.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png
.. |verilator multithreaded performance bg min| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png
.. |verilator usage 400x200 min| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png
.. |verilator community 400x125 min| image:: https://www.veripool.org/img/verilator_community_400x125-min.png
.. |verilator support 400x125 min| image:: https://www.veripool.org/img/verilator_support_400x125-min.png
.. |verilator multithreaded performance| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png
.. |verilator usage| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png
.. |verilator community| image:: https://www.veripool.org/img/verilator_community_400x125-min.png
.. |verilator support| image:: https://www.veripool.org/img/verilator_support_400x125-min.png

5340
bin/verilator
View File

File diff suppressed because it is too large Load Diff

139
bin/verilator_coverage
View File

@ -160,122 +160,28 @@ 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/guide/latest/exe_verilator_coverage.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 +194,15 @@ 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/guide/latest/exe_verilator_coverage.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
######################################################################

92
bin/verilator_gantt
View File

@ -535,83 +535,20 @@ 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/guide/latest/exe_verilator_gantt.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 +561,13 @@ 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/guide/latest/exe_verilator_gantt.html> for
detailed documentation.
=cut
######################################################################

19
bin/verilator_profcfunc
View File

@ -214,15 +214,13 @@ 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/guide/latest/exe_verilator_profcfuncs.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 +233,13 @@ 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/guide/latest/exe_verilator_profcfuncs.html> for
detailed documentation.
=cut
######################################################################

4
ci/ci-script.bash
View File

@ -166,9 +166,9 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
fatal "Unknown test: $TESTS"
;;
esac
# Upload coverage data to codecov.io
# Upload coverage data
if [[ $TESTS == coverage-* ]]; then
bash <(curl -s https://codecov.io/bash) -f nodist/obj_dir/coverage/app_total.info
bash <(cat ci/coverage-upload.sh) -f nodist/obj_dir/coverage/app_total.info
fi
else
##############################################################################

1884
ci/coverage-upload.sh Executable file
View File

File diff suppressed because it is too large Load Diff

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

5
configure.ac
View File

@ -7,7 +7,7 @@
#AC_INIT([Verilator],[#.### YYYY-MM-DD])
#AC_INIT([Verilator],[#.### devel])
AC_INIT([Verilator],[4.200 2021-03-12],
AC_INIT([Verilator],[4.202 2021-04-24],
[https://verilator.org],
[verilator],[https://verilator.org])
# When releasing, also update header of Changes file
@ -15,12 +15,13 @@ AC_INIT([Verilator],[4.200 2021-03-12],
# Then 'make maintainer-dist'
AC_CONFIG_HEADER(src/config_build.h)
AC_CONFIG_FILES(Makefile docs/Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake)
AC_CONFIG_FILES(Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake)
# Version
AC_MSG_RESULT([configuring for $PACKAGE_STRING])
PACKAGE_VERSION_NUMBER=`AS_ECHO("$PACKAGE_VERSION") | sed 's/ .*//g'`
AC_SUBST(PACKAGE_VERSION_NUMBER)
AC_DEFINE_UNQUOTED([PACKAGE_VERSION_NUMBER_STRING],["$PACKAGE_VERSION_NUMBER"],[Package version as a number])
# Ignore automake flags passed by Ubuntu builds
AC_ARG_ENABLE([dependency-tracking],

2
docs/.gitignore vendored
View File

@ -1,4 +1,4 @@
*.1
*.html
*.pdf
Makefile
_build

11
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,11 +82,11 @@ 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
the `Contributor Covenant version 1.4
<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>`__.
<https://www.contributor-covenant.org/version/1/4/code-of-conduct/>`__.
Thanks!

11
docs/CONTRIBUTORS
View File

@ -11,8 +11,10 @@ Chris Randall
Conor McCullough
Dan Petrisko
David Horton
David Metz
David Stanford
David Turner
Drew Taussig
Driss Hafdi
Edgar E. Iglesias
Eric Rippey
@ -21,14 +23,16 @@ Garrett Smith
Geza Lore
Gianfranco Costamagna
Glen Gibb
Graham Rushton
Harald Heckmann
Howard Su
Huang Rui
HyungKi Jeong
Iztok Jeras
James Hanlon
James Hutchinson
Jamey Hicks
James Pallister
Jamey Hicks
Jan Van Winkel
Jean Berniolles
Jeremy Bennett
@ -80,14 +84,13 @@ Tobias Wölfel
Todd Strader
Tomasz Gorochowik
Tymoteusz Blazejczyk
Udi Finkelstein
Unai Martinez-Corral
Victor Besyakov
Vassilis Papaefstathiou
Veripool API Bot
Victor Besyakov
Wilson Snyder
Yossi Nivin
Yuri Victorovich
Yutetsu TAKATSUKASA
Yves Mathieu
HyungKi Jeong
Drew Taussig

58
docs/Makefile.in → 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 = guide
BUILDDIR = _build
#### End of system configuration section. ####
######################################################################
.SUFFIXES:
@ -30,9 +31,46 @@ 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
server: html
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 linkcheck spelling::
$(MAKE) vl-extract
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
$(PYTHON3) bin/vl_sphinx_fix _build
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 +80,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

111
docs/TODO
View File

@ -1,111 +0,0 @@
// DESCRIPTION: Verilator: List of To Do issues.
//
// Copyright 2004-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
* Language support:
** Fix ordering of each bit separately in a signal (mips)
assign b[3:0] = b[7:4]; assign b[7:4] = in;
** Support UDP gate primitives/ cell libraries
(have code for combos - problem is sequential udps)
** Function to eval combo logic after /*verilator public*/ functions [gwaters]
** Support generated clocks (correctness)
** Recursive functions
** Verilog configuration files
** Expression coverage (see notes)
** Better tristate support
** UVM
* Long-term Features
** Assertions
** Tristate support
* Testing:
** Code to make wrapper that sets signals, so can do comparison checks
** New random program generator
** Better graph viewer with search and zoom
* Usability:
** Detect and pre-remove most UNOPTFLATs
** Better reporting of unopt problems, including what lines of code
** Report more errors (all of them?) before exiting [Eugene Weber]
** Auto-create scons config files
** Print version/etc message at runtime. (4.000?)
Include number of lines of code, percent comments, code complexity measurement
<-80chars------------------------------------------------------------------->
Verilator 3.600 - The fast free open-sourced simulator. Copyright 2001-2013.
Verilated #### modules, #### instances, ##### sigs,
#### non-comment lines, ##### ops, ### KB model size
* Lint:
** CDCRSTLOGIC should allow filtering with paths
"waive CDCRSTLOGIC --from a.b.sig --to a.c.sig --via OR"
* Internal Code:
** A Visitor class that understands how to traverse data types
** V3Graph should be templated container type, taking in Vertex + Edge types
** Instead of string, have an VEncodedString/VIdString which contains __DOT__ish
things, to reduce bugs. Also add _20 trailing space to \ encoded names.
* Runtime:
** New evalulation loop ~/src/verilator/notes/event_loop.txt (4.000?)
** Remove all private internal functions from top level wrapper header, move
to new level
** Completely standalone simulation
main() records arguments for $test$plusvars
instantiates top,
does tracing (support $dump?)
calls top->simulateForever()
exits
* Performance:
** Latch optimizations
** Constant propagation
Extra cleaning AND: 1 & ((VARREF >> 1) | ((&VARREF >> 1) & VARREF))
Extra shift (perhaps due to clean): if (1 & CAST (VARREF >> #))
** Gated clock and latch conversion to flops. [JeanPaul Vanitegem]
Could propagate the AND into pos/negedges and let domaining optimize.
** Negedge reset
Switch to remove negedges that don't matter
Can't remove async resets from control flops (like in syncronizers)
** If all references to array have a constant index, blow up into separate signals-per-index
** Bit-multiply for faster bit swapping and a=b[1,3,2] random bit reorderings.
** Move _last sets and all other combo logic inside master
if() that triggers on all possible sense items
** Rewrite and combine V3Life, V3Subst
If block temp only ever set in one place to constant, propagate it
Used in t_mem for array delayed assignments
Replace variables if set later in same cfunc branch
See for example duplicate sets of _narrow in cycle 90/91 of t_select_plusloop
** Same assignment on both if branches
"if (a) { ... b=2; } else { ... b=2;}" -> "b=2; if ..."
Careful though, as b could appear in the statement or multiple times in statement
(Could just require exatly two 'b's in statement)
** Simplify XOR/AND/OR bit selection trees
Foo = A[1] ^ A[2] ^ A[3] etc are better as ^ ( A & 32'b...1110 )
** Combine variables into wider elements
Parallel statements on different bits should become single signal
Variables that are always consumed in "parallel" can be joined
** Duplicate assignments in gate optimization
Common to have many separate posedge blocks, each with identical
reset_r <= rst_in
** If signal is used only once (not counting trace), always gate substitute
Don't merge if any combining would form circ logic (out goes back to in)
** Multiple assignments each bit can become single assign with concat
Make sure a SEL of a CONCAT can get the single bit back.
** Better ordering of a<=b, b<=c, put all refs to 'b' next to each other to optimize caching
** I-cache packing improvements (what/how?)
** Data cache organization (order of vars in class)
First have clocks,
then bools instead of uint32_t's
then based on what sense list they come from, all outputs, then all inputs
finally have any signals part of a "usually" block, or constant.
** Rather then tracking widths, have a MSB...LSB of this expression
(or better, a bitmask of bits relevant in this expression)
** Track recirculation and convert into clock-enables
** Clock enables should become new clocking domains for speed
** If floped(a) & flopped(b) and no other a&b, then instead flop(a&b).
** Sort by output bitselects so can combine more assignments (see DDP example dx_dm signal)

16
docs/_static/css/vlt_sphinx.css vendored Normal file
View File

@ -0,0 +1,16 @@
/*Verilator blue #008fd7; set in html*/
.wy-side-nav-search > div.version {
color: #111;
}
.fa-github::before, .icon-github::before {
content: "";
}
.fa-home::before, .icon-home::before {
content: "";
}
.fa-arrow-circle-right::before, .icon-circle-arrow-right::before {
content: "";
}
.fa-arrow-circle-left::before, .icon-circle-arrow-left::before {
content: "";
}

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

0
docs/verilator_logo.png → docs/_static/verilator_logo.png vendored
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.9 KiB

After

Width:  |  Height:  |  Size: 9.9 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:

6
docs/doxygen-mainpage
View File

@ -1,6 +0,0 @@
/*! \mainpage Verilator Doxygen Documentation
*
* \section intro_sec Introduction
*
* This is a full doxygen analysis of the Verilator source tree.
*/

1765
docs/doxygen.config
View File

File diff suppressed because it is too large Load Diff

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

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

@ -0,0 +1,229 @@
# 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 = "../../Makefile"
with open(filename) as fh:
for line in fh:
match = re.search(r"PACKAGE_VERSION_NUMBER *= *([a-z0-9.]+)", line)
if match:
return match.group(1)
return "unknown"
def setup(app):
app.add_css_file('css/vlt_sphinx.css')
# ----------------------------------------------------------------------
# -- 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 = "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', 'gen/ex_*',
'CONTRIBUTING.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/guide/',
}
# 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_copy_source = False
html_show_sourcelink = 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.

16
docs/guide/example_common_install.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
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.

1622
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

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

@ -0,0 +1,490 @@
.. 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.)

BIN
docs/guide/figures/fig_gantt_min.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

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

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

@ -0,0 +1,41 @@
.. Copyright 2003-2021 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
######################
Verilator User's Guide
######################
.. 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:: figures/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).

1628
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

63
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,13 +701,13 @@ that type (if it is of class ``SOMETYPE``, or a derived class of
as that is faster.)
.. _Testing
.. _Testing:
Testing
=======
For an overview of how to write a test see the BUGS section of the
Verilator primary manual.
`Verilator Manual <https://verilator.org/verilator_doc.html>`_.
It is important to add tests for failures as well as success (for
example to check that an error message is correctly triggered).
@ -872,7 +873,7 @@ There are scripts included to facilitate fuzzing of Verilator. These
have been successfully used to find a number of bugs in the frontend.
The scripts are based on using `American fuzzy
lop <http://lcamtuf.coredump.cx/afl/>`__ on a Debian-like system.
lop <https://lcamtuf.coredump.cx/afl/>`__ on a Debian-like system.
To get started, cd to "nodist/fuzzer/" and run "./all". A sudo password may
be required to setup the system for fuzzing.
@ -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

41
docs/verilated.dox Normal file
View File

@ -0,0 +1,41 @@
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=" \

5
docs/xml.rst
View File

@ -1,8 +1,8 @@
|Logo|
===========================
***************************
Verilator XML Output Format
===========================
***************************
Introduction
============
@ -69,7 +69,6 @@ The XML document consists of 4 sections within the top level
by elements in the ``<module>`` elements using the ``dtype_id``
attribute.
.. __distribution:
Distribution
============

6
examples/make_protect_lib/Makefile
View File

@ -36,6 +36,12 @@ VERILATOR_FLAGS += -cc
VERILATOR_FLAGS += -Os -x-assign 0
# Warn abount lint issues; may not want this on less solid designs
VERILATOR_FLAGS += -Wall
# This example does not use vl_time_stamp but rather
# VerilatedContext::timeInc(), so to avoid a linker error on cygwin which
# does not support weak symbols, we need to define VL_TIME_CONTEXT *in CPP*
# to not compile in the vl_time_stamp using code.
VERILATOR_FLAGS += -CFLAGS -DVL_TIME_CONTEXT
# Make waveforms
TOP_VERILATOR_FLAGS = $(VERILATOR_FLAGS) --trace

1
examples/make_tracing_c/Makefile
View File

@ -31,7 +31,6 @@ VERILATOR = $(VERILATOR_ROOT)/bin/verilator
VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
endif
VERILATOR_FLAGS =
# Generate C++ in executable form
VERILATOR_FLAGS += -cc --exe
# Generate makefile dependencies (not shown as complicates the Makefile)

14
examples/make_tracing_c/Makefile_obj
View File

@ -22,10 +22,13 @@ COMPILE.cc = $(OBJCACHE) $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
#######################################################################
# Compile flags
# Override some default compile flags
# Turn on creating .d make dependency files
CPPFLAGS += -MMD -MP
# Compile in Verilator runtime debugging, so +verilator+debug works
CPPFLAGS += -DVL_DEBUG=1
# Turn on some more flags (when configured appropriately)
# Turn on some more compiler lint flags (when configured appropriately)
# For testing inside Verilator, "configure --enable-ccwarn" will do this
# automatically; otherwise you may want this unconditionally enabled
ifeq ($(CFG_WITH_CCWARN),yes) # Local... Else don't burden users
@ -36,17 +39,12 @@ endif
# Support class optimizations. This includes the tracing and symbol table.
# SystemC takes minutes to optimize, thus it is off by default.
OPT_SLOW =
# Fast path optimizations. Most time is spent in these classes.
OPT_FAST = -Os -fstrict-aliasing
#OPT_FAST = -O
#OPT_FAST =
#######################################################################
# Linking final exe -- presumes have a sim_main.cpp
# Special compile rule
sim_main.o: sim_main.cpp $(VM_PREFIX).h
######################################################################
######################################################################
# Automatically understand dependencies

3
examples/make_tracing_c/sim_main.cpp
View File

@ -14,6 +14,9 @@
// Include model header, generated from Verilating "top.v"
#include "Vtop.h"
// Legacy function required only so linking works on Cygwin and MSVC++
double sc_time_stamp() { return 0; }
int main(int argc, char** argv, char** env) {
// This is a more complicated example, please also see the simpler examples/make_hello_c.

180
include/verilated.cpp
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// 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
@ -10,15 +12,15 @@
//=========================================================================
///
/// \file
/// \brief Verilator: Linked against all applications using Verilated source.
/// \brief Verilated general routine implementation code
///
/// This file must be compiled and linked against all objects
/// created from Verilator.
/// This file must be compiled and linked against all Verilated objects
/// (all code created from Verilator).
///
/// Those macro/function/variable starting or ending in _ are internal,
/// however many of the other function/macros here are also internal.
/// Verilator always adds this file to the Makefile for the linker.
///
/// Code available from: https://verilator.org
/// Those macro/function/variable starting or ending in _ are internal,
/// however many of the other function/macros here are also internal.
///
//=========================================================================
// Internal note:
@ -65,7 +67,7 @@
#endif
// clang-format on
/// Max static char array for VL_VALUE_STRING
// Max characters in static char string for VL_VALUE_STRING
constexpr unsigned VL_VALUE_STRING_MAX_WIDTH = 8192;
//===========================================================================
@ -93,7 +95,7 @@ VL_THREAD_LOCAL Verilated::ThreadLocal Verilated::t_s;
// Note a TODO is a future version of the API will pass a structure so that
// the calling arguments allow for extension
#ifndef VL_USER_FINISH ///< Define this to override this function
#ifndef VL_USER_FINISH ///< Define this to override the vl_finish function
void vl_finish(const char* filename, int linenum, const char* hier) VL_MT_UNSAFE {
if (false && hier) {}
VL_PRINTF( // Not VL_PRINTF_MT, already on main thread
@ -103,13 +105,13 @@ void vl_finish(const char* filename, int linenum, const char* hier) VL_MT_UNSAFE
"- %s:%d: Second verilog $finish, exiting\n", filename, linenum);
Verilated::runFlushCallbacks();
Verilated::runExitCallbacks();
exit(0);
std::exit(0);
}
Verilated::threadContextp()->gotFinish(true);
}
#endif
#ifndef VL_USER_STOP ///< Define this to override this function
#ifndef VL_USER_STOP ///< Define this to override the vl_stop function
void vl_stop(const char* filename, int linenum, const char* hier) VL_MT_UNSAFE {
const char* const msg = "Verilog $stop";
Verilated::threadContextp()->gotError(true);
@ -128,7 +130,7 @@ void vl_stop(const char* filename, int linenum, const char* hier) VL_MT_UNSAFE {
}
#endif
#ifndef VL_USER_FATAL ///< Define this to override this function
#ifndef VL_USER_FATAL ///< Define this to override the vl_fatal function
void vl_fatal(const char* filename, int linenum, const char* hier, const char* msg) VL_MT_UNSAFE {
if (false && hier) {}
Verilated::threadContextp()->gotError(true);
@ -148,11 +150,11 @@ void vl_fatal(const char* filename, int linenum, const char* hier, const char* m
// Callbacks prior to termination
Verilated::runExitCallbacks();
abort();
std::abort();
}
#endif
#ifndef VL_USER_STOP_MAYBE ///< Define this to override this function
#ifndef VL_USER_STOP_MAYBE ///< Define this to override the vl_stop_maybe function
void vl_stop_maybe(const char* filename, int linenum, const char* hier, bool maybe) VL_MT_UNSAFE {
Verilated::threadContextp()->errorCountInc();
if (maybe
@ -202,7 +204,7 @@ void VL_FATAL_MT(const char* filename, int linenum, const char* hier, const char
//===========================================================================
// Debug prints
/// sprintf but return as string (this isn't fast, for print messages only)
// sprintf but return as string (this isn't fast, for print messages only)
std::string _vl_string_vprintf(const char* formatp, va_list ap) VL_MT_SAFE {
va_list aq;
va_copy(aq, ap);
@ -277,7 +279,7 @@ static vluint32_t vl_sys_rand32() VL_MT_UNSAFE {
const VerilatedLockGuard lock(s_mutex); // Otherwise rand is unsafe
#if defined(_WIN32) && !defined(__CYGWIN__)
// Windows doesn't have lrand48(), although Cygwin does.
return (rand() << 16) ^ rand();
return (std::rand() << 16) ^ std::rand();
#else
return (lrand48() << 16) ^ lrand48();
#endif
@ -579,10 +581,10 @@ double VL_ITOR_D_W(int lbits, WDataInP lwp) VL_PURE {
EData ihi = lwp[ms_word];
EData imid = lwp[ms_word - 1];
EData ilo = lwp[ms_word - 2];
double hi = static_cast<double>(ihi) * exp2(2 * VL_EDATASIZE);
double mid = static_cast<double>(imid) * exp2(VL_EDATASIZE);
double hi = static_cast<double>(ihi) * std::exp2(2 * VL_EDATASIZE);
double mid = static_cast<double>(imid) * std::exp2(VL_EDATASIZE);
double lo = static_cast<double>(ilo);
double d = (hi + mid + lo) * exp2(VL_EDATASIZE * (ms_word - 2));
double d = (hi + mid + lo) * std::exp2(VL_EDATASIZE * (ms_word - 2));
return d;
}
double VL_ISTOR_D_W(int lbits, WDataInP lwp) VL_PURE {
@ -596,7 +598,7 @@ double VL_ISTOR_D_W(int lbits, WDataInP lwp) VL_PURE {
//===========================================================================
// Formatting
/// Output a string representation of a wide number
// Output a string representation of a wide number
std::string VL_DECIMAL_NW(int width, WDataInP lwp) VL_MT_SAFE {
int maxdecwidth = (width + 3) * 4 / 3;
// Or (maxdecwidth+7)/8], but can't have more than 4 BCD bits per word
@ -913,14 +915,14 @@ void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SA
static inline bool _vl_vsss_eof(FILE* fp, int floc) VL_MT_SAFE {
if (fp) {
return feof(fp) ? true : false; // true : false to prevent MSVC++ warning
return std::feof(fp) ? true : false; // true : false to prevent MSVC++ warning
} else {
return floc < 0;
}
}
static inline void _vl_vsss_advance(FILE* fp, int& floc) VL_MT_SAFE {
if (fp) {
fgetc(fp);
std::fgetc(fp);
} else {
floc -= 8;
}
@ -929,7 +931,7 @@ static inline int _vl_vsss_peek(FILE* fp, int& floc, WDataInP fromp,
const std::string& fstr) VL_MT_SAFE {
// Get a character without advancing
if (fp) {
int data = fgetc(fp);
int data = std::fgetc(fp);
if (data == EOF) return EOF;
ungetc(data, fp);
return data;
@ -947,7 +949,7 @@ static inline void _vl_vsss_skipspace(FILE* fp, int& floc, WDataInP fromp,
const std::string& fstr) VL_MT_SAFE {
while (true) {
int c = _vl_vsss_peek(fp, floc, fromp, fstr);
if (c == EOF || !isspace(c)) return;
if (c == EOF || !std::isspace(c)) return;
_vl_vsss_advance(fp, floc);
}
}
@ -957,9 +959,9 @@ static inline void _vl_vsss_read_str(FILE* fp, int& floc, WDataInP fromp, const
char* cp = tmpp;
while (true) {
int c = _vl_vsss_peek(fp, floc, fromp, fstr);
if (c == EOF || isspace(c)) break;
if (acceptp && nullptr == strchr(acceptp, c)) break; // String - allow anything
if (acceptp) c = tolower(c); // Non-strings we'll simplify
if (c == EOF || std::isspace(c)) break;
if (acceptp && nullptr == std::strchr(acceptp, c)) break; // String - allow anything
if (acceptp) c = std::tolower(c); // Non-strings we'll simplify
*cp++ = c;
_vl_vsss_advance(fp, floc);
}
@ -1035,8 +1037,8 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
if (!inPct && pos[0] == '%') {
inPct = true;
inIgnore = false;
} else if (!inPct && isspace(pos[0])) { // Format spaces
while (isspace(pos[1])) pos++;
} else if (!inPct && std::isspace(pos[0])) { // Format spaces
while (std::isspace(pos[1])) pos++;
_vl_vsss_skipspace(fp, floc, fromp, fstr);
} else if (!inPct) { // Expected Format
_vl_vsss_skipspace(fp, floc, fromp, fstr);
@ -1090,7 +1092,7 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
_vl_vsss_read_str(fp, floc, fromp, fstr, t_tmp, nullptr);
if (!t_tmp[0]) goto done;
if (owp) {
int lpos = (static_cast<int>(strlen(t_tmp))) - 1;
int lpos = (static_cast<int>(std::strlen(t_tmp))) - 1;
int lsb = 0;
for (int i = 0; i < obits && lpos >= 0; --lpos) {
_vl_vsss_setbit(owp, obits, lsb, 8, t_tmp[lpos]);
@ -1104,7 +1106,7 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
_vl_vsss_read_str(fp, floc, fromp, fstr, t_tmp, "0123456789+-xXzZ?_");
if (!t_tmp[0]) goto done;
vlsint64_t ld = 0;
sscanf(t_tmp, "%30" VL_PRI64 "d", &ld);
std::sscanf(t_tmp, "%30" VL_PRI64 "d", &ld);
VL_SET_WQ(owp, ld);
break;
}
@ -1119,7 +1121,7 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
double r;
vlsint64_t ld;
} u;
u.r = strtod(t_tmp, nullptr);
u.r = std::strtod(t_tmp, nullptr);
VL_SET_WQ(owp, u.ld);
break;
}
@ -1129,7 +1131,7 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
_vl_vsss_read_str(fp, floc, fromp, fstr, t_tmp, "0123456789+-xXzZ?_");
if (!t_tmp[0]) goto done;
QData ld = 0;
sscanf(t_tmp, "%30" VL_PRI64 "u", &ld);
std::sscanf(t_tmp, "%30" VL_PRI64 "u", &ld);
VL_SET_WQ(owp, ld);
break;
}
@ -1137,14 +1139,14 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
_vl_vsss_skipspace(fp, floc, fromp, fstr);
_vl_vsss_read_str(fp, floc, fromp, fstr, t_tmp, "01xXzZ?_");
if (!t_tmp[0]) goto done;
_vl_vsss_based(owp, obits, 1, t_tmp, 0, strlen(t_tmp));
_vl_vsss_based(owp, obits, 1, t_tmp, 0, std::strlen(t_tmp));
break;
}
case 'o': {
_vl_vsss_skipspace(fp, floc, fromp, fstr);
_vl_vsss_read_str(fp, floc, fromp, fstr, t_tmp, "01234567xXzZ?_");
if (!t_tmp[0]) goto done;
_vl_vsss_based(owp, obits, 3, t_tmp, 0, strlen(t_tmp));
_vl_vsss_based(owp, obits, 3, t_tmp, 0, std::strlen(t_tmp));
break;
}
case 'x': {
@ -1152,7 +1154,7 @@ IData _vl_vsscanf(FILE* fp, // If a fscanf
_vl_vsss_read_str(fp, floc, fromp, fstr, t_tmp,
"0123456789abcdefABCDEFxXzZ?_");
if (!t_tmp[0]) goto done;
_vl_vsss_based(owp, obits, 4, t_tmp, 0, strlen(t_tmp));
_vl_vsss_based(owp, obits, 4, t_tmp, 0, std::strlen(t_tmp));
break;
}
case 'u': {
@ -1240,7 +1242,7 @@ void _vl_vint_to_string(int obits, char* destoutp, WDataInP sourcep) VL_MT_SAFE
}
*destp = '\0'; // Terminate
if (!start) { // Drop trailing spaces
while (isspace(*(destp - 1)) && destp > destoutp) *--destp = '\0';
while (std::isspace(*(destp - 1)) && destp > destoutp) *--destp = '\0';
}
}
@ -1295,7 +1297,7 @@ IData VL_FGETS_NI(std::string& dest, IData fpi) VL_MT_SAFE {
IData VL_FERROR_IN(IData, std::string& outputr) VL_MT_SAFE {
// We ignore lhs/fpi - IEEE says "most recent error" so probably good enough
IData ret = errno;
outputr = std::string(::strerror(ret));
outputr = std::string(::std::strerror(ret));
return ret;
}
@ -1477,7 +1479,7 @@ IData VL_FREAD_I(int width, int array_lsb, int array_size, void* memp, IData fpi
// We process a character at a time, as then we don't need to deal
// with changing buffer sizes dynamically, etc.
while (true) {
int c = fgetc(fp);
int c = std::fgetc(fp);
if (VL_UNLIKELY(c == EOF)) break;
// Shift value in
IData entry = read_elements + start - array_lsb;
@ -1522,7 +1524,7 @@ IData VL_SYSTEM_IQ(QData lhs) VL_MT_SAFE {
IData VL_SYSTEM_IW(int lhswords, WDataInP lhsp) VL_MT_SAFE {
char filenamez[VL_TO_STRING_MAX_WORDS * VL_EDATASIZE + 1];
_vl_vint_to_string(lhswords * VL_EDATASIZE, filenamez, lhsp);
int code = system(filenamez); // Yes, system() is threadsafe
int code = std::system(filenamez); // Yes, std::system() is threadsafe
return code >> 8; // Want exit status
}
@ -1542,7 +1544,7 @@ IData VL_VALUEPLUSARGS_INW(int rbits, const std::string& ld, WDataOutP rwp) VL_M
} else if (!inPct) { // Normal text
prefix += *posp;
} else { // Format character
switch (tolower(*posp)) {
switch (std::tolower(*posp)) {
case '%':
prefix += *posp;
inPct = false;
@ -1560,20 +1562,20 @@ IData VL_VALUEPLUSARGS_INW(int rbits, const std::string& ld, WDataOutP rwp) VL_M
if (match.empty()) return 0;
VL_ZERO_RESET_W(rbits, rwp);
switch (tolower(fmt)) {
switch (std::tolower(fmt)) {
case 'd': {
vlsint64_t lld = 0;
sscanf(dp, "%30" VL_PRI64 "d", &lld);
std::sscanf(dp, "%30" VL_PRI64 "d", &lld);
VL_SET_WQ(rwp, lld);
break;
}
case 'b': _vl_vsss_based(rwp, rbits, 1, dp, 0, strlen(dp)); break;
case 'o': _vl_vsss_based(rwp, rbits, 3, dp, 0, strlen(dp)); break;
case 'b': _vl_vsss_based(rwp, rbits, 1, dp, 0, std::strlen(dp)); break;
case 'o': _vl_vsss_based(rwp, rbits, 3, dp, 0, std::strlen(dp)); break;
case 'h': // FALLTHRU
case 'x': _vl_vsss_based(rwp, rbits, 4, dp, 0, strlen(dp)); break;
case 'x': _vl_vsss_based(rwp, rbits, 4, dp, 0, std::strlen(dp)); break;
case 's': { // string/no conversion
for (int i = 0, lsb = 0, posp = static_cast<int>(strlen(dp)) - 1; i < rbits && posp >= 0;
--posp) {
for (int i = 0, lsb = 0, posp = static_cast<int>(std::strlen(dp)) - 1;
i < rbits && posp >= 0; --posp) {
_vl_vsss_setbit(rwp, rbits, lsb, 8, dp[posp]);
lsb += 8;
}
@ -1581,19 +1583,19 @@ IData VL_VALUEPLUSARGS_INW(int rbits, const std::string& ld, WDataOutP rwp) VL_M
}
case 'e': {
double temp = 0.F;
sscanf(dp, "%le", &temp);
std::sscanf(dp, "%le", &temp);
VL_SET_WQ(rwp, VL_CVT_Q_D(temp));
break;
}
case 'f': {
double temp = 0.F;
sscanf(dp, "%lf", &temp);
std::sscanf(dp, "%lf", &temp);
VL_SET_WQ(rwp, VL_CVT_Q_D(temp));
break;
}
case 'g': {
double temp = 0.F;
sscanf(dp, "%lg", &temp);
std::sscanf(dp, "%lg", &temp);
VL_SET_WQ(rwp, VL_CVT_Q_D(temp));
break;
}
@ -1613,7 +1615,7 @@ IData VL_VALUEPLUSARGS_INN(int, const std::string& ld, std::string& rdr) VL_MT_S
} else if (!inPct) { // Normal text
prefix += *posp;
} else { // Format character
switch (tolower(*posp)) {
switch (std::tolower(*posp)) {
case '%':
prefix += *posp;
inPct = false;
@ -1636,7 +1638,7 @@ const char* vl_mc_scan_plusargs(const char* prefixp) VL_MT_SAFE {
static VL_THREAD_LOCAL char t_outstr[VL_VALUE_STRING_MAX_WIDTH];
if (match.empty()) return nullptr;
char* dp = t_outstr;
for (const char* sp = match.c_str() + strlen(prefixp) + 1; // +1 to skip the "+"
for (const char* sp = match.c_str() + std::strlen(prefixp) + 1; // +1 to skip the "+"
*sp && (dp - t_outstr) < (VL_VALUE_STRING_MAX_WIDTH - 2);)
*dp++ = *sp++;
*dp++ = '\0';
@ -1656,12 +1658,12 @@ std::string VL_TO_STRING_W(int words, WDataInP obj) {
std::string VL_TOLOWER_NN(const std::string& ld) VL_MT_SAFE {
std::string out = ld;
for (auto& cr : out) cr = tolower(cr);
for (auto& cr : out) cr = std::tolower(cr);
return out;
}
std::string VL_TOUPPER_NN(const std::string& ld) VL_MT_SAFE {
std::string out = ld;
for (auto& cr : out) cr = toupper(cr);
for (auto& cr : out) cr = std::toupper(cr);
return out;
}
@ -1761,7 +1763,7 @@ VlReadMem::VlReadMem(bool hex, int bits, const std::string& filename, QData star
, m_end{end}
, m_addr{start}
, m_linenum{0} {
m_fp = fopen(filename.c_str(), "r");
m_fp = std::fopen(filename.c_str(), "r");
if (VL_UNLIKELY(!m_fp)) {
// We don't report the Verilog source filename as it slow to have to pass it down
VL_FATAL_MT(filename.c_str(), 0, "", "$readmem file not found");
@ -1771,7 +1773,7 @@ VlReadMem::VlReadMem(bool hex, int bits, const std::string& filename, QData star
}
VlReadMem::~VlReadMem() {
if (m_fp) {
fclose(m_fp);
std::fclose(m_fp);
m_fp = nullptr;
}
}
@ -1788,13 +1790,13 @@ bool VlReadMem::get(QData& addrr, std::string& valuer) {
// We process a character at a time, as then we don't need to deal
// with changing buffer sizes dynamically, etc.
while (true) {
int c = fgetc(m_fp);
int c = std::fgetc(m_fp);
if (VL_UNLIKELY(c == EOF)) break;
// printf("%d: Got '%c' Addr%lx IN%d IgE%d IgC%d\n",
// m_linenum, c, m_addr, indata, ignore_to_eol, ignore_to_cmt);
// See if previous data value has completed, and if so return
if (c == '_') continue; // Ignore _ e.g. inside a number
if (indata && !isxdigit(c) && c != 'x' && c != 'X') {
if (indata && !std::isxdigit(c) && c != 'x' && c != 'X') {
// printf("Got data @%lx = %s\n", m_addr, valuer.c_str());
ungetc(c, m_fp);
addrr = m_addr;
@ -1826,8 +1828,8 @@ bool VlReadMem::get(QData& addrr, std::string& valuer) {
m_addr = 0;
}
// Check for hex or binary digits as file format requests
else if (isxdigit(c) || (!reading_addr && (c == 'x' || c == 'X'))) {
c = tolower(c);
else if (std::isxdigit(c) || (!reading_addr && (c == 'x' || c == 'X'))) {
c = std::tolower(c);
int value
= (c >= 'a' ? (c == 'x' ? VL_RAND_RESET_I(4) : (c - 'a' + 10)) : (c - '0'));
if (reading_addr) {
@ -1861,7 +1863,7 @@ void VlReadMem::setData(void* valuep, const std::string& rhs) {
bool innum = false;
// Shift value in
for (const auto& i : rhs) {
char c = tolower(i);
char c = std::tolower(i);
int value = (c >= 'a' ? (c == 'x' ? VL_RAND_RESET_I(4) : (c - 'a' + 10)) : (c - '0'));
if (m_bits <= 8) {
CData* datap = reinterpret_cast<CData*>(valuep);
@ -1899,7 +1901,7 @@ VlWriteMem::VlWriteMem(bool hex, int bits, const std::string& filename, QData st
return;
}
m_fp = fopen(filename.c_str(), "w");
m_fp = std::fopen(filename.c_str(), "w");
if (VL_UNLIKELY(!m_fp)) {
VL_FATAL_MT(filename.c_str(), 0, "", "$writemem file not found");
// cppcheck-suppress resourceLeak // m_fp is nullptr - bug in cppcheck
@ -1908,7 +1910,7 @@ VlWriteMem::VlWriteMem(bool hex, int bits, const std::string& filename, QData st
}
VlWriteMem::~VlWriteMem() {
if (m_fp) {
fclose(m_fp);
std::fclose(m_fp);
m_fp = nullptr;
}
}
@ -2202,11 +2204,15 @@ void VerilatedContext::dumpfile(const std::string& flag) VL_MT_SAFE_EXCLUDES(m_t
}
std::string VerilatedContext::dumpfile() const VL_MT_SAFE_EXCLUDES(m_timeDumpMutex) {
const VerilatedLockGuard lock(m_timeDumpMutex);
if (VL_UNLIKELY(m_dumpfile.empty())) {
return m_dumpfile;
}
std::string VerilatedContext::dumpfileCheck() const VL_MT_SAFE_EXCLUDES(m_timeDumpMutex) {
const std::string out = dumpfile();
if (VL_UNLIKELY(out.empty())) {
VL_PRINTF_MT("%%Warning: $dumpvar ignored as not proceeded by $dumpfile\n");
return "";
}
return m_dumpfile;
return out;
}
void VerilatedContext::errorCount(int val) VL_MT_SAFE {
const VerilatedLockGuard lock(m_mutex);
@ -2349,7 +2355,7 @@ std::string VerilatedContextImp::argPlusMatch(const char* prefixp)
VL_MT_SAFE_EXCLUDES(m_argMutex) {
const VerilatedLockGuard lock(m_argMutex);
// Note prefixp does not include the leading "+"
size_t len = strlen(prefixp);
size_t len = std::strlen(prefixp);
if (VL_UNLIKELY(!m_args.m_argVecLoaded)) {
m_args.m_argVecLoaded = true; // Complain only once
VL_FATAL_MT("unknown", 0, "",
@ -2358,7 +2364,7 @@ std::string VerilatedContextImp::argPlusMatch(const char* prefixp)
}
for (const auto& i : m_args.m_argVec) {
if (i[0] == '+') {
if (0 == strncmp(prefixp, i.c_str() + 1, len)) return i;
if (0 == std::strncmp(prefixp, i.c_str() + 1, len)) return i;
}
}
return "";
@ -2377,7 +2383,7 @@ std::pair<int, char**> VerilatedContextImp::argc_argv() VL_MT_SAFE_EXCLUDES(m_ar
int in = 0;
for (const auto& i : m_args.m_argVec) {
s_argvp[in] = new char[i.length() + 1];
strcpy(s_argvp[in], i.c_str());
std::strcpy(s_argvp[in], i.c_str());
++in;
}
s_argvp[s_argc] = nullptr;
@ -2386,31 +2392,31 @@ std::pair<int, char**> VerilatedContextImp::argc_argv() VL_MT_SAFE_EXCLUDES(m_ar
}
void VerilatedContextImp::commandArgVl(const std::string& arg) {
if (0 == strncmp(arg.c_str(), "+verilator+", strlen("+verilator+"))) {
if (0 == std::strncmp(arg.c_str(), "+verilator+", std::strlen("+verilator+"))) {
std::string value;
if (arg == "+verilator+debug") {
Verilated::debug(4);
} else if (commandArgVlValue(arg, "+verilator+debugi+", value /*ref*/)) {
Verilated::debug(atoi(value.c_str()));
Verilated::debug(std::atoi(value.c_str()));
} else if (commandArgVlValue(arg, "+verilator+error+limit+", value /*ref*/)) {
errorLimit(atoi(value.c_str()));
errorLimit(std::atoi(value.c_str()));
} else if (arg == "+verilator+help") {
VerilatedImp::versionDump();
VL_PRINTF_MT("For help, please see 'verilator --help'\n");
VL_FATAL_MT("COMMAND_LINE", 0, "",
"Exiting due to command line argument (not an error)");
} else if (arg == "+verilator+noassert") {
assertOn(false);
} else if (commandArgVlValue(arg, "+verilator+prof+threads+start+", value /*ref*/)) {
profThreadsStart(atoll(value.c_str()));
profThreadsStart(std::atoll(value.c_str()));
} else if (commandArgVlValue(arg, "+verilator+prof+threads+window+", value /*ref*/)) {
profThreadsWindow(atol(value.c_str()));
profThreadsWindow(std::atol(value.c_str()));
} else if (commandArgVlValue(arg, "+verilator+prof+threads+file+", value /*ref*/)) {
profThreadsFilename(value);
} else if (commandArgVlValue(arg, "+verilator+rand+reset+", value /*ref*/)) {
randReset(atoi(value.c_str()));
randReset(std::atoi(value.c_str()));
} else if (commandArgVlValue(arg, "+verilator+seed+", value /*ref*/)) {
randSeed(atoi(value.c_str()));
} else if (arg == "+verilator+noassert") {
assertOn(false);
randSeed(std::atoi(value.c_str()));
} else if (arg == "+verilator+V") {
VerilatedImp::versionDump(); // Someday more info too
VL_FATAL_MT("COMMAND_LINE", 0, "",
@ -2427,7 +2433,7 @@ void VerilatedContextImp::commandArgVl(const std::string& arg) {
bool VerilatedContextImp::commandArgVlValue(const std::string& arg, const std::string& prefix,
std::string& valuer) {
size_t len = prefix.length();
if (0 == strncmp(prefix.c_str(), arg.c_str(), len)) {
if (0 == std::strncmp(prefix.c_str(), arg.c_str(), len)) {
valuer = arg.substr(len);
return true;
} else {
@ -2532,12 +2538,14 @@ void Verilated::debug(int level) VL_MT_SAFE {
}
}
const char* Verilated::catName(const char* n1, const char* n2, const char* delimiter) VL_MT_SAFE {
const char* Verilated::catName(const char* n1, const char* n2, int scopet,
const char* delimiter) VL_MT_SAFE {
// Returns new'ed data
// Used by symbol table creation to make module names
static VL_THREAD_LOCAL char* t_strp = nullptr;
static VL_THREAD_LOCAL size_t t_len = 0;
size_t newlen = strlen(n1) + strlen(n2) + strlen(delimiter) + 1;
size_t newlen
= std::strlen(n1) + std::strlen(n2) + std::strlen(delimiter) + (scopet > 0 ? 2 : 1);
if (VL_UNLIKELY(!t_strp || newlen > t_len)) {
if (t_strp) delete[] t_strp;
t_strp = new char[newlen];
@ -2545,6 +2553,8 @@ const char* Verilated::catName(const char* n1, const char* n2, const char* delim
}
char* dp = t_strp;
for (const char* sp = n1; *sp;) *dp++ = *sp++;
// Add scope type
if (scopet) *dp++ = (char)(0x80 + scopet);
for (const char* sp = delimiter; *sp;) *dp++ = *sp++;
for (const char* sp = n2; *sp;) *dp++ = *sp++;
*dp++ = '\0';
@ -2556,7 +2566,7 @@ const char* Verilated::catName(const char* n1, const char* n2, const char* delim
// Keeping these out of class Verilated to avoid having to include <list>
// in verilated.h (for compilation speed)
typedef std::list<std::pair<Verilated::VoidPCb, void*>> VoidPCbList;
using VoidPCbList = std::list<std::pair<Verilated::VoidPCb, void*>>;
static struct {
VerilatedMutex s_flushMutex;
VoidPCbList s_flushCbs VL_GUARDED_BY(s_flushMutex);
@ -2597,8 +2607,8 @@ void Verilated::runFlushCallbacks() VL_MT_SAFE {
runCallbacks(VlCbStatic.s_flushCbs);
}
--s_recursing;
fflush(stderr);
fflush(stdout);
std::fflush(stderr);
std::fflush(stdout);
// When running internal code coverage (gcc --coverage, as opposed to
// verilator --coverage), dump coverage data to properly cover failing
// tests.
@ -2754,7 +2764,7 @@ void VerilatedScope::configure(VerilatedSyms* symsp, const char* prefixp, const
m_type = type;
m_timeunit = timeunit;
{
char* namep = new char[strlen(prefixp) + strlen(suffixp) + 2];
char* namep = new char[std::strlen(prefixp) + std::strlen(suffixp) + 2];
char* dp = namep;
for (const char* sp = prefixp; *sp;) *dp++ = *sp++;
if (*prefixp && *suffixp) *dp++ = '.';
@ -2781,7 +2791,7 @@ void VerilatedScope::exportInsert(int finalize, const char* namep, void* cb) VL_
}
if (VL_UNLIKELY(!m_callbacksp)) { // First allocation
m_callbacksp = new void*[m_funcnumMax];
memset(m_callbacksp, 0, m_funcnumMax * sizeof(void*));
std::memset(m_callbacksp, 0, m_funcnumMax * sizeof(void*));
}
m_callbacksp[funcnum] = cb;
}

194
include/verilated.h
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// 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
@ -10,21 +12,23 @@
//*************************************************************************
///
/// \file
/// \brief Verilator: Common include for all Verilated C files
/// \brief Verilated common header, include for all Verilated C files
///
/// This file is included automatically by Verilator at the top of
/// all C++ files it generates. It contains standard macros and
/// classes required by the Verilated code.
/// This file is included automatically by Verilator at the top of all C++
/// files it generates. It contains standard macros and classes required
/// by the Verilated code.
///
/// Those macro/function/variable starting or ending in _ are internal,
/// however many of the other function/macros here are also internal.
/// User wrapper code may need to include this to get appropriate
/// structures, however they would generally just include the
/// Verilated-model's header instead (which then includes this).
///
/// Code available from: https://verilator.org
/// Those macro/function/variable starting or ending in _ are internal,
/// however many of the other function/macros here are also internal.
///
//*************************************************************************
#ifndef VERILATOR_VERILATED_H_
#define VERILATOR_VERILATED_H_ ///< Header Guard
#define VERILATOR_VERILATED_H_
// clang-format off
#include "verilatedos.h"
@ -71,37 +75,38 @@
#endif
// clang-format on
//=========================================================================
// Basic types
// clang-format off
// P // Packed data of bit type (C/S/I/Q/W)
typedef vluint8_t CData; ///< Verilated pack data, 1-8 bits
typedef vluint16_t SData; ///< Verilated pack data, 9-16 bits
typedef vluint32_t IData; ///< Verilated pack data, 17-32 bits
typedef vluint64_t QData; ///< Verilated pack data, 33-64 bits
typedef vluint32_t EData; ///< Verilated pack element of WData array
typedef EData WData; ///< Verilated pack data, >64 bits, as an array
// float F // No typedef needed; Verilator uses float
// double D // No typedef needed; Verilator uses double
// string N // No typedef needed; Verilator uses string
// clang-format on
typedef const WData* WDataInP; ///< Array input to a function
typedef WData* WDataOutP; ///< Array output from a function
class VerilatedContextImp;
class VerilatedContextImpData;
class VerilatedCovContext;
class VerilatedEvalMsgQueue;
class VerilatedFst;
class VerilatedFstC;
class VerilatedScope;
class VerilatedScopeNameMap;
class VerilatedVar;
class VerilatedVarNameMap;
class VerilatedVcd;
class VerilatedVcdC;
class VerilatedVcdSc;
class VerilatedFst;
class VerilatedFstC;
//=========================================================================
// Basic types
// clang-format off
// P // Packed data of bit type (C/S/I/Q/W)
using CData = vluint8_t; ///< Data representing 'bit' of 1-8 packed bits
using SData = vluint16_t; ///< Data representing 'bit' of 9-16 packed bits
using IData = vluint32_t; ///< Data representing 'bit' of 17-32 packed bits
using QData = vluint64_t; ///< Data representing 'bit' of 33-64 packed bits
using EData = vluint32_t; ///< Data representing one element of WData array
using WData = EData; ///< Data representing >64 packed bits (used as pointer)
// F = float; // No typedef needed; Verilator uses float
// D = double; // No typedef needed; Verilator uses double
// N = std::string; // No typedef needed; Verilator uses string
// clang-format on
using WDataInP = const WData*; ///< 'bit' of >64 packed bits as array input to a function
using WDataOutP = WData*; ///< 'bit' of >64 packed bits as array output from a function
enum VerilatedVarType : vluint8_t {
VLVT_UNKNOWN = 0,
@ -130,7 +135,7 @@ enum VerilatedVarFlags {
//=========================================================================
// Mutex and threading support
/// Return current thread ID (or 0), not super fast, cache if needed
// Return current thread ID (or 0), not super fast, cache if needed
extern vluint32_t VL_THREAD_ID() VL_MT_SAFE;
#if VL_THREADED
@ -214,7 +219,7 @@ public:
class VerilatedAssertOneThread final {
// MEMBERS
#if defined(VL_THREADED) && defined(VL_DEBUG)
vluint32_t m_threadid; /// Thread that is legal
vluint32_t m_threadid; // Thread that is legal
public:
// CONSTRUCTORS
// The constructor establishes the thread id for all later calls.
@ -241,17 +246,15 @@ public:
};
//=========================================================================
/// Base class for all Verilated module classes
class VerilatedScope;
/// Base class for all Verilated module classes.
class VerilatedModule VL_NOT_FINAL {
VL_UNCOPYABLE(VerilatedModule);
private:
const char* m_namep; ///< Module name
const char* m_namep; // Module name
public:
explicit VerilatedModule(const char* namep); ///< Create module with given hierarchy name
explicit VerilatedModule(const char* namep); // Create module with given hierarchy name
~VerilatedModule();
const char* name() const { return m_namep; } ///< Return name of module
};
@ -282,7 +285,7 @@ public:
#define VL_CELL(instname, type) ///< Declare a cell, ala SP_CELL
/// Declare a module, ala SC_MODULE
///< Declare a module, ala SC_MODULE
#define VL_MODULE(modname) class modname VL_NOT_FINAL : public VerilatedModule
// Not class final in VL_MODULE, as users might be abstracting our models (--hierarchical)
@ -466,6 +469,8 @@ public:
int randSeed() const VL_MT_SAFE { return m_s.m_randSeed; }
// Time handling
/// Returns current simulation time.
///
/// How Verilator runtime gets the current simulation time:
///
/// * If using SystemC, time comes from the SystemC kernel-defined
@ -529,6 +534,7 @@ public: // But for internal use only
// Internal: $dumpfile
void dumpfile(const std::string& flag) VL_MT_SAFE_EXCLUDES(m_timeDumpMutex);
std::string dumpfile() const VL_MT_SAFE_EXCLUDES(m_timeDumpMutex);
std::string dumpfileCheck() const VL_MT_SAFE_EXCLUDES(m_timeDumpMutex);
// Internal: --prof-threads related settings
void profThreadsStart(vluint64_t flag) VL_MT_SAFE;
@ -548,8 +554,8 @@ public: // But for internal use only
};
//===========================================================================
/// Verilator symbol table base class
/// Used for internal VPI implementation, and introspection into scopes
// Verilator symbol table base class
// Used for internal VPI implementation, and introspection into scopes
class VerilatedSyms VL_NOT_FINAL {
public: // But for internal use only
@ -564,26 +570,26 @@ public: // But for internal use only
};
//===========================================================================
/// Verilator scope information class
/// Used for internal VPI implementation, and introspection into scopes
// Verilator scope information class
// Used for internal VPI implementation, and introspection into scopes
class VerilatedScope final {
public:
typedef enum : vluint8_t {
enum Type : vluint8_t {
SCOPE_MODULE,
SCOPE_OTHER
} Type; // Type of a scope, currently module is only interesting
}; // Type of a scope, currently module is only interesting
private:
// Fastpath:
VerilatedSyms* m_symsp = nullptr; ///< Symbol table
void** m_callbacksp = nullptr; ///< Callback table pointer (Fastpath)
int m_funcnumMax = 0; ///< Maxium function number stored (Fastpath)
VerilatedSyms* m_symsp = nullptr; // Symbol table
void** m_callbacksp = nullptr; // Callback table pointer (Fastpath)
int m_funcnumMax = 0; // Maxium function number stored (Fastpath)
// 4 bytes padding (on -m64), for rent.
VerilatedVarNameMap* m_varsp = nullptr; ///< Variable map
const char* m_namep = nullptr; ///< Scope name (Slowpath)
const char* m_identifierp = nullptr; ///< Identifier of scope (with escapes removed)
vlsint8_t m_timeunit = 0; ///< Timeunit in negative power-of-10
Type m_type = SCOPE_OTHER; ///< Type of the scope
VerilatedVarNameMap* m_varsp = nullptr; // Variable map
const char* m_namep = nullptr; // Scope name (Slowpath)
const char* m_identifierp = nullptr; // Identifier of scope (with escapes removed)
vlsint8_t m_timeunit = 0; // Timeunit in negative power-of-10
Type m_type = SCOPE_OTHER; // Type of the scope
public: // But internals only - called from VerilatedModule's
VerilatedScope() = default;
@ -634,9 +640,9 @@ class Verilated final {
// Internal note: Globals may multi-construct, see verilated.cpp top.
// Debug is reloaded from on command-line settings, so do not need to persist
static int s_debug; ///< See accessors... only when VL_DEBUG set
static int s_debug; // See accessors... only when VL_DEBUG set
static VerilatedContext* s_lastContextp; ///< Last context constructed/attached
static VerilatedContext* s_lastContextp; // Last context constructed/attached
// Not covered by mutex, as per-thread
static VL_THREAD_LOCAL struct ThreadLocal {
@ -650,9 +656,9 @@ class Verilated final {
// Messages maybe pending on thread, needs end-of-eval calls
vluint32_t t_endOfEvalReqd = 0;
#endif
const VerilatedScope* t_dpiScopep = nullptr; ///< DPI context scope
const char* t_dpiFilename = nullptr; ///< DPI context filename
int t_dpiLineno = 0; ///< DPI context line number
const VerilatedScope* t_dpiScopep = nullptr; // DPI context scope
const char* t_dpiFilename = nullptr; // DPI context filename
int t_dpiLineno = 0; // DPI context line number
ThreadLocal() = default;
~ThreadLocal() = default;
@ -710,11 +716,13 @@ public:
#ifndef VL_NO_LEGACY
/// Call VerilatedContext::assertOn using current thread's VerilatedContext
static void assertOn(bool flag) VL_MT_SAFE { Verilated::threadContextp()->assertOn(flag); }
/// Return VerilatedContext::assertOn() using current thread's VerilatedContext
static bool assertOn() VL_MT_SAFE { return Verilated::threadContextp()->assertOn(); }
/// Call VerilatedContext::calcUnusedSigs using current thread's VerilatedContext
static void calcUnusedSigs(bool flag) VL_MT_SAFE {
Verilated::threadContextp()->calcUnusedSigs(flag);
}
/// Return VerilatedContext::calcUnusedSigs using current thread's VerilatedContext
static bool calcUnusedSigs() VL_MT_SAFE {
return Verilated::threadContextp()->calcUnusedSigs();
}
@ -725,43 +733,55 @@ public:
static void commandArgs(int argc, char** argv) VL_MT_SAFE {
commandArgs(argc, const_cast<const char**>(argv));
}
/// Call VerilatedContext::commandArgsAdd using current thread's VerilatedContext
static void commandArgsAdd(int argc, const char** argv) {
Verilated::threadContextp()->commandArgsAdd(argc, argv);
}
/// Return VerilatedContext::commandArgsPlusMatch using current thread's VerilatedContext
static const char* commandArgsPlusMatch(const char* prefixp) VL_MT_SAFE {
return Verilated::threadContextp()->commandArgsPlusMatch(prefixp);
}
/// Call VerilatedContext::errorLimit using current thread's VerilatedContext
static void errorLimit(int val) VL_MT_SAFE { Verilated::threadContextp()->errorLimit(val); }
/// Return VerilatedContext::errorLimit using current thread's VerilatedContext
static int errorLimit() VL_MT_SAFE { return Verilated::threadContextp()->errorLimit(); }
/// Call VerilatedContext::fatalOnError using current thread's VerilatedContext
static void fatalOnError(bool flag) VL_MT_SAFE {
Verilated::threadContextp()->fatalOnError(flag);
}
/// Return VerilatedContext::fatalOnError using current thread's VerilatedContext
static bool fatalOnError() VL_MT_SAFE { return Verilated::threadContextp()->fatalOnError(); }
/// Call VerilatedContext::fatalOnVpiError using current thread's VerilatedContext
static void fatalOnVpiError(bool flag) VL_MT_SAFE {
Verilated::threadContextp()->fatalOnVpiError(flag);
}
/// Return VerilatedContext::fatalOnVpiError using current thread's VerilatedContext
static bool fatalOnVpiError() VL_MT_SAFE {
return Verilated::threadContextp()->fatalOnVpiError();
}
/// Call VerilatedContext::gotError using current thread's VerilatedContext
static void gotError(bool flag) VL_MT_SAFE { Verilated::threadContextp()->gotError(flag); }
/// Return VerilatedContext::gotError using current thread's VerilatedContext
static bool gotError() VL_MT_SAFE { return Verilated::threadContextp()->gotError(); }
/// Call VerilatedContext::gotFinish using current thread's VerilatedContext
static void gotFinish(bool flag) VL_MT_SAFE { Verilated::threadContextp()->gotFinish(flag); }
/// Return VerilatedContext::gotFinish using current thread's VerilatedContext
static bool gotFinish() VL_MT_SAFE { return Verilated::threadContextp()->gotFinish(); }
/// Call VerilatedContext::randReset using current thread's VerilatedContext
static void randReset(int val) VL_MT_SAFE { Verilated::threadContextp()->randReset(val); }
/// Return VerilatedContext::randReset using current thread's VerilatedContext
static int randReset() VL_MT_SAFE { return Verilated::threadContextp()->randReset(); }
/// Call VerilatedContext::randSeed using current thread's VerilatedContext
static void randSeed(int val) VL_MT_SAFE { Verilated::threadContextp()->randSeed(val); }
/// Return VerilatedContext::randSeed using current thread's VerilatedContext
static int randSeed() VL_MT_SAFE { return Verilated::threadContextp()->randSeed(); }
/// Call VerilatedContext::time using current thread's VerilatedContext
static void time(vluint64_t val) VL_MT_SAFE { Verilated::threadContextp()->time(val); }
/// Return VerilatedContext::time using current thread's VerilatedContext
static vluint64_t time() VL_MT_SAFE { return Verilated::threadContextp()->time(); }
/// Call VerilatedContext::timeInc using current thread's VerilatedContext
static void timeInc(vluint64_t add) VL_MT_UNSAFE { Verilated::threadContextp()->timeInc(add); }
// Deprecated
static int timeunit() VL_MT_SAFE { return Verilated::threadContextp()->timeunit(); }
static int timeprecision() VL_MT_SAFE { return Verilated::threadContextp()->timeprecision(); }
/// Call VerilatedContext::tracesEverOn using current thread's VerilatedContext
@ -770,7 +790,8 @@ public:
}
#endif
typedef void (*VoidPCb)(void*); // Callback type for below
/// Callback typedef for addFlushCb, addExitCb
using VoidPCb = void (*)(void*);
/// Add callback to run on global flush
static void addFlushCb(VoidPCb cb, void* datap) VL_MT_SAFE;
/// Remove callback to run on global flush
@ -820,7 +841,7 @@ public:
public:
// METHODS - INTERNAL USE ONLY (but public due to what uses it)
// Internal: Create a new module name by concatenating two strings
static const char* catName(const char* n1, const char* n2,
static const char* catName(const char* n1, const char* n2, int scopet = 0,
const char* delimiter = "."); // Returns static data
// Internal: Throw signal assertion
@ -916,7 +937,7 @@ extern vluint64_t vl_rand64() VL_MT_SAFE;
inline IData VL_RANDOM_I(int obits) VL_MT_SAFE { return vl_rand64() & VL_MASK_I(obits); }
inline QData VL_RANDOM_Q(int obits) VL_MT_SAFE { return vl_rand64() & VL_MASK_Q(obits); }
#ifndef VL_NO_LEGACY
extern WDataOutP VL_RANDOM_W(int obits, WDataOutP outwp); ///< Randomize a signal
extern WDataOutP VL_RANDOM_W(int obits, WDataOutP outwp);
#endif
extern IData VL_RANDOM_SEEDED_II(int obits, IData seed) VL_MT_SAFE;
inline IData VL_URANDOM_RANGE_I(IData hi, IData lo) {
@ -929,10 +950,13 @@ inline IData VL_URANDOM_RANGE_I(IData hi, IData lo) {
}
}
/// Init time only, so slow is fine
extern IData VL_RAND_RESET_I(int obits); ///< Random reset a signal
extern QData VL_RAND_RESET_Q(int obits); ///< Random reset a signal
extern WDataOutP VL_RAND_RESET_W(int obits, WDataOutP outwp); ///< Random reset a signal
// These are init time only, so slow is fine
/// Random reset a signal of given width
extern IData VL_RAND_RESET_I(int obits);
/// Random reset a signal of given width
extern QData VL_RAND_RESET_Q(int obits);
/// Random reset a signal of given width
extern WDataOutP VL_RAND_RESET_W(int obits, WDataOutP outwp);
/// Zero reset a signal (slow - else use VL_ZERO_W)
extern WDataOutP VL_ZERO_RESET_W(int obits, WDataOutP outwp);
@ -948,11 +972,9 @@ inline QData VL_RDTSC_Q() {
extern void VL_PRINTTIMESCALE(const char* namep, const char* timeunitp,
const VerilatedContext* contextp) VL_MT_SAFE;
/// Math
extern WDataOutP _vl_moddiv_w(int lbits, WDataOutP owp, WDataInP lwp, WDataInP rwp,
bool is_modulus);
/// File I/O
extern IData VL_FGETS_IXI(int obits, void* destp, IData fpi);
extern void VL_FFLUSH_I(IData fdi);
@ -987,18 +1009,18 @@ extern const char* vl_mc_scan_plusargs(const char* prefixp); // PLIish
//=========================================================================
// Base macros
/// Return true if data[bit] set; not 0/1 return, but 0/non-zero return.
// Return true if data[bit] set; not 0/1 return, but 0/non-zero return.
#define VL_BITISSET_I(data, bit) ((data) & (VL_UL(1) << VL_BITBIT_I(bit)))
#define VL_BITISSET_Q(data, bit) ((data) & (1ULL << VL_BITBIT_Q(bit)))
#define VL_BITISSET_E(data, bit) ((data) & (VL_EUL(1) << VL_BITBIT_E(bit)))
#define VL_BITISSET_W(data, bit) ((data)[VL_BITWORD_E(bit)] & (VL_EUL(1) << VL_BITBIT_E(bit)))
#define VL_BITISSETLIMIT_W(data, width, bit) (((bit) < (width)) && VL_BITISSET_W(data, bit))
/// Shift appropriate word by bit. Does not account for wrapping between two words
// Shift appropriate word by bit. Does not account for wrapping between two words
#define VL_BITRSHIFT_W(data, bit) ((data)[VL_BITWORD_E(bit)] >> VL_BITBIT_E(bit))
/// Create two 32-bit words from quadword
/// WData is always at least 2 words; does not clean upper bits
// Create two 32-bit words from quadword
// WData is always at least 2 words; does not clean upper bits
#define VL_SET_WQ(owp, data) \
do { \
(owp)[0] = static_cast<IData>(data); \
@ -1014,31 +1036,31 @@ extern const char* vl_mc_scan_plusargs(const char* prefixp); // PLIish
| (static_cast<QData>((lwp)[1]) << (static_cast<QData>(VL_EDATASIZE))))
#define VL_SET_QII(ld, rd) ((static_cast<QData>(ld) << 32ULL) | static_cast<QData>(rd))
/// Return FILE* from IData
// Return FILE* from IData
extern FILE* VL_CVT_I_FP(IData lhs) VL_MT_SAFE;
// clang-format off
// Use a union to avoid cast-to-different-size warnings
/// Return void* from QData
// Return void* from QData
static inline void* VL_CVT_Q_VP(QData lhs) VL_PURE {
union { void* fp; QData q; } u;
u.q = lhs;
return u.fp;
}
/// Return QData from const void*
// Return QData from const void*
static inline QData VL_CVT_VP_Q(const void* fp) VL_PURE {
union { const void* fp; QData q; } u;
u.q = 0;
u.fp = fp;
return u.q;
}
/// Return double from QData (bits, not numerically)
// Return double from QData (bits, not numerically)
static inline double VL_CVT_D_Q(QData lhs) VL_PURE {
union { double d; QData q; } u;
u.q = lhs;
return u.d;
}
/// Return QData from double (bits, not numerically)
// Return QData from double (bits, not numerically)
static inline QData VL_CVT_Q_D(double lhs) VL_PURE {
union { double d; QData q; } u;
u.d = lhs;
@ -1046,7 +1068,7 @@ static inline QData VL_CVT_Q_D(double lhs) VL_PURE {
}
// clang-format on
/// Return double from lhs (numeric) unsigned
// Return double from lhs (numeric) unsigned
double VL_ITOR_D_W(int lbits, WDataInP lwp) VL_PURE;
static inline double VL_ITOR_D_I(int, IData lhs) VL_PURE {
return static_cast<double>(static_cast<vluint32_t>(lhs));
@ -1054,7 +1076,7 @@ static inline double VL_ITOR_D_I(int, IData lhs) VL_PURE {
static inline double VL_ITOR_D_Q(int, QData lhs) VL_PURE {
return static_cast<double>(static_cast<vluint64_t>(lhs));
}
/// Return double from lhs (numeric) signed
// Return double from lhs (numeric) signed
double VL_ISTOR_D_W(int lbits, WDataInP lwp) VL_PURE;
static inline double VL_ISTOR_D_I(int lbits, IData lhs) VL_PURE {
if (lbits == 32) return static_cast<double>(static_cast<vlsint32_t>(lhs));
@ -1068,7 +1090,7 @@ static inline double VL_ISTOR_D_Q(int lbits, QData lhs) VL_PURE {
VL_SET_WQ(lwp, lhs);
return VL_ISTOR_D_W(lbits, lwp);
}
/// Return QData from double (numeric)
// Return QData from double (numeric)
static inline IData VL_RTOI_I_D(double lhs) VL_PURE {
return static_cast<vlsint32_t>(VL_TRUNC(lhs));
}
@ -1117,8 +1139,8 @@ extern int VL_TIME_STR_CONVERT(const char* strp) VL_PURE;
# endif
#endif
/// Return current simulation time
#if defined(SYSTEMC_VERSION)
/// Return current simulation time
// Already defined: extern sc_time sc_time_stamp();
inline vluint64_t vl_time_stamp64() { return sc_time_stamp().value(); }
#else // Non-SystemC
@ -1157,24 +1179,24 @@ inline vluint64_t VerilatedContext::time() const VL_MT_SAFE {
#define VL_TIME_Q() (Verilated::threadContextp()->time())
#define VL_TIME_D() (static_cast<double>(VL_TIME_Q()))
/// Time scaled from 1-per-precision into a module's time units ("Unit"-ed, not "United")
// Time scaled from 1-per-precision into a module's time units ("Unit"-ed, not "United")
// Optimized assuming scale is always constant.
// Can't use multiply in Q flavor, as might lose precision
#define VL_TIME_UNITED_Q(scale) (VL_TIME_Q() / static_cast<QData>(scale))
#define VL_TIME_UNITED_D(scale) (VL_TIME_D() / static_cast<double>(scale))
/// Time imported from units to time precision
// Return time precision as multiplier of time units
double vl_time_multiplier(int scale) VL_PURE;
/// Evaluate expression if debug enabled
#ifdef VL_DEBUG
# define VL_DEBUG_IF(text) \
/// Evaluate statement if Verilated::debug() enabled
# define VL_DEBUG_IF(stmt) \
do { \
if (VL_UNLIKELY(Verilated::debug())) {text} \
if (VL_UNLIKELY(Verilated::debug())) {stmt} \
} while (false)
#else
// We intentionally do not compile the text to improve compile speed
# define VL_DEBUG_IF(text) do {} while (false)
// We intentionally do not compile the stmt to improve compile speed
# define VL_DEBUG_IF(stmt) do {} while (false)
#endif
// clang-format on
@ -2747,7 +2769,7 @@ static inline WDataOutP VL_SEL_WWII(int obits, int lbits, int, int, WDataOutP ow
//======================================================================
// Math needing insert/select
/// Return QData from double (numeric)
// Return QData from double (numeric)
// EMIT_RULE: VL_RTOIROUND_Q_D: oclean=dirty; lclean==clean/real
static inline QData VL_RTOIROUND_Q_D(int, double lhs) VL_PURE {
// IEEE format: [63]=sign [62:52]=exp+1023 [51:0]=mantissa

24
include/verilated.mk.in
View File

@ -201,26 +201,28 @@ else
VK_OBJS += $(VK_FAST_OBJS) $(VK_SLOW_OBJS)
endif
# When archiving just objects (.o), single $(AR) run is enough.
# When merging objects (.o) and archives (.a), the following steps are taken.
# When archiving just objects (.o), use single $(AR) run
# 1. Make .tmp file with list of objects so don't exceed commend line
# When merging objects (.o) and archives (.a) additionally:
# 1. Extract object files from .a
# 2. Create a new archive from extracted .o and given .o
%.a:
@echo "Archive $(AR) -cr $@ $^"
$(info Archive $(AR) -rcs $@ $^)
$(file >$@.tmp)
$(foreach L, $(filter-out %.a,$^), $(file >>$@.tmp, $L))
@if test $(words $(filter %.a,$^)) -eq 0; then \
$(AR) -cr $@ $^; \
$(RANLIB) $@; \
$(AR) -rcs $@ @$@.tmp; \
else \
$(RM) -rf $*__tmpdir; \
$(RM) -rf $@.tmpdir; \
for archive in $(filter %.a,$^); do \
mkdir -p $*__tmpdir/$$(basename $${archive}); \
cd $*__tmpdir/$$(basename $${archive}); \
mkdir -p $@.tmpdir/$$(basename $${archive}); \
cd $@.tmpdir/$$(basename $${archive}); \
$(AR) -x ../../$${archive}; \
cd ../..; \
done; \
$(AR) -cr $@ $(filter %.o,$^) $*__tmpdir/*/*.o; \
$(RM) -rf $*__tmpdir; \
fi
$(AR) -rcs $@ @$@.tmp $@.tmpdir/*/*.o; \
fi \
; $(RM) -rf $@.tmp $@.tmpdir
$(VM_PREFIX)__ALL.a: $(VK_OBJS) $(VM_HIER_LIBS)

2
include/verilated.v
View File

@ -2,8 +2,6 @@
//
// 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

12
include/verilated_config.h.in
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// 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
@ -10,14 +12,14 @@
//*************************************************************************
///
/// \file
/// \brief Verilator: Auto version information include for all Verilated C files
///
/// Code available from: https://verilator.org
/// \brief Verilator program version information header
///
//*************************************************************************
///**** Product and Version name
/// Verilator product name, e.g. "Verilator"
// Autoconf substitutes this with the strings from AC_INIT.
#define VERILATOR_PRODUCT "@PACKAGE_NAME@"
/// Verilator version name, e.g. "1.000 2000-01-01"
// Autoconf substitutes this with the strings from AC_INIT.
#define VERILATOR_VERSION "@PACKAGE_VERSION@"

91
include/verilated_cov.cpp
View File

@ -1,7 +1,7 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// THIS MODULE IS PUBLICLY LICENSED
// Code available from: https://verilator.org
//
// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
// can redistribute it and/or modify it under the terms of either the GNU
@ -12,7 +12,12 @@
//=============================================================================
///
/// \file
/// \brief Verilator coverage analysis
/// \brief Verilated coverage analysis implementation code
///
/// This file must be compiled and linked against all Verilated objects
/// that use coverage.
///
/// Use "verilator --coverage" to add this to the Makefile for the linker.
///
//=============================================================================
@ -31,19 +36,19 @@
struct VerilatedCovConst VL_NOT_FINAL {
// TYPES
enum { MAX_KEYS = 33 }; /// Maximum user arguments + filename+lineno
enum { KEY_UNDEF = 0 }; /// Magic key # for unspecified values
enum { MAX_KEYS = 33 }; // Maximum user arguments + filename+lineno
enum { KEY_UNDEF = 0 }; // Magic key # for unspecified values
};
//=============================================================================
// VerilatedCovImpItem
/// Implementation class for a VerilatedCov item
// Implementation class for a VerilatedCov item
class VerilatedCovImpItem VL_NOT_FINAL {
public: // But only local to this file
// MEMBERS
int m_keys[VerilatedCovConst::MAX_KEYS]; ///< Key
int m_vals[VerilatedCovConst::MAX_KEYS]; ///< Value for specified key
int m_keys[VerilatedCovConst::MAX_KEYS]; // Key
int m_vals[VerilatedCovConst::MAX_KEYS]; // Value for specified key
// CONSTRUCTORS
// Derived classes should call zero() in their constructor
VerilatedCovImpItem() {
@ -58,15 +63,15 @@ public: // But only local to this file
};
//=============================================================================
/// VerilatedCoverItem templated for a specific class
/// Creates a new coverage item for the specified type.
/// This isn't in the header file for auto-magic conversion because it
/// inlines to too much code and makes compilation too slow.
// VerilatedCoverItem templated for a specific class
// Creates a new coverage item for the specified type.
// This isn't in the header file for auto-magic conversion because it
// inlines to too much code and makes compilation too slow.
template <class T> class VerilatedCoverItemSpec final : public VerilatedCovImpItem {
private:
// MEMBERS
T* m_countp; ///< Count value
T* m_countp; // Count value
public:
// METHODS
// cppcheck-suppress truncLongCastReturn
@ -83,30 +88,31 @@ public:
//=============================================================================
// VerilatedCovImp
///
/// Implementation class for VerilatedCovContext. See that class for
/// public method information. All value and keys are indexed into a
/// unique number. Thus we can greatly reduce the storage requirements for
/// otherwise identical keys.
//
// Implementation class for VerilatedCovContext. See that class for
// public method information. All value and keys are indexed into a
// unique number. Thus we can greatly reduce the storage requirements for
// otherwise identical keys.
class VerilatedCovImp final : public VerilatedCovContext {
private:
// TYPES
typedef std::map<const std::string, int> ValueIndexMap;
typedef std::map<int, std::string> IndexValueMap;
typedef std::deque<VerilatedCovImpItem*> ItemList;
using ValueIndexMap = std::map<const std::string, int>;
using IndexValueMap = std::map<int, std::string>;
using ItemList = std::deque<VerilatedCovImpItem*>;
// MEMBERS
VerilatedMutex m_mutex; ///< Protects all members
ValueIndexMap m_valueIndexes VL_GUARDED_BY(m_mutex); ///< Unique arbitrary value for values
IndexValueMap m_indexValues VL_GUARDED_BY(m_mutex); ///< Unique arbitrary value for keys
ItemList m_items VL_GUARDED_BY(m_mutex); ///< List of all items
VerilatedMutex m_mutex; // Protects all members
ValueIndexMap m_valueIndexes VL_GUARDED_BY(m_mutex); // Unique arbitrary value for values
IndexValueMap m_indexValues VL_GUARDED_BY(m_mutex); // Unique arbitrary value for keys
ItemList m_items VL_GUARDED_BY(m_mutex); // List of all items
int m_nextIndex VL_GUARDED_BY(m_mutex)
= (VerilatedCovConst::KEY_UNDEF + 1); ///< Next insert value
= (VerilatedCovConst::KEY_UNDEF + 1); // Next insert value
VerilatedCovImpItem* m_insertp VL_GUARDED_BY(m_mutex) = nullptr; ///< Item about to insert
const char* m_insertFilenamep VL_GUARDED_BY(m_mutex) = nullptr; ///< Filename about to insert
int m_insertLineno VL_GUARDED_BY(m_mutex) = 0; ///< Line number about to insert
VerilatedCovImpItem* m_insertp VL_GUARDED_BY(m_mutex) = nullptr; // Item about to insert
const char* m_insertFilenamep VL_GUARDED_BY(m_mutex) = nullptr; // Filename about to insert
int m_insertLineno VL_GUARDED_BY(m_mutex) = 0; // Line number about to insert
bool m_forcePerInstance VL_GUARDED_BY(m_mutex) = false; // Force per_instance
public:
// CONSTRUCTORS
@ -136,7 +142,7 @@ private:
// Quote any special characters
std::string rtn;
for (const char* pos = text.c_str(); *pos; ++pos) {
if (!isprint(*pos) || *pos == '%' || *pos == '"') {
if (!std::isprint(*pos) || *pos == '%' || *pos == '"') {
char hex[10];
VL_SNPRINTF(hex, 10, "%%%02X", pos[0]);
rtn += hex;
@ -152,13 +158,13 @@ private:
// a letter differently, nor want them to rely on our compression...
// (Considered using numeric keys, but will remain back compatible.)
if (key.length() < 2) return false;
if (key.length() == 2 && isdigit(key[1])) return false;
if (key.length() == 2 && std::isdigit(key[1])) return false;
return true;
}
static std::string keyValueFormatter(const std::string& key,
const std::string& value) VL_PURE {
std::string name;
if (key.length() == 1 && isalpha(key[0])) {
if (key.length() == 1 && std::isalpha(key[0])) {
name += std::string("\001") + key;
} else {
name += std::string("\001") + dequote(key);
@ -190,8 +196,8 @@ private:
std::string prefix = std::string(a, apre - a);
// Scan backward to last mismatch
const char* apost = a + strlen(a) - 1;
const char* bpost = b + strlen(b) - 1;
const char* apost = a + std::strlen(a) - 1;
const char* bpost = b + std::strlen(b) - 1;
while (*apost == *bpost && apost > apre && bpost > bpre) {
apost--;
bpost--;
@ -245,6 +251,11 @@ private:
public:
// PUBLIC METHODS
void forcePerInstance(bool flag) VL_MT_SAFE_EXCLUDES(m_mutex) {
Verilated::quiesce();
const VerilatedLockGuard lock(m_mutex);
m_forcePerInstance = flag;
}
void clear() VL_MT_SAFE_EXCLUDES(m_mutex) {
Verilated::quiesce();
const VerilatedLockGuard lock(m_mutex);
@ -294,7 +305,7 @@ public:
valps[1] = linestr.c_str();
// Default page if not specified
const char* fnstartp = m_insertFilenamep;
while (const char* foundp = strchr(fnstartp, '/')) fnstartp = foundp + 1;
while (const char* foundp = std::strchr(fnstartp, '/')) fnstartp = foundp + 1;
const char* fnendp = fnstartp;
for (; *fnendp && *fnendp != '.'; fnendp++) {}
std::string page_default = "sp_user/" + std::string(fnstartp, fnendp - fnstartp);
@ -357,12 +368,12 @@ public:
os << "# SystemC::Coverage-3\n";
// Build list of events; totalize if collapsing hierarchy
typedef std::map<const std::string, std::pair<std::string, vluint64_t>> EventMap;
EventMap eventCounts;
std::map<const std::string, std::pair<std::string, vluint64_t>> eventCounts;
for (const auto& itemp : m_items) {
std::string name;
std::string hier;
bool per_instance = false;
if (m_forcePerInstance) per_instance = true;
for (int i = 0; i < VerilatedCovConst::MAX_KEYS; ++i) {
if (itemp->m_keys[i] != VerilatedCovConst::KEY_UNDEF) {
@ -396,7 +407,7 @@ public:
cit->second.second += itemp->count();
cit->second.first = combineHier(oldhier, hier);
} else {
eventCounts.emplace(name, make_pair(hier, itemp->count()));
eventCounts.emplace(name, std::make_pair(hier, itemp->count()));
}
}
@ -414,6 +425,9 @@ public:
//=============================================================================
// VerilatedCovContext
void VerilatedCovContext::forcePerInstance(bool flag) VL_MT_SAFE {
impp()->forcePerInstance(flag);
}
void VerilatedCovContext::clear() VL_MT_SAFE { impp()->clear(); }
void VerilatedCovContext::clearNonMatch(const char* matchp) VL_MT_SAFE {
impp()->clearNonMatch(matchp);
@ -430,6 +444,7 @@ void VerilatedCovContext::_insertf(const char* filename, int lineno) VL_MT_SAFE
impp()->insertf(filename, lineno);
}
#ifndef DOXYGEN
#define K(n) const char* key##n
#define A(n) const char *key##n, const char *valp##n // Argument list
#define C(n) key##n, valp##n // Calling argument list
@ -479,6 +494,8 @@ void VerilatedCovContext::_insertp(A(0), A(1), K(2), int val2, K(3), int val3, K
#undef N
#undef K
#endif // DOXYGEN
//=============================================================================
// VerilatedCov

61
include/verilated_cov.h
View File

@ -1,7 +1,7 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// THIS MODULE IS PUBLICLY LICENSED
// Code available from: https://verilator.org
//
// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
// can redistribute it and/or modify it under the terms of either the GNU
@ -12,7 +12,13 @@
//=============================================================================
///
/// \file
/// \brief Coverage analysis support
/// \brief Verilated coverage analysis support header
///
/// This must be included in user wrapper code that wants to save coverage
/// data.
///
/// It declares the VerilatedCovContext::write() which writes the collected
/// coverage information.
///
//=============================================================================
@ -29,7 +35,8 @@
class VerilatedCovImp;
//=============================================================================
/// Conditionally compile coverage code
/// Conditionally compile statements only when doing coverage (when
/// VM_COVERAGE is defined)
// clang-format off
#ifdef VM_COVERAGE
@ -50,7 +57,8 @@ class VerilatedCovImp;
/// The value may be a string, or another type which will be auto-converted to a string.
///
/// Some typical keys:
/// filename File the recording occurs in. Defaults to __FILE__
///
/// filename File the recording occurs in. Defaults to __FILE__.
/// lineno Line number the recording occurs in. Defaults to __LINE__
/// column Column number (or occurrence# for dup file/lines). Defaults to undef.
/// hier Hierarchical name. Defaults to name()
@ -60,14 +68,16 @@ class VerilatedCovImp;
/// Comments for type==block: 'if', 'else', 'elsif', 'case'
/// thresh Threshold to consider fully covered.
/// If unspecified, downstream tools will determine it.
/// per_instance If non-zero don't combine all hierarchies into one count
///
/// Examples:
/// Example:
///
/// vluint32_t m_cases[10];
/// constructor {
/// for (int i=0; i<10; ++i) { m_cases[i]=0; }
/// }
/// for (int i=0; i<10; ++i) {
/// vluint32_t m_cases[10]; // Storage for coverage data
/// constructor() {
/// // Initialize
/// for (int i = 0; i < 10; ++i) m_cases[i] = 0;
/// // Insert
/// for (int i = 0; i < 10; ++i)
/// VL_COVER_INSERT(&m_cases[i], "comment", "Coverage Case", "i", cvtToNumStr(i));
/// }
@ -76,7 +86,7 @@ class VerilatedCovImp;
covcontextp->_insertp("hier", name(), __VA_ARGS__))
//=============================================================================
/// Convert VL_COVER_INSERT value arguments to strings
// Convert VL_COVER_INSERT value arguments to strings, is \internal
template <class T> std::string vlCovCvtToStr(const T& t) VL_PURE {
std::ostringstream os;
@ -86,8 +96,11 @@ template <class T> std::string vlCovCvtToStr(const T& t) VL_PURE {
//=============================================================================
// VerilatedCov
/// Verilator coverage per-context structure
/// Per-VerilatedContext coverage data class.
/// All public methods in this class are thread safe.
///
/// This structure is accessed and constructed on first access via
/// VerilatedContext::coveragep()
class VerilatedCovContext VL_NOT_FINAL : public VerilatedVirtualBase {
VL_UNCOPYABLE(VerilatedCovContext);
@ -96,6 +109,8 @@ public:
// METHODS
/// Return default filename
static const char* defaultFilename() VL_PURE { return "coverage.dat"; }
/// Make all data per_instance, overriding point's per_instance
void forcePerInstance(bool flag) VL_MT_SAFE;
/// Write all coverage data to a file
void write(const char* filenamep = defaultFilename()) VL_MT_SAFE;
/// Clear coverage points (and call delete on all items)
@ -106,10 +121,10 @@ public:
void zero() VL_MT_SAFE;
public: // But Internal use only
/// Insert a coverage item
/// We accept from 1-30 key/value pairs, all as strings.
/// Call _insert1, followed by _insert2 and _insert3
/// Do not call directly; use VL_COVER_INSERT or higher level macros instead
// Insert a coverage item
// We accept from 1-30 key/value pairs, all as strings.
// Call _insert1, followed by _insert2 and _insert3
// Do not call directly; use VL_COVER_INSERT or higher level macros instead
// _insert1: Remember item pointer with count. (Not const, as may add zeroing function)
void _inserti(vluint32_t* itemp) VL_MT_SAFE;
void _inserti(vluint64_t* itemp) VL_MT_SAFE;
@ -119,6 +134,7 @@ public: // But Internal use only
// We could have just the maximum argument version, but this compiles
// much slower (nearly 2x) than having smaller versions also. However
// there's not much more gain in having a version for each number of args.
#ifndef DOXYGEN
#define K(n) const char* key##n
#define A(n) const char *key##n, const char *valp##n // Argument list
#define D(n) const char *key##n = nullptr, const char *valp##n = nullptr // Argument list
@ -135,6 +151,7 @@ public: // But Internal use only
#undef K
#undef A
#undef D
#endif // DOXYGEN
protected:
friend class VerilatedCovImp;
@ -150,11 +167,11 @@ protected:
//=============================================================================
// VerilatedCov
/// Verilator coverage global class
/// Coverage global class.
///
/// Global class that accesses via current thread's context. These are
/// provided for backward-compatibility, use VerilatedContext->coveragep()
/// instead.
/// Global class that accesses via current thread's context's
/// VerilatedCovContext. This class is provided only for
/// backward-compatibility, use VerilatedContext::coveragep() instead.
#ifndef VL_NO_LEGACY
class VerilatedCov final {
@ -178,9 +195,9 @@ public:
static void zero() VL_MT_SAFE { threadCovp()->zero(); }
private:
/// Current thread's coverage structure
// Current thread's coverage structure
static VerilatedCovContext* threadCovp() VL_MT_SAFE;
};
#endif
#endif // VL_NO_LEGACY
#endif // Guard

11
include/verilated_cov_key.h
View File

@ -1,7 +1,7 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// THIS MODULE IS PUBLICLY LICENSED
// Code available from: https://verilator.org
//
// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
// can redistribute it and/or modify it under the terms of either the GNU
@ -12,7 +12,10 @@
//=============================================================================
///
/// \file
/// \brief Coverage item keys
/// \brief Verilated coverage item keys internal header
///
/// This file is not part of the Verilated public-facing API.
/// It is only for internal use by the Verilated library coverage routines.
///
//=============================================================================
@ -57,11 +60,11 @@ VLCOVGEN_ITEM("'name':'weight', 'short':'w', 'group':0, 'default':None, 'd
//=============================================================================
// VerilatedCovKey
/// Verilator coverage global class.
/// This class is thread safe.
// Namespace-style static class for \internal use.
class VerilatedCovKey final {
public:
// Return the short key code for a given a long coverage key
static std::string shortKey(const std::string& key) VL_PURE {
// VLCOVGEN_SHORT_AUTO_EDIT_BEGIN
if (key == "column") return VL_CIK_COLUMN;

32
include/verilated_dpi.cpp
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// Code available from: https://verilator.org
//
// Copyright 2009-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
@ -10,12 +12,16 @@
//=========================================================================
///
/// \file
/// \brief Verilator: DPI implementation code
/// \brief Verilated DPI implementation code
///
/// This file must be compiled and linked against all objects
/// created from Verilator or called by Verilator that use the DPI.
/// This file must be compiled and linked against all Verilated objects
/// that use the DPI.
///
/// Code available from: https://verilator.org
/// Declare any DPI routine inside Verilog to add this to the Makefile for
/// the linker.
///
/// For documentation on the exported functions (named sv*) that are
/// implemented here, refer to the IEEE DPI chapter.
///
//=========================================================================
@ -197,13 +203,13 @@ int svIncrement(const svOpenArrayHandle h, int d) { return _vl_openhandle_varp(h
int svSize(const svOpenArrayHandle h, int d) { return _vl_openhandle_varp(h)->elements(d); }
int svDimensions(const svOpenArrayHandle h) { return _vl_openhandle_varp(h)->udims(); }
/// Return pointer to open array data, or nullptr if not in IEEE standard C layout
// Return pointer to open array data, or nullptr if not in IEEE standard C layout
void* svGetArrayPtr(const svOpenArrayHandle h) {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(h);
if (VL_UNLIKELY(!varp->isDpiStdLayout())) return nullptr;
return varp->datap();
}
/// Return size of open array, or 0 if not in IEEE standard C layout
// Return size of open array, or 0 if not in IEEE standard C layout
int svSizeOfArray(const svOpenArrayHandle h) {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(h);
if (VL_UNLIKELY(!varp->isDpiStdLayout())) return 0;
@ -253,7 +259,7 @@ static void* _vl_sv_adjusted_datap(const VerilatedDpiOpenVar* varp, int nargs, i
return datap;
}
/// Return pointer to simulator open array element, or nullptr if outside range
// Return pointer to simulator open array element, or nullptr if outside range
static void* _vl_svGetArrElemPtr(const svOpenArrayHandle h, int nargs, int indx1, int indx2,
int indx3) VL_MT_SAFE {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(h);
@ -262,7 +268,7 @@ static void* _vl_svGetArrElemPtr(const svOpenArrayHandle h, int nargs, int indx1
return datap;
}
/// Copy to user bit array from simulator open array
// Copy to user bit array from simulator open array
static void _vl_svGetBitArrElemVecVal(svBitVecVal* d, const svOpenArrayHandle s, int nargs,
int indx1, int indx2, int indx3) VL_MT_SAFE {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(s);
@ -290,7 +296,7 @@ static void _vl_svGetBitArrElemVecVal(svBitVecVal* d, const svOpenArrayHandle s,
return; // LCOV_EXCL_STOP
}
}
/// Copy to user logic array from simulator open array
// Copy to user logic array from simulator open array
static void _vl_svGetLogicArrElemVecVal(svLogicVecVal* d, const svOpenArrayHandle s, int nargs,
int indx1, int indx2, int indx3) VL_MT_SAFE {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(s);
@ -333,7 +339,7 @@ static void _vl_svGetLogicArrElemVecVal(svLogicVecVal* d, const svOpenArrayHandl
}
}
/// Copy to simulator open array from from user bit array
// Copy to simulator open array from from user bit array
static void _vl_svPutBitArrElemVecVal(const svOpenArrayHandle d, const svBitVecVal* s, int nargs,
int indx1, int indx2, int indx3) VL_MT_SAFE {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(d);
@ -355,7 +361,7 @@ static void _vl_svPutBitArrElemVecVal(const svOpenArrayHandle d, const svBitVecV
return; // LCOV_EXCL_STOP
}
}
/// Copy to simulator open array from from user logic array
// Copy to simulator open array from from user logic array
static void _vl_svPutLogicArrElemVecVal(const svOpenArrayHandle d, const svLogicVecVal* s,
int nargs, int indx1, int indx2, int indx3) VL_MT_SAFE {
const VerilatedDpiOpenVar* varp = _vl_openhandle_varp(d);
@ -378,7 +384,7 @@ static void _vl_svPutLogicArrElemVecVal(const svOpenArrayHandle d, const svLogic
}
}
/// Return bit from simulator open array
// Return bit from simulator open array
static svBit _vl_svGetBitArrElem(const svOpenArrayHandle s, int nargs, int indx1, int indx2,
int indx3, int indx4) VL_MT_SAFE {
// One extra index supported, as need bit number
@ -393,7 +399,7 @@ static svBit _vl_svGetBitArrElem(const svOpenArrayHandle s, int nargs, int indx1
return 0; // LCOV_EXCL_STOP
}
}
/// Update simulator open array from bit
// Update simulator open array from bit
static void _vl_svPutBitArrElem(const svOpenArrayHandle d, svBit value, int nargs, int indx1,
int indx2, int indx3, int indx4) VL_MT_SAFE {
// One extra index supported, as need bit number

15
include/verilated_dpi.h
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// 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
@ -10,18 +12,19 @@
//*************************************************************************
///
/// \file
/// \brief Verilator: Common include for all Verilated C files that use DPI
/// \brief Verilated DPI header
///
/// This file is included automatically by Verilator at the top of
/// all C++ files it generates where DPI is used. It contains
/// DPI interface functions required by the Verilated code.
/// This file is included automatically by Verilator at the top of all C++
/// files it generates where DPI is used. It contains DPI interface
/// functions required by the Verilated code.
///
/// Code available from: https://verilator.org
/// This file is not part of the Verilated public-facing API.
/// It is only for internal use.
///
//*************************************************************************
#ifndef VERILATOR_VERILATED_DPI_H_
#define VERILATOR_VERILATED_DPI_H_ ///< Header Guard
#define VERILATOR_VERILATED_DPI_H_
#include "verilatedos.h"
#include "verilated.h" // Also presumably included by caller

48
include/verilated_fst_c.cpp
View File

@ -1,7 +1,7 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// THIS MODULE IS PUBLICLY LICENSED
// Code available from: https://verilator.org
//
// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
// can redistribute it and/or modify it under the terms of either the GNU
@ -12,7 +12,12 @@
//=============================================================================
///
/// \file
/// \brief C++ Tracing in FST Format
/// \brief Verilated C++ tracing in FST format implementation code
///
/// This file must be compiled and linked against all Verilated objects
/// that use --trace-fst.
///
/// Use "verilator --trace-fst" to add this to the Makefile for the linker.
///
//=============================================================================
@ -46,6 +51,33 @@
// clang-format on
//=============================================================================
// Check that vltscope_t matches fstScopeType
static_assert((int)FST_ST_VCD_MODULE == (int)VLT_TRACE_SCOPE_MODULE,
"VLT_TRACE_SCOPE_MODULE mismatches");
static_assert((int)FST_ST_VCD_TASK == (int)VLT_TRACE_SCOPE_TASK,
"VLT_TRACE_SCOPE_TASK mismatches");
static_assert((int)FST_ST_VCD_FUNCTION == (int)VLT_TRACE_SCOPE_FUNCTION,
"VLT_TRACE_SCOPE_FUNCTION mismatches");
static_assert((int)FST_ST_VCD_BEGIN == (int)VLT_TRACE_SCOPE_BEGIN,
"VLT_TRACE_SCOPE_BEGIN mismatches");
static_assert((int)FST_ST_VCD_FORK == (int)VLT_TRACE_SCOPE_FORK,
"VLT_TRACE_SCOPE_FORK mismatches");
static_assert((int)FST_ST_VCD_GENERATE == (int)VLT_TRACE_SCOPE_GENERATE,
"VLT_TRACE_SCOPE_GENERATE mismatches");
static_assert((int)FST_ST_VCD_STRUCT == (int)VLT_TRACE_SCOPE_STRUCT,
"VLT_TRACE_SCOPE_STRUCT mismatches");
static_assert((int)FST_ST_VCD_UNION == (int)VLT_TRACE_SCOPE_UNION,
"VLT_TRACE_SCOPE_UNION mismatches");
static_assert((int)FST_ST_VCD_CLASS == (int)VLT_TRACE_SCOPE_CLASS,
"VLT_TRACE_SCOPE_CLASS mismatches");
static_assert((int)FST_ST_VCD_INTERFACE == (int)VLT_TRACE_SCOPE_INTERFACE,
"VLT_TRACE_SCOPE_INTERFACE mismatches");
static_assert((int)FST_ST_VCD_PACKAGE == (int)VLT_TRACE_SCOPE_PACKAGE,
"VLT_TRACE_SCOPE_PACKAGE mismatches");
static_assert((int)FST_ST_VCD_PROGRAM == (int)VLT_TRACE_SCOPE_PROGRAM,
"VLT_TRACE_SCOPE_PROGRAM mismatches");
//=============================================================================
// Specialization of the generics for this trace format
@ -73,6 +105,7 @@ void VerilatedFst::open(const char* filename) VL_MT_SAFE_EXCLUDES(m_mutex) {
#ifdef VL_TRACE_FST_WRITER_THREAD
fstWriterSetParallelMode(m_fst, 1);
#endif
fullDump(true); // First dump must be full for fst
m_curScope.clear();
@ -135,6 +168,7 @@ void VerilatedFst::declare(vluint32_t code, const char* name, int dtypenum, fstV
std::string symbol_name(tokens.back());
tokens.pop_back(); // Remove symbol name from hierarchy
tokens.insert(tokens.begin(), moduleName()); // Add current module to the hierarchy
std::string tmpModName;
// Find point where current and new scope diverge
auto cur_it = m_curScope.begin();
@ -153,7 +187,15 @@ void VerilatedFst::declare(vluint32_t code, const char* name, int dtypenum, fstV
// Follow the hierarchy of the new variable from the common scope point
while (new_it != tokens.end()) {
fstWriterSetScope(m_fst, FST_ST_VCD_SCOPE, new_it->c_str(), nullptr);
if ((new_it->back() & 0x80)) {
tmpModName = *new_it;
tmpModName.pop_back();
// If the scope ends with a non-ascii character, it will be 0x80 + fstScopeType
fstWriterSetScope(m_fst, (fstScopeType)(new_it->back() & 0x7f), tmpModName.c_str(),
nullptr);
} else
fstWriterSetScope(m_fst, FST_ST_VCD_SCOPE, new_it->c_str(), nullptr);
m_curScope.push_back(*new_it);
new_it = tokens.erase(new_it);
}

24
include/verilated_fst_c.h
View File

@ -1,7 +1,7 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// THIS MODULE IS PUBLICLY LICENSED
// Code available from: https://verilator.org
//
// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
// can redistribute it and/or modify it under the terms of either the GNU
@ -12,10 +12,11 @@
//=============================================================================
///
/// \file
/// \brief C++ Tracing in FST Format
/// \brief Verilated tracing in FST format header
///
/// User wrapper code should use this header when creating FST traces.
///
//=============================================================================
// SPDIFF_OFF
#ifndef VERILATOR_VERILATED_FST_C_H_
#define VERILATOR_VERILATED_FST_C_H_
@ -43,15 +44,12 @@ private:
//=========================================================================
// FST specific internals
typedef std::map<vluint32_t, fstHandle> Code2SymbolType;
typedef std::map<int, fstEnumHandle> Local2FstDtype;
void* m_fst;
Code2SymbolType m_code2symbol;
Local2FstDtype m_local2fstdtype;
std::map<vluint32_t, fstHandle> m_code2symbol;
std::map<int, fstEnumHandle> m_local2fstdtype;
std::list<std::string> m_curScope;
fstHandle* m_symbolp = nullptr; ///< same as m_code2symbol, but as an array
char* m_strbuf = nullptr; ///< String buffer long enough to hold maxBits() chars
fstHandle* m_symbolp = nullptr; // same as m_code2symbol, but as an array
char* m_strbuf = nullptr; // String buffer long enough to hold maxBits() chars
// CONSTRUCTORS
VL_UNCOPYABLE(VerilatedFst);
@ -116,20 +114,22 @@ public:
fstVarType vartype, bool array, int arraynum);
};
#ifndef DOXYGEN
// Declare specialization here as it's used in VerilatedFstC just below
template <> void VerilatedTrace<VerilatedFst>::dump(vluint64_t timeui);
template <> void VerilatedTrace<VerilatedFst>::set_time_unit(const char* unitp);
template <> void VerilatedTrace<VerilatedFst>::set_time_unit(const std::string& unit);
template <> void VerilatedTrace<VerilatedFst>::set_time_resolution(const char* unitp);
template <> void VerilatedTrace<VerilatedFst>::set_time_resolution(const std::string& unit);
#endif
//=============================================================================
// VerilatedFstC
/// Create a FST dump file in C standalone (no SystemC) simulations.
/// Also derived for use in SystemC simulations.
class VerilatedFstC final {
VerilatedFst m_sptrace; ///< Trace file being created
class VerilatedFstC VL_NOT_FINAL {
VerilatedFst m_sptrace; // Trace file being created
// CONSTRUCTORS
VL_UNCOPYABLE(VerilatedFstC);

84
include/verilated_fst_sc.cpp Normal file
View File

@ -0,0 +1,84 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// THIS MODULE IS PUBLICLY LICENSED
//
// Copyright 2001-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
//
//=============================================================================
///
/// \file
/// \brief Verilated tracing in FST for SystemC implementation code
///
/// This file must be compiled and linked against all Verilated objects
/// that use --sc --trace-fst.
///
/// Use "verilator --sc --trace-fst" to add this to the Makefile for the linker.
///
//=============================================================================
#include "verilatedos.h"
#include "verilated_fst_sc.h"
//======================================================================
//======================================================================
//--------------------------------------------------
// SystemC 2.1.v1
// cppcheck-suppress unusedFunction
void VerilatedFstSc::write_comment(const std::string&) {}
void VerilatedFstSc::trace(const unsigned int&, const std::string&, const char**) {}
#define DECL_TRACE_METHOD_A(tp) \
void VerilatedFstSc::trace(const tp& object, const std::string& name) {}
#define DECL_TRACE_METHOD_B(tp) \
void VerilatedFstSc::trace(const tp& object, const std::string& name, int width) {}
// clang-format off
#if (SYSTEMC_VERSION >= 20171012)
DECL_TRACE_METHOD_A( sc_event )
DECL_TRACE_METHOD_A( sc_time )
#endif
DECL_TRACE_METHOD_A( bool )
DECL_TRACE_METHOD_A( sc_dt::sc_bit )
DECL_TRACE_METHOD_A( sc_dt::sc_logic )
DECL_TRACE_METHOD_B( unsigned char )
DECL_TRACE_METHOD_B( unsigned short )
DECL_TRACE_METHOD_B( unsigned int )
DECL_TRACE_METHOD_B( unsigned long )
#ifdef SYSTEMC_64BIT_PATCHES
DECL_TRACE_METHOD_B( unsigned long long)
#endif
DECL_TRACE_METHOD_B( char )
DECL_TRACE_METHOD_B( short )
DECL_TRACE_METHOD_B( int )
DECL_TRACE_METHOD_B( long )
DECL_TRACE_METHOD_B( sc_dt::int64 )
DECL_TRACE_METHOD_B( sc_dt::uint64 )
DECL_TRACE_METHOD_A( float )
DECL_TRACE_METHOD_A( double )
DECL_TRACE_METHOD_A( sc_dt::sc_int_base )
DECL_TRACE_METHOD_A( sc_dt::sc_uint_base )
DECL_TRACE_METHOD_A( sc_dt::sc_signed )
DECL_TRACE_METHOD_A( sc_dt::sc_unsigned )
DECL_TRACE_METHOD_A( sc_dt::sc_fxval )
DECL_TRACE_METHOD_A( sc_dt::sc_fxval_fast )
DECL_TRACE_METHOD_A( sc_dt::sc_fxnum )
DECL_TRACE_METHOD_A( sc_dt::sc_fxnum_fast )
DECL_TRACE_METHOD_A( sc_dt::sc_bv_base )
DECL_TRACE_METHOD_A( sc_dt::sc_lv_base )
// clang-format on
#undef DECL_TRACE_METHOD_A
#undef DECL_TRACE_METHOD_B
//********************************************************************

123
include/verilated_fst_sc.h Normal file
View File

@ -0,0 +1,123 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//=============================================================================
//
// Copyright 2001-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
//
//=============================================================================
///
/// \file
/// \brief Verilator tracing in FST format for SystemC header
///
/// User wrapper code should use this header when creating FST SystemC
/// traces.
///
/// This class is not threadsafe, as the SystemC kernel is not threadsafe.
///
//=============================================================================
#ifndef _VERILATED_FST_SC_H_
#define _VERILATED_FST_SC_H_ 1
#include "verilatedos.h"
#include "verilated_sc.h"
#include "verilated_fst_c.h"
//=============================================================================
// VerilatedFstSc
///
/// This class is passed to the SystemC simulation kernel, just like a
/// documented SystemC trace format.
class VerilatedFstSc final : sc_trace_file, public VerilatedFstC {
// CONSTRUCTORS
VL_UNCOPYABLE(VerilatedFstSc);
public:
VerilatedFstSc() {
sc_get_curr_simcontext()->add_trace_file(this);
// We want to avoid a depreciated warning, but still be back compatible.
// Turning off the message just for this still results in an
// annoying "to turn off" message.
sc_time t1sec(1, SC_SEC);
if (t1sec.to_default_time_units() != 0) {
sc_time tunits(1.0 / t1sec.to_default_time_units(), SC_SEC);
spTrace()->set_time_unit(tunits.to_string());
}
spTrace()->set_time_resolution(sc_get_time_resolution().to_string());
}
virtual ~VerilatedFstSc() { close(); }
// METHODS
/// Called by SystemC simulate()
virtual void cycle(bool delta_cycle) {
if (!delta_cycle) { this->dump(sc_time_stamp().to_double()); }
}
private:
/// Fake outs for linker
#ifdef NC_SYSTEMC
// Cadence Incisive has these as abstract functions so we must create them
virtual void set_time_unit(int exponent10_seconds) {} // deprecated
#endif
virtual void set_time_unit(double v, sc_time_unit tu) {} // LCOV_EXCL_LINE
//--------------------------------------------------
// SystemC 2.1.v1
#define DECL_TRACE_METHOD_A(tp) virtual void trace(const tp& object, const std::string& name);
#define DECL_TRACE_METHOD_B(tp) \
virtual void trace(const tp& object, const std::string& name, int width);
virtual void write_comment(const std::string&);
virtual void trace(const unsigned int&, const std::string&, const char**);
// clang-format off
// Formatting matches that of sc_trace.h
#if (SYSTEMC_VERSION >= 20171012)
DECL_TRACE_METHOD_A( sc_event )
DECL_TRACE_METHOD_A( sc_time )
#endif
DECL_TRACE_METHOD_A( bool )
DECL_TRACE_METHOD_A( sc_dt::sc_bit )
DECL_TRACE_METHOD_A( sc_dt::sc_logic )
DECL_TRACE_METHOD_B( unsigned char )
DECL_TRACE_METHOD_B( unsigned short )
DECL_TRACE_METHOD_B( unsigned int )
DECL_TRACE_METHOD_B( unsigned long )
#ifdef SYSTEMC_64BIT_PATCHES
DECL_TRACE_METHOD_B( unsigned long long)
#endif
DECL_TRACE_METHOD_B( char )
DECL_TRACE_METHOD_B( short )
DECL_TRACE_METHOD_B( int )
DECL_TRACE_METHOD_B( long )
DECL_TRACE_METHOD_B( sc_dt::int64 )
DECL_TRACE_METHOD_B( sc_dt::uint64 )
DECL_TRACE_METHOD_A( float )
DECL_TRACE_METHOD_A( double )
DECL_TRACE_METHOD_A( sc_dt::sc_int_base )
DECL_TRACE_METHOD_A( sc_dt::sc_uint_base )
DECL_TRACE_METHOD_A( sc_dt::sc_signed )
DECL_TRACE_METHOD_A( sc_dt::sc_unsigned )
DECL_TRACE_METHOD_A( sc_dt::sc_fxval )
DECL_TRACE_METHOD_A( sc_dt::sc_fxval_fast )
DECL_TRACE_METHOD_A( sc_dt::sc_fxnum )
DECL_TRACE_METHOD_A( sc_dt::sc_fxnum_fast )
DECL_TRACE_METHOD_A( sc_dt::sc_bv_base )
DECL_TRACE_METHOD_A( sc_dt::sc_lv_base )
// clang-format on
#undef DECL_TRACE_METHOD_A
#undef DECL_TRACE_METHOD_B
};
#endif // Guard

73
include/verilated_heavy.h
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// Code available from: https://verilator.org
//
// Copyright 2010-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
@ -10,19 +12,17 @@
//*************************************************************************
///
/// \file
/// \brief Verilator: String include for all Verilated C files
/// \brief Verilated string and data-type header
///
/// This file is included automatically by Verilator at the top of
/// all C++ files it generates. It is used when strings or other
/// heavyweight types are required; these contents are not part of
/// verilated.h to save compile time when such types aren't used.
///
/// Code available from: https://verilator.org
/// This file is included automatically by Verilator at the top of
/// all C++ files it generates. It is used when strings or other
/// heavyweight types are required; these contents are not part of
/// verilated.h to save compile time when such types aren't used.
///
//*************************************************************************
#ifndef VERILATOR_VERILATED_HEAVY_H_
#define VERILATOR_VERILATED_HEAVY_H_ ///< Header Guard
#define VERILATOR_VERILATED_HEAVY_H_
#include "verilated.h"
@ -49,7 +49,7 @@ extern std::string VL_TO_STRING_W(int words, WDataInP obj);
class VlURNG final {
public:
typedef size_t result_type;
using result_type = size_t;
static constexpr size_t min() { return 0; }
static constexpr size_t max() { return 1ULL << 31; }
size_t operator()() { return VL_MASK_I(31) & VL_RANDOM_I(32); }
@ -88,12 +88,14 @@ public:
};
//===================================================================
// Verilog wide-number-in-array container
// Similar to std::array<WData, N>, but lighter weight, only methods needed
// by Verilator, to help compile time.
//
// This is only used when we need an upper-level container and so can't
// simply use a C style array (which is just a pointer).
/// Verilog wide unpacked bit container.
/// Similar to std::array<WData, N>, but lighter weight, only methods needed
/// by Verilator, to help compile time.
///
/// For example a Verilog "bit [94:0]" will become a VlWide<3> because 3*32
/// bits are needed to hold the 95 bits. The MSB (bit 96) must always be
/// zero in memory, but during intermediate operations in the Verilated
/// internals is unpredictable.
template <std::size_t T_Words> class VlWide final {
EData m_storage[T_Words];
@ -111,6 +113,7 @@ public:
const EData& operator[](size_t index) const { return m_storage[index]; };
EData& operator[](size_t index) { return m_storage[index]; };
operator WDataOutP() { return &m_storage[0]; }
operator WDataInP() const { return &m_storage[0]; }
// METHODS
const EData& at(size_t index) const { return m_storage[index]; }
@ -142,10 +145,10 @@ template <std::size_t T_Words> std::string VL_TO_STRING(const VlWide<T_Words>& o
template <class T_Value, size_t T_MaxSize = 0> class VlQueue final {
private:
// TYPES
typedef std::deque<T_Value> Deque;
using Deque = std::deque<T_Value>;
public:
typedef typename Deque::const_iterator const_iterator;
using const_iterator = typename Deque::const_iterator;
private:
// MEMBERS
@ -497,10 +500,10 @@ template <class T_Value> std::string VL_TO_STRING(const VlQueue<T_Value>& obj) {
template <class T_Key, class T_Value> class VlAssocArray final {
private:
// TYPES
typedef std::map<T_Key, T_Value> Map;
using Map = std::map<T_Key, T_Value>;
public:
typedef typename Map::const_iterator const_iterator;
using const_iterator = typename Map::const_iterator;
private:
// MEMBERS
@ -794,21 +797,24 @@ void VL_WRITEMEM_N(bool hex, int bits, const std::string& filename,
}
//===================================================================
// Verilog packed array container
// For when a standard C++[] array is not sufficient, e.g. an
// array under a queue, or methods operating on the array
/// Verilog packed array container
/// For when a standard C++[] array is not sufficient, e.g. an
/// array under a queue, or methods operating on the array.
///
/// This class may get exposed to a Verilated Model's top I/O, if the top
/// IO has an unpacked array.
template <class T_Value, std::size_t T_Depth> class VlUnpacked final {
private:
// TYPES
typedef std::array<T_Value, T_Depth> Array;
using Array = std::array<T_Value, T_Depth>;
public:
typedef typename Array::const_iterator const_iterator;
using const_iterator = typename Array::const_iterator;
private:
// MEMBERS
Array m_array; // State of the assoc array
Array m_array; // Contents of the packed array
public:
// CONSTRUCTORS
@ -826,13 +832,28 @@ public:
T_Value& operator[](size_t index) { return m_array[index]; };
const T_Value& operator[](size_t index) const { return m_array[index]; };
// Dumping. Verilog: str = $sformatf("%p", assoc)
std::string to_string() const {
std::string out = "'{";
std::string comma;
for (int i = 0; i < T_Depth; ++i) {
out += comma + VL_TO_STRING(m_array[i]);
comma = ", ";
}
return out + "} ";
}
};
template <class T_Value, std::size_t T_Depth>
std::string VL_TO_STRING(const VlUnpacked<T_Value, T_Depth>& obj) {
return obj.to_string();
}
//===================================================================
// Verilog class reference container
// There are no multithreaded locks on this; the base variable must
// be protected by other means
//
#define VlClassRef std::shared_ptr

83
include/verilated_imp.h
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// Code available from: https://verilator.org
//
// Copyright 2009-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
@ -10,14 +12,15 @@
//=========================================================================
///
/// \file
/// \brief Verilator: Implementation Header, only for verilated.cpp internals.
/// \brief Verilated implementation Header, only for verilated.cpp internals.
///
/// Code available from: https://verilator.org
/// This file is not part of the Verilated public-facing API.
/// It is only for internal use by the Verilated libraries.
///
//=========================================================================
#ifndef VERILATOR_VERILATED_IMP_H_
#define VERILATOR_VERILATED_IMP_H_ ///< Header Guard
#define VERILATOR_VERILATED_IMP_H_
// clang-format off
#if !defined(VERILATOR_VERILATED_CPP_) && !defined(VERILATOR_VERILATED_DPI_CPP_) \
@ -46,7 +49,7 @@ class VerilatedScope;
// Threaded message passing
#ifdef VL_THREADED
/// Message, enqueued on an mtask, and consumed on the main eval thread
// Message, enqueued on an mtask, and consumed on the main eval thread
class VerilatedMsg final {
public:
// TYPES
@ -58,8 +61,8 @@ public:
private:
// MEMBERS
vluint32_t m_mtaskId; ///< MTask that did enqueue
std::function<void()> m_cb; ///< Lambda to execute when message received
vluint32_t m_mtaskId; // MTask that did enqueue
std::function<void()> m_cb; // Lambda to execute when message received
public:
// CONSTRUCTORS
explicit VerilatedMsg(const std::function<void()>& cb)
@ -72,20 +75,20 @@ public:
VerilatedMsg& operator=(VerilatedMsg&&) = default;
// METHODS
vluint32_t mtaskId() const { return m_mtaskId; }
/// Execute the lambda function
// Execute the lambda function
void run() const { m_cb(); }
};
/// Each thread has a queue it pushes to
/// This assumes no thread starts pushing the next tick until the previous has drained.
/// If more aggressiveness is needed, a double-buffered scheme might work well.
// Each thread has a queue it pushes to
// This assumes no thread starts pushing the next tick until the previous has drained.
// If more aggressiveness is needed, a double-buffered scheme might work well.
class VerilatedEvalMsgQueue final {
typedef std::multiset<VerilatedMsg, VerilatedMsg::Cmp> VerilatedThreadQueue;
using VerilatedThreadQueue = std::multiset<VerilatedMsg, VerilatedMsg::Cmp>;
std::atomic<vluint64_t> m_depth; ///< Current depth of queue (see comments below)
std::atomic<vluint64_t> m_depth; // Current depth of queue (see comments below)
VerilatedMutex m_mutex; ///< Mutex protecting queue
VerilatedThreadQueue m_queue VL_GUARDED_BY(m_mutex); ///< Message queue
VerilatedMutex m_mutex; // Mutex protecting queue
VerilatedThreadQueue m_queue VL_GUARDED_BY(m_mutex); // Message queue
public:
// CONSTRUCTORS
VerilatedEvalMsgQueue()
@ -99,13 +102,13 @@ private:
public:
// METHODS
//// Add message to queue (called by producer)
// Add message to queue (called by producer)
void post(const VerilatedMsg& msg) VL_MT_SAFE_EXCLUDES(m_mutex) {
const VerilatedLockGuard lock(m_mutex);
m_queue.insert(msg); // Pass by value to copy the message into queue
++m_depth;
}
/// Service queue until completion (called by consumer)
// Service queue until completion (called by consumer)
void process() VL_MT_SAFE_EXCLUDES(m_mutex) {
// Tracking m_depth is redundant to e.g. getting the mutex and looking at queue size,
// but on the reader side it's 4x faster to test an atomic then getting a mutex
@ -130,7 +133,7 @@ public:
}
};
/// Each thread has a local queue to build up messages until the end of the eval() call
// Each thread has a local queue to build up messages until the end of the eval() call
class VerilatedThreadMsgQueue final {
std::queue<VerilatedMsg> m_queue;
@ -151,7 +154,7 @@ private:
}
public:
/// Add message to queue, called by producer
// Add message to queue, called by producer
static void post(const VerilatedMsg& msg) VL_MT_SAFE {
// Handle calls to threaded routines outside
// of any mtask -- if an initial block calls $finish, say.
@ -163,7 +166,7 @@ public:
threadton().m_queue.push(msg); // Pass by value to copy the message into queue
}
}
/// Push all messages to the eval's queue
// Push all messages to the eval's queue
static void flush(VerilatedEvalMsgQueue* evalMsgQp) VL_MT_SAFE {
while (!threadton().m_queue.empty()) {
evalMsgQp->post(threadton().m_queue.front());
@ -180,7 +183,7 @@ class VerilatedFpList final {
std::size_t m_sz = 0;
public:
typedef FILE* const* const_iterator;
using const_iterator = FILE* const*;
explicit VerilatedFpList() {}
const_iterator begin() const { return m_fp; }
const_iterator end() const { return m_fp + m_sz; }
@ -194,16 +197,16 @@ public:
//======================================================================
// VerilatedContextImpData
/// Class for hidden implementation members inside VerilatedContext
// Class for hidden implementation members inside VerilatedContext
// Avoids needing std::unordered_map inside verilated.h
class VerilatedContextImpData final {
friend class VerilatedContext;
friend class VerilatedContextImp;
protected:
/// Map of <scope_name, scope pointer>
// Map of <scope_name, scope pointer>
// Used by scopeInsert, scopeFind, scopeErase, scopeNameMap
mutable VerilatedMutex m_nameMutex; ///< Protect m_nameMap
mutable VerilatedMutex m_nameMutex; // Protect m_nameMap
VerilatedScopeNameMap m_nameMap VL_GUARDED_BY(m_nameMutex);
};
@ -277,12 +280,12 @@ public: // But only for verilated*.cpp
if (m_fdFreeMct.empty()) return 0;
IData idx = m_fdFreeMct.back();
m_fdFreeMct.pop_back();
m_fdps[idx] = fopen(filenamep, "w");
m_fdps[idx] = std::fopen(filenamep, "w");
if (VL_UNLIKELY(!m_fdps[idx])) return 0;
return (1 << idx);
}
IData fdNew(const char* filenamep, const char* modep) VL_MT_SAFE_EXCLUDES(m_fdMutex) {
FILE* fp = fopen(filenamep, modep);
FILE* fp = std::fopen(filenamep, modep);
if (VL_UNLIKELY(!fp)) return 0;
// Bit 31 indicates it's a descriptor not a MCD
const VerilatedLockGuard lock(m_fdMutex);
@ -305,20 +308,20 @@ public: // But only for verilated*.cpp
void fdFlush(IData fdi) VL_MT_SAFE_EXCLUDES(m_fdMutex) {
const VerilatedLockGuard lock(m_fdMutex);
const VerilatedFpList fdlist = fdToFpList(fdi);
for (const auto& i : fdlist) fflush(i);
for (const auto& i : fdlist) std::fflush(i);
}
IData fdSeek(IData fdi, IData offset, IData origin) VL_MT_SAFE_EXCLUDES(m_fdMutex) {
const VerilatedLockGuard lock(m_fdMutex);
const VerilatedFpList fdlist = fdToFpList(fdi);
if (VL_UNLIKELY(fdlist.size() != 1)) return 0;
return static_cast<IData>(
fseek(*fdlist.begin(), static_cast<long>(offset), static_cast<int>(origin)));
std::fseek(*fdlist.begin(), static_cast<long>(offset), static_cast<int>(origin)));
}
IData fdTell(IData fdi) VL_MT_SAFE_EXCLUDES(m_fdMutex) {
const VerilatedLockGuard lock(m_fdMutex);
const VerilatedFpList fdlist = fdToFpList(fdi);
if (VL_UNLIKELY(fdlist.size() != 1)) return 0;
return static_cast<IData>(ftell(*fdlist.begin()));
return static_cast<IData>(std::ftell(*fdlist.begin()));
}
void fdWrite(IData fdi, const std::string& output) VL_MT_SAFE_EXCLUDES(m_fdMutex) {
const VerilatedLockGuard lock(m_fdMutex);
@ -335,14 +338,14 @@ public: // But only for verilated*.cpp
IData idx = VL_MASK_I(31) & fdi;
if (VL_UNLIKELY(idx >= m_fdps.size())) return;
if (VL_UNLIKELY(!m_fdps[idx])) return; // Already free
fclose(m_fdps[idx]);
std::fclose(m_fdps[idx]);
m_fdps[idx] = (FILE*)0;
m_fdFree.push_back(idx);
} else {
// MCD case
for (int i = 0; (fdi != 0) && (i < 31); i++, fdi >>= 1) {
if (fdi & VL_MASK_I(1)) {
fclose(m_fdps[i]);
std::fclose(m_fdps[i]);
m_fdps[i] = nullptr;
m_fdFreeMct.push_back(i);
}
@ -398,28 +401,28 @@ protected:
friend class VerilatedImp;
// TYPES
typedef std::map<std::pair<const void*, void*>, void*> UserMap;
typedef std::map<const char*, int, VerilatedCStrCmp> ExportNameMap;
using UserMap = std::map<std::pair<const void*, void*>, void*>;
using ExportNameMap = std::map<const char*, int, VerilatedCStrCmp>;
// MEMBERS
// Nothing below here is save-restored; users expected to re-register appropriately
VerilatedMutex m_userMapMutex; ///< Protect m_userMap
VerilatedMutex m_userMapMutex; // Protect m_userMap
// For userInsert, userFind. As indexed by pointer is common across contexts.
UserMap m_userMap VL_GUARDED_BY(m_userMapMutex); ///< Map of <(scope,userkey), userData>
UserMap m_userMap VL_GUARDED_BY(m_userMapMutex); // Map of <(scope,userkey), userData>
VerilatedMutex m_hierMapMutex; ///< Protect m_hierMap
/// Map that represents scope hierarchy
VerilatedMutex m_hierMapMutex; // Protect m_hierMap
// Map that represents scope hierarchy
// Used by hierarchyAdd, hierarchyRemove, hierarchyMap
VerilatedHierarchyMap m_hierMap VL_GUARDED_BY(m_hierMapMutex);
// Slow - somewhat static:
VerilatedMutex m_exportMutex; ///< Protect m_nameMap
/// Map of <export_func_proto, func number>
VerilatedMutex m_exportMutex; // Protect m_nameMap
// Map of <export_func_proto, func number>
// Used by exportInsert, exportFind, exportName.
// Export numbers same across all contexts as just a string-to-number conversion
ExportNameMap m_exportMap VL_GUARDED_BY(m_exportMutex);
int m_exportNext VL_GUARDED_BY(m_exportMutex) = 0; ///< Next export funcnum
int m_exportNext VL_GUARDED_BY(m_exportMutex) = 0; // Next export funcnum
// CONSTRUCTORS
VerilatedImpData() = default;
@ -471,7 +474,7 @@ public:
}
public: // But only for verilated.cpp
/// Symbol table destruction cleans up the entries for each scope.
// Symbol table destruction cleans up the entries for each scope.
static void userEraseScope(const VerilatedScope* scopep) VL_MT_SAFE {
// Slow ok - called once/scope on destruction, so we simply iterate.
const VerilatedLockGuard lock(s().m_userMapMutex);

16
include/verilated_intrinsics.h
View File

@ -1,6 +1,8 @@
// -*- mode: C++; c-file-style: "cc-mode" -*-
//*************************************************************************
//
// 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
@ -10,17 +12,19 @@
//*************************************************************************
///
/// \file
/// \brief Verilator: Common include for target specific intrinsics.
/// \brief Verilator common target specific intrinsics header
///
/// Code using machine specific intrinsics for optimization should
/// include this header rather than directly including he target
/// specific headers. We provide macros to check for availability
/// of instruction sets, and a common mechanism to disable them.
/// This file is not part of the Verilated public-facing API.
///
/// It is only for internal use; code using machine specific intrinsics for
/// optimization should include this header rather than directly including
/// he target specific headers. We provide macros to check for availability
/// of instruction sets, and a common mechanism to disable them.
///
//*************************************************************************
#ifndef VERILATOR_VERILATED_INTRINSICS_H_
#define VERILATOR_VERILATED_INTRINSICS_H_ ///< Header Guard
#define VERILATOR_VERILATED_INTRINSICS_H_
// clang-format off

Some files were not shown because too many files have changed in this diff Show More