Commentary: Make RST documents round-trip clean. No output change intended.
This commit is contained in:
Wilson Snyder
parent
b92bf86016
commit
5fc03ae913
60
README.rst
60
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 <https://verilator.org/issues>`_
|
||||
|
||||
|
||||
Support
|
||||
=======
|
||||
|
||||
|
|
@ -133,7 +134,6 @@ Verilator also supports and encourages commercial support models and
|
|||
organizations; please see `Verilator Commercial Support
|
||||
<https://verilator.org/verilator_commercial_support>`_.
|
||||
|
||||
|
||||
Related Projects
|
||||
================
|
||||
|
||||
|
|
@ -150,7 +150,6 @@ Related Projects
|
|||
- `Surfer <https://surfer-project.org/>`_ - 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
|
||||
|
|
|
|||
|
|
@ -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``.
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,8 @@ Please refer to `sv-bugpoint README
|
|||
<https://github.com/antmicro/sv-bugpoint/blob/main/README.md>`_ for more
|
||||
information on how to use `sv-bugpoint`.
|
||||
|
||||
.. Contributing
|
||||
.. ============
|
||||
..
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. include:: ../CONTRIBUTING.rst
|
||||
|
|
|
|||
|
|
@ -30,10 +30,10 @@ Alliance <https://chipsalliance.org>`_, 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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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+\<filename\>`.
|
||||
|
||||
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+\<filename\>`.
|
||||
|
||||
* 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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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 ``<description>`` field is ``<identifier> : <type>``, where
|
|||
``<identifier>`` will be used as the base name of the generated operand
|
||||
accessors, and ``<type>`` 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[<AstNode sub-class>]``. This is just like in point 1 above,
|
||||
#. ``Optional[<AstNode sub-class>]``. 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_<newtestcase>.py --debug`` and it'll
|
||||
#. Now you can run ``test_regress/t/t_<newtestcase>.py --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.
|
||||
#. Modify the later visitor functions to process the new feature as needed.
|
||||
|
||||
|
||||
Adding a New Pass
|
||||
|
|
|
|||
Loading…
Reference in New Issue