diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index b069791d2..048e84fa1 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,6 +1,6 @@
---
name: Bug report
-about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc)
+about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
title: ''
labels: new
assignees: ''
diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md
index 1514b1287..3cc485eda 100644
--- a/.github/ISSUE_TEMPLATE/feature.md
+++ b/.github/ISSUE_TEMPLATE/feature.md
@@ -1,6 +1,6 @@
---
name: Feature Request
-about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc)
+about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
title: ''
labels: new
assignees: ''
diff --git a/.github/ISSUE_TEMPLATE/questions.md b/.github/ISSUE_TEMPLATE/questions.md
index 1d746589f..0571931ca 100644
--- a/.github/ISSUE_TEMPLATE/questions.md
+++ b/.github/ISSUE_TEMPLATE/questions.md
@@ -1,6 +1,6 @@
---
name: Q and A, or Other
-about: Ask a question, not related to a specific bug or feature request. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc)
+about: Ask a question, not related to a specific bug or feature request. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
title: ''
labels: new
assignees: ''
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index a05a08e94..fd0304994 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1 +1 @@
-We appreciate your contributing to Verilator. If this is your first commit, please add your name to docs/CONTRIBUTORS, and read our contributing guidelines in docs/CONTRIBUTING.adoc.
+We appreciate your contributing to Verilator. If this is your first commit, please add your name to docs/CONTRIBUTORS, and read our contributing guidelines in docs/CONTRIBUTING.rst.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 98ba13ed7..ca1b4f3f7 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -1,5 +1,5 @@
# DESCRIPTION: Github actions config
-# This name is key to badges in README.adoc, so we use the name build
+# This name is key to badges in README.rst, so we use the name build
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
name: build
diff --git a/.github/workflows/clang-format.yml b/.github/workflows/clang-format.yml
index 6cf4c5b4b..88a3c897c 100644
--- a/.github/workflows/clang-format.yml
+++ b/.github/workflows/clang-format.yml
@@ -1,5 +1,4 @@
# DESCRIPTION: Github actions config
-# This name is key to badges in README.adoc, so we use the name build
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
name: clang-format
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 4e6f4567f..8fa0e88e8 100644
--- a/.github/workflows/coverage.yml
+++ b/.github/workflows/coverage.yml
@@ -66,6 +66,12 @@ jobs:
- 1
- 2
- 3
+ - 4
+ - 5
+ - 6
+ - 7
+ - 8
+ - 9
include:
- { test: dist, num: '' }
name: test-${{ matrix.test }}${{ matrix.num }}
diff --git a/Changes b/Changes
index cf1962931..e09133c42 100644
--- a/Changes
+++ b/Changes
@@ -2,6 +2,28 @@ Revision history for Verilator
The contributors that suggested a given feature are shown in []. Thanks!
+* Verilator 4.200 2021-03-12
+
+** Add simulation context (VerilatedContext) to allow multiple fully independent
+ models to be in the same process. Please see the updated examples. (#2660)
+
+** Add context->time() and context->timeInc() API calls, to set simulation time.
+ These now are recommended in place of the legacy sc_time_stamp().
+
+**** Converted Asciidoc documentation into reStructuredText (RST) format.
+
+**** --inhibit-sim is planned for deprecation, file a bug if this is still being used.
+
+**** Fix range inheritance on port without data type (#2753). [Embedded Go]
+
+**** Fix slice-assign overflow (#2803) (#2811). [David Turner]
+
+**** Fix interface array connection ordering broken in v4.110 (#2827). [Don Owen]
+
+**** Fix or-reduction on different scopes broken in 4.110 (#2828). [Yinan Xu]
+
+**** Fix MSVC++ compile error. (#2831) (#2833) [Drew Taussig]
+
* Verilator 4.110 2021-02-25
diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP
index 6c8b4c4c0..298886f43 100644
--- a/MANIFEST.SKIP
+++ b/MANIFEST.SKIP
@@ -43,6 +43,7 @@ docs/clang-format.txt$
docs/doxygen-doc/.*
examples/xml_py/copied/
examples/xml_py/graph.*
+sonar-project.properties
src/Makefile$
src/Makefile_obj$
include/verilated.mk$
diff --git a/Makefile.in b/Makefile.in
index fdf0ef90e..de87a7a68 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -124,7 +124,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
Changes \
LICENSE \
MANIFEST.SKIP \
- README.adoc \
+ README.rst \
verilator-config.cmake.in \
verilator-config-version.cmake.in \
bin/verilator \
@@ -134,16 +134,16 @@ DISTFILES_INC = $(INFOS) .gitignore \
bin/verilator_includer \
bin/verilator_profcfunc \
docs/.gitignore \
- docs/CONTRIBUTING.adoc \
+ docs/CONTRIBUTING.rst \
docs/CONTRIBUTORS \
docs/Makefile.in \
docs/TODO \
docs/doxygen-mainpage \
docs/doxygen.config \
- docs/install.adoc \
- docs/internals.adoc \
+ docs/install.rst \
+ docs/internals.rst \
docs/verilator_logo.png \
- docs/xml.adoc \
+ docs/xml.rst \
install-sh configure *.pod \
include/*.[chv]* \
include/*.in \
@@ -474,9 +474,7 @@ clang-format:
|| echo "*** You are not using clang-format 10.0, indents may differ from master's ***"
$(CLANGFORMAT) $(CLANGFORMAT_FLAGS) $(CLANGFORMAT_FILES)
-YAPF = yapf3
-YAPF_FLAGS = -i
-YAPF_FILES = \
+PY_PROGRAMS = \
examples/xml_py/vl_file_copy \
examples/xml_py/vl_hier_graph \
src/astgen \
@@ -486,14 +484,32 @@ YAPF_FILES = \
src/flexfix \
src/vlcovgen \
nodist/code_coverage \
- nodist/code_coverage.dat \
nodist/dot_importer \
nodist/fuzzer/actual_fail \
nodist/fuzzer/generate_dictionary \
nodist/install_test \
+PY_FILES = \
+ $(PY_PROGRAMS) \
+ nodist/code_coverage.dat \
+
+YAPF = yapf3
+YAPF_FLAGS = -i
+
yapf:
- $(YAPF) $(YAPF_FLAGS) $(YAPF_FILES)
+ $(YAPF) $(YAPF_FLAGS) $(PY_FILES)
+
+FLAKE8 = flake8
+FLAKE8_FLAGS = \
+ --extend-exclude=fastcov.py \
+ --ignore=E123,E129,E251,E501,W503,W504,E701
+
+PYLINT = pylint
+PYLINT_FLAGS = --disable=R0801
+
+lint-py:
+ $(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
+ $(PYLINT) $(PYLINT_FLAGS) $(PY_PROGRAMS)
format-pl-exec:
-chmod a+x test_regress/t/*.pl
diff --git a/README.adoc b/README.adoc
deleted file mode 100644
index f97ba1f06..000000000
--- a/README.adoc
+++ /dev/null
@@ -1,154 +0,0 @@
-// Github doesn't render images unless absolute URL
-:!toc:
-
-ifdef::env-github[]
-image:https://img.shields.io/badge/License-LGPL%20v3-blue.svg[license LGPLv3,link=https://www.gnu.org/licenses/lgpl-3.0]
-image:https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg[license Artistic-2.0,link=https://opensource.org/licenses/Artistic-2.0]
-image:https://api.codacy.com/project/badge/Grade/fa78caa433c84a4ab9049c43e9debc6f[Code Quality,link=https://www.codacy.com/gh/verilator/verilator]
-image:https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg[Coverage,link=https://codecov.io/gh/verilator/verilator]
-image:https://github.com/verilator/verilator/workflows/build/badge.svg[Build Status (GitHub),link=https://github.com/verilator/verilator/actions?query=workflow%3Abuild]
-endif::[]
-
-ifdef::env-github[]
-:link_verilator_contributing: link:docs/CONTRIBUTING.adoc
-:link_verilator_install: link:docs/install.adoc
-endif::[]
-ifndef::env-github[]
-:link_verilator_contributing: https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc
-:link_verilator_install: https://verilator.org/install
-endif::[]
-:link_verilator_commercial_support: https://verilator.org/verilator_commercial_support
-
-== Welcome to Verilator
-
-[cols="a,a",indent=0,frame="none",grid="rows"]
-|===
-^.^| *Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.*
-+++
+++ • Accepts synthesizable Verilog or SystemVerilog
-+++
+++ • Performs lint code-quality checks
-+++
+++ • Compiles into multithreaded {cpp}, or SystemC
-+++
+++ • Creates XML to front-end your own tools
-<.^|image:https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200]
-
->.^|image:https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png[,388,178]
-^.^| *Fast*
-+++
+++ • 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
-<.^|image:https://www.veripool.org/img/verilator_usage_400x200-min.png[,400,200]
-
->.^|image:https://www.veripool.org/img/verilator_community_400x125-min.png[,400,125]
-^.^| *Community Driven & Openly Licensed*
-+++
+++ • Guided by the https://chipsalliance.org/[CHIPS Alliance] and https://www.linuxfoundation.org/[Linux Foundation]
-+++
+++ • Open, and free as in both speech and beer
-+++
+++ • More simulation for your verification budget
-
-^.^| *Commercial Support Available*
-+++
+++ • Commercial support contracts
-+++
+++ • Design support contracts
-+++
+++ • Enhancement contracts
-<.^|image:https://www.veripool.org/img/verilator_support_400x125-min.png[,400,125]
-
-|===
-
-== What Verilator Does
-
-Verilator is invoked with parameters similar to GCC or Synopsys's VCS. It
-"Verilates" the specified Verilog or SystemVerilog code by
-reading it, performing lint checks, and optionally inserting assertion
-checks and coverage-analysis points. It outputs single- or multi-threaded
-.cpp and .h files, the "Verilated" code.
-
-The user writes a little {cpp}/SystemC wrapper file, which instantiates the
-"Verilated" model of the user's top level module. These {cpp}/SystemC
-files are then compiled by a {cpp} compiler (gcc/clang/MSVC++). The
-resulting executable performs the design simulation. Verilator also
-supports linking its generated libraries, optionally encrypted, into other
-simulators.
-
-Verilator may not be the best choice if you are expecting a full featured
-replacement for NC-Verilog, VCS or another commercial Verilog simulator, or
-if you are looking for a behavioral Verilog simulator e.g. for a quick
-class project (we recommend http://iverilog.icarus.com[Icarus Verilog] for
-this.) However, if you are looking for a path to migrate SystemVerilog to
-{cpp} or SystemC, or your team is comfortable writing just a touch of {cpp}
-code, Verilator is the tool for you.
-
-== Performance
-
-Verilator does not simply convert Verilog HDL to {cpp} or SystemC. Rather,
-Verilator compiles your code into a much faster optimized and optionally
-thread-partitioned model, which is in turn wrapped inside a
-{cpp}/SystemC module. The results are a compiled
-Verilog model that executes even on a single-thread over 10x faster than
-standalone SystemC, and on a single thread is about 100 times faster than
-interpreted Verilog simulators such as http://iverilog.icarus.com[Icarus
-Verilog]. Another 2-10x speedup might be gained from multithreading
-(yielding 200-1000x total over interpreted simulators).
-
-Verilator has typically similar or better performance versus the
-closed-source Verilog simulators (Carbon Design Systems Carbonator,
-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
-https://www.veripool.org/verilog_sim_benchmarks.html[Verilog Simulator
-Benchmarks]. (If you benchmark Verilator, please see the notes in the
-https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)], and also
-if possible post on the forums the results; there may be additional tweaks
-possible.)
-
-== Installation & Documentation
-
-For more information:
-
-* {link_verilator_install}[Verilator installation and package directory
- structure]
-
-* https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
-or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)]
-
-* https://github.com/verilator/verilator-announce[Subscribe to verilator announcements]
-
-* https://verilator.org/forum[Verilator forum]
-
-* https://verilator.org/issues[Verilator issues]
-
-== Support
-
-Verilator is a community project, guided by the
-https://chipsalliance.org/[CHIPS Alliance] under the
-https://www.linuxfoundation.org/[Linux Foundation].
-
-We appreciate and welcome your contributions in whatever form; please see
-{link_verilator_contributing}[Contributing to Verilator]. Thanks to our
-https://verilator.org/verilator_doc.html#CONTRIBUTORS[Contributors and
-Sponsors].
-
-Verilator also supports and encourages commercial support models and
-organizations; please see {link_verilator_commercial_support}[Verilator
-Commercial Support].
-
-== Related Projects
-
-* http://gtkwave.sourceforge.net/[GTKwave] - Waveform viewer for Verilator
-traces.
-
-* http://iverilog.icarus.com[Icarus Verilog] - Icarus is a full featured
-interpreted Verilog simulator. If Verilator does not support your needs,
-perhaps Icarus may.
-
-== Open License
-
-Verilator is Copyright 2003-2021 by Wilson Snyder. (Report bugs to
-https://verilator.org/issues[Verilator Issues].)
-
-Verilator is free software; you can redistribute it and/or modify it under
-the terms of either the GNU Lesser General Public License Version 3 or the
-Perl Artistic License Version 2.0. See the documentation for more
-details.
diff --git a/README.rst b/README.rst
new file mode 100644
index 000000000..8591c7587
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,160 @@
+.. Github doesn't render images unless absolute URL
+.. Do not know of a conditional tag, "only: github" nor "github display" works
+
+.. image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
+ :target: https://www.gnu.org/licenses/lgpl-3.0]
+.. image:: https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg
+ :target: https://opensource.org/licenses/Artistic-2.0
+.. image:: https://api.codacy.com/project/badge/Grade/fa78caa433c84a4ab9049c43e9debc6f
+ :target: https://www.codacy.com/gh/verilator/verilator
+.. image:: https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg
+ :target: https://codecov.io/gh/verilator/verilator
+.. image:: https://github.com/verilator/verilator/workflows/build/badge.svg
+ :target: https://github.com/verilator/verilator/actions?query=workflow%3Abuild
+
+Welcome to Verilator
+====================
+
+.. list-table::
+
+ * - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
+ * Accepts synthesizable Verilog or SystemVerilog
+ * Performs lint code-quality checks
+ * Compiles into multithreaded C++, or SystemC
+ * Creates XML to front-end your own tools
+ - |Logo|
+ * - |verilator multithreaded performance bg min|
+ - **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|
+ - **Community Driven & Openly Licensed**
+ * Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
+ * Open, and free as in both speech and beer
+ * More simulation for your verification budget
+ * - **Commercial Support Available**
+ * Commercial support contracts
+ * Design support contracts
+ * Enhancement contracts
+ - |verilator support 400x125 min|
+
+
+What Verilator Does
+===================
+
+Verilator is invoked with parameters similar to GCC or Synopsys's VCS. It
+"Verilates" the specified Verilog or SystemVerilog code by reading it,
+performing lint checks, and optionally inserting assertion checks and
+coverage-analysis points. It outputs single- or multi-threaded .cpp and .h
+files, the "Verilated" code.
+
+The user writes a little C++/SystemC wrapper file, which instantiates the
+"Verilated" model of the user's top level module. These C++/SystemC files
+are then compiled by a C++ compiler (gcc/clang/MSVC++). The resulting
+executable performs the design simulation. Verilator also supports linking
+its generated libraries, optionally encrypted, into other simulators.
+
+Verilator may not be the best choice if you are expecting a full featured
+replacement for NC-Verilog, VCS or another commercial Verilog simulator, or
+if you are looking for a behavioral Verilog simulator e.g. for a quick
+class project (we recommend `Icarus Verilog`_ for this.) However, if you
+are looking for a path to migrate SystemVerilog to C++ or SystemC, or your
+team is comfortable writing just a touch of C++ code, Verilator is the tool
+for you.
+
+
+Performance
+===========
+
+Verilator does not simply convert Verilog HDL to C++ or SystemC. Rather,
+Verilator compiles your code into a much faster optimized and optionally
+thread-partitioned model, which is in turn wrapped inside a C++/SystemC
+module. The results are a compiled Verilog model that executes even on a
+single-thread over 10x faster than standalone SystemC, and on a single
+thread is about 100 times faster than interpreted Verilog simulators such
+as `Icarus Verilog`_. Another 2-10x speedup might be gained from
+multithreading (yielding 200-1000x total over interpreted simulators).
+
+Verilator has typically similar or better performance versus the
+closed-source Verilog simulators (Carbon Design Systems Carbonator,
+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
+`_. (If you
+benchmark Verilator, please see the notes in the `Verilator manual (PDF)
+`_, and also if possible post on
+the forums the results; there may be additional tweaks possible.)
+
+
+Installation & Documentation
+============================
+
+For more information:
+
+- `Verilator installation and package directory structure
+ `_
+
+- `Verilator manual (HTML) `_,
+ or `Verilator manual (PDF) `_
+
+- `Subscribe to verilator announcements
+ `_
+
+- `Verilator forum `_
+
+- `Verilator issues `_
+
+
+Support
+=======
+
+Verilator is a community project, guided by the `CHIPS Alliance`_ under the
+`Linux Foundation`_.
+
+We appreciate and welcome your contributions in whatever form; please see
+`Contributing to Verilator
+`_.
+Thanks to our `Contributors and Sponsors
+`_.
+
+Verilator also supports and encourages commercial support models and
+organizations; please see `Verilator Commercial Support
+`_.
+
+
+Related Projects
+================
+
+- `GTKwave `_ - Waveform viewer for
+ Verilator traces.
+
+- `Icarus Verilog`_ - Icarus is a full featured interpreted Verilog
+ simulator. If Verilator does not support your needs, perhaps Icarus may.
+
+
+Open License
+============
+
+Verilator is Copyright 2003-2021 by Wilson Snyder. (Report bugs to
+`Verilator Issues `_.)
+
+Verilator is free software; you can redistribute it and/or modify it under
+the terms of either the GNU Lesser General Public License Version 3 or the
+Perl Artistic License Version 2.0. See the documentation for more details.
+
+.. _CHIPS Alliance: https://chipsalliance.org
+.. _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
diff --git a/bin/verilator b/bin/verilator
index e6c16fe2c..d18eafd5c 100755
--- a/bin/verilator
+++ b/bin/verilator
@@ -1953,7 +1953,8 @@ Displays program version and exits.
=head1 EXAMPLE C++ EXECUTION
-We'll compile this example into C++.
+We'll compile this example into C++. For an extended and commented version
+of what this C++ code is doing, see examples/make_tracing_c/sim_main.cpp.
mkdir test_our
cd test_our
@@ -1968,21 +1969,24 @@ We'll compile this example into C++.
#include "Vour.h"
#include "verilated.h"
int main(int argc, char** argv, char** env) {
- Verilated::commandArgs(argc, argv);
- Vour* top = new Vour;
- while (!Verilated::gotFinish()) { top->eval(); }
+ VerilatedContext* contextp = new VerilatedContext;
+ contextp->commandArgs(argc, argv);
+ Vour* top = new Vour{contextp};
+ while (!contextp->gotFinish()) { top->eval(); }
delete top;
- exit(0);
+ delete contextp;
+ return 0;
}
EOF
-See the README in the source kit for various ways to install or point to
-Verilator binaries. In brief, if you installed Verilator using the package
-manager of your operating system, or did a "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:
+Next we need Verilator installed. See the README in the source kit for
+various ways to install or point to Verilator binaries. In brief, if you
+installed Verilator using the package manager of your operating system, or
+did a "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:
# See above; don't do this if using an OS-distributed Verilator
export VERILATOR_ROOT=/path/to/where/verilator/was/installed
@@ -2037,13 +2041,12 @@ This is an example similar to the above, but using SystemC.
#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;
- top = new Vour("top");
+ 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;
- exit(0);
+ return 0;
}
EOF
@@ -2101,15 +2104,15 @@ 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 eval(), or eval_step() and eval_end_step().
-1. When there is a single design instantiated at the C++ level that needs to
-evaluate, just call designp->eval().
+1. When there is a single design instantiated at the C++ level that needs
+to evaluate within a given context, just call designp->eval().
-2. When there are multiple designs instantiated at the C++ level that
-need to evaluate, call first_designp->eval_step() then ->eval_step() on all
-other designs. Then call ->eval_end_step() on the first design then all
-other designs. If there is only a single design, you would call
-eval_step() then eval_end_step(); in fact eval() described above is just a
-wrapper which calls these two functions.
+2. When there are multiple designs instantiated at the C++ level that need
+to evaluate within a context, call first_designp->eval_step() then
+->eval_step() on all other designs. Then call ->eval_end_step() on the
+first design then all other designs. If there is only a single design, you
+would call eval_step() then eval_end_step(); in fact eval() described above
+is just a wrapper which calls these two functions.
When eval() is called Verilator looks for changes in clock signals and
evaluates related sequential always blocks, such as computing always_ff @
@@ -2124,7 +2127,7 @@ 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 eval() calls.
-For more information on evaluation, see docs/internals.adoc in the
+For more information on evaluation, see docs/internals.rst in the
distribution.
@@ -2704,7 +2707,7 @@ accesses the above signal "readme" would be:
read_and_check();
}
delete top;
- exit(0);
+ return 0;
}
EOF
@@ -5127,6 +5130,10 @@ 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.
+=item --inhibit-sim
+
+The --inhibit-sim option is planned for removal no sooner than July 2021.
+
=item Configuration File -msg
The -msg argument to lint_off has been replaced with -rule. -msg is
@@ -5414,8 +5421,14 @@ controlled by --assert are disabled.
=item Why do I get "undefined reference to `sc_time_stamp()'"?
-In C++ (non SystemC) code you need to define this function so that the
-simulator knows the current time. See the "CONNECTING TO C++" examples.
+In 4.200 and later, using the timeInc function is recommended instead. See
+the "CONNECTING TO C++" examples. Some linkers (MSVC++) still require
+sc_time_stamp() to be defined, either define this with ("double
+sc_time_stamp() { return 0; }") or compile the Verilated code with
+-DVL_TIME_CONTEXT.
+
+Prior to Verilator 4.200, the sc_time_stamp function needs to be defined in
+C++ (non SystemC) to return the current simulation time.
=item Why do I get "undefined reference to `VL_RAND_RESET_I' or `Verilated::...'"?
@@ -5753,7 +5766,7 @@ L, L, L, L,
L which is the source for this document,
-and docs/internals.adoc in the distribution.
+and docs/internals.rst in the distribution.
=cut
diff --git a/bin/verilator_coverage b/bin/verilator_coverage
index bd0fee254..8093ad94a 100755
--- a/bin/verilator_coverage
+++ b/bin/verilator_coverage
@@ -158,22 +158,25 @@ verilator_coverage - Verilator coverage analyzer
verilator_coverage -write-info merged.info -read ...
-Verilator_coverage processes Verilator coverage reports.
+Verilator_coverage processes Verilated model-generated coverage reports.
-With --anotate, it reads the specified data file and generates annotated
-source code with coverage metrics annotated. If multiple coverage points
-exist on the same line, additional lines will be inserted to report the
-additional points.
+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-standard arguments specify the search paths necessary to
-find the source code that the coverage analysis was performed on.
+Additional Verilog-XL-style standard arguments specify the search paths
+necessary to find the source code that the coverage analysis was performed
+on.
-To get correct coverage percentages, you may wish to read logs/coverage.dat
-into Emacs and do a M-x keep-lines to include only those statistics of
-interest.
+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, you should add a $stop
-statement. This will remove the coverage during the next build.
+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
@@ -181,12 +184,12 @@ statement. This will remove the coverage during the next build.
=item I
-Specify input data file, may be repeated to read multiple inputs. If no
+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
-Sprcifies the directory name that source files with annotated coverage data
+Specifies the directory name that source files with annotated coverage data
should be written to.
=item --annotate-all
diff --git a/bin/verilator_gantt b/bin/verilator_gantt
index ac9683385..701a08788 100755
--- a/bin/verilator_gantt
+++ b/bin/verilator_gantt
@@ -544,9 +544,9 @@ 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
+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
+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.
diff --git a/ci/ci-script.bash b/ci/ci-script.bash
index eb3b828cf..c8a822d5c 100755
--- a/ci/ci-script.bash
+++ b/ci/ci-script.bash
@@ -103,28 +103,64 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
nodist/code_coverage --stages 1- --scenarios=--dist
;;
coverage-vlt-0)
- nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=0/4
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=0/10
;;
coverage-vlt-1)
- nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=1/4
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=1/10
;;
coverage-vlt-2)
- nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=2/4
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=2/10
;;
coverage-vlt-3)
- nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=3/4
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=3/10
+ ;;
+ coverage-vlt-4)
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=4/10
+ ;;
+ coverage-vlt-5)
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=5/10
+ ;;
+ coverage-vlt-6)
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=6/10
+ ;;
+ coverage-vlt-7)
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=7/10
+ ;;
+ coverage-vlt-8)
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=8/10
+ ;;
+ coverage-vlt-9)
+ nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=9/10
;;
coverage-vltmt-0)
- nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=0/4
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=0/10
;;
coverage-vltmt-1)
- nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=1/4
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=1/10
;;
coverage-vltmt-2)
- nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=2/4
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=2/10
;;
coverage-vltmt-3)
- nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=3/4
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=3/10
+ ;;
+ coverage-vltmt-4)
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=4/10
+ ;;
+ coverage-vltmt-5)
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=5/10
+ ;;
+ coverage-vltmt-6)
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=6/10
+ ;;
+ coverage-vltmt-7)
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=7/10
+ ;;
+ coverage-vltmt-8)
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=8/10
+ ;;
+ coverage-vltmt-9)
+ nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=9/10
;;
*)
fatal "Unknown test: $TESTS"
diff --git a/ci/docker/buildenv/README.adoc b/ci/docker/buildenv/README.adoc
deleted file mode 100644
index ed2270eed..000000000
--- a/ci/docker/buildenv/README.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-= Verilator Docker Build Environment
-
-This Verilator Build container is set up to compile and test a Verilator
-build. It uses the following parameters:
-
-* Source repository (default: https://github.com/verilator/verilator)
-* Source revision (default: master)
-* Compiler (GCC 9.3.0, clang 10.0.0, default: 9.3.0)
-
-The container is published as `verilator/verilator-buildenv` on
-https://hub.docker.com/repository/docker/verilator/verilator-buildenv[docker hub].
-
-To run the basic build using the current Verilator master:
-
- docker run -ti verilator/verilator-buildenv
-
-To also run tests:
-
- docker run -ti verilator/verilator-buildenv test
-
-To change the compiler:
-
- docker run -ti -e CC=clang-10 -e CXX=clang++-10 verilator/verilator-buildenv test
-
-The tests that involve gdb are not working due to security restrictions.
-To run those too:
-
-....
-docker run -ti -e CC=clang-10 -e CXX=clang++-10 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
-....
-
-Rather then building using a remote git repository you may prefer to use a
-working copy on the local filesystem. Mount the local working copy path as
-a volume and use that in place of git. When doing this be careful to have
-all changes committed to the local git area. To build the current HEAD from
-top of a repository:
-
-....
-docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
-....
-
-== Rebuilding
-
-To rebuild the Verilator-buildenv docker image, run:
-
- docker build .
-
-This will also build SystemC under all supported compiler variants to
-reduce the SystemC testing time.
diff --git a/ci/docker/buildenv/README.rst b/ci/docker/buildenv/README.rst
new file mode 100644
index 000000000..2dd2c7215
--- /dev/null
+++ b/ci/docker/buildenv/README.rst
@@ -0,0 +1,64 @@
+================================
+Verilator Build Docker Container
+================================
+
+This Verilator Build Docker Container is set up to compile and test a
+Verilator build. It uses the following parameters:
+
+- Source repository (default: https://github.com/verilator/verilator)
+
+- Source revision (default: master)
+
+- Compiler (GCC 9.3.0, clang 10.0.0, default: 9.3.0)
+
+The container is published as ``verilator/verilator-buildenv`` on `docker
+hub
+`__.
+
+To run the basic build using the current Verilator master:
+
+::
+
+ docker run -ti verilator/verilator-buildenv
+
+To also run tests:
+
+::
+
+ docker run -ti verilator/verilator-buildenv test
+
+To change the compiler:
+
+::
+
+ docker run -ti -e CC=clang-10 -e CXX=clang++-10 verilator/verilator-buildenv test
+
+The tests that involve gdb are not working due to security restrictions.
+To run those too:
+
+::
+
+ docker run -ti -e CC=clang-10 -e CXX=clang++-10 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
+
+Rather then building using a remote git repository you may prefer to use a
+working copy on the local filesystem. Mount the local working copy path as
+a volume and use that in place of git. When doing this be careful to have
+all changes committed to the local git area. To build the current HEAD from
+top of a repository:
+
+::
+
+ docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
+
+
+Rebuilding
+==========
+
+To rebuild the Verilator-buildenv docker image, run:
+
+::
+
+ docker build .
+
+This will also build SystemC under all supported compiler variants to
+reduce the SystemC testing time.
diff --git a/ci/docker/run/README.adoc b/ci/docker/run/README.adoc
deleted file mode 100644
index 84321ac06..000000000
--- a/ci/docker/run/README.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-= Verilator Executable Docker Container
-
-The Verilator Executable Docker Container allows you to run Verilator
-easily as a docker image, e.g.:
-
- docker run -ti verilator/verilator:latest --version
-
-This will install the container, run the latest Verilator and print
-Verilator's version.
-
-Containers are automatically built for all released versions, so you may
-easily compare results across versions, e.g.:
-
- docker run -ti verilator/verilator:4.030 --version
-
-Verilator needs to read and write files on the local system. To simplify
-this process, use the `verilator-docker` convenience script. This script
-takes the version number, and all remaining arguments are passed through to
-Verilator. e.g.:
-
- ./verilator-docker 4.030 --version
-
-or
-
- ./verilator-docker 4.030 --cc test.v
-
-If you prefer not to use `verilator-docker` you must give the container
-access to your files as a volume with appropriate user rights. For example
-to Verilate test.v:
-
-....
-docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
-....
-
-This method can only access files below the current directory. An
-alternative is setup the volume `-workdir`.
-
-You can also work in the container by setting the entrypoint
-(don't forget to mount a volume if you want your work persistent):
-
- docker run -ti --entrypoint /bin/bash verilator/verilator:latest
-
-You can also use the container to build Verilator at a specific
-commit:
-
- docker build --build-arg SOURCE_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
-(`verilator-wrap.sh`). That script 1. calls Verilator, and 2. copies the
-Verilated runtime files to the `obj_dir` or the `-Mdir` respectively. This
-allows the user to have the files to they may later build the C++ output
-with the matching runtime files. The wrapper also patches the Verilated
-Makefile accordingly.
-
-There is also a hook defined that is run by docker hub via automated
-builds.
diff --git a/ci/docker/run/README.rst b/ci/docker/run/README.rst
new file mode 100644
index 000000000..c635a9546
--- /dev/null
+++ b/ci/docker/run/README.rst
@@ -0,0 +1,74 @@
+=====================================
+Verilator Executable Docker Container
+=====================================
+
+The Verilator Executable Docker Container allows you to run Verilator
+easily as a docker image, e.g.:
+
+::
+
+ docker run -ti verilator/verilator:latest --version
+
+This will install the container, run the latest Verilator and print
+Verilator's version.
+
+Containers are automatically built for all released versions, so you may
+easily compare results across versions, e.g.:
+
+::
+
+ docker run -ti verilator/verilator:4.030 --version
+
+Verilator needs to read and write files on the local system. To simplify
+this process, use the ``verilator-docker`` convenience script. This script
+takes the version number, and all remaining arguments are passed through to
+Verilator. e.g.:
+
+::
+
+ ./verilator-docker 4.030 --version
+
+or
+
+::
+
+ ./verilator-docker 4.030 --cc test.v
+
+If you prefer not to use ``verilator-docker`` you must give the container
+access to your files as a volume with appropriate user rights. For example
+to Verilate test.v:
+
+::
+
+ docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
+
+This method can only access files below the current directory. An
+alternative is setup the volume ``-workdir``.
+
+You can also work in the container by setting the entrypoint (don't forget
+to mount a volume if you want your work persistent):
+
+::
+
+ docker run -ti --entrypoint /bin/bash verilator/verilator:latest
+
+You can also use the container to build Verilator at a specific commit:
+
+::
+
+ docker build --build-arg SOURCE_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
+(``verilator-wrap.sh``). That script 1. calls Verilator, and 2. copies the
+Verilated runtime files to the ``obj_dir`` or the ``-Mdir``
+respectively. This allows the user to have the files to they may later
+build the C++ output with the matching runtime files. The wrapper also
+patches the Verilated Makefile accordingly.
+
+There is also a hook defined that is run by docker hub via automated
+builds.
diff --git a/configure.ac b/configure.ac
index 5cbb6ffe0..3d7c5ea55 100644
--- a/configure.ac
+++ b/configure.ac
@@ -7,7 +7,7 @@
#AC_INIT([Verilator],[#.### YYYY-MM-DD])
#AC_INIT([Verilator],[#.### devel])
-AC_INIT([Verilator],[4.110 2021-02-25],
+AC_INIT([Verilator],[4.200 2021-03-12],
[https://verilator.org],
[verilator],[https://verilator.org])
# When releasing, also update header of Changes file
diff --git a/docs/CONTRIBUTING.adoc b/docs/CONTRIBUTING.adoc
deleted file mode 100644
index eda1108e6..000000000
--- a/docs/CONTRIBUTING.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-= How to contribute to Verilator
-
-Thanks for using Verilator! We welcome your contributions in whatever form.
-
-This contributing document contains some suggestions that may make
-contributions flow more efficiently.
-
-==== Did you find a bug?
-
-* Please **Ensure the bug was not already reported** by searching
- https://verilator.org/issues[Verilator Issues].
-
-* If you're unable to find an open issue addressing the problem,
- https://verilator.org/issues/new[open a new Verilator issue].
-
-** Be sure to include a **code sample** or an **executable test case**
- demonstrating the bug and expected behavior that is not occurring.
-
-** The ideal example works against other simulators, and is in the
- test_regress/t test format, as described in
- link:internals.adoc[docs/internals].
-
-==== Did you write a patch that fixes a bug?
-
-* Please https://verilator.org/issues/new[Open a new issue].
-
-* You may attach a patch to the issue, or (preferred) may request a GitHub
- pull request.
-
-** Verilator uses GitHub Actions to provide continuous integration. You may
- want to enable Actions on your GitHub branch to ensure your changes
- keep the tests passing. See link:internals.adoc[docs/internals].
-
-* Your source-code contributions must be certified as open source, under
- the https://developercertificate.org/[Developer Certificate of
- Origin]. On your first contribution, you must either:
-
-** Have your patch include the addition of your name to
- link:CONTRIBUTORS[docs/CONTRIBUTORS] (preferred).
-
-** Use "git -s" as part of your commit. This adds a "signed-of-by"
- attribute which will certify your contribution as described in the
- https://github.com/wking/signed-off-by/blob/master/Documentation/SubmittingPatches[Signed-of-By
- convention].
-
-** Email, or post in an issue a statement that you certify your
- contributions.
-
-** In any of these cases your name will be added to
- link:CONTRIBUTORS[docs/CONTRIBUTORS] and you are agreeing all future
- contributions are also certified.
-
-** We occasionally accept contributions where people do not want their name
- published. Please email us; you must still privately certify your
- contribution.
-
-* Your test contributions are generally considered released into the
- Creative Commons Public Domain (CC0), unless you request otherwise or put
- a GNU/Artistic license on your file.
-
-* Most important is we get your patch. If you'd like to clean up
- indentation and related issues ahead of our feedback, that is
- appreciated; please see the coding conventions in
- link:internals.adoc[docs/internals].
-
-==== Do you have questions?
-
-* Please see FAQ section and rest of the
- https://verilator.org/verilator_doc.html[Verilator manual],
- or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-* Ask any question in the
- https://verilator.org/forum[Verilator forum].
-
-==== 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 https://www.contributor-covenant.org/version/1/4/code-of-conduct.html[Contributor
- Covenant version 1.4].
-
-Thanks!
diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst
new file mode 100644
index 000000000..a9ae58e42
--- /dev/null
+++ b/docs/CONTRIBUTING.rst
@@ -0,0 +1,93 @@
+=========================
+Contributing to Verilator
+=========================
+
+Thanks for using Verilator! We welcome your contributions in whatever form.
+
+This contributing document contains some suggestions that may make
+contributions flow more efficiently.
+
+
+Did you find a bug?
+===================
+
+- Please **Ensure the bug was not already reported** by searching
+ `Verilator Issues `__.
+
+- If you're unable to find an open issue addressing the problem, `open a
+ new Verilator issue `__.
+
+ - Be sure to include a **code sample** or an **executable test case**
+ demonstrating the bug and expected behavior that is not occurring.
+
+ - The ideal example works against other simulators, and is in the
+ test_regress/t test format, as described in `docs/internals
+ `__.
+
+
+Did you write a patch that fixes a bug?
+=======================================
+
+- Please `Open a new issue `__.
+
+- You may attach a patch to the issue, or (preferred) may request a
+ GitHub pull request.
+
+ - Verilator uses GitHub Actions to provide continuous integration. You
+ may want to enable Actions on your GitHub branch to ensure your changes
+ keep the tests passing. See `docs/internals `__.
+
+- Your source-code contributions must be certified as open source,
+ under the `Developer Certificate of
+ Origin `__. On your first
+ contribution, you must either:
+
+ - Have your patch include the addition of your name to `docs/CONTRIBUTORS
+ `__ (preferred).
+
+ - Use "git -s" as part of your commit. This adds a "signed-of-by"
+ attribute which will certify your contribution as described in the
+ `Signed-of-By convention
+ `__.
+
+ - Email, or post in an issue a statement that you certify your
+ contributions.
+
+ - In any of these cases your name will be added to `docs/CONTRIBUTORS
+ `__ and you are agreeing all future contributions are
+ also certified.
+
+ - We occasionally accept contributions where people do not want their
+ name published. Please email us; you must still privately certify your
+ contribution.
+
+- Your test contributions are generally considered released into the
+ Creative Commons Public Domain (CC0), unless you request otherwise or
+ put a GNU/Artistic license on your file.
+
+- Most important is we get your patch. If you’d like to clean up
+ indentation and related issues ahead of our feedback, that is
+ appreciated; please see the coding conventions in `docs/internals
+ `__.
+
+
+Do you have questions?
+======================
+
+- Please see FAQ section and rest of the `Verilator
+ manual `__, or `Verilator
+ manual (PDF) `__.
+
+- Ask any question in the `Verilator forum
+ `__.
+
+
+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
+ `__.
+
+Thanks!
diff --git a/docs/CONTRIBUTORS b/docs/CONTRIBUTORS
index f3de9d893..9d35df7de 100644
--- a/docs/CONTRIBUTORS
+++ b/docs/CONTRIBUTORS
@@ -12,6 +12,7 @@ Conor McCullough
Dan Petrisko
David Horton
David Stanford
+David Turner
Driss Hafdi
Edgar E. Iglesias
Eric Rippey
@@ -89,3 +90,4 @@ Yuri Victorovich
Yutetsu TAKATSUKASA
Yves Mathieu
HyungKi Jeong
+Drew Taussig
diff --git a/docs/Makefile.in b/docs/Makefile.in
index 8c755ab43..609b67b19 100644
--- a/docs/Makefile.in
+++ b/docs/Makefile.in
@@ -19,8 +19,8 @@
#### Start of system configuration section. ####
-ASCIIDOCTOR = asciidoctor
DOXYGEN = doxygen
+RST2HTML = rst2html
#### End of system configuration section. ####
######################################################################
@@ -30,8 +30,8 @@ DOXYGEN = doxygen
default:
@echo "error: make not supported here, run 'make docs' from Verilator top-level"
-%.html: %.adoc
- $(ASCIIDOCTOR) $< -n -o $@
+%.html: %.rst
+ $(RST2HTML) $< $@
clean mostlyclean distclean maintainer-clean::
rm -f $(SCRIPTS) *.tmp
diff --git a/docs/install.adoc b/docs/install.adoc
deleted file mode 100644
index 2cf4498b6..000000000
--- a/docs/install.adoc
+++ /dev/null
@@ -1,303 +0,0 @@
-= Verilator Installation
-:toc: right
-
-// Github doesn't render unless absolute URL
-image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
-
-== Introduction
-
-This discusses how to install Verilator. For more general information
-please see https://verilator.org[verilator.org].
-
-== Quick-start
-
-=== Install From a Package Manager
-
-Using a distribution's package manager is the easiest way to get
-started. (Note packages are unlikely to have the most recent version, so
-Git, below, maybe a better alternative.) To install as a package:
-
- apt-get install verilator
-
-If this works, skip down to <>.
-
-=== Docker
-
-Verilator is available in pre-built Docker containers. See
-https://github.com/verilator/verilator/blob/master/ci/docker/run/README.adoc
-
-=== Git
-
-Installing Verilator with Git provides the most flexibility.
-For additional options and details see the additional sections below. In
-brief:
-
-// Also update README
-....
-# Prerequisites:
-#sudo apt-get install git make autoconf g++ flex bison
-#sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)
-#sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error)
-
-git clone 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 <>.
-
-== 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 <>.
-
-=== 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.adoc):
-
- 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
-https://www.accellera.org/downloads/standards/systemc[SystemC].
-Follow their installation instructions. You will need to set `SYSTEMC_INCLUDE`
-to point to the include directory with `systemc.h` in it, and `SYSTEMC_LIBDIR`
-to points to the directory with `libsystemc.a` in it. (Older installations
-may set `SYSTEMC` and `SYSTEMC_ARCH` instead.)
-
-==== Install GTKWave
-
-To make use of Verilator FST tracing you will want
-http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not
-required at Verilator build time.
-
-=== Obtain Sources
-
-You may use Git or a tarball for the sources. Git is the supported option.
-(If using a historical build that uses a tarball, tarballs are obtained
-from https://www.veripool.org/projects/verilator/wiki/Download[Verilator
-Downloads]; we presume you know how to use it, and is not described here.)
-
-Get the sources from the repository: (You need do this only once, ever.)
-
- git clone 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
-http://modules.sourceforge.net/[modulecmd], you'll want a module file like
-the following:
-
-.modulecmd's verilator/version file
-----
-set install_root /CAD_DISK/verilator/{version-number-used-above}
-unsetenv VERILATOR_ROOT
-prepend-path PATH $install_root/bin
-prepend-path MANPATH $install_root/man
-prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
-----
-
-==== 3. Install into a Specific Path
-
-You may eventually install Verilator into a specific installation prefix,
-as most GNU tools support:
-
- unset VERILATOR_ROOT # if your shell is bash
- unsetenv VERILATOR_ROOT # if your shell is csh
- ./configure --prefix /opt/verilator-VERSION
-
-Then after installing (below steps) you will need to add
-`/opt/verilator-VERSION/bin` to `$PATH`.
-
-==== 4. Install System Globally
-
-The final option is to eventually install Verilator globally, using the
-normal system paths:
-
- unset VERILATOR_ROOT # if your shell is bash
- unsetenv VERILATOR_ROOT # if your shell is csh
- ./configure
-
-Then after installing (below) the binary directories should already be in
-your `$PATH`.
-
-=== Configure
-
-The command to configure the package was described in the previous step.
-Developers should configure to have more complete developer tests.
-Additional packages may be required for these tests.
-
- export VERILATOR_AUTHOR_SITE=1 # Put in your .bashrc
- ./configure --enable-longtests ...above options...
-
-=== Compile
-
-Compile Verilator:
-
- make -j
-
-=== Test
-
-Check the compilation by running self-tests:
-
- make test
-
-=== Install
-
-If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
-install to the OS-standard place:
-
- make install
-
-== Running Verilator
-
-To run Verilator, see the example sections in the
-https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
-or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-Also see the `examples/` directory that is part of the kit, and is installed
-(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
-
- cd examples/make_hello_c
- make
-
-Note if you did a `make install` above you should not have `VERILATOR_ROOT`
-set in your environment; it is built into the executable.
-
-== Announcements
-
-To get notified of new releases, go to
-https://github.com/verilator/verilator-announce[Verilator announcement
-repository] and follow the instructions there.
-
-== Directory Structure
-
-Some relevant files and directories in this package are as follows:
-
- Changes => Version history
- README.adoc => This document
- bin/verilator => Compiler wrapper invoked to Verilate code
- docs/ => Additional documentation
- examples/make_hello_c => Example GNU-make simple Verilog->C++ conversion
- examples/make_hello_sc => Example GNU-make simple Verilog->SystemC conversion
- examples/make_tracing_c => Example GNU-make Verilog->C++ with tracing
- examples/make_tracing_sc => Example GNU-make Verilog->SystemC with tracing
- examples/make_protect_lib => Example using --protect-lib
- examples/cmake_hello_c => Example building make_hello_c with CMake
- examples/cmake_hello_sc => Example building make_hello_sc with CMake
- examples/cmake_tracing_c => Example building make_tracing_c with CMake
- examples/cmake_tracing_sc => Example building make_tracing_sc with CMake
- examples/cmake_protect_lib => Example building make_protect_lib with CMake
- include/ => Files that should be in your -I compiler path
- include/verilated*.cpp => Global routines to link into your simulator
- include/verilated*.h => Global headers
- include/verilated.mk => Common Makefile
- src/ => Translator source code
- test_regress => Internal tests
-
-For files created after a design is Verilated, see the
-https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
-or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-== License
-
-Copyright 2008-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.
-// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
diff --git a/docs/install.rst b/docs/install.rst
new file mode 100644
index 000000000..0a47b3822
--- /dev/null
+++ b/docs/install.rst
@@ -0,0 +1,397 @@
+|Logo|
+
+======================
+Verilator Installation
+======================
+
+.. contents::
+ :depth: 3
+
+Introduction
+============
+
+This discusses how to install Verilator. For more general information
+please see `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
+`__. 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
+`__ 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
+`__; 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
+`__, 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)
+`__, or `Verilator manual (PDF)
+`__.
+
+Also see the ``examples/`` directory that is part of the kit, and is
+installed (in a OS-specific place, often in e.g.
+``/usr/local/share/verilator/examples``).
+
+::
+
+ cd examples/make_hello_c
+ make
+
+Note if you did a ``make install`` above you should not have
+``VERILATOR_ROOT`` set in your environment; it is built into the
+executable.
+
+
+Announcements
+=============
+
+To get notified of new releases, go to `Verilator announcement repository
+`__ 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) `__, or `Verilator
+manual (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
diff --git a/docs/internals.adoc b/docs/internals.adoc
deleted file mode 100644
index 0a2f64909..000000000
--- a/docs/internals.adoc
+++ /dev/null
@@ -1,1030 +0,0 @@
-= Verilator Internals Documentation
-:toc: right
-
-// Github doesn't render unless absolute URL
-image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
-
-== Introduction
-
-This file discusses internal and programming details for Verilator. It's a
-reference for developers and debugging problems.
-
-See also the Verilator internals presentation at https://www.veripool.org.
-
-== Code Flows
-
-=== Verilator Flow
-
-The main flow of Verilator can be followed by reading the Verilator.cpp
-`process()` function:
-
-. First, the files specified on the command line are read. Reading
-involves preprocessing, then lexical analysis with Flex and parsing with
-Bison. This produces an abstract syntax tree (AST) representation of the
-design, which is what is visible in the .tree files described below.
-
-. Verilator then makes a series of passes over the AST, progressively
-refining and optimizing it.
-
-. Cells in the AST first linked, which will read and parse additional files
-as above.
-
-. Functions, variable and other references are linked to their definitions.
-
-. Parameters are resolved and the design is elaborated.
-
-. Verilator then performs many additional edits and optimizations on the
-hierarchical design. This includes coverage, assertions, X elimination,
-inlining, constant propagation, and dead code elimination.
-
-. References in the design are then pseudo-flattened. Each module's
-variables and functions get "Scope" references. A scope reference is an
-occurrence of that un-flattened variable in the flattened hierarchy. A
-module that occurs only once in the hierarchy will have a single scope and
-single VarScope for each variable. A module that occurs twice will have a
-scope for each occurrence, and two VarScopes for each variable. This
-allows optimizations to proceed across the flattened design, while still
-preserving the hierarchy.
-
-. Additional edits and optimizations proceed on the pseudo-flat design.
-These include module references, function inlining, loop unrolling,
-variable lifetime analysis, lookup table creation, always splitting, and
-logic gate simplifications (pushing inverters, etc).
-
-. Verilator orders the code. Best case, this results in a single "eval"
-function which has all always statements flowing from top to bottom with no
-loops.
-
-. Verilator mostly removes the flattening, so that code may be shared
-between multiple invocations of the same module. It localizes variables,
-combines identical functions, expands macros to C primitives, adds branch
-prediction hints, and performs additional constant propagation.
-
-. Verilator finally writes the C++ modules.
-
-=== 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. `AstGenerate` for a generate block) or groups of components
-(e.g. `AstNodeFTask` for functions and tasks, which in turn has `AstFunc`
-and `AstTask` as derived classes). An important property of the `AstNode`
-type hierarchy is that all non-final subclasses of `AstNode` (i.e.: those
-which themselves have subclasses) must be abstract as well, and be named
-with the prefix `AstNode*`. The `astgen` (see below) script relies on this.
-
-Each `AstNode` has pointers to up to four children, accessed by the `op1p`
-through `op4p` methods. These methods are then abstracted in a specific
-Ast* node class to a more specific name. For example with the `AstIf` node
-(for `if` statements), `ifsp` calls `op2p` to give the pointer to the AST
-for the "then" block, while `elsesp` calls `op3p` to give the pointer to
-the AST for the "else" block, or NULL if there is not one.
-
-`AstNode` has the concept of a next and previous AST - for example the next
-and previous statements in a block. Pointers to the AST for these
-statements (if they exist) can be obtained using the `back` and `next`
-methods.
-
-It is useful to remember that the derived class `AstNetlist` is at the top
-of the tree, so checking for this class is the standard way to see if you
-are at the top of the tree.
-
-By convention, each function/method uses the variable `nodep` as a 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
-instance of the visitor class, which in turn implements a method to perform
-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
-provided to manipulate the graphs and to output them in
-https://www.graphviz.org[GraphViz] dot format. `V3Graph.h` provides
-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 algorithms
-for ordering the graph. A generic `user`/`userp` member variable is also
-provided.
-
-Virtual methods are provided to specify the name, color, shape and style to
-be used in dot output. Typically users provide derived classes from
-`V3GraphVertex` which will reimplement these methods.
-
-Iterators are provided to access in and out edges. Typically these are used
-in the form:
-
- for (V3GraphEdge *edgep = vertexp->inBeginp();
- edgep;
- edgep = edgep->inNextp()) {
-
-==== `V3GraphEdge`
-
-`V3GraphEdge` is the base class for directed edges between pairs of
-vertices. Edges have an associated `weight` and may also be made
-`cutable`. A generic `user`/`userp` member variable is also provided.
-
-Accessors, `fromp` and `top` return the "from" and "to" vertices
-respectively.
-
-Virtual methods are provided to specify the label, color and style to be
-used in dot output. Typically users provided derived classes from
-`V3GraphEdge` which will reimplement these methods.
-
-==== `V3GraphAlg`
-
-This is the base class for graph algorithms. It implements a `bool` method,
-`followEdge` which algorithms can use to decide whether an edge is
-followed. This method returns true if the graph edge has weight greater
-than one and a user function, `edgeFuncp` (supplied in the constructor)
-returns `true`.
-
-A number of predefined derived algorithm classes and access methods are
-provided and documented in `V3GraphAlg.cpp`.
-
-=== Multithreaded Mode
-
-In `--threads` mode, the frontend of the Verilator pipeline is the same as
-serial mode, up until V3Order.
-
-`V3Order` builds a fine-grained, statement-level dependency graph that
-governs the ordering of code within a single `eval()` call. In serial mode,
-that dependency graph is used to order all statements into a total serial
-order. In parallel mode, the same dependency graph is the starting point
-for a partitioner (`V3Partition`).
-
-The partitioner's goal is to coarsen the fine-grained graph into a coarser
-graph, while maintaining as much available parallelism as possible. Often
-the partitioner can transform an input graph with millions of nodes into a
-coarsened execution graph with a few dozen nodes, while maintaining enough
-parallelism to take advantage of a modern multicore CPU. Runtime
-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_.
-
-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
-through the graph. This is the speedup you would get from running the graph
-in parallel, if given infinite CPU cores available and communication and
-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
-coarsened graph are "macro-tasks". This term comes from Sarkar. Each
-macro-task executes from start to end on one processor, without any
-synchronization to any other macro-task during its
-execution. (Synchronization only happens before the macro-task begins or
-after it 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
-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
-cost, plus the critical path from the end of the node to the end of the
-graph.
-
-Sarkar calls out an important trade-off: coarsening the graph reduces
-runtime synchronization overhead among the macro-tasks, but it tends to
-increase the critical path through the graph and thus reduces par-factor.
-
-Sarkar's partitioner, and ours, chooses pairs of macro-tasks to merge such
-that the growth in critical path is minimized. Each candidate merge would
-result in a new node, which would have some local critical path. We choose
-the candidate that would produce the shortest local critical path. Repeat
-until par-factor falls to a target threshold. It's a greedy algorithm, and
-it's not guaranteed to produce the best partition (which Sarkar proves is
-NP-hard).
-
-==== 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
-cost which is simply the sum of its tasks' costs. We assume that
-communication overhead and synchronization overhead are zero, so the cost
-of any given path through the graph is simply the sum of macro-task
-execution costs. Sarkar does almost the same thing, except that he has
-nonzero estimates for synchronization costs.
-
-Verilator's cost estimates are assigned by `InstrCountCostVisitor`. This
-class is perhaps the most fragile piece of the multithread implementation.
-It's easy to have a bug where you count something cheap (eg. accessing one
-element of a huge array) as if it were expensive (eg. by counting it as if
-it were an access to the entire array.) Even without such gross bugs, the
-estimates this produce are only loosely predictive of actual runtime cost.
-Multithread performance would be better with better 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 at
-runtime, with a runtime graph follower. Sarkar calls this the
-"macro-dataflow model." Verilator does not support this; early experiments
-with this approach had poor performance.
-
-The other option is to statically assign macro-tasks to threads, with each
-thread running its macro-tasks in a static order. Sarkar describes this in
-Chapter 5. Verilator takes this static approach. The only dynamic aspect is
-that each macro task may block before starting, to wait until its
-prerequisites on other threads have finished.
-
-The synchronization cost is cheap if the prereqs are done. If they're not,
-fragmentation (idle CPU cores waiting) is possible. This is the major
-source of overhead in this approach. The `--prof-threads` switch and the
-`verilator_gantt` script can visualize the time lost to such 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
-memory. This provides "spatial locality" -- when we pull in a 64-byte
-cache line to access a 2-byte variable, we want the other 62 bytes to be
-ones we'll also likely access soon, for best cache performance.
-
-This turns out to be critical for performance. It should allow Verilator to
-scale to very large models. We don't rely on our working set fitting in any
-CPU cache; instead we essentially "stream" data into caches from
-memory. It's not literally streaming, where the address increases
-monotonically, but it should have similar performance characteristics, so
-long as each macro-task's dataset fits in one core's local caches.
-
-To achieve spatial locality, we tag each variable with the set of
-macro-tasks that access it. Let's call this set the "footprint" of that
-variable. The variables in a given module have a set of footprints. We can
-order those footprints to minimize the distance between them (distance is
-the number of macro-tasks that are different across any two footprints) and
-then emit all variables into the struct in ordered-footprint order.
-
-The footprint ordering is literally the traveling salesman problem, and we
-use a TSP-approximation algorithm to get close to an optimal sort.
-
-This is an old idea. Simulators designed at DEC in the early 1990s used
-similar techniques to optimize both single-thread and multi-thread modes.
-(Verilator does not optimize variable placement for spatial 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
-before `eval()` is called or continues after `eval()` returns. For now all
-work on a cycle happens during the `eval()` call, leaving Verilator's
-threads idle while the testbench (everything outside `eval()`) is
-working. This would involve fundamental changes within the partitioner,
-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
-entire core to scheduling, so that scheduler data structures would fit in
-its L1 cache and thus the cost of traversing priority-ordered ready lists
-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
-macro-tasks into the threads also at run time. Say, re-pack once every
-10,000 cycles or something. This has the potential to do better than our
-static estimates about macro-task run times. It could potentially react to
-CPU cores that aren't performing equally, due to NUMA or thermal throttling
-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
-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
-runtime. That variance is magnified if MTasks are homogeneous, containing
-similar repeating logic which was generally close together in source code
-and which is still packed together even after going through Verilator's
-digestive tract.
-
-If Verilator could avoid doing that, and instead would take source logic
-that was close together and distribute it across MTasks, that would
-increase the diversity of any given MTask, and this should reduce variance
-in the cost estimates.
-
-One way to do that might be to make various "tie breaker" comparison
-routines in the sources to rely more heavily on randomness, and generally
-try harder not to keep input nodes together when we have the 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
-modes. This would help to avoid performance regressions, and also to
-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
-the variable sort will be suboptimal for either instance. A possible
-improvement would be to emit a unique class for each instance of a module,
-and sort its variables optimally for that instance's code stream.
-
-=== Verilated Flow
-
-The evaluation loop outputted by Verilator is designed to allow a single
-function to perform evaluation under most situations.
-
-On the first evaluation, the Verilated code calls initial blocks, and then
-"settles" the modules, by evaluating functions (from always statements)
-until all signals are stable.
-
-On other evaluations, the Verilated code detects what input signals have
-changes. If any are clocks, it calls the appropriate sequential functions
-(from `always @ posedge` statements). Interspersed with sequential functions
-it calls combo functions (from `always @*`). After this is complete, it
-detects any changes due to combo loops or internally generated clocks, and
-if one is found must reevaluate the model again.
-
-For SystemC code, the `eval()` function is wrapped in a SystemC
-`SC_METHOD`, sensitive to all inputs. (Ideally it would only be sensitive
-to clocks and combo inputs, but tracing requires all signals to cause
-evaluation, and the performance difference is small.)
-
-If tracing is enabled, a callback examines all variables in the design for
-changes, and writes the trace for each change. To accelerate this process
-the evaluation process records a bitmask of variables that might have
-changed; if clear, checking those signals for changes may be skipped.
-
-== Coding Conventions
-
-=== Compiler Version and C++11
-
-Verilator requires C++11. Verilator does not require any newer versions,
-but is maintained to build successfully with C++14/C++17/C++20.
-
-=== Indentation and Naming Style
-
-We will work with contributors to fix up indentation style issues, but it
-is appreciated if you could match our style:
-
-* All files should contain the magic header to ensure standard indentation:
-+
- // -*- mode: C++; c-file-style: "cc-mode" -*-
-+
-This sets indentation to the `cc-mode` defaults. (Verilator predates a
-CC-mode change of several years ago which overrides the defaults with GNU
-style indentation; the `c-set-style` undoes that.)
-
-* Use "mixedCapsSymbols" instead of "underlined_symbols".
-
-* Uas a "p" suffix on variables that are pointers, e.g. "nodep".
-
-* Comment every member variable.
-
-Indentation is automatically maintained with "make format" using
-clang-format version 10.0.0, and yapf for python, and is automatically
-corrected in the CI actions. For those manually formatting C++ code:
-
-* Use 4 spaces per level, and no tabs.
-
-* Use 2 spaces between the end of source and the beginning of a comment.
-
-* Use 1 space after if/for/switch/while and similar keywords.
-
-* No spaces before semicolons, nor between a function's name and open
-parenthesis (only applies to functions; if/else has a following space).
-
-=== The `astgen` Script
-
-Some of the code implementing passes is extremely repetitive, and must be
-implemented for each sub-class of `AstNode`. However, while repetitive,
-there is more variability than can be handled in C++ macros.
-
-In Verilator this is implemented by using a Perl script, `astgen` to
-pre-process the C++ code. For example in `V3Const.cpp` this is used to
-implement the `visit()` functions for each binary operation using the
-`TREEOP` macro.
-
-The original C++ source code is transformed into C++ code in the `obj_opt`
-and `obj_dbg` sub-directories (the former for the optimized version of
-Verilator, the latter for the debug version). So for example `V3Const.cpp`
-into `V3Const__gen.cpp`.
-
-=== Visitor Functions
-
-Verilator uses the "Visitor" design pattern to implement its refinement and
-optimization passes. This allows separation of the pass algorithm from the
-AST on which it operates. Wikipedia provides an introduction to the concept
-at https://en.wikipedia.org/wiki/Visitor_pattern.
-
-As noted above, all visitors are derived classes of `AstNVisitor`. All
-derived classes of `AstNode` implement the `accept` method, which takes as
-argument a reference to an instance or a `AstNVisitor` derived class and
-applies the visit method of the `AstNVisitor` to the invoking AstNode
-instance (i.e. `this`).
-
-One possible difficulty is that a call to `accept` may perform an edit
-which destroys the node it receives as argument. The
-`acceptSubtreeReturnEdits` method of `AstNode` is provided to apply
-`accept` and return the resulting node, even if the original node is
-destroyed (if it is not destroyed it will just return the original node).
-
-The behavior of the visitor classes is achieved by overloading the `visit`
-function for the different `AstNode` derived classes. If a specific
-implementation is not found, the system will look in turn for overloaded
-implementations up the inheritance hierarchy. For example calling `accept`
-on `AstIf` will look in turn for:
-
- void visit(AstIf* nodep)
- void visit(AstNodeIf* nodep)
- void visit(AstNodeStmt* nodep)
- void visit(AstNode* nodep)
-
-There are three ways data is passed between visitor functions.
-
-1. A visitor-class member variable. This is generally for passing "parent"
-information down to children. `m_modp` is a common example. It's set to
-NULL in the constructor, where that node (`AstModule` visitor) sets it,
-then the children are iterated, then it's cleared. Children under an
-`AstModule` will see it set, while nodes elsewhere will see it clear. If
-there can be nested items (for example an `AstFor` under an `AstFor`) the
-variable needs to be save-set-restored in the `AstFor` visitor, otherwise
-exiting the lower for will lose the upper for's setting.
-
-2. User attributes. Each `AstNode` (*Note.* The AST node, not the visitor)
-has five user attributes, which may be accessed as an integer using the
-`user1()` through `user5()` methods, or as a pointer (of type `AstNUser`)
-using the `user1p()` through `user5p()` methods (a common technique lifted
-from graph traversal packages).
-+
-A visitor first clears the one it wants to use by calling
-`AstNode::user#ClearTree()`, then it can mark any node's `user#()` with whatever
-data it wants. Readers just call `nodep->user()`, but may need to cast
-appropriately, so you'll often see `VN_CAST(nodep->userp(), SOMETYPE)`.
-At the top of each visitor are comments describing how the `user()` stuff
-applies to that visitor class. For example:
-+
- // NODE STATE
- // Cleared entire netlist
- // AstModule::user1p() // bool. True to inline this module
-+
-This says that at the `AstNetlist` `user1ClearTree()` is called. Each
-`AstModule`'s `user1()` is used to indicate if we're going to inline it.
-+
-These comments are important to make sure a `user#()` on a given `AstNode`
-type is never being used for two different purposes.
-+
-Note that calling `user#ClearTree` is fast, it doesn't walk the tree, so
-it's ok to call fairly often. For example, it's commonly called on every
-module.
-
-3. Parameters can be passed between the visitors in close to the "normal"
-function caller to callee way. This is the second `vup` parameter of type
-`AstNUser` that is ignored on most of the visitor functions. V3Width does
-this, but it proved more messy than the above and is deprecated. (V3Width
-was nearly the first module written. Someday this scheme may be removed,
-as it slows the program down to have to pass vup everywhere.)
-
-=== Iterators
-
-`AstNVisitor` provides a set of iterators to facilitate walking over the
-tree. Each operates on the current `AstNVisitor` class (as this) and takes
-an argument type `AstNode*`.
-
-`iterate`::
-
-Applies the `accept` method of the `AstNode` to the visitor function.
-
-`iterateAndNextIgnoreEdit`::
-
-Applies the `accept` method of each `AstNode` in a list (i.e. connected by
-`nextp` and `backp` pointers).
-
-`iterateAndNextNull`::
-
-Applies the `accept` method of each `AstNode` in a list, only if the
-provided node is non-NULL. If a node is edited by the call to `accept`,
-apply `accept` again, until the node does not change.
-
-`iterateListBackwards`::
-
-Applies the `accept` method of each `AstNode` in a list, starting with the
-last one.
-
-`iterateChildren`::
-
-Applies the `iterateAndNextNull` method on each child `op1p` through `op4p`
-in turn.
-
-`iterateChildrenBackwards`::
-
-Applies the `iterateListBackwards` method on each child `op1p` through
-`op4p` in turn.
-
-==== 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 needs
-to be aware that calling iteration may cause the children to change. For
-example:
-
- // nodep->lhsp() is 0x1234000
- iterateAndNextNull(nodep->lhsp()); // and under covers nodep->lhsp() changes
- // nodep->lhsp() is 0x5678400
- iterateAndNextNull(nodep->lhsp());
-
-Will work fine, as even if the first iterate causes a new node to take the
-place of the `lhsp()`, that edit will update `nodep->lhsp()` and the second
-call will correctly see the change. Alternatively:
-
- lp = nodep->lhsp();
- // nodep->lhsp() is 0x1234000, lp is 0x1234000
- iterateAndNextNull(lp); **lhsp=NULL;** // and under covers nodep->lhsp() changes
- // nodep->lhsp() is 0x5678400, lp is 0x1234000
- iterateAndNextNull(lp);
-
-This will cause bugs or a core dump, as lp is a dangling pointer. Thus it
-is advisable to set lhsp=NULL shown in the *'s above to make sure these
-dangles are avoided. Another alternative used in special cases mostly in
-V3Width is to use acceptSubtreeReturnEdits, which operates on a single node
-and returns the new pointer if any. Note acceptSubtreeReturnEdits does not
-follow `nextp()` links.
-
- lp = acceptSubtreeReturnEdits(lp)
-
-=== Identifying Derived Classes
-
-A common requirement is to identify the specific `AstNode` class we are
-dealing with. For example a visitor might not implement separate `visit`
-methods for `AstIf` and `AstGenIf`, but just a single method for the base
-class:
-
- void visit(AstNodeIf* nodep)
-
-However that method might want to specify additional code if it is called
-for `AstGenIf`. Verilator does this by providing a `VN_IS` method for each
-possible node type, which returns true if the node is of that type (or
-derived from that type). So our `visit` method could use:
-
- if (VN_IS(nodep, AstGenIf) {
-
- }
-
-Additionally the `VN_CAST` method converts pointers similar to C++
-`dynamic_cast`. This either returns a pointer to the object cast to that
-type (if it is of class `SOMETYPE`, or a derived class of `SOMETYPE`) or
-else NULL. (However, for true/false tests use `VN_IS` as that is faster.)
-
-== Testing
-
-For an overview of how to write a test see the BUGS section of the
-Verilator primary manual.
-
-It is important to add tests for failures as well as success (for example
-to check that an error message is correctly triggered).
-
-Tests that fail should by convention have the suffix `_bad` in their name,
-and include `fails = 1` in either their `compile` or `execute` step as
-appropriate.
-
-=== Preparing to Run Tests
-
-For all tests to pass you must install the following packages:
-
-* SystemC to compile the SystemC outputs, see http://systemc.org
-
-* Parallel::Forker from CPAN to run tests in parallel, you can install this
-with e.g. "sudo cpan install Parallel::Forker".
-
-* vcddiff to find differences in VCD outputs. See the readme at
-https://github.com/veripool/vcddiff
-
-* Cmake for build paths that use it.
-
-=== Controlling the Test Driver
-
-Test drivers are written in PERL. All invoke the main test driver script,
-which can provide detailed help on all the features available when writing
-a test driver.
-
- test_regress/driver.pl --help
-
-For convenience, a summary of the most commonly used features is provided
-here. All drivers require a call to `compile` subroutine to compile the
-test. For run-time tests, this is followed by a call to the `execute`
-subroutine. Both of these functions can optionally be provided with a hash
-table as argument specifying additional options.
-
-The test driver assumes by default that the source Verilog file name
-matches the PERL driver name. So a test whose driver is `t/t_mytest.pl`
-will expect a Verilog source file `t/t_mytest.v`. This can be changed
-using the `top_filename` subroutine, for example
-
- top_filename("t/t_myothertest.v");
-
-By default all tests will run with major simulators (Icarus Verilog, NC,
-VCS, ModelSim, etc) as well as Verilator, to allow results to be
-compared. However if you wish a test only to be used with Verilator, you
-can use the following:
-
- scenarios(vlt => 1);
-
-Of the many options that can be set through arguments to `compiler` and
-`execute`, the following are particularly useful:
-
-`verilator_flags2`::
-
-A list of flags to be passed to verilator when compiling.
-
-`fails`::
-
-Set to 1 to indicate that the compilation or execution is intended to fail.
-
-For example the following would specify that compilation requires two
-defines and is expected to fail.
-
- compile(
- verilator_flags2 => ["-DSMALL_CLOCK -DGATED_COMMENT"],
- fails => 1,
- );
-
-=== Regression Testing for Developers
-
-Developers will also want to call ./configure with two extra flags:
-
-`--enable-ccwarn`::
-
-Causes the build to stop on warnings as well as errors. A good way to
-ensure no sloppy code gets added, however it can be painful when it comes
-to testing, since third party code used in the tests (e.g. SystemC) may not
-be warning free.
-
-`--enable-longtests`::
-
-In addition to the standard C, SystemC examples, also run the tests in the
-`test_regress` directory when using _make test_'. This is disabled by
-default as SystemC installation problems would otherwise falsely indicate a
-Verilator problem.
-
-When enabling the long tests, some additional PERL modules are needed,
-which you can install using cpan.
-
- cpan install Parallel::Forker
-
-There are some traps to avoid when running regression tests
-
-* When checking the MANIFEST, the test will barf on unexpected code in the
-Verilator tree. So make sure to keep any such code outside the tree.
-
-* Not all Linux systems install Perldoc by default. This is needed for the
-`--help_' option to Verilator, and also for regression testing. This can be
-installed using cpan:
-+
- cpan install Pod::Perldoc
-+
-Many Linux systems also offer a standard package for this. Red
-Hat/Fedora/Centos offer _perl-Pod-Perldoc_', while Debian/Ubuntu/Linux Mint
-offer `perl-doc'.
-
-* Running regression may exhaust resources on some Linux systems,
-particularly file handles and user processes. Increase these to
-respectively 16,384 and 4,096. The method of doing this is system
-dependent, but on Fedora Linux it would require editing the
-`/etc/security/limits.conf` file as root.
-
-=== Manual Test Execution
-
-A specific regression test can be executed manually. To start the "EXAMPLE"
-test, run the following command.
-
- test_regress/t/t_EXAMPLE.pl
-
-=== Continuous Integration
-
-Verilator uses GitHub Actions which automatically tests the master branch
-for test failures on new commits. It also runs a daily cron job to validate
-all of the tests against different OS and compiler versions.
-
-Developers can enable Actions on their GitHub repository so that the CI
-environment can check their branches too by enabling the build workflow:
-
-* On GitHub, navigate to the main page of the repository.
-* Under your repository name, click Actions.
-* In the left sidebar, click the workflow you want to enable ("build").
-* Click Enable workflow.
-
-=== Fuzzing
-
-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 http://lcamtuf.coredump.cx/afl/[American fuzzy lop]
-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.
-
-== Debugging
-
-=== Debug Levels
-
-The "UINFO" calls in the source indicate a debug level. Messages level 3
-and below are globally enabled with `--debug`. Higher levels may be
-controlled with `--debugi `. An individual source file levels may
-be controlled with `-debugi- `. For example `--debug
---debugi 5 --debugi-V3Width 9` will use the debug binary at default debug
-level 5, with the V3Width.cpp file at level 9.
-
-=== --debug
-
-When you run with `--debug` there are two primary output file types placed
-into the obj_dir, .tree and .dot files.
-
-=== .dot Output
-
-Dot files are dumps of internal graphs in
-https://www.graphviz.org[Graphviz] dot format. When a dot file is dumped,
-Verilator will also print a line on stdout that can be used to format the
-output, for example:
-
- dot -Tps -o ~/a.ps obj_dir/Vtop_foo.dot
-
-You can then print a.ps. You may prefer gif format, which doesn't get
-scaled so can be more useful with large graphs.
-
-For interactive graph viewing consider
-https://github.com/jrfonseca/xdot.py[xdot] or
-http://zvtm.sourceforge.net/zgrviewer.html[ZGRViewer]. If you know of
-better viewers (especially for large graphs) please let us know.
-
-=== .tree Output
-
-Tree files are dumps of the AST Tree and are produced between every major
-algorithmic stage. An example:
-
- NETLIST 0x90fb00 {a0ah}
- 1: MODULE 0x912b20 {a8ah} top L2 [P]
- *1:2: VAR 0x91a780 {a22ah} @dt=0xa2e640(w32) out_wide [O] WIRE
- 1:2:1: BASICDTYPE 0xa2e640 {e24ah} @dt=this(sw32) integer kwd=integer range=[31:0]
-
-The following summarizes the above example dump, with more detail on each
-field in the section below.
-
-[cols="20%,80%"]
-|===
-
-|`1:2:` | indicates the hierarchy of the `VAR` is the `op2p` pointer under
-the `MODULE`, which in turn is the `op1p` pointer under the `NETLIST`
-
-|`VAR` | is the AstNodeType.
-
-| `0x91a780` | is the address of this node.
-
-| `` | means the 74th edit to the netlist was the last modification to
-this node.
-
-| `{a22ah}` | indicates this node is related to the source filename "a",
-where "a" is the first file read, "z" the 26th, and "aa" the 27th. Then
-line 22 in that file, then column 8 (aa=0, az=25, ba=26, ...).
-
-| `@dt=0x...` | indicates the address of the data type this node contains.
-
-| `w32` | indicates the width is 32 bits.
-
-| `out_wide` | is the name of the node, in this case the name of the variable.
-
-| `[O]` | are flags which vary with the type of node, in this case it means the
-variable is an output.
-
-|===
-
-In more detail the following fields are dumped common to all nodes. They
-are produced by the `AstNode::dump()` method:
-
-Tree Hierarchy::
-
-The dump lines begin with numbers and colons to indicate the child node
-hierarchy. As noted above, `AstNode` has lists of items at the same level
-in the AST, connected by the `nextp()` and `prevp()` pointers. These appear
-as nodes at the same level. For example after inlining:
-
- NETLIST 0x929c1c8 {a0} w0
- 1: MODULE 0x92bac80 {e14} w0 TOP_t L1 [P]
- 1:1: CELLINLINE 0x92bab18 {e14} w0 v -> t
- 1:1: CELLINLINE 0x92bc1d8 {e24} w0 v__DOT__i_test_gen -> test_gen
- ...
- 1: MODULE 0x92b9bb0 {e47} w0 test_gen L3
- ...
-
-AstNode type::
-
-The textual name of this node AST type (always in capitals). Many of these
-correspond directly to Verilog entities (for example `MODULE` and
-`TASK`), but others are internal to Verilator (for example `NETLIST` and
-`BASICDTYPE`).
-
-Address of the node::
-
-A hexadecimal address of the node in memory. Useful for examining with the
-debugger. If the actual address values are not important, then using the
-`--dump-tree-addrids` option will convert address values to short identifiers
-of the form `([A-Z]*)`, which is hopefully easier for the reader to cross
-reference throughout the dump.
-
-Last edit number::
-
-Of the form `` or `` , where `nnnn` is the number
-of the last edit to modify this node. The trailing `#` indicates the node
-has been edited since the last tree dump (which typically means in the last
-refinement or optimization pass). GDB can watch for this, see << /Debugging >>.
-
-Source file and line::
-
-Of the form `{xxnnnn}`, where C{xx} is the filename letter (or
-letters) and `nnnn` is the line number within that file. The first file is
-`a`, the 26th is `z`, the 27th is `aa` and so on.
-
-User pointers::
-
-Shows the value of the node's user1p...user5p, if non-NULL.
-
-Data type::
-
-Many nodes have an explicit data type. "@dt=0x..." indicates the address
-of the data type (AstNodeDType) this node uses.
-+
-If a data type is present and is numeric, it then prints the width of the
-item. This field is a sequence of flag characters and width data as follows:
-+
-* `s` if the node is signed.
-* `d` if the node is a double (i.e a floating point entity).
-* `w` always present, indicating this is the width field.
-* `u` if the node is unsized.
-* `/nnnn` if the node is unsized, where `nnnn` is the minimum width.
-
-Name of the entity represented by the node if it exists::
-
-For example for a `VAR` it is the name of the variable.
-
-Many nodes follow these fields with additional node specific
-information. Thus the `VARREF` node will print either `[LV]` or `[RV]`
-to indicate a left value or right value, followed by the node of the
-variable being referred to. For example:
-
- 1:2:1:1: VARREF 0x92c2598 {e24} w0 clk [RV] <- VAR 0x92a2e90 {e18} w0 clk [I] INPUT
-
-In general, examine the `dump()` method in `V3AstNodes.cpp` of the node
-type in question to determine additional fields that may be printed.
-
-The `MODULE` has a list of `CELLINLINE` nodes referred to by its
-`op1p()` pointer, connected by `nextp()` and `prevp()` pointers.
-
-Similarly the `NETLIST` has a list of modules referred to by its `op1p()`
-pointer.
-
-=== Debugging with GDB
-
-The test_regress/driver.pl script accepts `--debug --gdb` to start
-Verilator under gdb and break when an error is hit or the program is about
-to exit. You can also use `--debug --gdbbt` to just backtrace and then
-exit gdb. To debug the Verilated executable, use `--gdbsim`.
-
-If you wish to start Verilator under GDB (or another debugger), then you
-can use `--debug` and look at the underlying invocation of
-`verilator_dbg`. For example
-
- t/t_alw_dly.pl --debug
-
-shows it invokes the command:
-
- ../verilator_bin_dbg --prefix Vt_alw_dly --x-assign unique --debug
- -cc -Mdir obj_dir/t_alw_dly --debug-check -f input.vc t/t_alw_dly.v
-
-Start GDB, then `start` with the remaining arguments.
-
- gdb ../verilator_bin_dbg
- ...
- (gdb) start --prefix Vt_alw_dly --x-assign unique --debug -cc -Mdir
- obj_dir/t_alw_dly --debug-check -f input.vc t/t_alw_dly.v
- > obj_dir/t_alw_dly/vlt_compile.log
- ...
- Temporary breakpoint 1, main (argc=13, argv=0xbfffefa4, env=0xbfffefdc)
- at ../Verilator.cpp:615
- 615 ios::sync_with_stdio();
- (gdb)
-
-You can then continue execution with breakpoints as required.
-
-To break at a specific edit number which changed a node (presumably to find
-what made a line in the tree dumps):
-
- watch AstNode::s_editCntGbl==####
-
-Then, when the watch fires, to break at every following change to that node:
-
- watch m_editCount
-
-To print a node:
-
- pn nodep
- # or: call dumpGdb(nodep) # aliased to "pn" in src/.gdbinit
- pnt nodep
- # or: call dumpTreeGdb(nodep) # aliased to "pnt" in src/.gdbinit
-
-When GDB halts, it is useful to understand that the backtrace will commonly
-show the iterator functions between each invocation of `visit` in the
-backtrace. You will typically see a frame sequence something like
-
- ...
- visit()
- iterateChildren()
- iterateAndNext()
- accept()
- visit()
- ...
-
-== Adding a New Feature
-
-Generally what would you do to add a new feature?
-
-. File an issue (if there isn't already) so others know what you're working on.
-
-. Make a testcase in the test_regress/t/t_EXAMPLE format, see << /TESTING >>.
-
-. If grammar changes are needed, look at the git version of VerilogPerl's
-src/VParseGrammar.y, as this grammar supports the full SystemVerilog
-language and has a lot of back-and-forth with Verilator's grammar. Copy
-the appropriate rules to src/verilog.y and modify the productions.
-
-. If a new Ast type is needed, add it to V3AstNodes.h. Follow the convention
-described above about the AstNode type hierarchy.
-
-. Now you can run "test_regress/t/t_{new testcase}.pl --debug" and it'll
-probably fail but you'll see a 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.
-
-. Modify the later visitor functions to process the new feature as needed.
-
-=== Adding a New Pass
-
-For more substantial changes you may need to add a new pass. The simplest
-way to do this is to copy the `.cpp` and `.h` files from an existing
-pass. You'll need to add a call into your pass from the `process()`
-function in `src/verilator.cpp`.
-
-To get your pass to build you'll need to add its binary filename to the
-list in `src/Makefile_obj.in` and reconfigure.
-
-=== "Never" features
-
-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.
-
-[horizontal]
-IEEE 1800-2017 3.3 recursive modules:: Little/no tool support, and arguably not a good practice.
-IEEE 1800-2017 6.12 "shortreal":: Little/no tool support, and easily simply promoted to real.
-IEEE 1800-2017 11.11 Min, typ, max:: No SDF support so will always use typical.
-IEEE 1800-2017 11.12 "let":: Little/no tool support, makes difficult to implement parsers.
-IEEE 1800-2017 20.15 Probabilistic functions:: Little industry use.
-IEEE 1800-2017 20.16 Stochastic analysis:: Little industry use.
-IEEE 1800-2017 20.17 PLA modeling:: Little industry use and outdated technology.
-IEEE 1800-2017 31 Timing checks:: No longer relevant with static timing analysis tools.
-IEEE 1800-2017 32 SDF annotation:: No longer relevant with static timing analysis tools.
-IEEE 1800-2017 33 Config:: Little/no tool support or industry use.
-
-== Distribution
-
-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.
-// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
diff --git a/docs/internals.rst b/docs/internals.rst
new file mode 100644
index 000000000..496598fb4
--- /dev/null
+++ b/docs/internals.rst
@@ -0,0 +1,1213 @@
+|Logo|
+
+===================
+Verilator Internals
+===================
+
+.. contents::
+ :depth: 3
+
+Introduction
+============
+
+This file discusses internal and programming details for Verilator. It's
+a reference for developers and debugging problems.
+
+See also the Verilator internals presentation at
+https://www.veripool.org.
+
+
+Code Flows
+==========
+
+
+Verilator Flow
+--------------
+
+The main flow of Verilator can be followed by reading the Verilator.cpp
+``process()`` function:
+
+1. First, the files specified on the command line are read. Reading
+ involves preprocessing, then lexical analysis with Flex and parsing
+ with Bison. This produces an abstract syntax tree (AST)
+ representation of the design, which is what is visible in the .tree
+ files described below.
+
+2. Verilator then makes a series of passes over the AST, progressively
+ refining and optimizing it.
+
+3. Cells in the AST first linked, which will read and parse additional
+ files as above.
+
+4. Functions, variable and other references are linked to their
+ definitions.
+
+5. Parameters are resolved and the design is elaborated.
+
+6. Verilator then performs many additional edits and optimizations on
+ the hierarchical design. This includes coverage, assertions, X
+ elimination, inlining, constant propagation, and dead code
+ elimination.
+
+7. References in the design are then pseudo-flattened. Each module's
+ variables and functions get "Scope" references. A scope reference is
+ an occurrence of that un-flattened variable in the flattened
+ hierarchy. A module that occurs only once in the hierarchy will have
+ a single scope and single VarScope for each variable. A module that
+ occurs twice will have a scope for each occurrence, and two
+ VarScopes for each variable. This allows optimizations to proceed
+ across the flattened design, while still preserving the hierarchy.
+
+8. Additional edits and optimizations proceed on the pseudo-flat
+ design. These include module references, function inlining, loop
+ unrolling, variable lifetime analysis, lookup table creation, always
+ splitting, and logic gate simplifications (pushing inverters, etc).
+
+9. Verilator orders the code. Best case, this results in a single
+ "eval" function which has all always statements flowing from top to
+ bottom with no loops.
+
+10. Verilator mostly removes the flattening, so that code may be shared
+ between multiple invocations of the same module. It localizes
+ variables, combines identical functions, expands macros to C
+ primitives, adds branch prediction hints, and performs additional
+ constant propagation.
+
+11. Verilator finally writes the C++ modules.
+
+
+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.
+``AstGenerate`` for a generate block) or groups of components (e.g.
+``AstNodeFTask`` for functions and tasks, which in turn has ``AstFunc`` and
+``AstTask`` as derived classes). An important property of the ``AstNode``
+type hierarchy is that all non-final subclasses of ``AstNode`` (i.e.: those
+which themselves have subclasses) must be abstract as well, and be named
+with the prefix ``AstNode*``. The ``astgen`` (see below) script relies on
+this.
+
+Each ``AstNode`` has pointers to up to four children, accessed by the
+``op1p`` through ``op4p`` methods. These methods are then abstracted in a
+specific Ast\* node class to a more specific name. For example with the
+``AstIf`` node (for ``if`` statements), ``ifsp`` calls ``op2p`` to give the
+pointer to the AST for the "then" block, while ``elsesp`` calls ``op3p`` to
+give the pointer to the AST for the "else" block, or NULL if there is not
+one.
+
+``AstNode`` has the concept of a next and previous AST - for example the
+next and previous statements in a block. Pointers to the AST for these
+statements (if they exist) can be obtained using the ``back`` and ``next``
+methods.
+
+It is useful to remember that the derived class ``AstNetlist`` is at the
+top of the tree, so checking for this class is the standard way to see if
+you are at the top of the tree.
+
+By convention, each function/method uses the variable ``nodep`` as a
+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
+instance of the visitor class, which in turn implements a method to perform
+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
+provided to manipulate the graphs and to output them in `GraphViz
+`__ dot format. ``V3Graph.h`` provides
+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
+algorithms for ordering the graph. A generic ``user``/``userp`` member
+variable is also provided.
+
+Virtual methods are provided to specify the name, color, shape and style to
+be used in dot output. Typically users provide derived classes from
+``V3GraphVertex`` which will reimplement these methods.
+
+Iterators are provided to access in and out edges. Typically these are used
+in the form:
+
+::
+
+ for (V3GraphEdge *edgep = vertexp->inBeginp();
+ edgep;
+ edgep = edgep->inNextp()) {
+
+
+``V3GraphEdge``
+~~~~~~~~~~~~~~~
+
+``V3GraphEdge`` is the base class for directed edges between pairs of
+vertices. Edges have an associated ``weight`` and may also be made
+``cutable``. A generic ``user``/``userp`` member variable is also provided.
+
+Accessors, ``fromp`` and ``top`` return the "from" and "to" vertices
+respectively.
+
+Virtual methods are provided to specify the label, color and style to be
+used in dot output. Typically users provided derived classes from
+``V3GraphEdge`` which will reimplement these methods.
+
+
+``V3GraphAlg``
+~~~~~~~~~~~~~~
+
+This is the base class for graph algorithms. It implements a ``bool``
+method, ``followEdge`` which algorithms can use to decide whether an edge
+is followed. This method returns true if the graph edge has weight greater
+than one and a user function, ``edgeFuncp`` (supplied in the constructor)
+returns ``true``.
+
+A number of predefined derived algorithm classes and access methods are
+provided and documented in ``V3GraphAlg.cpp``.
+
+
+Multithreaded Mode
+------------------
+
+In ``--threads`` mode, the frontend of the Verilator pipeline is the same
+as serial mode, up until V3Order.
+
+``V3Order`` builds a fine-grained, statement-level dependency graph that
+governs the ordering of code within a single ``eval()`` call. In serial
+mode, that dependency graph is used to order all statements into a total
+serial order. In parallel mode, the same dependency graph is the starting
+point for a partitioner (``V3Partition``).
+
+The partitioner's goal is to coarsen the fine-grained graph into a coarser
+graph, while maintaining as much available parallelism as possible. Often
+the partitioner can transform an input graph with millions of nodes into a
+coarsened execution graph with a few dozen nodes, while maintaining enough
+parallelism to take advantage of a modern multicore CPU. Runtime
+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*.
+
+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
+through the graph. This is the speedup you would get from running the graph
+in parallel, if given infinite CPU cores available and communication and
+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
+coarsened graph are "macro-tasks". This term comes from Sarkar. Each
+macro-task executes from start to end on one processor, without any
+synchronization to any other macro-task during its execution.
+(Synchronization only happens before the macro-task begins or after it
+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
+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
+cost, plus the critical path from the end of the node to the end of the
+graph.
+
+Sarkar calls out an important trade-off: coarsening the graph reduces
+runtime synchronization overhead among the macro-tasks, but it tends to
+increase the critical path through the graph and thus reduces par-factor.
+
+Sarkar's partitioner, and ours, chooses pairs of macro-tasks to merge such
+that the growth in critical path is minimized. Each candidate merge would
+result in a new node, which would have some local critical path. We choose
+the candidate that would produce the shortest local critical path. Repeat
+until par-factor falls to a target threshold. It's a greedy algorithm, and
+it's not guaranteed to produce the best partition (which Sarkar proves is
+NP-hard).
+
+
+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
+cost which is simply the sum of its tasks' costs. We assume that
+communication overhead and synchronization overhead are zero, so the cost
+of any given path through the graph is simply the sum of macro-task
+execution costs. Sarkar does almost the same thing, except that he has
+nonzero estimates for synchronization costs.
+
+Verilator's cost estimates are assigned by ``InstrCountCostVisitor``. This
+class is perhaps the most fragile piece of the multithread
+implementation. It's easy to have a bug where you count something cheap
+(eg. accessing one element of a huge array) as if it were expensive (eg.
+by counting it as if it were an access to the entire array.) Even without
+such gross bugs, the estimates this produce are only loosely predictive of
+actual runtime cost. Multithread performance would be better with better
+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
+at runtime, with a runtime graph follower. Sarkar calls this the
+"macro-dataflow model." Verilator does not support this; early experiments
+with this approach had poor performance.
+
+The other option is to statically assign macro-tasks to threads, with each
+thread running its macro-tasks in a static order. Sarkar describes this in
+Chapter 5. Verilator takes this static approach. The only dynamic aspect is
+that each macro task may block before starting, to wait until its
+prerequisites on other threads have finished.
+
+The synchronization cost is cheap if the prereqs are done. If they're not,
+fragmentation (idle CPU cores waiting) is possible. This is the major
+source of overhead in this approach. The ``--prof-threads`` switch and the
+``verilator_gantt`` script can visualize the time lost to such
+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
+memory. This provides "spatial locality" - when we pull in a 64-byte cache
+line to access a 2-byte variable, we want the other 62 bytes to be ones
+we'll also likely access soon, for best cache performance.
+
+This turns out to be critical for performance. It should allow Verilator
+to scale to very large models. We don't rely on our working set fitting
+in any CPU cache; instead we essentially "stream" data into caches from
+memory. It's not literally streaming, where the address increases
+monotonically, but it should have similar performance characteristics,
+so long as each macro-task's dataset fits in one core's local caches.
+
+To achieve spatial locality, we tag each variable with the set of
+macro-tasks that access it. Let's call this set the "footprint" of that
+variable. The variables in a given module have a set of footprints. We
+can order those footprints to minimize the distance between them
+(distance is the number of macro-tasks that are different across any two
+footprints) and then emit all variables into the struct in
+ordered-footprint order.
+
+The footprint ordering is literally the traveling salesman problem, and
+we use a TSP-approximation algorithm to get close to an optimal sort.
+
+This is an old idea. Simulators designed at DEC in the early 1990s used
+similar techniques to optimize both single-thread and multi-thread
+modes. (Verilator does not optimize variable placement for spatial
+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
+before ``eval()`` is called or continues after ``eval()`` returns. For now
+all work on a cycle happens during the ``eval()`` call, leaving Verilator's
+threads idle while the testbench (everything outside ``eval()``) is
+working. This would involve fundamental changes within the partitioner,
+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
+entire core to scheduling, so that scheduler data structures would fit in
+its L1 cache and thus the cost of traversing priority-ordered ready lists
+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
+macro-tasks into the threads also at run time. Say, re-pack once every
+10,000 cycles or something. This has the potential to do better than our
+static estimates about macro-task run times. It could potentially react to
+CPU cores that aren't performing equally, due to NUMA or thermal throttling
+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
+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
+runtime. That variance is magnified if MTasks are homogeneous, containing
+similar repeating logic which was generally close together in source code
+and which is still packed together even after going through Verilator's
+digestive tract.
+
+If Verilator could avoid doing that, and instead would take source logic
+that was close together and distribute it across MTasks, that would
+increase the diversity of any given MTask, and this should reduce variance
+in the cost estimates.
+
+One way to do that might be to make various "tie breaker" comparison
+routines in the sources to rely more heavily on randomness, and
+generally try harder not to keep input nodes together when we have the
+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
+modes. This would help to avoid performance regressions, and also to
+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
+the variable sort will be suboptimal for either instance. A possible
+improvement would be to emit a unique class for each instance of a module,
+and sort its variables optimally for that instance's code stream.
+
+
+Verilated Flow
+--------------
+
+The evaluation loop outputted by Verilator is designed to allow a single
+function to perform evaluation under most situations.
+
+On the first evaluation, the Verilated code calls initial blocks, and then
+"settles" the modules, by evaluating functions (from always statements)
+until all signals are stable.
+
+On other evaluations, the Verilated code detects what input signals have
+changes. If any are clocks, it calls the appropriate sequential functions
+(from ``always @ posedge`` statements). Interspersed with sequential
+functions it calls combo functions (from ``always @*``). After this is
+complete, it detects any changes due to combo loops or internally generated
+clocks, and if one is found must reevaluate the model again.
+
+For SystemC code, the ``eval()`` function is wrapped in a SystemC
+``SC_METHOD``, sensitive to all inputs. (Ideally it would only be sensitive
+to clocks and combo inputs, but tracing requires all signals to cause
+evaluation, and the performance difference is small.)
+
+If tracing is enabled, a callback examines all variables in the design for
+changes, and writes the trace for each change. To accelerate this process
+the evaluation process records a bitmask of variables that might have
+changed; if clear, checking those signals for changes may be skipped.
+
+
+Coding Conventions
+==================
+
+
+Compiler Version and C++11
+--------------------------
+
+Verilator requires C11. Verilator does not require any newer versions, but
+is maintained to build successfully with C14/C17/C20.
+
+
+Indentation and Naming Style
+----------------------------
+
+We will work with contributors to fix up indentation style issues, but it
+is appreciated if you could match our style:
+
+- Use "mixedCapsSymbols" instead of "underlined_symbols".
+
+- Uas a "p" suffix on variables that are pointers, e.g. "nodep".
+
+- Comment every member variable.
+
+- In the include directory, use /// to document functions the user
+ calls. (This convention has not been applied retroactively.)
+
+C and Python indentation is automatically maintained with "make format"
+using clang-format version 10.0.0, and yapf for python, and is
+automatically corrected in the CI actions. For those manually formatting C
+code:
+
+- Use 4 spaces per level, and no tabs.
+
+- Use 2 spaces between the end of source and the beginning of a
+ comment.
+
+- Use 1 space after if/for/switch/while and similar keywords.
+
+- No spaces before semicolons, nor between a function's name and open
+ parenthesis (only applies to functions; if/else has a following space).
+
+
+The ``astgen`` Script
+---------------------
+
+Some of the code implementing passes is extremely repetitive, and must be
+implemented for each sub-class of ``AstNode``. However, while repetitive,
+there is more variability than can be handled in C++ macros.
+
+In Verilator this is implemented by using a Perl script, ``astgen`` to
+pre-process the C++ code. For example in ``V3Const.cpp`` this is used to
+implement the ``visit()`` functions for each binary operation using the
+``TREEOP`` macro.
+
+The original C source code is transformed into C code in the ``obj_opt``
+and ``obj_dbg`` sub-directories (the former for the optimized version of
+Verilator, the latter for the debug version). So for example
+``V3Const.cpp`` into ``V3Const__gen.cpp``.
+
+
+Visitor Functions -----------------
+
+Verilator uses the "Visitor" design pattern to implement its refinement and
+optimization passes. This allows separation of the pass algorithm from the
+AST on which it operates. Wikipedia provides an introduction to the concept
+at https://en.wikipedia.org/wiki/Visitor_pattern.
+
+As noted above, all visitors are derived classes of ``AstNVisitor``. All
+derived classes of ``AstNode`` implement the ``accept`` method, which takes
+as argument a reference to an instance or a ``AstNVisitor`` derived class
+and applies the visit method of the ``AstNVisitor`` to the invoking AstNode
+instance (i.e. ``this``).
+
+One possible difficulty is that a call to ``accept`` may perform an edit
+which destroys the node it receives as argument. The
+``acceptSubtreeReturnEdits`` method of ``AstNode`` is provided to apply
+``accept`` and return the resulting node, even if the original node is
+destroyed (if it is not destroyed it will just return the original node).
+
+The behavior of the visitor classes is achieved by overloading the
+``visit`` function for the different ``AstNode`` derived classes. If a
+specific implementation is not found, the system will look in turn for
+overloaded implementations up the inheritance hierarchy. For example
+calling ``accept`` on ``AstIf`` will look in turn for:
+
+::
+
+ void visit(AstIf* nodep)
+ void visit(AstNodeIf* nodep)
+ void visit(AstNodeStmt* nodep)
+ void visit(AstNode* nodep)
+
+There are three ways data is passed between visitor functions.
+
+1. A visitor-class member variable. This is generally for passing
+ "parent" information down to children. ``m_modp`` is a common
+ example. It's set to NULL in the constructor, where that node
+ (``AstModule`` visitor) sets it, then the children are iterated, then
+ it's cleared. Children under an ``AstModule`` will see it set, while
+ nodes elsewhere will see it clear. If there can be nested items (for
+ example an ``AstFor`` under an ``AstFor``) the variable needs to be
+ save-set-restored in the ``AstFor`` visitor, otherwise exiting the
+ lower for will lose the upper for's setting.
+
+2. User attributes. Each ``AstNode`` (**Note.** The AST node, not the
+ visitor) has five user attributes, which may be accessed as an
+ integer using the ``user1()`` through ``user5()`` methods, or as a
+ pointer (of type ``AstNUser``) using the ``user1p()`` through
+ ``user5p()`` methods (a common technique lifted from graph traversal
+ packages).
+
+ A visitor first clears the one it wants to use by calling
+ ``AstNode::user#ClearTree()``, then it can mark any node's
+ ``user#()`` with whatever data it wants. Readers just call
+ ``nodep->user()``, but may need to cast appropriately, so you'll often
+ see ``VN_CAST(nodep->userp(), SOMETYPE)``. At the top of each visitor
+ are comments describing how the ``user()`` stuff applies to that
+ visitor class. For example:
+
+ ::
+
+ // NODE STATE
+ // Cleared entire netlist
+ // AstModule::user1p() // bool. True to inline this module
+
+ This says that at the ``AstNetlist`` ``user1ClearTree()`` is called.
+ Each :literal:`AstModule's `user1()` is used to indicate if we're
+ going to inline it.
+
+ These comments are important to make sure a ``user#()`` on a given
+ ``AstNode`` type is never being used for two different purposes.
+
+ Note that calling ``user#ClearTree`` is fast, it doesn't walk the
+ tree, so it's ok to call fairly often. For example, it's commonly
+ called on every module.
+
+3. Parameters can be passed between the visitors in close to the
+ "normal" function caller to callee way. This is the second ``vup``
+ parameter of type ``AstNUser`` that is ignored on most of the visitor
+ functions. V3Width does this, but it proved more messy than the above
+ and is deprecated. (V3Width was nearly the first module written.
+ Someday this scheme may be removed, as it slows the program down to
+ have to pass vup everywhere.)
+
+
+Iterators
+---------
+
+``AstNVisitor`` provides a set of iterators to facilitate walking over
+the tree. Each operates on the current ``AstNVisitor`` class (as this)
+and takes an argument type ``AstNode*``.
+
+``iterate``
+ Applies the ``accept`` method of the ``AstNode`` to the visitor
+ function.
+
+``iterateAndNextIgnoreEdit``
+ Applies the ``accept`` method of each ``AstNode`` in a list (i.e.
+ connected by ``nextp`` and ``backp`` pointers).
+
+``iterateAndNextNull``
+ Applies the ``accept`` method of each ``AstNode`` in a list, only if
+ the provided node is non-NULL. If a node is edited by the call to
+ ``accept``, apply ``accept`` again, until the node does not change.
+
+``iterateListBackwards``
+ Applies the ``accept`` method of each ``AstNode`` in a list, starting
+ with the last one.
+
+``iterateChildren``
+ Applies the ``iterateAndNextNull`` method on each child ``op1p``
+ through ``op4p`` in turn.
+
+``iterateChildrenBackwards``
+ Applies the ``iterateListBackwards`` method on each child ``op1p``
+ through ``op4p`` in turn.
+
+
+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
+needs to be aware that calling iteration may cause the children to
+change. For example:
+
+::
+
+ // nodep->lhsp() is 0x1234000
+ iterateAndNextNull(nodep->lhsp()); // and under covers nodep->lhsp() changes
+ // nodep->lhsp() is 0x5678400
+ iterateAndNextNull(nodep->lhsp());
+
+Will work fine, as even if the first iterate causes a new node to take
+the place of the ``lhsp()``, that edit will update ``nodep->lhsp()`` and
+the second call will correctly see the change. Alternatively:
+
+::
+
+ lp = nodep->lhsp();
+ // nodep->lhsp() is 0x1234000, lp is 0x1234000
+ iterateAndNextNull(lp); **lhsp=NULL;** // and under covers nodep->lhsp() changes
+ // nodep->lhsp() is 0x5678400, lp is 0x1234000
+ iterateAndNextNull(lp);
+
+This will cause bugs or a core dump, as lp is a dangling pointer. Thus
+it is advisable to set lhsp=NULL shown in the \*'s above to make sure
+these dangles are avoided. Another alternative used in special cases
+mostly in V3Width is to use acceptSubtreeReturnEdits, which operates on
+a single node and returns the new pointer if any. Note
+acceptSubtreeReturnEdits does not follow ``nextp()`` links.
+
+::
+
+ lp = acceptSubtreeReturnEdits(lp)
+
+
+Identifying Derived Classes
+---------------------------
+
+A common requirement is to identify the specific ``AstNode`` class we
+are dealing with. For example a visitor might not implement separate
+``visit`` methods for ``AstIf`` and ``AstGenIf``, but just a single
+method for the base class:
+
+::
+
+ void visit(AstNodeIf* nodep)
+
+However that method might want to specify additional code if it is
+called for ``AstGenIf``. Verilator does this by providing a ``VN_IS``
+method for each possible node type, which returns true if the node is of
+that type (or derived from that type). So our ``visit`` method could
+use:
+
+::
+
+ if (VN_IS(nodep, AstGenIf) {
+
+ }
+
+Additionally the ``VN_CAST`` method converts pointers similar to C++
+``dynamic_cast``. This either returns a pointer to the object cast to
+that type (if it is of class ``SOMETYPE``, or a derived class of
+``SOMETYPE``) or else NULL. (However, for true/false tests use ``VN_IS``
+as that is faster.)
+
+
+.. _Testing
+
+Testing
+=======
+
+For an overview of how to write a test see the BUGS section of the
+Verilator primary manual.
+
+It is important to add tests for failures as well as success (for
+example to check that an error message is correctly triggered).
+
+Tests that fail should by convention have the suffix ``_bad`` in their
+name, and include ``fails = 1`` in either their ``compile`` or
+``execute`` step as appropriate.
+
+
+Preparing to Run Tests
+----------------------
+
+For all tests to pass you must install the following packages:
+
+- SystemC to compile the SystemC outputs, see http://systemc.org
+
+- Parallel::Forker from CPAN to run tests in parallel, you can install
+ this with e.g. "sudo cpan install Parallel::Forker".
+
+- vcddiff to find differences in VCD outputs. See the readme at
+ https://github.com/veripool/vcddiff
+
+- Cmake for build paths that use it.
+
+
+Controlling the Test Driver
+---------------------------
+
+Test drivers are written in PERL. All invoke the main test driver script,
+which can provide detailed help on all the features available when writing
+a test driver.
+
+::
+
+ test_regress/driver.pl --help
+
+For convenience, a summary of the most commonly used features is provided
+here. All drivers require a call to ``compile`` subroutine to compile the
+test. For run-time tests, this is followed by a call to the ``execute``
+subroutine. Both of these functions can optionally be provided with a hash
+table as argument specifying additional options.
+
+The test driver assumes by default that the source Verilog file name
+matches the PERL driver name. So a test whose driver is
+``t/t_mytest.pl`` will expect a Verilog source file ``t/t_mytest.v``.
+This can be changed using the ``top_filename`` subroutine, for example
+
+::
+
+ top_filename("t/t_myothertest.v");
+
+By default all tests will run with major simulators (Icarus Verilog, NC,
+VCS, ModelSim, etc) as well as Verilator, to allow results to be
+compared. However if you wish a test only to be used with Verilator, you
+can use the following:
+
+::
+
+ scenarios(vlt => 1);
+
+Of the many options that can be set through arguments to ``compiler`` and
+``execute``, the following are particularly useful:
+
+``verilator_flags2``
+ A list of flags to be passed to verilator when compiling.
+
+``fails``
+ Set to 1 to indicate that the compilation or execution is intended to fail.
+
+For example the following would specify that compilation requires two
+defines and is expected to fail.
+
+::
+
+ compile(
+ verilator_flags2 => ["-DSMALL_CLOCK -DGATED_COMMENT"],
+ fails => 1,
+ );
+
+
+Regression Testing for Developers
+---------------------------------
+
+Developers will also want to call ./configure with two extra flags:
+
+``--enable-ccwarn``
+ Causes the build to stop on warnings as well as errors. A good way to
+ ensure no sloppy code gets added, however it can be painful when it
+ comes to testing, since third party code used in the tests (e.g.
+ SystemC) may not be warning free.
+
+``--enable-longtests``
+ In addition to the standard C, SystemC examples, also run the tests
+ in the ``test_regress`` directory when using *make test*'. This is
+ disabled by default as SystemC installation problems would otherwise
+ falsely indicate a Verilator problem.
+
+When enabling the long tests, some additional PERL modules are needed,
+which you can install using cpan.
+
+::
+
+ cpan install Parallel::Forker
+
+There are some traps to avoid when running regression tests
+
+- When checking the MANIFEST, the test will barf on unexpected code in the
+ Verilator tree. So make sure to keep any such code outside the tree.
+
+- Not all Linux systems install Perldoc by default. This is needed for the
+ ``--help`` option to Verilator, and also for regression testing. This
+ can be installed using cpan:
+
+ ::
+
+ cpan install Pod::Perldoc
+
+ Many Linux systems also offer a standard package for this. Red
+ Hat/Fedora/Centos offer *perl-Pod-Perldoc*', while
+ Debian/Ubuntu/Linux Mint offer \`perl-doc'.
+
+- Running regression may exhaust resources on some Linux systems,
+ particularly file handles and user processes. Increase these to
+ respectively 16,384 and 4,096. The method of doing this is system
+ dependent, but on Fedora Linux it would require editing the
+ ``/etc/security/limits.conf`` file as root.
+
+
+Manual Test Execution
+---------------------
+
+A specific regression test can be executed manually. To start the
+"EXAMPLE" test, run the following command.
+
+::
+
+ test_regress/t/t_EXAMPLE.pl
+
+
+Continuous Integration
+----------------------
+
+Verilator uses GitHub Actions which automatically tests the master branch
+for test failures on new commits. It also runs a daily cron job to validate
+all of the tests against different OS and compiler versions.
+
+Developers can enable Actions on their GitHub repository so that the CI
+environment can check their branches too by enabling the build workflow:
+
+- On GitHub, navigate to the main page of the repository.
+
+- Under your repository name, click Actions.
+
+- In the left sidebar, click the workflow you want to enable ("build").
+
+- Click Enable workflow.
+
+
+Fuzzing
+-------
+
+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 `__ 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.
+
+
+Debugging
+=========
+
+
+Debug Levels
+------------
+
+The "UINFO" calls in the source indicate a debug level. Messages level 3
+and below are globally enabled with ``--debug``. Higher levels may be
+controlled with ``--debugi ``. An individual source file levels may
+be controlled with ``-debugi- ``. For example ``--debug
+--debugi 5 --debugi-V3Width 9`` will use the debug binary at default
+debug level 5, with the V3Width.cpp file at level 9.
+
+
+--debug
+-------
+
+When you run with ``--debug`` there are two primary output file types
+placed into the obj_dir, .tree and .dot files.
+
+
+.dot Output
+-----------
+
+Dot files are dumps of internal graphs in `Graphviz
+`__ dot format. When a dot file is dumped,
+Verilator will also print a line on stdout that can be used to format the
+output, for example:
+
+::
+
+ dot -Tps -o ~/a.ps obj_dir/Vtop_foo.dot
+
+You can then print a.ps. You may prefer gif format, which doesn't get
+scaled so can be more useful with large graphs.
+
+For interactive graph viewing consider `xdot
+`__ or `ZGRViewer
+`__. If you know of better
+viewers (especially for large graphs) please let us know.
+
+
+.tree Output
+------------
+
+Tree files are dumps of the AST Tree and are produced between every major
+algorithmic stage. An example:
+
+::
+
+ NETLIST 0x90fb00 {a0ah}
+ 1: MODULE 0x912b20 {a8ah} top L2 [P]
+ *1:2: VAR 0x91a780 {a22ah} @dt=0xa2e640(w32) out_wide [O] WIRE
+ 1:2:1: BASICDTYPE 0xa2e640 {e24ah} @dt=this(sw32) integer kwd=integer range=[31:0]
+
+The following summarizes the above example dump, with more detail on each
+field in the section below.
+
++---------------+--------------------------------------------------------+
+| ``1:2:`` | The hierarchy of the ``VAR`` is the ``op2p`` |
+| | pointer under the ``MODULE``, which in turn is the |
+| | ``op1p`` pointer under the ``NETLIST`` |
++---------------+--------------------------------------------------------+
+| ``VAR`` | The AstNodeType (e.g. ``AstVar``). |
++---------------+--------------------------------------------------------+
+| ``0x91a780`` | Address of this node. |
++---------------+--------------------------------------------------------+
+| ```` | The 74th edit to the netlist was the last |
+| | modification to this node. |
++---------------+--------------------------------------------------------+
+| ``{a22ah}`` | This node is related to the source filename |
+| | "a", where "a" is the first file read, "z" the 26th, |
+| | and "aa" the 27th. Then line 22 in that file, then |
+| | column 8 (aa=0, az=25, ba=26, ...). |
++---------------+--------------------------------------------------------+
+| ``@dt=0x...`` | The address of the data type this node contains. |
++---------------+--------------------------------------------------------+
+| ``w32`` | The data-type width() is 32 bits. |
++---------------+--------------------------------------------------------+
+| ``out_wide`` | The name() of the node, in this case the name of the |
+| | variable. |
++---------------+--------------------------------------------------------+
+| ``[O]`` | Flags which vary with the type of node, in this |
+| | case it means the variable is an output. |
++---------------+--------------------------------------------------------+
+
+In more detail the following fields are dumped common to all nodes. They
+are produced by the ``AstNode::dump()`` method:
+
+Tree Hierarchy
+ The dump lines begin with numbers and colons to indicate the child
+ node hierarchy. As noted above, ``AstNode`` has lists of items at the
+ same level in the AST, connected by the ``nextp()`` and ``prevp()``
+ pointers. These appear as nodes at the same level. For example after
+ inlining:
+
+ ::
+
+ NETLIST 0x929c1c8 {a0} w0
+ 1: MODULE 0x92bac80 {e14} w0 TOP_t L1 [P]
+ 1:1: CELLINLINE 0x92bab18 {e14} w0 v -> t
+ 1:1: CELLINLINE 0x92bc1d8 {e24} w0 v__DOT__i_test_gen -> test_gen
+ ...
+ 1: MODULE 0x92b9bb0 {e47} w0 test_gen L3
+ ...
+
+AstNode type
+ The textual name of this node AST type (always in capitals). Many of
+ these correspond directly to Verilog entities (for example ``MODULE``
+ and ``TASK``), but others are internal to Verilator (for example
+ ``NETLIST`` and ``BASICDTYPE``).
+
+Address of the node
+ A hexadecimal address of the node in memory. Useful for examining
+ with the debugger. If the actual address values are not important,
+ then using the ``--dump-tree-addrids`` option will convert address
+ values to short identifiers of the form ``([A-Z]*)``, which is
+ hopefully easier for the reader to cross reference throughout the
+ dump.
+
+Last edit number
+ Of the form ```` or ```` , where ``nnnn`` is the
+ number of the last edit to modify this node. The trailing ``#``
+ indicates the node has been edited since the last tree dump (which
+ typically means in the last refinement or optimization pass). GDB can
+ watch for this, see << /Debugging >>.
+
+Source file and line
+ Of the form ``{xxnnnn}``, where C{xx} is the filename letter (or
+ letters) and ``nnnn`` is the line number within that file. The first
+ file is ``a``, the 26th is ``z``, the 27th is ``aa`` and so on.
+
+User pointers
+ Shows the value of the node's user1p...user5p, if non-NULL.
+
+Data type
+ Many nodes have an explicit data type. "@dt=0x..." indicates the
+ address of the data type (AstNodeDType) this node uses.
+
+ If a data type is present and is numeric, it then prints the width of
+ the item. This field is a sequence of flag characters and width data
+ as follows:
+
+ - ``s`` if the node is signed.
+
+ - ``d`` if the node is a double (i.e a floating point entity).
+
+ - ``w`` always present, indicating this is the width field.
+
+ - ``u`` if the node is unsized.
+
+ - ``/nnnn`` if the node is unsized, where ``nnnn`` is the minimum
+ width.
+
+Name of the entity represented by the node if it exists
+ For example for a ``VAR`` it is the name of the variable.
+
+Many nodes follow these fields with additional node specific
+information. Thus the ``VARREF`` node will print either ``[LV]`` or
+``[RV]`` to indicate a left value or right value, followed by the node
+of the variable being referred to. For example:
+
+::
+
+ 1:2:1:1: VARREF 0x92c2598 {e24} w0 clk [RV] <- VAR 0x92a2e90 {e18} w0 clk [I] INPUT
+
+In general, examine the ``dump()`` method in ``V3AstNodes.cpp`` of the node
+type in question to determine additional fields that may be printed.
+
+The ``MODULE`` has a list of ``CELLINLINE`` nodes referred to by its
+``op1p()`` pointer, connected by ``nextp()`` and ``prevp()`` pointers.
+
+Similarly the ``NETLIST`` has a list of modules referred to by its
+``op1p()`` pointer.
+
+
+Debugging with GDB
+------------------
+
+The test_regress/driver.pl script accepts ``--debug --gdb`` to start
+Verilator under gdb and break when an error is hit or the program is about
+to exit. You can also use ``--debug --gdbbt`` to just backtrace and then
+exit gdb. To debug the Verilated executable, use ``--gdbsim``.
+
+If you wish to start Verilator under GDB (or another debugger), then you
+can use ``--debug`` and look at the underlying invocation of
+``verilator_dbg``. For example
+
+::
+
+ t/t_alw_dly.pl --debug
+
+shows it invokes the command:
+
+::
+
+ ../verilator_bin_dbg --prefix Vt_alw_dly --x-assign unique --debug
+ -cc -Mdir obj_dir/t_alw_dly --debug-check -f input.vc t/t_alw_dly.v
+
+Start GDB, then ``start`` with the remaining arguments.
+
+::
+
+ gdb ../verilator_bin_dbg
+ ...
+ (gdb) start --prefix Vt_alw_dly --x-assign unique --debug -cc -Mdir
+ obj_dir/t_alw_dly --debug-check -f input.vc t/t_alw_dly.v
+ > obj_dir/t_alw_dly/vlt_compile.log
+ ...
+ Temporary breakpoint 1, main (argc=13, argv=0xbfffefa4, env=0xbfffefdc)
+ at ../Verilator.cpp:615
+ 615 ios::sync_with_stdio();
+ (gdb)
+
+You can then continue execution with breakpoints as required.
+
+To break at a specific edit number which changed a node (presumably to
+find what made a line in the tree dumps):
+
+::
+
+ watch AstNode::s_editCntGbl==####
+
+Then, when the watch fires, to break at every following change to that
+node:
+
+::
+
+ watch m_editCount
+
+To print a node:
+
+::
+
+ pn nodep
+ # or: call dumpGdb(nodep) # aliased to "pn" in src/.gdbinit
+ pnt nodep
+ # or: call dumpTreeGdb(nodep) # aliased to "pnt" in src/.gdbinit
+
+When GDB halts, it is useful to understand that the backtrace will commonly
+show the iterator functions between each invocation of ``visit`` in the
+backtrace. You will typically see a frame sequence something like:
+
+::
+
+ ...
+ visit()
+ iterateChildren()
+ iterateAndNext()
+ accept()
+ visit()
+ ...
+
+
+Adding a New Feature
+====================
+
+Generally what would you do to add a new feature?
+
+1. File an issue (if there isn't already) so others know what you're
+ working on.
+
+2. Make a testcase in the test_regress/t/t_EXAMPLE format, see
+ :ref:`Testing`.
+
+3. If grammar changes are needed, look at the git version of VerilogPerl's
+ src/VParseGrammar.y, as this grammar supports the full SystemVerilog
+ language and has a lot of back-and-forth with Verilator's grammar. Copy
+ the appropriate rules to src/verilog.y and modify the productions.
+
+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
+ probably fail but you'll see a
+ 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.
+
+
+Adding a New Pass
+-----------------
+
+For more substantial changes you may need to add a new pass. The simplest
+way to do this is to copy the ``.cpp`` and ``.h`` files from an existing
+pass. You'll need to add a call into your pass from the ``process()``
+function in ``src/verilator.cpp``.
+
+To get your pass to build you'll need to add its binary filename to the
+list in ``src/Makefile_obj.in`` and reconfigure.
+
+
+"Never" features
+----------------
+
+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"
+ Little/no tool support, and easily simply promoted to real.
+IEEE 1800-2017 11.11 Min, typ, max
+ No SDF support so will always use typical.
+IEEE 1800-2017 11.12 "let"
+ Little/no tool support, makes difficult to implement parsers.
+IEEE 1800-2017 20.15 Probabilistic functions
+ Little industry use.
+IEEE 1800-2017 20.16 Stochastic analysis
+ Little industry use.
+IEEE 1800-2017 20.17 PLA modeling
+ Little industry use and outdated technology.
+IEEE 1800-2017 31 Timing checks
+ No longer relevant with static timing analysis tools.
+IEEE 1800-2017 32 SDF annotation
+ No longer relevant with static timing analysis tools.
+IEEE 1800-2017 33 Config
+ Little/no tool support or industry use.
+
+
+Distribution
+============
+
+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
diff --git a/docs/xml.adoc b/docs/xml.adoc
deleted file mode 100644
index b200e5de3..000000000
--- a/docs/xml.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-= Verilator XML Output
-:toc: right
-
-// Github doesn't render unless absolute URL
-image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
-
-== Introduction
-
-This document describes Verilator's XML output. For more general information
-please see https://verilator.org[verilator.org].
-
-== General
-
-Verilator's XML output is enabled with the `--xml-only` flag. It contains
-limited information about the elaborated design including files, modules,
-instance hierarchy, logic and data types. There is no formal schema since part
-of the structure of the XML document matches the compiled code which would
-require the schema to describe legal SystemVerilog structure. The intended
-usage is to enable other downstream tools to take advantage of Verilator's
-parser.
-
-== Structure
-
-The XML document consists of 4 sections within the top level `verilator_xml`
-element:
-
-``...``::
-
-This section contains a list of all design files read, including the
-built-in constructs and the command line as their own entries. Each
-`` has an attribute `id` which is a short ASCII string unique to that
-file. Other elements' `loc` attributes use this id to refer to a particular
-file.
-
-``...``::
-
-All files containing Verilog module definitions are listed in this section.
-This element's contents is a subset of the `` element's contents.
-
-``...``::
-
-The cells section of the XML document contains the design instance
-hierarchy. Each instance is represented with the `` element with the
-following attributes:
-
-* `fl` (deprecated): The file id and line number where the module was
- instanced. Use `loc` instead.
-
-* `loc`: The file id, first line number, last line number, first column
- number and last column number of the identifier where the module was
- instanced, separated by commas.
-
-* `name`: The instance name.
-
-* `submodname`: The module name uniquified with particular parameter values (if any).
-
-* `hier`: The full hierarchy path.
-
-``...``::
-
-The netlist section contains a number of ``...`` elements,
-each describing the contents of that module, and a single ``...
-`` element which lists all used types used within the
-modules. Each type has a numeric `id` attribute that is referred to by
-elements in the `` elements using the `dtype_id` attribute.
-
-== Distribution
-
-Copyright 2020-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.
-// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
diff --git a/docs/xml.rst b/docs/xml.rst
new file mode 100644
index 000000000..6231c8273
--- /dev/null
+++ b/docs/xml.rst
@@ -0,0 +1,81 @@
+|Logo|
+
+===========================
+Verilator XML Output Format
+===========================
+
+Introduction
+============
+
+This document describes Verilator's XML output. For more general
+information please see `verilator.org `__.
+
+
+General
+=======
+
+Verilator's XML output is enabled with the ``--xml-only`` flag. It contains
+limited information about the elaborated design including files, modules,
+instance hierarchy, logic and data types. There is no formal schema since
+part of the structure of the XML document matches the compiled code which
+would require the schema to describe legal SystemVerilog structure. The
+intended usage is to enable other downstream tools to take advantage of
+Verilator's parser.
+
+
+Structure
+=========
+
+The XML document consists of 4 sections within the top level
+``verilator_xml`` element:
+
+````\ ... ````
+ This section contains a list of all design files read, including the
+ built-in constructs and the command line as their own entries. Each
+ ```` has an attribute ``id`` which is a short ASCII string
+ unique to that file. Other elements' ``loc`` attributes use this id
+ to refer to a particular file.
+
+````\ ... ````
+ All files containing Verilog module definitions are listed in this
+ section. This element's contents is a subset of the ````
+ element's contents.
+
+````\ ... ````
+ The cells section of the XML document contains the design instance
+ hierarchy. Each instance is represented with the ```` element
+ with the following attributes:
+
+ - ``fl`` (deprecated): The file id and line number where the module
+ was instanced. Use ``loc`` instead.
+
+ - ``loc``: The file id, first line number, last line number, first
+ column number and last column number of the identifier where the
+ module was instanced, separated by commas.
+
+ - ``name``: The instance name.
+
+ - ``submodname``: The module name uniquified with particular
+ parameter values (if any).
+
+ - ``hier``: The full hierarchy path.
+
+````\ ... ````
+ The netlist section contains a number of
+ ````\ ... ```` elements, each describing the
+ contents of that module, and a single ````\ ...
+ ```` element which lists all used types used within the
+ modules. Each type has a numeric ``id`` attribute that is referred to
+ by elements in the ```` elements using the ``dtype_id``
+ attribute.
+
+.. __distribution:
+
+Distribution
+============
+
+Copyright 2020-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
diff --git a/examples/make_hello_sc/sc_main.cpp b/examples/make_hello_sc/sc_main.cpp
index 6fef7ca31..587010712 100644
--- a/examples/make_hello_sc/sc_main.cpp
+++ b/examples/make_hello_sc/sc_main.cpp
@@ -26,7 +26,7 @@ int sc_main(int argc, char* argv[]) {
if (false && argc && argv) {}
// Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
- Vtop* top = new Vtop("top");
+ Vtop* top = new Vtop{"top"};
// Initialize SC model
sc_start(1, SC_NS);
diff --git a/examples/make_protect_lib/secret_impl.v b/examples/make_protect_lib/secret_impl.v
index 1e39257f5..2a12a272c 100644
--- a/examples/make_protect_lib/secret_impl.v
+++ b/examples/make_protect_lib/secret_impl.v
@@ -17,7 +17,7 @@ module secret_impl
logic [31:0] accum_q = 0;
logic [31:0] secret_value = 9;
- initial $display("%m: initialized");
+ initial $display("[%0t] %m: initialized", $time);
always @(posedge clk) begin
accum_q <= accum_q + a;
diff --git a/examples/make_protect_lib/sim_main.cpp b/examples/make_protect_lib/sim_main.cpp
index 4d15ea360..b3096b4c5 100644
--- a/examples/make_protect_lib/sim_main.cpp
+++ b/examples/make_protect_lib/sim_main.cpp
@@ -16,25 +16,24 @@
#include
#endif
-vluint64_t main_time = 0;
-double sc_time_stamp() { return main_time; }
-
int main(int argc, char** argv, char** env) {
if (false && argc && argv && env) {}
- Verilated::debug(0);
- Verilated::randReset(2);
- Verilated::commandArgs(argc, argv);
+ // Construct context to hold simulation time, etc
+ VerilatedContext* contextp = new VerilatedContext;
+ contextp->debug(0);
+ contextp->randReset(2);
+ contextp->commandArgs(argc, argv);
// Construct the Verilated model, including the secret module
- Vtop* top = new Vtop;
+ Vtop* top = new Vtop{contextp};
#if VM_TRACE
// When tracing, the contents of the secret module will not be seen
VerilatedVcdC* tfp = nullptr;
- const char* flag = Verilated::commandArgsPlusMatch("trace");
+ const char* flag = contextp->commandArgsPlusMatch("trace");
if (flag && 0 == strcmp(flag, "+trace")) {
- Verilated::traceEverOn(true);
+ contextp->traceEverOn(true);
VL_PRINTF("Enabling waves into logs/vlt_dump.vcd...\n");
tfp = new VerilatedVcdC;
top->trace(tfp, 99);
@@ -46,12 +45,12 @@ int main(int argc, char** argv, char** env) {
top->clk = 0;
// Simulate until $finish
- while (!Verilated::gotFinish()) {
- main_time++;
+ while (!contextp->gotFinish()) {
+ contextp->timeInc(1);
top->clk = ~top->clk & 0x1;
top->eval();
#if VM_TRACE
- if (tfp) tfp->dump(main_time);
+ if (tfp) tfp->dump(contextp->time());
#endif
}
@@ -69,6 +68,8 @@ int main(int argc, char** argv, char** env) {
// Destroy model
delete top;
top = nullptr;
+ delete contextp;
+ contextp = nullptr;
// Return good completion status
// Don't use exit() or destructor won't get called
diff --git a/examples/make_tracing_c/sim_main.cpp b/examples/make_tracing_c/sim_main.cpp
index 08fa60098..edd786a14 100644
--- a/examples/make_tracing_c/sim_main.cpp
+++ b/examples/make_tracing_c/sim_main.cpp
@@ -14,42 +14,45 @@
// Include model header, generated from Verilating "top.v"
#include "Vtop.h"
-// Current simulation time (64-bit unsigned)
-vluint64_t main_time = 0;
-// Called by $time in Verilog
-double sc_time_stamp() {
- return main_time; // Note does conversion to real, to match SystemC
-}
-
int main(int argc, char** argv, char** env) {
// This is a more complicated example, please also see the simpler examples/make_hello_c.
// Prevent unused variable warnings
if (false && argc && argv && env) {}
- // Set debug level, 0 is off, 9 is highest presently used
- // May be overridden by commandArgs
- Verilated::debug(0);
-
- // Randomization reset policy
- // May be overridden by commandArgs
- Verilated::randReset(2);
-
- // Verilator must compute traced signals
- Verilated::traceEverOn(true);
-
- // Pass arguments so Verilated code can see them, e.g. $value$plusargs
- // This needs to be called before you create any model
- Verilated::commandArgs(argc, argv);
-
// Create logs/ directory in case we have traces to put under it
Verilated::mkdir("logs");
- // Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
- // Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end
- const std::unique_ptr top{new Vtop};
+ // Construct a VerilatedContext to hold simulation time, etc.
+ // Multiple modules (made later below with Vtop) may share the same
+ // context to share time, or modules may have different contexts if
+ // they should be independent from each other.
- // Set some inputs
+ // Using unique_ptr is similar to
+ // "VerilatedContext* contextp = new VerilatedContext" then deleting at end.
+ const std::unique_ptr contextp{new VerilatedContext};
+
+ // Set debug level, 0 is off, 9 is highest presently used
+ // May be overridden by commandArgs argument parsing
+ contextp->debug(0);
+
+ // Randomization reset policy
+ // May be overridden by commandArgs argument parsing
+ contextp->randReset(2);
+
+ // Verilator must compute traced signals
+ contextp->traceEverOn(true);
+
+ // Pass arguments so Verilated code can see them, e.g. $value$plusargs
+ // This needs to be called before you create any model
+ contextp->commandArgs(argc, argv);
+
+ // Construct the Verilated model, from Vtop.h generated from Verilating "top.v".
+ // Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end.
+ // "TOP" will be the hierarchical name of the module.
+ const std::unique_ptr top{new Vtop{contextp.get(), "TOP"}};
+
+ // Set Vtop's input signals
top->reset_l = !0;
top->clk = 0;
top->in_small = 1;
@@ -59,8 +62,19 @@ int main(int argc, char** argv, char** env) {
top->in_wide[2] = 0x3;
// Simulate until $finish
- while (!Verilated::gotFinish()) {
- main_time++; // Time passes...
+ while (!contextp->gotFinish()) {
+ // Historical note, before Verilator 4.200 Verilated::gotFinish()
+ // was used above in place of contextp->gotFinish().
+ // Most of the contextp-> calls can use Verilated:: calls instead;
+ // the Verilated:: versions simply assume there's a single context
+ // being used (per thread). It's faster and clearer to use the
+ // newer contextp-> versions.
+
+ contextp->timeInc(1); // 1 timeprecision period passes...
+ // Historical note, before Verilator 4.200 a sc_time_stamp()
+ // function was required instead of using timeInc. Once timeInc()
+ // is called (with non-zero), the Verilated libraries assume the
+ // new API, and sc_time_stamp() will no longer work.
// Toggle a fast (time/2 period) clock
top->clk = !top->clk;
@@ -70,7 +84,7 @@ int main(int argc, char** argv, char** env) {
// this only on a negedge of clk, because we know
// reset is not sampled there.
if (!top->clk) {
- if (main_time > 1 && main_time < 10) {
+ if (contextp->time() > 1 && contextp->time() < 10) {
top->reset_l = !1; // Assert reset
} else {
top->reset_l = !0; // Deassert reset
@@ -82,23 +96,23 @@ int main(int argc, char** argv, char** env) {
// Evaluate model
// (If you have multiple models being simulated in the same
// timestep then instead of eval(), call eval_step() on each, then
- // eval_end_step() on each.)
+ // eval_end_step() on each. See the manual.)
top->eval();
// Read outputs
VL_PRINTF("[%" VL_PRI64 "d] clk=%x rstl=%x iquad=%" VL_PRI64 "x"
" -> oquad=%" VL_PRI64 "x owide=%x_%08x_%08x\n",
- main_time, top->clk, top->reset_l, top->in_quad, top->out_quad, top->out_wide[2],
- top->out_wide[1], top->out_wide[0]);
+ contextp->time(), top->clk, top->reset_l, top->in_quad, top->out_quad,
+ top->out_wide[2], top->out_wide[1], top->out_wide[0]);
}
// Final model cleanup
top->final();
- // Coverage analysis (since test passed)
+ // Coverage analysis (calling write only after the test is known to pass)
#if VM_COVERAGE
Verilated::mkdir("logs");
- VerilatedCov::write("logs/coverage.dat");
+ contextp->coveragep()->write("logs/coverage.dat");
#endif
// Return good completion status
diff --git a/examples/make_tracing_sc/sc_main.cpp b/examples/make_tracing_sc/sc_main.cpp
index 4f7628113..ee42a0aa6 100644
--- a/examples/make_tracing_sc/sc_main.cpp
+++ b/examples/make_tracing_sc/sc_main.cpp
@@ -29,21 +29,26 @@ int sc_main(int argc, char* argv[]) {
// Prevent unused variable warnings
if (false && argc && argv) {}
+ // Create logs/ directory in case we have traces to put under it
+ Verilated::mkdir("logs");
+
// Set debug level, 0 is off, 9 is highest presently used
- // May be overridden by commandArgs
+ // May be overridden by commandArgs argument parsing
Verilated::debug(0);
// Randomization reset policy
- // May be overridden by commandArgs
+ // May be overridden by commandArgs argument parsing
Verilated::randReset(2);
+#if VM_TRACE
+ // Before any evaluation, need to know to calculate those signals only used for tracing
+ Verilated::traceEverOn(true);
+#endif
+
// Pass arguments so Verilated code can see them, e.g. $value$plusargs
// This needs to be called before you create any model
Verilated::commandArgs(argc, argv);
- // Create logs/ directory in case we have traces to put under it
- Verilated::mkdir("logs");
-
// General logfile
ios::sync_with_stdio();
@@ -64,7 +69,7 @@ int sc_main(int argc, char* argv[]) {
// Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end
const std::unique_ptr top{new Vtop{"top"}};
- // Attach signals to the model
+ // Attach Vtop's signals to this upper model
top->clk(clk);
top->fastclk(fastclk);
top->reset_l(reset_l);
@@ -75,11 +80,6 @@ int sc_main(int argc, char* argv[]) {
top->out_quad(out_quad);
top->out_wide(out_wide);
-#if VM_TRACE
- // Before any evaluation, need to know to calculate those signals only used for tracing
- Verilated::traceEverOn(true);
-#endif
-
// You must do one evaluation before enabling waves, in order to allow
// SystemC to interconnect everything for testing.
sc_start(1, SC_NS);
@@ -128,7 +128,7 @@ int sc_main(int argc, char* argv[]) {
}
#endif
- // Coverage analysis (since test passed)
+ // Coverage analysis (calling write only after the test is known to pass)
#if VM_COVERAGE
Verilated::mkdir("logs");
VerilatedCov::write("logs/coverage.dat");
diff --git a/examples/xml_py/vl_file_copy b/examples/xml_py/vl_file_copy
index d3f46629d..5eae927ed 100755
--- a/examples/xml_py/vl_file_copy
+++ b/examples/xml_py/vl_file_copy
@@ -1,16 +1,16 @@
#!/usr/bin/env python3
# -*- Python -*- See copyright, etc below
+# pylint: disable=C0114,C0115,R0903
######################################################################
import argparse
import os
import re
import subprocess
-import sys
import tempfile
import xml.etree.ElementTree as ET
from shutil import copy2
-from pprint import pprint, pformat
+# from pprint import pprint, pformat
#######################################################################
@@ -22,19 +22,20 @@ class VlFileCopy:
# ideally this script would check against options mentioned in help
debug=0,
output_dir='copied'): # directory name we output file uses
+
self.debug = debug
xml_temp = tempfile.NamedTemporaryFile()
- args = [
+ vargs = [
'--xml-output',
xml_temp.name,
'--bbox-sys', # Parse some stuff can't translate
'--bbox-unsup',
'--prefix vlxml'
] # So we know name of .xml output
- args += verilator_args
- self.run_verilator(args)
+ vargs += verilator_args
+ self.run_verilator(vargs)
self.tree = ET.parse(xml_temp.name)
os.makedirs(output_dir, 0o777, True)
@@ -49,13 +50,13 @@ class VlFileCopy:
print("\tcp %s %s" % (filename, output_dir))
copy2(filename, output_dir)
- def run_verilator(self, args):
+ def run_verilator(self, vargs):
"""Run Verilator command, check errors"""
if os.getenv("VERILATOR_ROOT"):
command = os.getenv("VERILATOR_ROOT") + "/bin/verilator"
else:
command = "verilator"
- command += ' ' + ' '.join(args)
+ command += ' ' + ' '.join(vargs)
if self.debug:
print("\t%s " % command)
status = subprocess.call(command, shell=True)
@@ -119,6 +120,6 @@ SPDX-License-Identifier: CC0-1.0
fc = VlFileCopy(output_dir=args.odir, debug=args.debug, verilator_args=rem)
######################################################################
-### Local Variables:
-### compile-command: "./vl_file_copy -h ; VERILATOR_ROOT=$V4 ./vl_file_copy +define+thru top.v"
-### End:
+# Local Variables:
+# compile-command: "./vl_file_copy -h ; VERILATOR_ROOT=$V4 ./vl_file_copy +define+thru top.v"
+# End:
diff --git a/examples/xml_py/vl_hier_graph b/examples/xml_py/vl_hier_graph
index af9f83023..359bd5da2 100755
--- a/examples/xml_py/vl_hier_graph
+++ b/examples/xml_py/vl_hier_graph
@@ -1,16 +1,14 @@
#!/usr/bin/env python3
# -*- Python -*- See copyright, etc below
+# pylint: disable=C0103,C0114,C0115,C0115,C0116,R0914
######################################################################
import argparse
import os
-import re
import subprocess
-import sys
import tempfile
import xml.etree.ElementTree as ET
-from shutil import copy2
-from pprint import pprint, pformat
+# from pprint import pprint, pformat
#######################################################################
@@ -28,15 +26,15 @@ class VlHierGraph:
xml_temp = tempfile.NamedTemporaryFile()
- args = [
+ vargs = [
'--xml-output',
xml_temp.name,
'--bbox-sys', # Parse some stuff can't translate
'--bbox-unsup',
'--prefix vlxml'
] # So we know name of .xml output
- args += verilator_args
- self.run_verilator(args)
+ vargs += verilator_args
+ self.run_verilator(vargs)
self.tree = ET.parse(xml_temp.name)
with open(output_filename, "w") as fh:
@@ -70,18 +68,18 @@ class VlHierGraph:
fh.write("}\n")
def name_to_vertex_number(self, name):
- if not name in self.name_to_number:
+ if name not in self.name_to_number:
self.next_vertex_number += 1
self.name_to_number[name] = self.next_vertex_number
return self.name_to_number[name]
- def run_verilator(self, args):
+ def run_verilator(self, vargs):
"""Run Verilator command, check errors"""
if os.getenv("VERILATOR_ROOT"):
command = os.getenv("VERILATOR_ROOT") + "/bin/verilator"
else:
command = "verilator"
- command += ' ' + ' '.join(args)
+ command += ' ' + ' '.join(vargs)
if self.debug:
print("\t%s " % command)
status = subprocess.call(command, shell=True)
@@ -146,6 +144,6 @@ SPDX-License-Identifier: CC0-1.0
verilator_args=rem)
######################################################################
-### Local Variables:
-### compile-command: "./vl_hier_graph -h ; VERILATOR_ROOT=$V4 ./vl_hier_graph +define+thru top.v"
-### End:
+# Local Variables:
+# compile-command: "./vl_hier_graph -h ; VERILATOR_ROOT=$V4 ./vl_hier_graph +define+thru top.v"
+# End:
diff --git a/include/verilated.cpp b/include/verilated.cpp
index 17949a17c..0421b0438 100644
--- a/include/verilated.cpp
+++ b/include/verilated.cpp
@@ -15,11 +15,35 @@
/// This file must be compiled and linked against all objects
/// created from Verilator.
///
+/// Those macro/function/variable starting or ending in _ are internal,
+/// however many of the other function/macros here are also internal.
+///
/// Code available from: https://verilator.org
///
//=========================================================================
+// Internal note:
+//
+// verilated.o may exist both in protect-lib (incrementally linked .a/.so)
+// and the main module. Both refer the same instance of static
+// variables/VL_THREAD_LOCAL in verilated.o such as Verilated, or
+// VerilatedImpData. This is important to share that state, but the
+// sharing may cause a double-free error when shutting down because the
+// loader will insert a constructor/destructor at each reference to
+// verilated.o, resulting in at runtime constructors/destructors being
+// called multiple times.
+//
+// To avoid the trouble:
+// * Statics declared inside functions. The compiler will wrap
+// the construction in must-be-one-time checks.
+// * Or, use only C++20 constinit types. (TODO: Make a VL_CONSTINIT).
+// * Or, use types that are multi-constructor safe.
+// * Or, the static should be of a union, which will avoid compiler
+// construction, and appropriately check for duplicate construction.
+// * Or, code is not linked in protected library. e.g. the VPI
+// and DPI libraries are not needed there.
+//=========================================================================
-#define _VERILATED_CPP_
+#define VERILATOR_VERILATED_CPP_
#include "verilatedos.h"
#include "verilated_imp.h"
@@ -54,41 +78,16 @@ static_assert(sizeof(vluint64_t) == 8, "vluint8_t is missized");
//===========================================================================
// Global variables
+// Internal note: Globals may multi-construct, see verilated.cpp top.
-// Slow path variables
-VerilatedMutex Verilated::s_mutex;
+// Fast path, keep together
+int Verilated::s_debug = 0;
+VerilatedContext* Verilated::s_lastContextp = nullptr;
// Keep below together in one cache line
-Verilated::Serialized Verilated::s_s;
-Verilated::NonSerialized Verilated::s_ns;
+// Internal note: Globals may multi-construct, see verilated.cpp top.
VL_THREAD_LOCAL Verilated::ThreadLocal Verilated::t_s;
-Verilated::CommandArgValues Verilated::s_args;
-
-VerilatedImp::VerilatedImpU VerilatedImp::s_s;
-
-// Guarantees to call setup() and teardown() just once.
-struct VerilatedInitializer {
- VerilatedInitializer() { setup(); }
- ~VerilatedInitializer() { teardown(); }
- void setup() {
- static bool done = false;
- if (!done) {
- VerilatedImp::setup();
- Verilated::s_ns.setup();
- done = true;
- }
- }
- void teardown() {
- static bool done = false;
- if (!done) {
- VerilatedImp::teardown();
- Verilated::s_ns.teardown();
- done = true;
- }
- }
-} s_VerilatedInitializer;
-
//===========================================================================
// User definable functions
// Note a TODO is a future version of the API will pass a structure so that
@@ -99,29 +98,41 @@ 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
"- %s:%d: Verilog $finish\n", filename, linenum);
- if (Verilated::gotFinish()) {
+ if (Verilated::threadContextp()->gotFinish()) {
VL_PRINTF( // Not VL_PRINTF_MT, already on main thread
"- %s:%d: Second verilog $finish, exiting\n", filename, linenum);
Verilated::runFlushCallbacks();
Verilated::runExitCallbacks();
exit(0);
}
- Verilated::gotFinish(true);
+ Verilated::threadContextp()->gotFinish(true);
}
#endif
#ifndef VL_USER_STOP ///< Define this to override this function
void vl_stop(const char* filename, int linenum, const char* hier) VL_MT_UNSAFE {
- Verilated::gotFinish(true);
- Verilated::runFlushCallbacks();
- vl_fatal(filename, linenum, hier, "Verilog $stop");
+ const char* const msg = "Verilog $stop";
+ Verilated::threadContextp()->gotError(true);
+ Verilated::threadContextp()->gotFinish(true);
+ if (Verilated::threadContextp()->fatalOnError()) {
+ vl_fatal(filename, linenum, hier, msg);
+ } else {
+ if (filename && filename[0]) {
+ // Not VL_PRINTF_MT, already on main thread
+ VL_PRINTF("%%Error: %s:%d: %s\n", filename, linenum, msg);
+ } else {
+ VL_PRINTF("%%Error: %s\n", msg);
+ }
+ Verilated::runFlushCallbacks();
+ }
}
#endif
#ifndef VL_USER_FATAL ///< Define this to override this function
void vl_fatal(const char* filename, int linenum, const char* hier, const char* msg) VL_MT_UNSAFE {
if (false && hier) {}
- Verilated::gotFinish(true);
+ Verilated::threadContextp()->gotError(true);
+ Verilated::threadContextp()->gotFinish(true);
if (filename && filename[0]) {
// Not VL_PRINTF_MT, already on main thread
VL_PRINTF("%%Error: %s:%d: %s\n", filename, linenum, msg);
@@ -143,8 +154,9 @@ void vl_fatal(const char* filename, int linenum, const char* hier, const char* m
#ifndef VL_USER_STOP_MAYBE ///< Define this to override this function
void vl_stop_maybe(const char* filename, int linenum, const char* hier, bool maybe) VL_MT_UNSAFE {
- Verilated::errorCountInc();
- if (maybe && Verilated::errorCount() < Verilated::errorLimit()) {
+ Verilated::threadContextp()->errorCountInc();
+ if (maybe
+ && Verilated::threadContextp()->errorCount() < Verilated::threadContextp()->errorLimit()) {
VL_PRINTF( // Not VL_PRINTF_MT, already on main thread
"-Info: %s:%d: %s\n", filename, linenum,
"Verilog $stop, ignored due to +verilator+error+limit");
@@ -255,34 +267,6 @@ void VL_PRINTF_MT(const char* formatp, ...) VL_MT_SAFE {
}
#endif
-//===========================================================================
-// Overall class init
-
-Verilated::Serialized::Serialized() {
- s_calcUnusedSigs = false;
- s_gotFinish = false;
- s_assertOn = true;
- s_fatalOnVpiError = true; // retains old default behaviour
- s_errorCount = 0;
- s_errorLimit = 1;
- s_randReset = 0;
- s_randSeed = 0;
- s_randSeedEpoch = 1;
- s_timeunit = VL_TIME_UNIT; // Initial value until overriden by _Vconfigure
- s_timeprecision = VL_TIME_PRECISION; // Initial value until overriden by _Vconfigure
-}
-
-void Verilated::NonSerialized::setup() { s_profThreadsFilenamep = strdup("profile_threads.dat"); }
-void Verilated::NonSerialized::teardown() {
- if (s_profThreadsFilenamep) {
- VL_DO_CLEAR(free(const_cast(s_profThreadsFilenamep)),
- s_profThreadsFilenamep = nullptr);
- }
-}
-
-size_t Verilated::serialized2Size() VL_PURE { return sizeof(VerilatedImp::s_s.v.m_ser); }
-void* Verilated::serialized2Ptr() VL_MT_UNSAFE { return &VerilatedImp::s_s.v.m_ser; }
-
//===========================================================================
// Random -- Mostly called at init time, so not inline.
@@ -300,13 +284,14 @@ static vluint32_t vl_sys_rand32() VL_MT_UNSAFE {
}
vluint64_t vl_rand64() VL_MT_SAFE {
- static VL_THREAD_LOCAL vluint32_t t_seedEpoch = 0;
static VL_THREAD_LOCAL vluint64_t t_state[2];
+ static VL_THREAD_LOCAL vluint32_t t_seedEpoch = 0;
// For speed, we use a thread-local epoch number to know when to reseed
- if (VL_UNLIKELY(t_seedEpoch != Verilated::randSeedEpoch())) {
- // Set epoch before state, in case races with new seeding
- t_seedEpoch = Verilated::randSeedEpoch();
- t_state[0] = Verilated::randSeedDefault64();
+ // A thread always belongs to a single context, so this works out ok
+ if (VL_UNLIKELY(t_seedEpoch != VerilatedContextImp::randSeedEpoch())) {
+ // Set epoch before state, to avoid race case with new seeding
+ t_seedEpoch = VerilatedContextImp::randSeedEpoch();
+ t_state[0] = Verilated::threadContextp()->impp()->randSeedDefault64();
t_state[1] = t_state[0];
// Fix state as algorithm is slow to randomize if many zeros
// This causes a loss of ~ 1 bit of seed entropy, no big deal
@@ -333,23 +318,23 @@ WDataOutP VL_RANDOM_W(int obits, WDataOutP outwp) VL_MT_SAFE {
#endif
IData VL_RANDOM_SEEDED_II(int obits, IData seed) VL_MT_SAFE {
- Verilated::randSeed(static_cast(seed));
+ Verilated::threadContextp()->randSeed(static_cast(seed));
return VL_RANDOM_I(obits);
}
IData VL_RAND_RESET_I(int obits) VL_MT_SAFE {
- if (Verilated::randReset() == 0) return 0;
+ if (Verilated::threadContextp()->randReset() == 0) return 0;
IData data = ~0;
- if (Verilated::randReset() != 1) { // if 2, randomize
+ if (Verilated::threadContextp()->randReset() != 1) { // if 2, randomize
data = VL_RANDOM_I(obits);
}
data &= VL_MASK_I(obits);
return data;
}
QData VL_RAND_RESET_Q(int obits) VL_MT_SAFE {
- if (Verilated::randReset() == 0) return 0;
+ if (Verilated::threadContextp()->randReset() == 0) return 0;
QData data = ~0ULL;
- if (Verilated::randReset() != 1) { // if 2, randomize
+ if (Verilated::threadContextp()->randReset() != 1) { // if 2, randomize
data = VL_RANDOM_Q(obits);
}
data &= VL_MASK_Q(obits);
@@ -369,7 +354,7 @@ WDataOutP VL_ZERO_RESET_W(int obits, WDataOutP outwp) VL_MT_SAFE {
//===========================================================================
// Debug
-void _VL_DEBUG_PRINT_W(int lbits, WDataInP iwp) VL_MT_SAFE {
+void _vl_debug_print_w(int lbits, WDataInP iwp) VL_MT_SAFE {
VL_PRINTF_MT(" Data: w%d: ", lbits);
for (int i = VL_WORDS_I(lbits) - 1; i >= 0; --i) VL_PRINTF_MT("%08x ", iwp[i]);
VL_PRINTF_MT("\n");
@@ -604,7 +589,7 @@ double VL_ISTOR_D_W(int lbits, WDataInP lwp) VL_PURE {
if (!VL_SIGN_W(lbits, lwp)) return VL_ITOR_D_W(lbits, lwp);
vluint32_t pos[VL_MULS_MAX_WORDS + 1]; // Fixed size, as MSVC++ doesn't allow [words] here
VL_NEGATE_W(VL_WORDS_I(lbits), pos, lwp);
- _VL_CLEAN_INPLACE_W(lbits, pos);
+ _vl_clean_inplace_w(lbits, pos);
return -VL_ITOR_D_W(lbits, pos);
}
@@ -652,10 +637,10 @@ std::string VL_DECIMAL_NW(int width, WDataInP lwp) VL_MT_SAFE {
std::string _vl_vsformat_time(char* tmp, double ld, bool left, size_t width) {
// Double may lose precision, but sc_time_stamp has similar limit
- std::string suffix = VerilatedImp::timeFormatSuffix();
- int userUnits = VerilatedImp::timeFormatUnits(); // 0..-15
- int fracDigits = VerilatedImp::timeFormatPrecision(); // 0..N
- int prec = Verilated::timeprecision(); // 0..-15
+ std::string suffix = Verilated::threadContextp()->impp()->timeFormatSuffix();
+ int userUnits = Verilated::threadContextp()->impp()->timeFormatUnits(); // 0..-15
+ int fracDigits = Verilated::threadContextp()->impp()->timeFormatPrecision(); // 0..N
+ int prec = Verilated::threadContextp()->timeprecision(); // 0..-15
int shift = prec - userUnits + fracDigits; // 0..-15
double shiftd = vl_time_multiplier(shift);
double scaled = ld * shiftd;
@@ -664,10 +649,11 @@ std::string _vl_vsformat_time(char* tmp, double ld, bool left, size_t width) {
QData fraction = static_cast(scaled) % fracDiv;
int digits = 0;
if (!fracDigits) {
- digits = sprintf(tmp, "%" VL_PRI64 "u%s", whole, suffix.c_str());
+ digits = VL_SNPRINTF(tmp, VL_VALUE_STRING_MAX_WIDTH, "%" VL_PRI64 "u%s", whole,
+ suffix.c_str());
} else {
- digits = sprintf(tmp, "%" VL_PRI64 "u.%0*" VL_PRI64 "u%s", whole, fracDigits, fraction,
- suffix.c_str());
+ digits = VL_SNPRINTF(tmp, VL_VALUE_STRING_MAX_WIDTH, "%" VL_PRI64 "u.%0*" VL_PRI64 "u%s",
+ whole, fracDigits, fraction, suffix.c_str());
}
int needmore = width - digits;
std::string padding;
@@ -676,7 +662,7 @@ std::string _vl_vsformat_time(char* tmp, double ld, bool left, size_t width) {
}
// Do a va_arg returning a quad, assuming input argument is anything less than wide
-#define _VL_VA_ARG_Q(ap, bits) (((bits) <= VL_IDATASIZE) ? va_arg(ap, IData) : va_arg(ap, QData))
+#define VL_VA_ARG_Q_(ap, bits) (((bits) <= VL_IDATASIZE) ? va_arg(ap, IData) : va_arg(ap, QData))
void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SAFE {
// Format a Verilog $write style format into the output list
@@ -763,11 +749,11 @@ void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SA
double d = va_arg(ap, double);
if (lbits) {} // UNUSED - always 64
if (fmt == '^') { // Realtime
- if (!widthSet) width = VerilatedImp::timeFormatWidth();
+ if (!widthSet) width = Verilated::threadContextp()->impp()->timeFormatWidth();
output += _vl_vsformat_time(t_tmp, d, left, width);
} else {
std::string fmts(pctp, pos - pctp + 1);
- sprintf(t_tmp, fmts.c_str(), d);
+ VL_SNPRINTF(t_tmp, VL_VALUE_STRING_MAX_WIDTH, fmts.c_str(), d);
output += t_tmp;
}
break;
@@ -779,7 +765,7 @@ void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SA
WData qlwp[VL_WQ_WORDS_E];
WDataInP lwp = nullptr;
if (lbits <= VL_QUADSIZE) {
- ld = _VL_VA_ARG_Q(ap, lbits);
+ ld = VL_VA_ARG_Q_(ap, lbits);
VL_SET_WQ(qlwp, ld);
lwp = qlwp;
} else {
@@ -812,8 +798,9 @@ void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SA
int digits = 0;
std::string append;
if (lbits <= VL_QUADSIZE) {
- digits = sprintf(t_tmp, "%" VL_PRI64 "d",
- static_cast(VL_EXTENDS_QQ(lbits, lbits, ld)));
+ digits = VL_SNPRINTF(
+ t_tmp, VL_VALUE_STRING_MAX_WIDTH, "%" VL_PRI64 "d",
+ static_cast(VL_EXTENDS_QQ(lbits, lbits, ld)));
append = t_tmp;
} else {
if (VL_SIGN_E(lbits, lwp[VL_WORDS_I(lbits) - 1])) {
@@ -841,7 +828,8 @@ void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SA
int digits = 0;
std::string append;
if (lbits <= VL_QUADSIZE) {
- digits = sprintf(t_tmp, "%" VL_PRI64 "u", ld);
+ digits
+ = VL_SNPRINTF(t_tmp, VL_VALUE_STRING_MAX_WIDTH, "%" VL_PRI64 "u", ld);
append = t_tmp;
} else {
append = VL_DECIMAL_NW(lbits, lwp);
@@ -860,7 +848,7 @@ void _vl_vsformat(std::string& output, const char* formatp, va_list ap) VL_MT_SA
break;
}
case 't': { // Time
- if (!widthSet) width = VerilatedImp::timeFormatWidth();
+ if (!widthSet) width = Verilated::threadContextp()->impp()->timeFormatWidth();
output += _vl_vsformat_time(t_tmp, static_cast(ld), left, width);
break;
}
@@ -1234,10 +1222,10 @@ done:
FILE* VL_CVT_I_FP(IData lhs) VL_MT_SAFE {
// Expected non-MCD case; returns null on MCD descriptors.
- return VerilatedImp::fdToFp(lhs);
+ return Verilated::threadContextp()->impp()->fdToFp(lhs);
}
-void _VL_VINT_TO_STRING(int obits, char* destoutp, WDataInP sourcep) VL_MT_SAFE {
+void _vl_vint_to_string(int obits, char* destoutp, WDataInP sourcep) VL_MT_SAFE {
// See also VL_DATA_TO_STRING_NW
int lsb = obits - 1;
bool start = true;
@@ -1256,7 +1244,7 @@ void _VL_VINT_TO_STRING(int obits, char* destoutp, WDataInP sourcep) VL_MT_SAFE
}
}
-void _VL_STRING_TO_VINT(int obits, void* destp, size_t srclen, const char* srcp) VL_MT_SAFE {
+void _vl_string_to_vint(int obits, void* destp, size_t srclen, const char* srcp) VL_MT_SAFE {
// Convert C string to Verilog format
size_t bytes = VL_BYTES_I(obits);
char* op = reinterpret_cast(destp);
@@ -1295,7 +1283,7 @@ IData VL_FGETS_IXI(int obits, void* destp, IData fpi) VL_MT_SAFE {
VL_FATAL_MT(__FILE__, __LINE__, "", "Internal: fgets buffer overrun"); // LCOV_EXCL_LINE
}
- _VL_STRING_TO_VINT(obits, destp, got, str.data());
+ _vl_string_to_vint(obits, destp, got, str.data());
return got;
}
@@ -1312,20 +1300,20 @@ IData VL_FERROR_IN(IData, std::string& outputr) VL_MT_SAFE {
}
IData VL_FOPEN_NN(const std::string& filename, const std::string& mode) {
- return VerilatedImp::fdNew(filename.c_str(), mode.c_str());
+ return Verilated::threadContextp()->impp()->fdNew(filename.c_str(), mode.c_str());
}
IData VL_FOPEN_MCD_N(const std::string& filename) VL_MT_SAFE {
- return VerilatedImp::fdNewMcd(filename.c_str());
+ return Verilated::threadContextp()->impp()->fdNewMcd(filename.c_str());
}
-void VL_FFLUSH_I(IData fdi) VL_MT_SAFE { VerilatedImp::fdFlush(fdi); }
+void VL_FFLUSH_I(IData fdi) VL_MT_SAFE { Verilated::threadContextp()->impp()->fdFlush(fdi); }
IData VL_FSEEK_I(IData fdi, IData offset, IData origin) VL_MT_SAFE {
- return VerilatedImp::fdSeek(fdi, offset, origin);
+ return Verilated::threadContextp()->impp()->fdSeek(fdi, offset, origin);
}
-IData VL_FTELL_I(IData fdi) VL_MT_SAFE { return VerilatedImp::fdTell(fdi); }
+IData VL_FTELL_I(IData fdi) VL_MT_SAFE { return Verilated::threadContextp()->impp()->fdTell(fdi); }
void VL_FCLOSE_I(IData fdi) VL_MT_SAFE {
// While threadsafe, each thread can only access different file handles
- VerilatedImp::fdClose(fdi);
+ Verilated::threadContextp()->impp()->fdClose(fdi);
}
void VL_SFORMAT_X(int obits, CData& destr, const char* formatp, ...) VL_MT_SAFE {
@@ -1336,7 +1324,7 @@ void VL_SFORMAT_X(int obits, CData& destr, const char* formatp, ...) VL_MT_SAFE
_vl_vsformat(t_output, formatp, ap);
va_end(ap);
- _VL_STRING_TO_VINT(obits, &destr, t_output.length(), t_output.c_str());
+ _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
}
void VL_SFORMAT_X(int obits, SData& destr, const char* formatp, ...) VL_MT_SAFE {
@@ -1347,7 +1335,7 @@ void VL_SFORMAT_X(int obits, SData& destr, const char* formatp, ...) VL_MT_SAFE
_vl_vsformat(t_output, formatp, ap);
va_end(ap);
- _VL_STRING_TO_VINT(obits, &destr, t_output.length(), t_output.c_str());
+ _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
}
void VL_SFORMAT_X(int obits, IData& destr, const char* formatp, ...) VL_MT_SAFE {
@@ -1358,7 +1346,7 @@ void VL_SFORMAT_X(int obits, IData& destr, const char* formatp, ...) VL_MT_SAFE
_vl_vsformat(t_output, formatp, ap);
va_end(ap);
- _VL_STRING_TO_VINT(obits, &destr, t_output.length(), t_output.c_str());
+ _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
}
void VL_SFORMAT_X(int obits, QData& destr, const char* formatp, ...) VL_MT_SAFE {
@@ -1369,7 +1357,7 @@ void VL_SFORMAT_X(int obits, QData& destr, const char* formatp, ...) VL_MT_SAFE
_vl_vsformat(t_output, formatp, ap);
va_end(ap);
- _VL_STRING_TO_VINT(obits, &destr, t_output.length(), t_output.c_str());
+ _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
}
void VL_SFORMAT_X(int obits, void* destp, const char* formatp, ...) VL_MT_SAFE {
@@ -1380,7 +1368,7 @@ void VL_SFORMAT_X(int obits, void* destp, const char* formatp, ...) VL_MT_SAFE {
_vl_vsformat(t_output, formatp, ap);
va_end(ap);
- _VL_STRING_TO_VINT(obits, destp, t_output.length(), t_output.c_str());
+ _vl_string_to_vint(obits, destp, t_output.length(), t_output.c_str());
}
void VL_SFORMAT_X(int obits_ignored, std::string& output, const char* formatp, ...) VL_MT_SAFE {
@@ -1424,7 +1412,7 @@ void VL_FWRITEF(IData fpi, const char* formatp, ...) VL_MT_SAFE {
_vl_vsformat(t_output, formatp, ap);
va_end(ap);
- VerilatedImp::fdWrite(fpi, t_output);
+ Verilated::threadContextp()->impp()->fdWrite(fpi, t_output);
}
IData VL_FSCANF_IX(IData fpi, const char* formatp, ...) VL_MT_SAFE {
@@ -1533,13 +1521,13 @@ 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);
+ _vl_vint_to_string(lhswords * VL_EDATASIZE, filenamez, lhsp);
int code = system(filenamez); // Yes, system() is threadsafe
return code >> 8; // Want exit status
}
IData VL_TESTPLUSARGS_I(const char* formatp) VL_MT_SAFE {
- const std::string& match = VerilatedImp::argPlusMatch(formatp);
+ const std::string& match = Verilated::threadContextp()->impp()->argPlusMatch(formatp);
return match.empty() ? 0 : 1;
}
@@ -1567,7 +1555,7 @@ IData VL_VALUEPLUSARGS_INW(int rbits, const std::string& ld, WDataOutP rwp) VL_M
}
}
- const std::string& match = VerilatedImp::argPlusMatch(prefix.c_str());
+ const std::string& match = Verilated::threadContextp()->impp()->argPlusMatch(prefix.c_str());
const char* dp = match.c_str() + 1 /*leading + */ + prefix.length();
if (match.empty()) return 0;
@@ -1612,7 +1600,7 @@ IData VL_VALUEPLUSARGS_INW(int rbits, const std::string& ld, WDataOutP rwp) VL_M
default: // Other simulators simply return 0 in these cases and don't error out
return 0;
}
- _VL_CLEAN_INPLACE_W(rbits, rwp);
+ _vl_clean_inplace_w(rbits, rwp);
return 1;
}
IData VL_VALUEPLUSARGS_INN(int, const std::string& ld, std::string& rdr) VL_MT_SAFE {
@@ -1636,7 +1624,7 @@ IData VL_VALUEPLUSARGS_INN(int, const std::string& ld, std::string& rdr) VL_MT_S
}
}
}
- const std::string& match = VerilatedImp::argPlusMatch(prefix.c_str());
+ const std::string& match = Verilated::threadContextp()->impp()->argPlusMatch(prefix.c_str());
const char* dp = match.c_str() + 1 /*leading + */ + prefix.length();
if (match.empty()) return 0;
rdr = std::string(dp);
@@ -1644,12 +1632,14 @@ IData VL_VALUEPLUSARGS_INN(int, const std::string& ld, std::string& rdr) VL_MT_S
}
const char* vl_mc_scan_plusargs(const char* prefixp) VL_MT_SAFE {
- const std::string& match = VerilatedImp::argPlusMatch(prefixp);
+ const std::string& match = Verilated::threadContextp()->impp()->argPlusMatch(prefixp);
static VL_THREAD_LOCAL char t_outstr[VL_VALUE_STRING_MAX_WIDTH];
if (match.empty()) return nullptr;
- t_outstr[0] = '\0';
- strncat(t_outstr, match.c_str() + strlen(prefixp) + 1, // +1 to skip the "+"
- VL_VALUE_STRING_MAX_WIDTH - 1);
+ char* dp = t_outstr;
+ for (const char* sp = match.c_str() + strlen(prefixp) + 1; // +1 to skip the "+"
+ *sp && (dp - t_outstr) < (VL_VALUE_STRING_MAX_WIDTH - 2);)
+ *dp++ = *sp++;
+ *dp++ = '\0';
return t_outstr;
}
@@ -1676,7 +1666,7 @@ std::string VL_TOUPPER_NN(const std::string& ld) VL_MT_SAFE {
}
std::string VL_CVT_PACK_STR_NW(int lwords, WDataInP lwp) VL_MT_SAFE {
- // See also _VL_VINT_TO_STRING
+ // See also _vl_vint_to_string
char destout[VL_TO_STRING_MAX_WORDS * VL_EDATASIZE + 1];
int obits = lwords * VL_EDATASIZE;
int lsb = obits - 1;
@@ -1731,25 +1721,6 @@ IData VL_ATOI_N(const std::string& str, int base) VL_PURE {
return static_cast(v);
}
-//===========================================================================
-// Dumping
-
-const char* vl_dumpctl_filenamep(bool setit, const std::string& filename) VL_MT_SAFE {
- // This function performs both accessing and setting so it's easy to make an in-function static
- static VL_THREAD_LOCAL std::string t_filename;
- if (setit) {
- t_filename = filename;
- } else {
- static VL_THREAD_LOCAL bool t_warned = false;
- if (VL_UNLIKELY(t_filename.empty() && !t_warned)) {
- t_warned = true;
- VL_PRINTF_MT("%%Warning: $dumpvar ignored as not proceeded by $dumpfile\n");
- return "";
- }
- }
- return t_filename.c_str();
-}
-
//===========================================================================
// Readmem/writemem
@@ -1912,7 +1883,7 @@ void VlReadMem::setData(void* valuep, const std::string& rhs) {
} else {
WDataOutP datap = reinterpret_cast(valuep);
if (!innum) VL_ZERO_RESET_W(m_bits, datap);
- _VL_SHIFTL_INPLACE_W(m_bits, datap, static_cast(shift));
+ _vl_shiftl_inplace_w(m_bits, datap, static_cast(shift));
datap[0] |= value;
}
innum = true;
@@ -2181,99 +2152,119 @@ double vl_time_multiplier(int scale) VL_PURE {
return pow10[scale];
}
}
-const char* Verilated::timeunitString() VL_MT_SAFE { return vl_time_str(timeunit()); }
-const char* Verilated::timeprecisionString() VL_MT_SAFE { return vl_time_str(timeprecision()); }
-void VL_PRINTTIMESCALE(const char* namep, const char* timeunitp) VL_MT_SAFE {
+void VL_PRINTTIMESCALE(const char* namep, const char* timeunitp,
+ const VerilatedContext* contextp) VL_MT_SAFE {
VL_PRINTF_MT("Time scale of %s is %s / %s\n", namep, timeunitp,
- Verilated::timeprecisionString());
+ contextp->timeprecisionString());
}
-void VL_TIMEFORMAT_IINI(int units, int precision, const std::string& suffix,
- int width) VL_MT_SAFE {
- VerilatedImp::timeFormatUnits(units);
- VerilatedImp::timeFormatPrecision(precision);
- VerilatedImp::timeFormatSuffix(suffix);
- VerilatedImp::timeFormatWidth(width);
+void VL_TIMEFORMAT_IINI(int units, int precision, const std::string& suffix, int width,
+ VerilatedContext* contextp) VL_MT_SAFE {
+ contextp->impp()->timeFormatUnits(units);
+ contextp->impp()->timeFormatPrecision(precision);
+ contextp->impp()->timeFormatSuffix(suffix);
+ contextp->impp()->timeFormatWidth(width);
}
-//===========================================================================
-// Verilated:: Methods
+//======================================================================
+// VerilatedContext:: Methods
-void Verilated::debug(int level) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_ns.s_debug = level;
- if (level) {
-#ifdef VL_DEBUG
- VL_DEBUG_IF(VL_DBG_MSGF("- Verilated::debug is on."
- " Message prefix indicates {,}.\n"););
-#else
- VL_PRINTF_MT("- Verilated::debug attempted,"
- " but compiled without VL_DEBUG, so messages suppressed.\n"
- "- Suggest remake using 'make ... CPPFLAGS=-DVL_DEBUG'\n");
-#endif
+VerilatedContext::VerilatedContext()
+ : m_impdatap{new VerilatedContextImpData} {
+ Verilated::lastContextp(this);
+ Verilated::threadContextp(this);
+ m_ns.m_profThreadsFilename = "profile_threads.dat";
+ m_fdps.resize(31);
+ std::fill(m_fdps.begin(), m_fdps.end(), (FILE*)0);
+ m_fdFreeMct.resize(30);
+ for (std::size_t i = 0, id = 1; i < m_fdFreeMct.size(); ++i, ++id) m_fdFreeMct[i] = id;
+}
+
+// Must declare here not in interface, as otherwise forward declarations not known
+VerilatedContext::~VerilatedContext() {}
+
+VerilatedContext::Serialized::Serialized() {
+ m_timeunit = VL_TIME_UNIT; // Initial value until overriden by _Vconfigure
+ m_timeprecision = VL_TIME_PRECISION; // Initial value until overriden by _Vconfigure
+}
+
+void VerilatedContext::assertOn(bool flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_assertOn = flag;
+}
+void VerilatedContext::calcUnusedSigs(bool flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_calcUnusedSigs = flag;
+}
+void VerilatedContext::dumpfile(const std::string& flag) VL_MT_SAFE_EXCLUDES(m_timeDumpMutex) {
+ const VerilatedLockGuard lock(m_timeDumpMutex);
+ m_dumpfile = flag;
+}
+std::string VerilatedContext::dumpfile() const VL_MT_SAFE_EXCLUDES(m_timeDumpMutex) {
+ const VerilatedLockGuard lock(m_timeDumpMutex);
+ if (VL_UNLIKELY(m_dumpfile.empty())) {
+ VL_PRINTF_MT("%%Warning: $dumpvar ignored as not proceeded by $dumpfile\n");
+ return "";
}
+ return m_dumpfile;
}
-void Verilated::randReset(int val) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_randReset = val;
+void VerilatedContext::errorCount(int val) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_errorCount = val;
}
-void Verilated::randSeed(int val) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_randSeed = val;
- vluint64_t newEpoch = s_s.s_randSeedEpoch + 1;
- if (VL_UNLIKELY(newEpoch == 0)) newEpoch = 1;
- // Obververs must see new epoch AFTER seed updated
-#ifdef VL_THREADED
- std::atomic_signal_fence(std::memory_order_release);
-#endif
- s_s.s_randSeedEpoch = newEpoch;
+void VerilatedContext::errorCountInc() VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ ++m_s.m_errorCount;
}
-vluint64_t Verilated::randSeedDefault64() VL_MT_SAFE {
- if (Verilated::randSeed() != 0) {
- return ((static_cast(Verilated::randSeed()) << 32)
- ^ (static_cast(Verilated::randSeed())));
- } else {
- return ((static_cast(vl_sys_rand32()) << 32)
- ^ (static_cast(vl_sys_rand32())));
- }
+void VerilatedContext::errorLimit(int val) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_errorLimit = val;
}
-void Verilated::calcUnusedSigs(bool flag) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_calcUnusedSigs = flag;
+void VerilatedContext::fatalOnError(bool flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_fatalOnError = flag;
}
-void Verilated::errorCount(int val) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_errorCount = val;
+void VerilatedContext::fatalOnVpiError(bool flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_fatalOnVpiError = flag;
}
-void Verilated::errorCountInc() VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- ++s_s.s_errorCount;
+void VerilatedContext::gotError(bool flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_gotError = flag;
}
-void Verilated::errorLimit(int val) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_errorLimit = val;
+void VerilatedContext::gotFinish(bool flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_gotFinish = flag;
}
-void Verilated::gotFinish(bool flag) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_gotFinish = flag;
+void VerilatedContext::profThreadsStart(vluint64_t flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_ns.m_profThreadsStart = flag;
}
-void Verilated::assertOn(bool flag) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_assertOn = flag;
+void VerilatedContext::profThreadsWindow(vluint64_t flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_ns.m_profThreadsWindow = flag;
}
-void Verilated::fatalOnVpiError(bool flag) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_fatalOnVpiError = flag;
+void VerilatedContext::profThreadsFilename(const std::string& flag) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_ns.m_profThreadsFilename = flag;
}
-void Verilated::timeunit(int value) VL_MT_SAFE {
+std::string VerilatedContext::profThreadsFilename() const VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ return m_ns.m_profThreadsFilename;
+}
+void VerilatedContext::randReset(int val) VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_randReset = val;
+}
+void VerilatedContext::timeunit(int value) VL_MT_SAFE {
if (value < 0) value = -value; // Stored as 0..15
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_timeunit = value;
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_timeunit = value;
}
-void Verilated::timeprecision(int value) VL_MT_SAFE {
+void VerilatedContext::timeprecision(int value) VL_MT_SAFE {
if (value < 0) value = -value; // Stored as 0..15
- const VerilatedLockGuard lock(s_mutex);
- s_s.s_timeprecision = value;
+ const VerilatedLockGuard lock(m_mutex);
+ m_s.m_timeprecision = value;
#ifdef SYSTEMC_VERSION
sc_time sc_res = sc_get_time_resolution();
int sc_prec = 99;
@@ -2302,18 +2293,243 @@ void Verilated::timeprecision(int value) VL_MT_SAFE {
}
#endif
}
-void Verilated::profThreadsStart(vluint64_t flag) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_ns.s_profThreadsStart = flag;
+const char* VerilatedContext::timeunitString() const VL_MT_SAFE { return vl_time_str(timeunit()); }
+const char* VerilatedContext::timeprecisionString() const VL_MT_SAFE {
+ return vl_time_str(timeprecision());
}
-void Verilated::profThreadsWindow(vluint64_t flag) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- s_ns.s_profThreadsWindow = flag;
+
+void VerilatedContext::commandArgs(int argc, const char** argv) VL_MT_SAFE_EXCLUDES(m_argMutex) {
+ const VerilatedLockGuard lock(m_argMutex);
+ m_args.m_argVec.clear(); // Empty first, then add
+ impp()->commandArgsAddGuts(argc, argv);
}
-void Verilated::profThreadsFilenamep(const char* flagp) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- if (s_ns.s_profThreadsFilenamep) free(const_cast(s_ns.s_profThreadsFilenamep));
- s_ns.s_profThreadsFilenamep = strdup(flagp);
+void VerilatedContext::commandArgsAdd(int argc, const char** argv)
+ VL_MT_SAFE_EXCLUDES(m_argMutex) {
+ const VerilatedLockGuard lock(m_argMutex);
+ impp()->commandArgsAddGuts(argc, argv);
+}
+const char* VerilatedContext::commandArgsPlusMatch(const char* prefixp)
+ VL_MT_SAFE_EXCLUDES(m_argMutex) {
+ const std::string& match = impp()->argPlusMatch(prefixp);
+ static VL_THREAD_LOCAL char t_outstr[VL_VALUE_STRING_MAX_WIDTH];
+ if (match.empty()) return "";
+ char* dp = t_outstr;
+ for (const char* sp = match.c_str(); *sp && (dp - t_outstr) < (VL_VALUE_STRING_MAX_WIDTH - 2);)
+ *dp++ = *sp++;
+ *dp++ = '\0';
+ return t_outstr;
+}
+void VerilatedContext::internalsDump() const VL_MT_SAFE {
+ VL_PRINTF_MT("internalsDump:\n");
+ VerilatedImp::versionDump();
+ impp()->commandArgDump();
+ impp()->scopesDump();
+ VerilatedImp::exportsDump();
+ VerilatedImp::userDump();
+}
+
+//======================================================================
+// VerilatedContextImp:: Methods - command line
+
+void VerilatedContextImp::commandArgsAddGuts(int argc, const char** argv) VL_REQUIRES(m_argMutex) {
+ if (!m_args.m_argVecLoaded) m_args.m_argVec.clear();
+ for (int i = 0; i < argc; ++i) {
+ m_args.m_argVec.push_back(argv[i]);
+ commandArgVl(argv[i]);
+ }
+ m_args.m_argVecLoaded = true; // Can't just test later for empty vector, no arguments is ok
+}
+void VerilatedContextImp::commandArgDump() const VL_MT_SAFE_EXCLUDES(m_argMutex) {
+ const VerilatedLockGuard lock(m_argMutex);
+ VL_PRINTF_MT(" Argv:");
+ for (const auto& i : m_args.m_argVec) VL_PRINTF_MT(" %s", i.c_str());
+ VL_PRINTF_MT("\n");
+}
+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);
+ if (VL_UNLIKELY(!m_args.m_argVecLoaded)) {
+ m_args.m_argVecLoaded = true; // Complain only once
+ VL_FATAL_MT("unknown", 0, "",
+ "%Error: Verilog called $test$plusargs or $value$plusargs without"
+ " testbench C first calling Verilated::commandArgs(argc,argv).");
+ }
+ for (const auto& i : m_args.m_argVec) {
+ if (i[0] == '+') {
+ if (0 == strncmp(prefixp, i.c_str() + 1, len)) return i;
+ }
+ }
+ return "";
+}
+// Return string representing current argv
+// Only used by VPI so uses static storage, only supports most recent called context
+std::pair VerilatedContextImp::argc_argv() VL_MT_SAFE_EXCLUDES(m_argMutex) {
+ const VerilatedLockGuard lock(m_argMutex);
+ static bool s_loaded = false;
+ static int s_argc = 0;
+ static char** s_argvp = nullptr;
+ if (VL_UNLIKELY(!s_loaded)) {
+ s_loaded = true;
+ s_argc = m_args.m_argVec.size();
+ s_argvp = new char*[s_argc + 1];
+ 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());
+ ++in;
+ }
+ s_argvp[s_argc] = nullptr;
+ }
+ return std::make_pair(s_argc, s_argvp);
+}
+
+void VerilatedContextImp::commandArgVl(const std::string& arg) {
+ if (0 == strncmp(arg.c_str(), "+verilator+", 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()));
+ } else if (commandArgVlValue(arg, "+verilator+error+limit+", value /*ref*/)) {
+ errorLimit(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 (commandArgVlValue(arg, "+verilator+prof+threads+start+", value /*ref*/)) {
+ profThreadsStart(atoll(value.c_str()));
+ } else if (commandArgVlValue(arg, "+verilator+prof+threads+window+", value /*ref*/)) {
+ profThreadsWindow(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()));
+ } else if (commandArgVlValue(arg, "+verilator+seed+", value /*ref*/)) {
+ randSeed(atoi(value.c_str()));
+ } else if (arg == "+verilator+noassert") {
+ assertOn(false);
+ } else if (arg == "+verilator+V") {
+ VerilatedImp::versionDump(); // Someday more info too
+ VL_FATAL_MT("COMMAND_LINE", 0, "",
+ "Exiting due to command line argument (not an error)");
+ } else if (arg == "+verilator+version") {
+ VerilatedImp::versionDump();
+ VL_FATAL_MT("COMMAND_LINE", 0, "",
+ "Exiting due to command line argument (not an error)");
+ } else {
+ VL_PRINTF_MT("%%Warning: Unknown +verilator runtime argument: '%s'\n", arg.c_str());
+ }
+ }
+}
+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)) {
+ valuer = arg.substr(len);
+ return true;
+ } else {
+ return false;
+ }
+}
+
+//======================================================================
+// VerilatedContext:: + VerilatedContextImp:: Methods - random
+
+void VerilatedContext::randSeed(int val) VL_MT_SAFE {
+ // As we have per-thread state, the epoch must be static,
+ // and so the rand seed's mutex must also be static
+ const VerilatedLockGuard lock(VerilatedContextImp::s().s_randMutex);
+ m_s.m_randSeed = val;
+ vluint64_t newEpoch = VerilatedContextImp::s().s_randSeedEpoch + 1;
+ // Obververs must see new epoch AFTER seed updated
+#ifdef VL_THREADED
+ std::atomic_signal_fence(std::memory_order_release);
+#endif
+ VerilatedContextImp::s().s_randSeedEpoch = newEpoch;
+}
+vluint64_t VerilatedContextImp::randSeedDefault64() const VL_MT_SAFE {
+ if (randSeed() != 0) {
+ return ((static_cast(randSeed()) << 32)
+ ^ (static_cast(randSeed())));
+ } else {
+ return ((static_cast(vl_sys_rand32()) << 32)
+ ^ (static_cast(vl_sys_rand32())));
+ }
+}
+
+//======================================================================
+// VerilatedContext:: Methods - scopes
+
+void VerilatedContext::scopesDump() const VL_MT_SAFE {
+ const VerilatedLockGuard lock(m_impdatap->m_nameMutex);
+ VL_PRINTF_MT(" scopesDump:\n");
+ for (const auto& i : m_impdatap->m_nameMap) {
+ const VerilatedScope* scopep = i.second;
+ scopep->scopeDump();
+ }
+ VL_PRINTF_MT("\n");
+}
+
+void VerilatedContextImp::scopeInsert(const VerilatedScope* scopep) VL_MT_SAFE {
+ // Slow ok - called once/scope at construction
+ const VerilatedLockGuard lock(m_impdatap->m_nameMutex);
+ const auto it = m_impdatap->m_nameMap.find(scopep->name());
+ if (it == m_impdatap->m_nameMap.end()) m_impdatap->m_nameMap.emplace(scopep->name(), scopep);
+}
+void VerilatedContextImp::scopeErase(const VerilatedScope* scopep) VL_MT_SAFE {
+ // Slow ok - called once/scope at destruction
+ const VerilatedLockGuard lock(m_impdatap->m_nameMutex);
+ VerilatedImp::userEraseScope(scopep);
+ const auto it = m_impdatap->m_nameMap.find(scopep->name());
+ if (it != m_impdatap->m_nameMap.end()) m_impdatap->m_nameMap.erase(it);
+}
+const VerilatedScope* VerilatedContext::scopeFind(const char* namep) const VL_MT_SAFE {
+ // Thread save only assuming this is called only after model construction completed
+ const VerilatedLockGuard lock(m_impdatap->m_nameMutex);
+ // If too slow, can assume this is only VL_MT_SAFE_POSINIT
+ const auto& it = m_impdatap->m_nameMap.find(namep);
+ if (VL_UNLIKELY(it == m_impdatap->m_nameMap.end())) return nullptr;
+ return it->second;
+}
+const VerilatedScopeNameMap* VerilatedContext::scopeNameMap() VL_MT_SAFE {
+ return &(impp()->m_impdatap->m_nameMap);
+}
+
+//======================================================================
+// VerilatedSyms:: Methods
+
+VerilatedSyms::VerilatedSyms(VerilatedContext* contextp)
+ : _vm_contextp__(contextp ? contextp : Verilated::threadContextp()) {
+ Verilated::threadContextp(_vm_contextp__);
+#ifdef VL_THREADED
+ __Vm_evalMsgQp = new VerilatedEvalMsgQueue;
+#endif
+}
+
+VerilatedSyms::~VerilatedSyms() {
+#ifdef VL_THREADED
+ delete __Vm_evalMsgQp;
+#endif
+}
+
+//===========================================================================
+// Verilated:: Methods
+
+void Verilated::debug(int level) VL_MT_SAFE {
+ s_debug = level;
+ if (level) {
+#ifdef VL_DEBUG
+ VL_DEBUG_IF(VL_DBG_MSGF("- Verilated::debug is on."
+ " Message prefix indicates {,}.\n"););
+#else
+ VL_PRINTF_MT("- Verilated::debug attempted,"
+ " but compiled without VL_DEBUG, so messages suppressed.\n"
+ "- Suggest remake using 'make ... CPPFLAGS=-DVL_DEBUG'\n");
+#endif
+ }
}
const char* Verilated::catName(const char* n1, const char* n2, const char* delimiter) VL_MT_SAFE {
@@ -2322,14 +2538,16 @@ const char* Verilated::catName(const char* n1, const char* n2, const char* delim
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;
- if (!t_strp || newlen > t_len) {
+ if (VL_UNLIKELY(!t_strp || newlen > t_len)) {
if (t_strp) delete[] t_strp;
t_strp = new char[newlen];
t_len = newlen;
}
- strcpy(t_strp, n1);
- if (*n1) strcat(t_strp, delimiter);
- strcat(t_strp, n2);
+ char* dp = t_strp;
+ for (const char* sp = n1; *sp;) *dp++ = *sp++;
+ for (const char* sp = delimiter; *sp;) *dp++ = *sp++;
+ for (const char* sp = n2; *sp;) *dp++ = *sp++;
+ *dp++ = '\0';
return t_strp;
}
@@ -2339,8 +2557,12 @@ const char* Verilated::catName(const char* n1, const char* n2, const char* delim
// Keeping these out of class Verilated to avoid having to include
// in verilated.h (for compilation speed)
typedef std::list> VoidPCbList;
-static VoidPCbList s_flushCbs;
-static VoidPCbList s_exitCbs;
+static struct {
+ VerilatedMutex s_flushMutex;
+ VoidPCbList s_flushCbs VL_GUARDED_BY(s_flushMutex);
+ VerilatedMutex s_exitMutex;
+ VoidPCbList s_exitCbs VL_GUARDED_BY(s_exitMutex);
+} VlCbStatic;
static void addCb(Verilated::VoidPCb cb, void* datap, VoidPCbList& cbs) {
std::pair pair(cb, datap);
@@ -2356,16 +2578,25 @@ static void runCallbacks(const VoidPCbList& cbs) VL_MT_SAFE {
}
void Verilated::addFlushCb(VoidPCb cb, void* datap) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- addCb(cb, datap, s_flushCbs);
+ const VerilatedLockGuard lock(VlCbStatic.s_flushMutex);
+ addCb(cb, datap, VlCbStatic.s_flushCbs);
}
void Verilated::removeFlushCb(VoidPCb cb, void* datap) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- removeCb(cb, datap, s_flushCbs);
+ const VerilatedLockGuard lock(VlCbStatic.s_flushMutex);
+ removeCb(cb, datap, VlCbStatic.s_flushCbs);
}
void Verilated::runFlushCallbacks() VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- runCallbacks(s_flushCbs);
+ // Flush routines may call flush, so avoid mutex deadlock
+#ifdef VL_THREADED
+ static std::atomic s_recursing;
+#else
+ static int s_recursing = 0;
+#endif
+ if (!s_recursing++) {
+ const VerilatedLockGuard lock(VlCbStatic.s_flushMutex);
+ runCallbacks(VlCbStatic.s_flushCbs);
+ }
+ --s_recursing;
fflush(stderr);
fflush(stdout);
// When running internal code coverage (gcc --coverage, as opposed to
@@ -2375,37 +2606,29 @@ void Verilated::runFlushCallbacks() VL_MT_SAFE {
}
void Verilated::addExitCb(VoidPCb cb, void* datap) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- addCb(cb, datap, s_exitCbs);
+ const VerilatedLockGuard lock(VlCbStatic.s_exitMutex);
+ addCb(cb, datap, VlCbStatic.s_exitCbs);
}
void Verilated::removeExitCb(VoidPCb cb, void* datap) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- removeCb(cb, datap, s_exitCbs);
+ const VerilatedLockGuard lock(VlCbStatic.s_exitMutex);
+ removeCb(cb, datap, VlCbStatic.s_exitCbs);
}
void Verilated::runExitCallbacks() VL_MT_SAFE {
- const VerilatedLockGuard lock(s_mutex);
- runCallbacks(s_exitCbs);
+#ifdef VL_THREADED
+ static std::atomic s_recursing;
+#else
+ static int s_recursing = 0;
+#endif
+ if (!s_recursing++) {
+ const VerilatedLockGuard lock(VlCbStatic.s_exitMutex);
+ runCallbacks(VlCbStatic.s_exitCbs);
+ }
+ --s_recursing;
}
const char* Verilated::productName() VL_PURE { return VERILATOR_PRODUCT; }
const char* Verilated::productVersion() VL_PURE { return VERILATOR_VERSION; }
-void Verilated::commandArgs(int argc, const char** argv) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_args.m_argMutex);
- s_args.argc = argc;
- s_args.argv = argv;
- VerilatedImp::commandArgs(argc, argv);
-}
-
-const char* Verilated::commandArgsPlusMatch(const char* prefixp) VL_MT_SAFE {
- const std::string& match = VerilatedImp::argPlusMatch(prefixp);
- static VL_THREAD_LOCAL char t_outstr[VL_VALUE_STRING_MAX_WIDTH];
- if (match.empty()) return "";
- t_outstr[0] = '\0';
- strncat(t_outstr, match.c_str(), VL_VALUE_STRING_MAX_WIDTH - 1);
- return t_outstr;
-}
-
void Verilated::nullPointerError(const char* filename, int linenum) VL_MT_SAFE {
// Slowpath - Called only on error
VL_FATAL_MT(filename, linenum, "", "Null pointer dereferenced");
@@ -2435,22 +2658,10 @@ void Verilated::quiesce() VL_MT_SAFE {
#endif
}
-void Verilated::internalsDump() VL_MT_SAFE { VerilatedImp::internalsDump(); }
-
-void Verilated::scopesDump() VL_MT_SAFE { VerilatedImp::scopesDump(); }
-
-const VerilatedScope* Verilated::scopeFind(const char* namep) VL_MT_SAFE {
- return VerilatedImp::scopeFind(namep);
-}
-
int Verilated::exportFuncNum(const char* namep) VL_MT_SAFE {
return VerilatedImp::exportFind(namep);
}
-const VerilatedScopeNameMap* Verilated::scopeNameMap() VL_MT_SAFE {
- return VerilatedImp::scopeNameMap();
-}
-
#ifdef VL_THREADED
void Verilated::endOfThreadMTaskGuts(VerilatedEvalMsgQueue* evalMsgQp) VL_MT_SAFE {
VL_DEBUG_IF(VL_DBG_MSGF("End of thread mtask\n"););
@@ -2467,138 +2678,13 @@ void Verilated::endOfEval(VerilatedEvalMsgQueue* evalMsgQp) VL_MT_SAFE {
}
#endif
-//===========================================================================
-// VerilatedImp:: Constructors
-
-// verilated.o may exist both in protect-lib and main module.
-// Both the main module and the protect-lib refer the same instance of
-// static variables such as Verilated or VerilatedImplData.
-// This is important to share the state such as Verilated::gotFinish.
-// But the sharing may cause double-free error when shutting down because destructors
-// are called twice.
-// 1st time:From protect-lib shared object on the way of unloading after exiting main()
-// 2nd time:From main executable.
-//
-// To avoid the trouble, all member variables are enclosed in VerilatedImpU union.
-// ctor nor dtor of members are not called automatically.
-// VerilatedInitializer::setup() and teardown() guarantees to initialize/destruct just once.
-
-void VerilatedImp::setup() { new (&VerilatedImp::s_s) VerilatedImpData(); }
-void VerilatedImp::teardown() { VerilatedImp::s_s.~VerilatedImpU(); }
-
//===========================================================================
// VerilatedImp:: Methods
-std::string VerilatedImp::timeFormatSuffix() VL_MT_SAFE {
- const VerilatedLockGuard lock(s_s.v.m_sergMutex);
- return s_s.v.m_serg.m_timeFormatSuffix;
-}
-void VerilatedImp::timeFormatSuffix(const std::string& value) VL_MT_SAFE {
- const VerilatedLockGuard lock(s_s.v.m_sergMutex);
- s_s.v.m_serg.m_timeFormatSuffix = value;
-}
-void VerilatedImp::timeFormatUnits(int value) VL_MT_SAFE { s_s.v.m_ser.m_timeFormatUnits = value; }
-void VerilatedImp::timeFormatPrecision(int value) VL_MT_SAFE {
- s_s.v.m_ser.m_timeFormatPrecision = value;
-}
-void VerilatedImp::timeFormatWidth(int value) VL_MT_SAFE { s_s.v.m_ser.m_timeFormatWidth = value; }
-
-void VerilatedImp::internalsDump() VL_MT_SAFE {
- const VerilatedLockGuard lock(s_s.v.m_argMutex);
- VL_PRINTF_MT("internalsDump:\n");
- versionDump();
- VL_PRINTF_MT(" Argv:");
- for (const auto& i : s_s.v.m_argVec) VL_PRINTF_MT(" %s", i.c_str());
- VL_PRINTF_MT("\n");
- scopesDump();
- exportsDump();
- userDump();
-}
void VerilatedImp::versionDump() VL_MT_SAFE {
VL_PRINTF_MT(" Version: %s %s\n", Verilated::productName(), Verilated::productVersion());
}
-void VerilatedImp::commandArgs(int argc, const char** argv) VL_EXCLUDES(s_s.v.m_argMutex) {
- const VerilatedLockGuard lock(s_s.v.m_argMutex);
- s_s.v.m_argVec.clear(); // Always clear
- commandArgsAddGuts(argc, argv);
-}
-void VerilatedImp::commandArgsAdd(int argc, const char** argv) VL_EXCLUDES(s_s.v.m_argMutex) {
- const VerilatedLockGuard lock(s_s.v.m_argMutex);
- commandArgsAddGuts(argc, argv);
-}
-void VerilatedImp::commandArgsAddGuts(int argc, const char** argv) VL_REQUIRES(s_s.v.m_argMutex) {
- if (!s_s.v.m_argVecLoaded) s_s.v.m_argVec.clear();
- for (int i = 0; i < argc; ++i) {
- s_s.v.m_argVec.push_back(argv[i]);
- commandArgVl(argv[i]);
- }
- s_s.v.m_argVecLoaded = true; // Can't just test later for empty vector, no arguments is ok
-}
-void VerilatedImp::commandArgVl(const std::string& arg) {
- if (0 == strncmp(arg.c_str(), "+verilator+", 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()));
- } else if (commandArgVlValue(arg, "+verilator+error+limit+", value /*ref*/)) {
- Verilated::errorLimit(atoi(value.c_str()));
- } else if (arg == "+verilator+help") {
- 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 (commandArgVlValue(arg, "+verilator+prof+threads+start+", value /*ref*/)) {
- Verilated::profThreadsStart(atoll(value.c_str()));
- } else if (commandArgVlValue(arg, "+verilator+prof+threads+window+", value /*ref*/)) {
- Verilated::profThreadsWindow(atol(value.c_str()));
- } else if (commandArgVlValue(arg, "+verilator+prof+threads+file+", value /*ref*/)) {
- Verilated::profThreadsFilenamep(value.c_str());
- } else if (commandArgVlValue(arg, "+verilator+rand+reset+", value /*ref*/)) {
- Verilated::randReset(atoi(value.c_str()));
- } else if (commandArgVlValue(arg, "+verilator+seed+", value /*ref*/)) {
- Verilated::randSeed(atoi(value.c_str()));
- } else if (arg == "+verilator+noassert") {
- Verilated::assertOn(false);
- } else if (arg == "+verilator+V") {
- versionDump(); // Someday more info too
- VL_FATAL_MT("COMMAND_LINE", 0, "",
- "Exiting due to command line argument (not an error)");
- } else if (arg == "+verilator+version") {
- versionDump();
- VL_FATAL_MT("COMMAND_LINE", 0, "",
- "Exiting due to command line argument (not an error)");
- } else {
- VL_PRINTF_MT("%%Warning: Unknown +verilator runtime argument: '%s'\n", arg.c_str());
- }
- }
-}
-bool VerilatedImp::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)) {
- valuer = arg.substr(len);
- return true;
- } else {
- return false;
- }
-}
-
-//======================================================================
-// VerilatedSyms:: Methods
-
-VerilatedSyms::VerilatedSyms() {
-#ifdef VL_THREADED
- __Vm_evalMsgQp = new VerilatedEvalMsgQueue;
-#endif
-}
-VerilatedSyms::~VerilatedSyms() {
-#ifdef VL_THREADED
- delete __Vm_evalMsgQp;
-#endif
-}
-
//===========================================================================
// VerilatedModule:: Methods
@@ -2652,7 +2738,7 @@ void* VerilatedVarProps::datapAdjustIndex(void* datap, int dim, int indx) const
VerilatedScope::~VerilatedScope() {
// Memory cleanup - not called during normal operation
- VerilatedImp::scopeErase(this);
+ Verilated::threadContextp()->impp()->scopeErase(this);
if (m_namep) VL_DO_CLEAR(delete[] m_namep, m_namep = nullptr);
if (m_callbacksp) VL_DO_CLEAR(delete[] m_callbacksp, m_callbacksp = nullptr);
if (m_varsp) VL_DO_CLEAR(delete m_varsp, m_varsp = nullptr);
@@ -2667,13 +2753,17 @@ void VerilatedScope::configure(VerilatedSyms* symsp, const char* prefixp, const
m_symsp = symsp;
m_type = type;
m_timeunit = timeunit;
- char* namep = new char[strlen(prefixp) + strlen(suffixp) + 2];
- strcpy(namep, prefixp);
- if (*prefixp && *suffixp) strcat(namep, ".");
- strcat(namep, suffixp);
- m_namep = namep;
+ {
+ char* namep = new char[strlen(prefixp) + strlen(suffixp) + 2];
+ char* dp = namep;
+ for (const char* sp = prefixp; *sp;) *dp++ = *sp++;
+ if (*prefixp && *suffixp) *dp++ = '.';
+ for (const char* sp = suffixp; *sp;) *dp++ = *sp++;
+ *dp++ = '\0';
+ m_namep = namep;
+ }
m_identifierp = identifier;
- VerilatedImp::scopeInsert(this);
+ Verilated::threadContextp()->impp()->scopeInsert(this);
}
void VerilatedScope::exportInsert(int finalize, const char* namep, void* cb) VL_MT_UNSAFE {
diff --git a/include/verilated.h b/include/verilated.h
index b78c3ad21..580cc2753 100644
--- a/include/verilated.h
+++ b/include/verilated.h
@@ -16,12 +16,15 @@
/// 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.
+///
/// Code available from: https://verilator.org
///
//*************************************************************************
-#ifndef _VERILATED_H_
-#define _VERILATED_H_ 1 ///< Header Guard
+#ifndef VERILATOR_VERILATED_H_
+#define VERILATOR_VERILATED_H_ ///< Header Guard
// clang-format off
#include "verilatedos.h"
@@ -35,6 +38,9 @@
#include
#include
#include
+#include
+#include
+#include
// avoided to reduce compile time
// | |