diff --git a/README.rst b/README.rst index 8dd591838..d51837df2 100644 --- a/README.rst +++ b/README.rst @@ -8,52 +8,56 @@ .. |badge1| image:: https://img.shields.io/badge/Website-Verilator.org-181717.svg :target: https://verilator.org + .. |badge2| image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg :target: https://www.gnu.org/licenses/lgpl-3.0 + .. |badge3| image:: https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg :target: https://opensource.org/licenses/Artistic-2.0 + .. |badge4| image:: https://repology.org/badge/tiny-repos/verilator.svg?header=distro%20packages :target: https://repology.org/project/verilator/versions + .. |badge5| image:: https://img.shields.io/docker/pulls/verilator/verilator :target: https://hub.docker.com/r/verilator/verilator + .. |badge7| image:: https://github.com/verilator/verilator/workflows/build/badge.svg :target: https://github.com/verilator/verilator/actions?query=workflow%3Abuild + .. |badge8| image:: https://img.shields.io/github/actions/workflow/status/verilator/verilator/rtlmeter.yml?branch=master&event=schedule&label=benchmarks :target: https://verilator.github.io/verilator-rtlmeter-results - Welcome to Verilator ==================== .. list-table:: - * - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.** - * Accepts Verilog or SystemVerilog - * Performs lint code-quality checks - * Compiles into multithreaded C++, or SystemC - * Creates JSON to front-end your own tools + - - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.** + - Accepts Verilog or SystemVerilog + - Performs lint code-quality checks + - Compiles into multithreaded C++, or SystemC + - Creates JSON to front-end your own tools - |Logo| - * - |verilator multithreaded performance| + - - |verilator multithreaded performance| - **Fast** - * Outperforms many closed-source commercial simulators - * Single- and multithreaded output models - * - **Widely Used** - * Wide industry and academic deployment - * Out-of-the-box support from Arm and RISC-V vendor IP - * Over 700 contributors + - Outperforms many closed-source commercial simulators + - Single- and multithreaded output models + - - **Widely Used** + - Wide industry and academic deployment + - Out-of-the-box support from Arm and RISC-V vendor IP + - Over 700 contributors - |verilator usage| - * - |verilator community| + - - |verilator community| - **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 + - 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| - What Verilator Does =================== @@ -78,7 +82,6 @@ SDF annotation, or mixed-signal simulation. However, if you are looking for a path to migrate SystemVerilog to C++/SystemC, or want high-speed simulation, Verilator is the tool for you. - Performance =========== @@ -97,7 +100,6 @@ Mentor ModelSim/Questa, 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 simulation cycles/dollar. - Installation & Documentation ============================ @@ -116,7 +118,6 @@ For more information: - `Verilator issues `_ - Support ======= @@ -133,7 +134,6 @@ Verilator also supports and encourages commercial support models and organizations; please see `Verilator Commercial Support `_. - Related Projects ================ @@ -150,7 +150,6 @@ Related Projects - `Surfer `_ - Web or offline waveform viewer for Verilator traces. - Open License ============ @@ -162,10 +161,17 @@ 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: https://steveicarus.github.io/iverilog + .. _linux foundation: https://www.linuxfoundation.org + .. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png + .. |verilator multithreaded performance| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png + .. |verilator usage| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png + .. |verilator community| image:: https://www.veripool.org/img/verilator_community_400x125-min.png + .. |verilator support| image:: https://www.veripool.org/img/verilator_support_400x125-min.png diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst index 2876ae765..1d714ce4e 100644 --- a/docs/guide/connecting.rst +++ b/docs/guide/connecting.rst @@ -29,13 +29,13 @@ The generated model class file manages all internal state required by the model, and exposes the following interface that allows interaction with the model: -* Top level IO ports are exposed as references to the appropriate internal +- Top level IO ports are exposed as references to the appropriate internal equivalents. -* Public top level module instances are exposed as pointers to allow access +- Public top level module instances are exposed as pointers to allow access to ``/* verilator public */`` items. -* The root of the design hierarchy (as in SystemVerilog ``$root``) is +- The root of the design hierarchy (as in SystemVerilog ``$root``) is exposed via the ``rootp`` member pointer to allow access to model internals, including ``/* verilator public_flat */`` items. @@ -59,22 +59,22 @@ This means that user code that accesses internal signals in the model (likely including ``/* verilator public_flat */`` signals, as they are often inlined into the root scope) will need to be updated as follows: -* No change required for accessing top level IO signals. These are directly +- No change required for accessing top level IO signals. These are directly accessible in the model class via references. -* No change required for accessing ``/* verilator public */`` items. These +- No change required for accessing ``/* verilator public */`` items. These are directly accessible via sub-module pointers in the model class. -* Accessing any other internal members, including - ``/* verilator public_flat */`` items requires the following changes: +- Accessing any other internal members, including ``/* verilator + public_flat */`` items requires the following changes: - * Additionally include :file:`{prefix}___024root.h`. This header defines + - Additionally include :file:`{prefix}___024root.h`. This header defines type of the ``rootp`` pointer within the model class. Note the ``__024`` substring is the Verilator escape sequence for the ``$`` character, i.e.: ``rootp`` points to the Verilated SystemVerilog ``$root`` scope. - * Replace ``modelp->internal->member`` references with + - Replace ``modelp->internal->member`` references with ``modelp->rootp->internal->member`` references, which contain one additional indirection via the ``rootp`` pointer. @@ -503,9 +503,9 @@ described above is just a wrapper which calls these two functions. 3. If using delays and :vlopt:`--timing`, there are two additional methods the user should call: - * ``designp->eventsPending()``, which returns ``true`` if there are any + - ``designp->eventsPending()``, which returns ``true`` if there are any delayed events pending, - * ``designp->nextTimeSlot()``, which returns the simulation time of the + - ``designp->nextTimeSlot()``, which returns the simulation time of the next delayed event. This method can only be called if ``designp->eventsPending()`` returned ``true``. diff --git a/docs/guide/contributing.rst b/docs/guide/contributing.rst index 3a2e57e81..8f834d5a9 100644 --- a/docs/guide/contributing.rst +++ b/docs/guide/contributing.rst @@ -87,7 +87,8 @@ Please refer to `sv-bugpoint README `_ for more information on how to use `sv-bugpoint`. -.. Contributing -.. ============ +.. + Contributing + ============ .. include:: ../CONTRIBUTING.rst diff --git a/docs/guide/contributors.rst b/docs/guide/contributors.rst index 2d31c91c8..37d7ef9f1 100644 --- a/docs/guide/contributors.rst +++ b/docs/guide/contributors.rst @@ -30,10 +30,10 @@ Alliance `_, and `Antmicro Ltd Previous major corporate sponsors of Verilator, by providing significant contributions of time or funds include: Antmicro Ltd., Atmel Corporation, Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd., Fractile -Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed Technologies -Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus -Networks Inc., SiCortex Inc, Shunyao CAD, Tenstorrent USA, Inc. and Western -Digital Inc. +Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed +Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems +Inc., Nauticus Networks Inc., SiCortex Inc, Shunyao CAD, Tenstorrent USA, +Inc. and Western Digital Inc. The contributors of major functionality are: Jeremy Bennett, Krzysztof Bieganski, Byron Bradley, Lane Brooks, John Coiner, Duane Galbi, Arkadiusz @@ -143,18 +143,18 @@ Krzysztof Obłonczek, Danny Oler, Andreas Olofsson, Baltazar Ortiz, Aleksander Osman, Don Owen, Tim Paine, Deepa Palaniappan, James Pallister, Vassilis Papaefstathiou, Sanggyu Park, Brad Parker, Risto Pejašinović, Seth Pellegrino, Joel Peltonen, Morten Borup Petersen, Dan Petrisko, Thanh Tung -Pham, Wesley Piard, Maciej Piechotka, David Pierce, Cody Piersall, -T. Platz, Michael Platzer, Dominic Plunkett, Nolan Poe, Tuomas Poikela, -George Polack, David Poole, Michael Popoloski, Roman Popov, Aylon Chaim -Porat, Oron Port, Rich Porter, Rick Porter, Stefan Post, Niranjan Prabhu, -Damien Pretet, Harald Pretl, Bill Pringlemeir, Usha Priyadharshini, Mark -Jackson Pulver, Prateek Puri, Nikolay Puzanov, Han Qi, Jiacheng Qian, -Marshal Qiao, Raynard Qiao, Yujia Qiao, Jasen Qin, Frank Qiu, Nandu Raj, -Kamil Rakoczy, Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh -Redford, Odd Magne Reitan, Frédéric Requin, Wajahat Riaz, Dustin Richmond, -Samuel Riedel, Alberto Del Rio, Eric Rippey, Narcis Rodas, Oleg Rodionov, -Ludwig Rogiers, Paul Rolfe, Michail Rontionov, Arjen Roodselaar, Arthur -Rosa, Tobias Rosenkranz, Yernagula Roshit, Diego Roux, Ryszard Rozak, Dan +Pham, Wesley Piard, Maciej Piechotka, David Pierce, Cody Piersall, T. +Platz, Michael Platzer, Dominic Plunkett, Nolan Poe, Tuomas Poikela, George +Polack, David Poole, Michael Popoloski, Roman Popov, Aylon Chaim Porat, +Oron Port, Rich Porter, Rick Porter, Stefan Post, Niranjan Prabhu, Damien +Pretet, Harald Pretl, Bill Pringlemeir, Usha Priyadharshini, Mark Jackson +Pulver, Prateek Puri, Nikolay Puzanov, Han Qi, Jiacheng Qian, Marshal Qiao, +Raynard Qiao, Yujia Qiao, Jasen Qin, Frank Qiu, Nandu Raj, Kamil Rakoczy, +Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh Redford, Odd +Magne Reitan, Frédéric Requin, Wajahat Riaz, Dustin Richmond, Samuel +Riedel, Alberto Del Rio, Eric Rippey, Narcis Rodas, Oleg Rodionov, Ludwig +Rogiers, Paul Rolfe, Michail Rontionov, Arjen Roodselaar, Arthur Rosa, +Tobias Rosenkranz, Yernagula Roshit, Diego Roux, Ryszard Rozak, Dan Ruelas-Petrisko, Luca Rufer, Huang Rui, Graham Rushton, Jan Egil Ruud, Denis Rystsov, Pawel Sagan, Robert Sammelson, Adrian Sampson, John Sanguinetti, Josep Sans, Dave Sargeant, Luca Sasselli, Philippe Sauter, diff --git a/docs/guide/examples.rst b/docs/guide/examples.rst index 1702ac513..35fead694 100644 --- a/docs/guide/examples.rst +++ b/docs/guide/examples.rst @@ -10,10 +10,10 @@ Examples This section covers the following examples: -* :ref:`Example Create-Binary Execution` -* :ref:`Example C++ Execution` -* :ref:`Example SystemC Execution` -* :ref:`Examples in the Distribution` +- :ref:`Example Create-Binary Execution` +- :ref:`Example C++ Execution` +- :ref:`Example SystemC Execution` +- :ref:`Examples in the Distribution` .. toctree:: :maxdepth: 1 diff --git a/docs/guide/faq.rst b/docs/guide/faq.rst index e0b184385..96245574c 100644 --- a/docs/guide/faq.rst +++ b/docs/guide/faq.rst @@ -83,17 +83,17 @@ the licenses for details. Some examples: -* Any SystemVerilog or other input fed into Verilator remains your own. +- Any SystemVerilog or other input fed into Verilator remains your own. -* Any of your VPI/DPI C++ routines that Verilator calls remain your own. +- Any of your VPI/DPI C++ routines that Verilator calls remain your own. -* Any of your main() C++ code that calls into Verilator remains your own. +- Any of your main() C++ code that calls into Verilator remains your own. -* If you change Verilator itself, for example, changing or adding a file +- If you change Verilator itself, for example, changing or adding a file under the src/ directory in the repository, you must make the source code available under the GNU Lesser Public License. -* If you change a header Verilator provides, for example, under include/ in +- If you change a header Verilator provides, for example, under include/ in the repository, you must make the source code available under the GNU Lesser Public License. @@ -385,33 +385,33 @@ example of how to do this. How do I get faster build times? """""""""""""""""""""""""""""""" -* When running make, pass the make variable VM_PARALLEL_BUILDS=1, so that +- When running make, pass the make variable VM_PARALLEL_BUILDS=1, so that builds occur in parallel. Note this is now set by default if an output file is large enough to be split due to the :vlopt:`--output-split` option. -* Verilator emits any infrequently executed "cold" routines into separate +- Verilator emits any infrequently executed "cold" routines into separate __Slow.cpp files. This can accelerate compilation as optimization can be disabled on these routines. See the OPT_FAST and OPT_SLOW make variables and :ref:`Benchmarking & Optimization`. -* Use a recent compiler. Newer compilers tend to be faster. +- Use a recent compiler. Newer compilers tend to be faster. -* Compile in parallel on many machines and use caching; see the web for the +- Compile in parallel on many machines and use caching; see the web for the ccache, sccache, distcc, or icecream packages. ccache will skip GCC runs between identical source builds, even across different users. If ccache was installed when Verilator was built, it is used, or see OBJCACHE environment variable to override this. Also see the :vlopt:`--output-split` option and :ref: `Profiling ccache efficiency`. -* To reduce the compile time of classes that use a Verilated module (e.g., +- To reduce the compile time of classes that use a Verilated module (e.g., a top CPP file) you may wish to add a :option:`/*verilator&32;no_inline_module*/` metacomment to your top-level module. This will decrease the amount of code in the model's Verilated class, improving compile times of any instantiating top-level C++ code, at a relatively small cost of execution performance. -* Use :ref:`hierarchical verilation`. +- Use :ref:`hierarchical verilation`. Why do so many files need to recompile when I add a signal? @@ -499,12 +499,12 @@ equal, the best performance is when Verilator sees all of the design. So, look at the hierarchy of your design, labeling instances as to if they are SystemC or Verilog. Then: -* A module with only SystemC instances below must be SystemC. +- A module with only SystemC instances below must be SystemC. -* A module with a mix of Verilog and SystemC instances below must be +- A module with a mix of Verilog and SystemC instances below must be SystemC. (As Verilator cannot connect to lower-level SystemC instances.) -* A module with only Verilog instances below can be either, but for best +- A module with only Verilog instances below can be either, but for best performance should be Verilog. (The exception is if you have a design that is instantiated many times; in this case, Verilating one of the lower modules and instantiating that Verilated instances multiple times diff --git a/docs/guide/files.rst b/docs/guide/files.rst index d50b291df..c2dfb5004 100644 --- a/docs/guide/files.rst +++ b/docs/guide/files.rst @@ -43,140 +43,141 @@ For --cc/--sc, it creates: .. list-table:: - * - *{prefix}*.json + - - *{prefix}*.json - JSON build definition compiling (from --make json) - * - *{prefix}*.mk + - - *{prefix}*.mk - Make include file for compiling (from --make gmake) - * - *{prefix}*\ _classes.mk + - - *{prefix}*\ _classes.mk - Make include file with class names (from --make gmake) - * - *{prefix}*.h + - - *{prefix}*.h - Model header - * - *{prefix}*.cpp + - - *{prefix}*.cpp - Model C++ file - * - *{prefix}*\ ___024root.h + - - *{prefix}*\ ___024root.h - Top-level internal header file (from SystemVerilog $root) - * - *{prefix}*\ ___024root.cpp + - - *{prefix}*\ ___024root.cpp - Top-level internal C++ file (from SystemVerilog $root) - * - *{prefix}*\ ___024root\ *{__n}*.cpp + - - *{prefix}*\ ___024root\ *{__n}*.cpp - Additional top-level internal C++ files - * - *{prefix}*\ ___024root__Slow\ *{__n}*.cpp + - - *{prefix}*\ ___024root__Slow\ *{__n}*.cpp - Infrequent cold routines - * - *{prefix}*\ ___024root__Trace\ *{__n}*.cpp + - - *{prefix}*\ ___024root__Trace\ *{__n}*.cpp - Wave file generation code (from --trace-\*) - * - *{prefix}*\ ___024root__Trace__Slow\ *{__n}*.cpp + - - *{prefix}*\ ___024root__Trace__Slow\ *{__n}*.cpp - Wave file generation code (from --trace-\*) - * - *{prefix}*\ __Dpi.h + - - *{prefix}*\ __Dpi.h - DPI import and export declarations (from --dpi) - * - *{prefix}*\ __Dpi.cpp + - - *{prefix}*\ __Dpi.cpp - Global DPI export wrappers (from --dpi) - * - *{prefix}*\ __Dpi_Export\ *{__n}*.cpp + - - *{prefix}*\ __Dpi_Export\ *{__n}*.cpp - DPI export wrappers scoped to this particular model (from --dpi) - * - *{prefix}*\ __Inlines.h + - - *{prefix}*\ __Inlines.h - Inline support functions - * - *{prefix}*\ __Syms.h + - - *{prefix}*\ __Syms.h - Global symbol table header - * - *{prefix}*\ __Syms.cpp + - - *{prefix}*\ __Syms.cpp - Global symbol table C++ - * - *{prefix}{each_verilog_module}*.h + - - *{prefix}{each_verilog_module}*.h - Lower level internal header files - * - *{prefix}{each_verilog_module}*.cpp + - - *{prefix}{each_verilog_module}*.cpp - Lower level internal C++ files - * - *{prefix}{each_verilog_module}{__n}*.cpp + - - *{prefix}{each_verilog_module}{__n}*.cpp - Additional lower C++ files For --hierarchical mode, it creates: .. list-table:: - * - V\ *{hier_block}*\ / + - - V\ *{hier_block}*/ - Directory to Verilate each hierarchical block (from --hierarchical) - * - *{prefix}*\ __hierVer.d + - - *{prefix}*\ __hierVer.d - Make dependencies of the top module (from --hierarchical) - * - *{prefix}*\ _hier.mk + - - *{prefix}*\ _hier.mk - Make file for hierarchical blocks (from --make gmake) - * - *{prefix}*\ __hierMkJsonArgs.f + - - *{prefix}*\ __hierMkJsonArgs.f - Arguments for hierarchical Verilation (from --make json) - * - *{prefix}*\ __hierMkArgs.f + - - *{prefix}*\ __hierMkArgs.f - Arguments for hierarchical Verilation (from --make gmake) - * - *{prefix}*\ __hierParameters.v + - - *{prefix}*\ __hierParameters.v - Module parameters for hierarchical blocks - * - *{prefix}*\ __hier.dir - - Directory to store .dot, .vpp, .tree of top module (from --hierarchical) + - - *{prefix}*\ __hier.dir + - Directory to store .dot, .vpp, .tree of top module (from + --hierarchical) In specific debug and other modes, it also creates: .. list-table:: - * - *{prefix}*.sarif + - - *{prefix}*.sarif - SARIF diagnostics (from --diagnostics-sarif) - * - *{prefix}*.tree.json + - - *{prefix}*.tree.json - JSON tree information (from --json-only) - * - *{prefix}*.tree.meta.json + - - *{prefix}*.tree.meta.json - JSON tree metadata (from --json-only) - * - *{prefix}*\ __cdc.txt + - - *{prefix}*\ __cdc.txt - Clock Domain Crossing checks (from --cdc) - * - *{prefix}*\ __stats.txt + - - *{prefix}*\ __stats.txt - Statistics (from --stats) - * - *{prefix}*\ __idmap.txt + - - *{prefix}*\ __idmap.txt - Symbol demangling (from --protect-ids) - * - *{prefix}*\ __ver.d + - - *{prefix}*\ __ver.d - Make dependencies (from -MMD) - * - *{prefix}*\ __verFiles.dat + - - *{prefix}*\ __verFiles.dat - Timestamps (from --skip-identical) - * - *{prefix}{misc}*.dot + - - *{prefix}{misc}*.dot - Debugging graph files (from --debug) - * - *{prefix}{misc}*.tree + - - *{prefix}{misc}*.tree - Debugging files (from --debug) - * - *{prefix}*\ __inputs.vpp + - - *{prefix}*\ __inputs.vpp - Pre-processed verilog for all files (from --debug) - * - *{prefix}*\ _ *{each_verilog_base_filename}*.vpp + - - *{prefix}*\ _ *{each_verilog_base_filename}*.vpp - Pre-processed verilog for each file (from --debug) After running Make, the C++ compiler may produce the following: .. list-table:: - * - verilated{misc}*.d + - - verilated{misc}*.d - Intermediate dependencies - * - verilated{misc}*.o + - - verilated{misc}*.o - Intermediate objects - * - {mod_prefix}{misc}*.d + - - {mod_prefix}{misc}*.d - Intermediate dependencies - * - {mod_prefix}{misc}*.o + - - {mod_prefix}{misc}*.o - Intermediate objects - * - *{prefix}*\ + - - *{prefix}*\ - Final executable (from --exe) - * - lib\ *{prefix}*.a + - - lib\ *{prefix}*.a - Final archive (default lib mode) - * - libverilated.a + - - libverilated.a - Runtime for verilated model (default lib mode) - * - *{prefix}*\ __ALL.a + - - *{prefix}*\ __ALL.a - Library of all Verilated objects - * - *{prefix}*\ __ALL.cpp + - - *{prefix}*\ __ALL.cpp - Include of all code for single compile - * - *{prefix}{misc}*.d + - - *{prefix}{misc}*.d - Intermediate dependencies - * - *{prefix}{misc}*.o + - - *{prefix}{misc}*.o - Intermediate objects The Verilated executable may produce the following: .. list-table:: - * - coverage.dat + - - coverage.dat - Code coverage output, and default input filename for :command:`verilator_coverage` - * - gmon.out + - - gmon.out - GCC/clang code profiler output, often fed into :command:`verilator_profcfunc` - * - profile.vlt + - - profile.vlt - --prof-pgo data file for :ref:`Thread PGO` - * - profile_exec.dat + - - profile_exec.dat - --prof-exec data file for :command:`verilator_gantt` Verilator_gantt may produce the following: .. list-table:: - * - profile_exec.vcd + - - profile_exec.vcd - Gantt report waveform output diff --git a/docs/guide/install-cmake.rst b/docs/guide/install-cmake.rst index 56723842b..6d840a552 100644 --- a/docs/guide/install-cmake.rst +++ b/docs/guide/install-cmake.rst @@ -17,16 +17,16 @@ Linux). Quick Install ============= -1. Install Python for your platform from https://www.python.org/downloads/. -2. Install CMake for your platform from https://cmake.org/download/ or +#. Install Python for your platform from https://www.python.org/downloads/. +#. Install CMake for your platform from https://cmake.org/download/ or build it from source. -3. If the compiler of your choice is MSVC, then install +#. If the compiler of your choice is MSVC, then install https://visualstudio.microsoft.com/downloads/. If the compiler of your choice is Clang, then install https://releases.llvm.org/download.html or build it from source. -4. For flex and bison use https://github.com/lexxmark/winflexbison to build +#. For flex and bison use https://github.com/lexxmark/winflexbison to build and install. -5. For build on Windows using MSVC set environment variable WIN_FLEX_BISON +#. For build on Windows using MSVC set environment variable WIN_FLEX_BISON to install directory. For build on Windows/Linux/OS-X using ninja set the environment variable FLEX_INCLUDE to the directory containing FlexLexer.h and ensure that flex/bison is available within the PATH. diff --git a/docs/guide/install.rst b/docs/guide/install.rst index 59b29b2cf..99d8f66a5 100644 --- a/docs/guide/install.rst +++ b/docs/guide/install.rst @@ -385,12 +385,10 @@ the files: make install - .. Docker Build Environment .. include:: ../../ci/docker/buildenv/README.rst - .. Docker Run Environment .. include:: ../../ci/docker/run/README.rst diff --git a/docs/guide/languages.rst b/docs/guide/languages.rst index b0d2f57f5..b2bd17e69 100644 --- a/docs/guide/languages.rst +++ b/docs/guide/languages.rst @@ -103,11 +103,11 @@ Time With :vlopt:`--timing`, all timing controls are supported: -* delay statements, -* event control statements not only at the top of a process, -* intra-assignment timing controls, -* net delays, -* ``wait`` statements, +- delay statements, +- event control statements not only at the top of a process, +- intra-assignment timing controls, +- net delays, +- ``wait`` statements, as well as all flavors of ``fork``. @@ -129,26 +129,26 @@ simulation (perhaps using :vlopt:`--build`) and run it. With :vlopt:`--no-timing`, all timing controls cause the :option:`NOTIMING` error, except: -* delay statements - they are ignored (as they are in synthesis), though they - do issue a :option:`STMTDLY` warning, -* intra-assignment timing controls - they are ignored, though they do issue +- delay statements - they are ignored (as they are in synthesis), though + they do issue a :option:`STMTDLY` warning, +- intra-assignment timing controls - they are ignored, though they do issue an :option:`ASSIGNDLY` warning, -* net delays - they are ignored, -* event controls at the top of the procedure, +- net delays - they are ignored, +- event controls at the top of the procedure, Forks cause this error as well, except: -* forks with no statements, -* ``fork..join`` or ``fork..join_any`` with one statement, -* forks with :vlopt:`--bbox-unsup`. +- forks with no statements, +- ``fork..join`` or ``fork..join_any`` with one statement, +- forks with :vlopt:`--bbox-unsup`. If neither :vlopt:`--timing` nor :vlopt:`--no-timing` is specified, all timing controls cause the :option:`NEEDTIMINGOPT` error, except event controls at the top of the process. Forks cause this error as well, except: -* forks with no statements, -* ``fork..join`` or ``fork..join_any`` with one statement, -* forks with :vlopt:`--bbox-unsup`. +- forks with no statements, +- ``fork..join`` or ``fork..join_any`` with one statement, +- forks with :vlopt:`--bbox-unsup`. Timing controls and forks can also be ignored in specific files or parts of files. The :option:`/*verilator&32;timing_off*/` and diff --git a/docs/guide/overview.rst b/docs/guide/overview.rst index 7bd01c1b8..bf57423a0 100644 --- a/docs/guide/overview.rst +++ b/docs/guide/overview.rst @@ -48,9 +48,9 @@ The best place to get started is to try the :ref:`Examples`. uses the shorthand, e.g., "IEEE 1364-2005", to refer to the, e.g., 2005 version of this standard. -.. [#] SystemVerilog is defined by the `Institute of Electrical and - Electronics Engineers (IEEE) Standard for SystemVerilog - Unified - Hardware Design, Specification, and Verification Language`, Standard - 1800, released in 2005, 2009, 2012, 2017, and 2023. The Verilator - documentation uses the shorthand e.g., "IEEE 1800-2023", to refer to - the, e.g., 2023 version of this standard. +.. [#] SystemVerilog is defined by the `Institute of Electrical and Electronics + Engineers (IEEE) Standard for SystemVerilog - Unified Hardware Design, + Specification, and Verification Language`, Standard 1800, released in + 2005, 2009, 2012, 2017, and 2023. The Verilator documentation uses the + shorthand e.g., "IEEE 1800-2023", to refer to the, e.g., 2023 version of + this standard. diff --git a/docs/guide/simulating.rst b/docs/guide/simulating.rst index 168a02414..6ace6014d 100644 --- a/docs/guide/simulating.rst +++ b/docs/guide/simulating.rst @@ -210,7 +210,8 @@ For simple coverage points, use the ``cover property`` construct: DefaultClock: cover property (@(posedge clk) cyc==3); -This adds a coverage point that tracks whether the condition has been observed. +This adds a coverage point that tracks whether the condition has been +observed. .. _covergroup coverage: @@ -268,13 +269,12 @@ deeply nested control recovery, or cross-module state alias tracing. The following metacomments may be attached to the state variable to steer the extracted coverage model: -- ``/*verilator fsm_state*/`` forces the variable to be treated as - FSM state. -- ``/*verilator fsm_reset_arc*/`` marks reset transitions as - user-visible reset arcs instead of defaulting to a hidden reset-only - summary. -- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch - arcs that would otherwise be skipped by the conservative extractor. +- ``/*verilator fsm_state*/`` forces the variable to be treated as FSM + state. +- ``/*verilator fsm_reset_arc*/`` marks reset transitions as user-visible + reset arcs instead of defaulting to a hidden reset-only summary. +- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch arcs that + would otherwise be skipped by the conservative extractor. State registers may also be wrapped by a transparent instance, for example a project flop wrapper or primitive. Such wrappers must be described @@ -433,11 +433,11 @@ coverage point insertions into the model and collect the coverage data. To get the coverage data from the model, write the coverage with either: -1. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump +#. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump coverage when the test completes to the filename specified with :vlopt:`+verilator+coverage+file+\`. -2. In the user wrapper code, typically at the end once a test passes, call +#. In the user wrapper code, typically at the end once a test passes, call ``Verilated::threadContextp()->coveragep()->write`` with an argument of the filename for the coverage data file to write coverage data to (typically "logs/coverage.dat"). @@ -502,12 +502,12 @@ how execution time is distributed in a verilated model. With the :vlopt:`--prof-exec` option, Verilator will: -* Add code to the Verilated model to record execution flow. +- Add code to the Verilated model to record execution flow. -* Add code to save profiling data in non-human-friendly form to the file +- Add code to save profiling data in non-human-friendly form to the file specified with :vlopt:`+verilator+prof+exec+file+\`. -* In multithreaded models, add code to record each macro-task's start and +- In multithreaded models, add code to record each macro-task's start and end time across several calls to eval. (What is a macro-task? See the Verilator internals document (:file:`docs/internals.rst` in the distribution.) @@ -607,8 +607,8 @@ There are two forms of profile-guided optimizations. Unfortunately, for best results, they must each be performed from the highest level code to the lowest, which means performing them separately and in this order: -* :ref:`Thread PGO` -* :ref:`Compiler PGO` +- :ref:`Thread PGO` +- :ref:`Compiler PGO` Other forms of PGO may be supported in the future, such as clock and reset toggle rate PGO, branch prediction PGO, statement execution time PGO, or @@ -674,7 +674,7 @@ multithreaded models. Please see the appropriate compiler documentation to use PGO with GCC or Clang. The process in GCC 10 was as follows: -1. Compile the Verilated model with the compiler's "-fprofile-generate" +#. Compile the Verilated model with the compiler's "-fprofile-generate" flag: .. code-block:: bash @@ -685,10 +685,10 @@ Clang. The process in GCC 10 was as follows: Or, if calling make yourself, add -fprofile-generate appropriately to your Makefile. -2. Run your simulation. This will create \*.gcda file(s) in the same +#. Run your simulation. This will create \*.gcda file(s) in the same directory as the source files. -3. Recompile the model with -fprofile-use. The compiler will read the +#. Recompile the model with -fprofile-use. The compiler will read the \*.gcda file(s). For GCC: diff --git a/docs/guide/verilating.rst b/docs/guide/verilating.rst index 65a6f2d07..6a856248d 100644 --- a/docs/guide/verilating.rst +++ b/docs/guide/verilating.rst @@ -8,21 +8,21 @@ Verilating Verilator may be used in five major ways: -* With the :vlopt:`--binary` option, Verilator will translate the design +- With the :vlopt:`--binary` option, Verilator will translate the design into an executable, via generating C++ and compiling it. See :ref:`Binary, C++ and SystemC Generation`. -* With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate +- With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate the design into C++ or SystemC code, respectively. See :ref:`Binary, C++ and SystemC Generation`. -* With the :vlopt:`--lint-only` option, Verilator will lint the design to +- With the :vlopt:`--lint-only` option, Verilator will lint the design to check for warnings but will not typically create any output files. -* With the :vlopt:`--json-only` option, Verilator will create JSON output +- With the :vlopt:`--json-only` option, Verilator will create JSON output that may be used to feed into other user-designed tools. -* With the :vlopt:`-E` option, Verilator will preprocess the code according +- With the :vlopt:`-E` option, Verilator will preprocess the code according to IEEE preprocessing rules and write the output to standard out. This is useful to feed other tools and to debug how "\`define" statements are expanded. @@ -128,9 +128,9 @@ Usage Users need to mark one or more moderate-size modules as hierarchy block(s). There are two ways to mark a module: -* Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code. +- Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code. -* Add a :option:`hier_block` line in the :ref:`Verilator Control Files`. +- Add a :option:`hier_block` line in the :ref:`Verilator Control Files`. Then pass the :vlopt:`--hierarchical` option to Verilator. @@ -146,28 +146,28 @@ Limitations Hierarchy blocks have some limitations, including: -* Internals of the hierarchy block cannot be accessed using dot (.) from +- Internals of the hierarchy block cannot be accessed using dot (.) from the upper module(s) or other hierarchy blocks, except that ports of a hierarchy block instance can be accessed from the directly enclosing nested hierarchy block, or from the top level non-hierarchical portions of the design if not a nested hierarchy block. -* Modport cannot be used at the hierarchical block boundary. +- Modport cannot be used at the hierarchical block boundary. -* The simulation speed is likely not as fast as flat Verilation, in which +- The simulation speed is likely not as fast as flat Verilation, in which all modules are globally scheduled. -* Generated clocks may not work correctly if generated in the hierarchical +- Generated clocks may not work correctly if generated in the hierarchical model and passed into another hierarchical model or the top module. -* Delays are not allowed in hierarchy blocks. +- Delays are not allowed in hierarchy blocks. But, the following usage is supported: -* Nested hierarchy blocks. A hierarchy block may instantiate other +- Nested hierarchy blocks. A hierarchy block may instantiate other hierarchy blocks. -* Parameterized hierarchy block. Parameters of a hierarchy block can be +- Parameterized hierarchy block. Parameters of a hierarchy block can be overridden using ``#(.param_name(value))`` construct. diff --git a/docs/internals.rst b/docs/internals.rst index ab5754dd0..fb3b5281d 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -113,9 +113,9 @@ pointer to the ``AstNode`` currently being processed. There are notable sub-hierarchies of the ``AstNode`` sub-types, namely: -1. All AST nodes representing data types derive from ``AstNodeDType``. +#. All AST nodes representing data types derive from ``AstNodeDType``. -2. All AST nodes representing expressions (i.e.: anything that stands for, +#. All AST nodes representing expressions (i.e.: anything that stands for, or evaluates to a value) derive from ``AstNodeExpr``. @@ -666,23 +666,23 @@ The second visitor in ``V3Timing.cpp``, ``TimingControlVisitor``, uses the information provided by ``TimingSuspendableVisitor`` and transforms each timing control into a ``co_await``. -* event controls are turned into ``co_await`` on a trigger scheduler's +- event controls are turned into ``co_await`` on a trigger scheduler's ``trigger`` method. The awaited trigger scheduler is the one corresponding to the sentree referenced by the event control. This sentree is also referenced by the ``AstCAwait`` node, to be used later by the static scheduling code. -* if an event control waits on a local variable or class member, it uses a +- if an event control waits on a local variable or class member, it uses a local trigger which it evaluates inline. It awaits a dynamic trigger scheduler multiple times: for trigger evaluation, updates, and resumption. The dynamic trigger scheduler is responsible for resuming the coroutine at the correct point of evaluation. -* delays are turned into ``co_await`` on a delay scheduler's ``delay`` +- delays are turned into ``co_await`` on a delay scheduler's ``delay`` method. The created ``AstCAwait`` nodes also reference a special sentree related to delays, to be used later by the static scheduling code. -* ``join`` and ``join_any`` are turned into ``co_await`` on a +- ``join`` and ``join_any`` are turned into ``co_await`` on a ``VlForkSync``'s ``join`` method. Each forked process gets a ``VlForkSync::done`` call at the end. @@ -732,22 +732,22 @@ event `a` was called first - which is necessary to know. There are two functions for managing timing logic called by ``_eval()``: -* ``_timing_ready()``, which commits all coroutines whose triggers were not +- ``_timing_ready()``, which commits all coroutines whose triggers were not set in the current iteration, -* ``_timing_resume()``, which calls `resume()` on all trigger and delay +- ``_timing_resume()``, which calls `resume()` on all trigger and delay schedulers whose triggers were set in the current iteration. Thanks to this separation a coroutine: -* awaiting a trigger cannot be suspended and resumed in the same iteration +- awaiting a trigger cannot be suspended and resumed in the same iteration (``test_regress/t/t_timing_eval_act.v``) - which is necessary to make Verilator more predictable; this is the reason for introduction of 3rd stage in `VlTriggerScheduler` and thanks to this it is guaranteed that downstream logic will be evaluated before resumption (assuming that the coroutine wasn't already triggered in previous iteration); -* cannot be resumed before it is suspended - +- cannot be resumed before it is suspended - ``test_regress/t/t_event_control_double_excessive.v``; -* firing cannot cannot be lost +- firing cannot cannot be lost (``test_regress/t/t_event_control_double_lost.v``) - which is possible when triggers are not evaluated right before awaiting. @@ -1300,15 +1300,15 @@ the ```` field is `` : ``, where ```` will be used as the base name of the generated operand accessors, and ```` is one of: -1. An ``AstNode`` sub-class, defining the operand to be of that type, +#. An ``AstNode`` sub-class, defining the operand to be of that type, always no-null, and with an always null ``nextp()``. That is, the child node is always present, and is a single ``AstNode`` (as opposed to a list). -2. ``Optional[]``. This is just like in point 1 above, +#. ``Optional[]``. This is just like in point 1 above, but defines the child node to be optional, meaning it may be null. -3. ``List[AstNode sub-class]`` describes a list operand, which means the +#. ``List[AstNode sub-class]`` describes a list operand, which means the child node may have a non-null ``nextp()`` and in addition the child itself may be null, representing an empty list. @@ -1395,7 +1395,7 @@ calling ``accept`` on ``AstIf`` will look in turn for: There are three ways data is passed between visitor functions. -1. A visitor-class member variable. This is generally for passing "parent" +#. 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 @@ -1405,7 +1405,7 @@ There are three ways data is passed between visitor functions. visitor; otherwise exiting the lower for will lose the upper for's setting. -2. User attributes. Each ``AstNode`` (**Note.** The AST node, not the +#. 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 ``user4()`` methods, or as a pointer (of type ``AstNUser``) using the ``user1p()`` through ``user4p()`` methods @@ -1436,7 +1436,7 @@ There are three ways data is passed between visitor functions. 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" +#. 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 messier than the above and is @@ -2126,19 +2126,19 @@ To print a node: ``src/.gdbinit`` and ``src/.gdbinit.py`` define handy utilities for working with JSON AST dumps. For example: -* ``jstash nodep`` - Perform a JSON AST dump and save it into GDB value +- ``jstash nodep`` - Perform a JSON AST dump and save it into GDB value history (e.g. ``$1``) -* ``jtree nodep`` - Perform a JSON AST dump and pretty print it using +- ``jtree nodep`` - Perform a JSON AST dump and pretty print it using ``astsee_verilator``. -* ``jtree $1`` - Pretty print a dump that was previously saved by +- ``jtree $1`` - Pretty print a dump that was previously saved by ``jstash``. -* ``jtree nodep -d '.file, .timeunit'`` - Perform a JSON AST dump, filter +- ``jtree nodep -d '.file, .timeunit'`` - Perform a JSON AST dump, filter out some fields and pretty print it. -* ``jtree 0x55555613dca0`` - Pretty print using address literal (rather +- ``jtree 0x55555613dca0`` - Pretty print using address literal (rather than actual pointer). -* ``jtree $1 nodep`` - Diff ``nodep`` against an older dump. +- ``jtree $1 nodep`` - Diff ``nodep`` against an older dump. A detailed description of ``jstash`` and ``jtree`` can be displayed using ``gdb``'s ``help`` command. @@ -2244,25 +2244,25 @@ 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 +#. 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 `Testing`. +#. Make a testcase in the test_regress/t/t_EXAMPLE format, see `Testing`. -3. If grammar changes are needed, look at the IEEE 1800-2023 Appendix A, as +#. If grammar changes are needed, look at the IEEE 1800-2023 Appendix A, as src/verilog.y generally follows the same rule layout. -4. If a new Ast type is needed, add it to the appropriate V3AstNode*.h. +#. If a new Ast type is needed, add it to the appropriate V3AstNode*.h. Follow the convention described above about the AstNode type hierarchy. Ordering of definitions is enforced by ``astgen``. -5. Now you can run ``test_regress/t/t_.py --debug`` and it'll +#. Now you can run ``test_regress/t/t_.py --debug`` and it'll probably fail, but you'll see a ``test_regress/obj_dir/t_/*.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. +#. Modify the later visitor functions to process the new feature as needed. Adding a New Pass