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/Changes b/Changes index 858163fd4..7f165373c 100644 --- a/Changes +++ b/Changes @@ -10,6 +10,8 @@ The contributors that suggested a given feature are shown in []. Thanks! ** 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] diff --git a/Makefile.in b/Makefile.in index 112f7dedb..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 \ 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 c710b3361..33758538e 100755 --- a/bin/verilator +++ b/bin/verilator @@ -2127,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. @@ -5766,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/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/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/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 95c712cd0..000000000 --- a/docs/internals.adoc +++ /dev/null @@ -1,1026 +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: - -* 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 -`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