diff --git a/bin/verilator b/bin/verilator index c78b8c2d5..be1156d0f 100755 --- a/bin/verilator +++ b/bin/verilator @@ -287,7 +287,7 @@ detailed descriptions of these arguments. =for VL_SPHINX_EXTRACT "_build/gen/args_verilator.rst" - Verilog package, module and top module filenames + Verilog package, module, and top module filenames Optional C++ files to compile in Optional C++ files to link in @@ -379,7 +379,7 @@ detailed descriptions of these arguments. --MP Create phony dependency targets +notimingchecks Ignored -O0 Disable optimizations - -O3 High performance optimizations + -O3 High-performance optimizations -O Selectable optimizations -o Name of final executable --no-order-clock-delay Disable ordering clock enable assignments @@ -387,14 +387,14 @@ detailed descriptions of these arguments. --output-split-cfuncs Split model functions --output-split-ctrace Split tracing functions -P Disable line numbers and blanks with -E - --pins-bv Specify types for top level ports - --pins-sc-biguint Specify types for top level ports - --pins-sc-uint Specify types for top level ports - --pins-uint8 Specify types for top level ports + --pins-bv Specify types for top-level ports + --pins-sc-biguint Specify types for top-level ports + --pins-sc-uint Specify types for top-level ports + --pins-uint8 Specify types for top-level ports --no-pins64 Don't use uint64_t's for 33-64 bit sigs --pipe-filter Filter all input through a script --pp-comments Show preprocessor comments with -E - --prefix Name of top level class + --prefix Name of top-level class --private Debugging; see docs --prof-c Compile C++ code with profiling --prof-cfuncs Name functions for profiling @@ -426,7 +426,7 @@ detailed descriptions of these arguments. --timescale Sets default timescale --timescale-override Overrides all timescales --top Alias of --top-module - --top-module Name of top level input module + --top-module Name of top-level input module --trace Enable waveform creation --trace-coverage Enable tracing of coverage --trace-depth Depth of tracing diff --git a/ci/docker/run/README.rst b/ci/docker/run/README.rst index ccd5709a7..dd778f4fb 100644 --- a/ci/docker/run/README.rst +++ b/ci/docker/run/README.rst @@ -62,12 +62,11 @@ Internals --------- The Dockerfile builds Verilator and removes the tree when completed to -reduce the image size. The entrypoint is set as a wrapper script +reduce the image size. The entrypoint is a wrapper script (``verilator-wrap.sh``). That script 1. calls Verilator, and 2. copies the Verilated runtime files to the ``obj_dir`` or the ``-Mdir`` respectively. This allows the user to have the files to they may later build the C++ output with the matching runtime files. The wrapper also patches the Verilated Makefile accordingly. -There is also a hook defined that is run by docker hub via automated -builds. +A hook is also defined and run by Docker Hub via automated builds. diff --git a/docs/guide/contributors.rst b/docs/guide/contributors.rst index 3d82e0b62..b743bddc5 100644 --- a/docs/guide/contributors.rst +++ b/docs/guide/contributors.rst @@ -11,7 +11,7 @@ Authors When possible, please instead report bugs at `Verilator Issues `_. -Primary author is Wilson Snyder . +The primary author is Wilson Snyder . Major concepts by Paul Wasson, Duane Galbi, John Coiner, Geza Lore, Yutetsu Takatsukasa, and Jie Xu. @@ -22,18 +22,18 @@ Contributors Many people have provided ideas and other assistance with Verilator. -Verilator is receiving major development support from the `CHIPS Alliance -`_, `Antmicro Ltd `_ and -`Shunyao CAD `_. +Verilator is receiving significant development support from the `CHIPS +Alliance `_, `Antmicro Ltd +`_ and `Shunyao CAD `_. Previous major corporate sponsors of Verilator, by providing significant -contributions of time or funds included include: Atmel Corporation, Cavium +contributions of time or funds include: Atmel Corporation, Cavium Inc., Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd., Hicamp Systems, Intel Corporation, Mindspeed Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus Networks Inc., SiCortex Inc, and Shunyao CAD. -The people who have contributed major functionality are: Krzysztof +The contributors of major functionality are: Krzysztof Bieganski, Byron Bradley, Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Geza Lore, Todd Strader, Stefan Wallentowitz, Paul Wasson, Jie Xu, and Wilson Snyder. Major testers included Jeff Dutton, Jonathon Donaldson, @@ -129,8 +129,9 @@ Jeff Winston, Joshua Wise, Clifford Wolf, Tobias Wolfel, Johan Wouters, Paul Wright, Junyi Xi, Ding Xiaoliang, Jie Xu, Mandy Xu, Yinan Xu, Luke Yang, Amir Yazdanbakhsh, Keyi Zhang, and Xi Zhang. -Thanks to them, and all those we've missed including above, or wished to -remain anonymous. +Thanks to them, and all those we've missed mentioning above, and to those +whom have wished to remain anonymous. + Historical Origins ================== @@ -140,10 +141,10 @@ Digital Equipment Corporation. The Verilog code that was converted to C was then merged with a C-based CPU model of the Alpha processor and simulated in a C-based environment called CCLI. -In 1995 Verilator started being also used for Multimedia and Network -Processor development inside Digital. Duane Galbi took over the active -development of Verilator, and added several performance enhancements. CCLI -was still being used as the shell. +In 1995 Verilator started being used for Multimedia and Network Processor +development inside Digital. Duane Galbi took over the active development +of Verilator, and added several performance enhancements, and CCLI was +still being used as the shell. In 1998, through the efforts of existing DECies, mainly Duane Galbi, Digital graciously agreed to release the source code. (Subject to the code @@ -168,5 +169,5 @@ fork/join, delay handling, DFG performance optimizations, and other improvements. Currently, various language features and performance enhancements are added -as the need arises, with a focus on getting to complete Universal -Verification Methodology (UVM, IEEE 1800.2-2017) support. +as the need arises, focusing on completing Universal Verification +Methodology (UVM, IEEE 1800.2-2017) support. diff --git a/docs/guide/environment.rst b/docs/guide/environment.rst index 99c283e6b..99ef9767c 100644 --- a/docs/guide/environment.rst +++ b/docs/guide/environment.rst @@ -10,7 +10,7 @@ associated programs. .. option:: LD_LIBRARY_PATH A generic Linux/OS variable specifying what directories have shared - object (.so) files. This path should include SystemC and any other + object (.so) files. This path should include SystemC and other shared objects needed at simulation runtime. .. option:: MAKE @@ -54,14 +54,14 @@ associated programs. .. option:: SYSTEMC_INCLUDE - If set, specifies the directory containing the systemc.h header file. If - not specified, it will come from a default optionally specified at + If set, specifies the directory containing the systemc.h header file. + If not specified, it will come from a default optionally specified at configure time (before Verilator was compiled), or computed from SYSTEMC/include. .. option:: SYSTEMC_LIBDIR - If set, specifies the directory containing the libsystemc.a library. If + If set, specifies the directory containing the libsystemc.a library. If not specified, it will come from a default optionally specified at configure time (before Verilator was compiled), or computed from SYSTEMC/lib-SYSTEMC_ARCH. diff --git a/docs/guide/example_binary.rst b/docs/guide/example_binary.rst index 0cb1514be..fbcda7e86 100644 --- a/docs/guide/example_binary.rst +++ b/docs/guide/example_binary.rst @@ -42,7 +42,7 @@ Breaking this command down: #. :vlopt:`-Wall` so Verilator has stronger lint warnings enabled. -#. An finally, :command:`our.v` which is our SystemVerilog design file. +#. An finally, :command:`our.v`, which is our SystemVerilog design file. And now we run it: @@ -57,7 +57,7 @@ And we get as output: Hello World - our.v:2: Verilog $finish -Really, you're better off using a Makefile to run the steps for you so when -your source changes it will automatically run all of the appropriate steps. -To aid this Verilator can create a makefile dependency file. For examples -that do this see the :file:`examples` directory in the distribution. +You're better off using a Makefile to run the steps for you, so when your +source changes, it will automatically run all of the appropriate steps. To +aid this, Verilator can create a makefile dependency file. For examples +that do this, see the :file:`examples` directory in the distribution. diff --git a/docs/guide/example_cc.rst b/docs/guide/example_cc.rst index 41280015b..bc4e578f2 100644 --- a/docs/guide/example_cc.rst +++ b/docs/guide/example_cc.rst @@ -12,7 +12,7 @@ of what this C++ code is doing, see .. include:: example_common_install.rst -Now, let's create an example Verilog, and C++ wrapper file: +Now, let's create an example Verilog and C++ wrapper file: .. code-block:: bash @@ -39,7 +39,7 @@ Now, let's create an example Verilog, and C++ wrapper file: } EOF -Now we run Verilator on our little example. +Now we run Verilator on our little example; .. code-block:: bash @@ -47,8 +47,7 @@ Now we run Verilator on our little example. Breaking this command down: -#. :vlopt:`--cc` to get C++ output (versus e.g. SystemC - or only linting). +#. :vlopt:`--cc` to get C++ output (versus e.g., SystemC, or only linting). #. :vlopt:`--exe`, along with our :command:`sim_main.cpp` wrapper file, so the build will create an executable instead of only a library. @@ -89,7 +88,7 @@ And we get as output: Hello World - our.v:2: Verilog $finish -Really, you're better off using a Makefile to run the steps for you so when -your source changes it will automatically run all of the appropriate steps. -To aid this Verilator can create a makefile dependency file. For examples -that do this see the :file:`examples` directory in the distribution. +You're better off using a Makefile to run the steps for you, so when your +source changes, it will automatically run all of the appropriate steps. To +aid this, Verilator can create a makefile dependency file. For examples +that do this, see the :file:`examples` directory in the distribution. diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index 25534b23c..2ba344e72 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -4,8 +4,7 @@ verilator Arguments =================== -The following are the arguments that may be passed to the "verilator" -executable. +The following arguments may be passed to the "verilator" executable. Summary: @@ -28,11 +27,11 @@ Summary: .. option:: - Specifies optional object or library files to be linked in with the + Specifies optional object or library files to be linked with the Verilog code, as a shorthand for :vlopt:`-LDFLAGS \ <-LDFLAGS>`. The file path should either be - absolute, or relative to where the make will be executed from, or add to - your makefile's VPATH the appropriate directory to find the file. + absolute, or relative to where the make will be executed from, or add + the appropriate directory to your makefile's VPATH to find the file. If any files are specified in this way, Verilator will include a make rule that uses these files when linking the module's executable. This @@ -79,8 +78,8 @@ Summary: ```begin_keywords`` is a SystemVerilog construct, which specifies *only* the set of keywords to be recognized. This also controls some - error messages that vary between language standards. Note at present - Verilator tends to be overly permissive, e.g. it will accept many + error messages that vary between language standards. At present, + Verilator tends to be overly permissive, e.g., it will accept many grammar and other semantic extensions which might not be legal when set to an older standard. @@ -92,7 +91,7 @@ Summary: After every $display or $fdisplay, flush the output stream. This ensures that messages will appear immediately but may reduce - performance. For best performance call :code:`fflush(stdout)` + performance. For best performance, call :code:`fflush(stdout)` occasionally in the C++ main loop. Defaults to off, which will buffer output as provided by the normal C/C++ standard library IO. @@ -101,8 +100,8 @@ Summary: Black box any unknown $system task or function calls. System tasks will become no-operations, and system functions will be replaced with unsized zero. Arguments to such functions will be parsed, but not otherwise - checked. This prevents errors when linting in the presence of company - specific PLI calls. + checked. This prevents errors when linting in the presence of + company-specific PLI calls. Using this argument will likely cause incorrect simulation. @@ -110,7 +109,7 @@ Summary: Black box some unsupported language features, currently UDP tables, the cmos and tran gate primitives, deassign statements, and mixed edge - errors. This may enable linting the rest of the design even when + errors. This may enable linting of the rest of the design even when unsupported constructs are present. Using this argument will likely cause incorrect simulation. @@ -133,10 +132,10 @@ Summary: Rarely needed. When a dependency (.d) file is created, this filename will become a source dependency, such that a change in this binary will - have make rebuild the output files. Defaults to the full path to the - Verilator binary. + have ``make`` rebuild the output files. Defaults to the full path to + the Verilator binary. - This option was named `--bin` prior to version 4.228. + This option was named `--bin` before version 4.228. .. option:: --build-jobs [] @@ -149,46 +148,46 @@ Summary: .. option:: --cc - Specifies C++ without SystemC output mode; see also :vlopt:`--sc` + Specify C++ without SystemC output mode; see also the :vlopt:`--sc` option. .. option:: --cdc Permanently experimental. Perform some clock domain crossing checks and issue related warnings (CDCRSTLOGIC) and then exit; if warnings other - than CDC warnings are needed make a second run with + than CDC warnings are needed, make a second run with :vlopt:`--lint-only`. Additional warning information is also written to the file :file:`__cdc.txt`. - Currently only checks some items that other CDC tools missed; if you - have interest in adding more traditional CDC checks, please contact the + Currently only checks some items that other CDC tools missed; if you are + interested in adding more traditional CDC checks, please contact the authors. .. option:: -CFLAGS Add specified C compiler argument to the generated makefiles. For - multiple flags either pass them as a single argument with space + multiple flags, either pass them as a single argument with space separators quoted in the shell (:command:`-CFLAGS "-a -b"`), or use multiple -CFLAGS options (:command:`-CFLAGS -a -CFLAGS -b`). - When make is run on the generated makefile these will be passed to the + When make is run on the generated makefile, these will be passed to the C++ compiler (g++/clang++/msvc++). .. option:: --clk With :vlopt:`--clk`, the specified signal is marked as a clock signal. - The provided signal-name is specified using a RTL hierarchy path. For + The provided signal name is specified using a RTL hierarchy path. For example, v.foo.bar. If the signal is the input to top-module, then directly provide the signal name. Alternatively, use a :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the signal directly. - If clock signals are assigned to vectors and then later used as - individual bits, Verilator will attempt to decompose the vector and - connect the single-bit clock signals. + If clock signals are assigned to vectors and later used as individual + bits, Verilator will attempt to decompose the vector and connect the + single-bit clock signals. - In versions prior to 5.000, the clocker attribute is useful in cases where + In versions before 5.000, the clocker attribute is useful in cases where Verilator does not properly distinguish clock signals from other data signals. Using clocker will cause the signal indicated to be considered a clock, and remove it from the combinatorial logic reevaluation checking @@ -196,23 +195,23 @@ Summary: .. option:: --no-clk - Prevent the specified signal from being marked as clock. See + Prevent the specified signal from being marked as a clock. See :vlopt:`--clk`. .. option:: --compiler Enables workarounds for the specified C++ compiler (list below). - Currently this does not change any performance tuning options, but it may + This does not change any performance tuning options, but it may in the future. clang Tune for clang. This may reduce execution speed as it enables several workarounds to avoid silly hard-coded limits in clang. This includes - breaking deep structures as for msvc as described below. + breaking deep structures as for msvc, as described below. gcc Tune for GNU C++, although generated code should work on almost any - compliant C++ compiler. Currently the default. + compliant C++ compiler. Currently, the default. msvc Tune for Microsoft Visual C++. This may reduce execution speed as it @@ -228,7 +227,7 @@ Summary: .. option:: --coverage - Enables all forms of coverage, alias for :vlopt:`--coverage-line` + Enables all forms of coverage, an alias for :vlopt:`--coverage-line` :vlopt:`--coverage-toggle` :vlopt:`--coverage-user`. .. option:: --coverage-line @@ -237,7 +236,7 @@ Summary: .. option:: --coverage-max-width - Rarely needed. Specify the maximum bit width of a signal that is + Rarely needed. Specify the maximum bit width of a signal subject to toggle coverage. Defaults to 256, as covering large vectors may greatly slow coverage simulations. @@ -253,21 +252,21 @@ Summary: .. option:: --coverage-user - Enables adding user inserted functional coverage. See :ref:`User Coverage`. + Enables adding user-inserted functional coverage. See :ref:`User Coverage`. .. option:: -D= Defines the given preprocessor symbol. Similar to :vlopt:`+define <+define+>`, but does not allow multiple - definitions with a single option using plus signs. "+define" is fairly - standard across Verilog tools while "-D" is similar to + definitions with a single option using plus signs. "+define" is relatively + standard across Verilog tools, while "-D" is similar to :command:`gcc -D`. .. option:: --debug Run under debug. - * Select the debug executable of Verilator (if available), this + * Select the debug executable of Verilator (if available). This generally is a less-optimized binary with symbols present (so GDB can be used on it). * Enable debugging messages (equivalent to :vlopt:`--debugi 3 <--debugi>`). * Enable internal assertions (equivalent to :vlopt:`--debug-check`). @@ -286,7 +285,7 @@ Summary: .. option:: --no-debug-leak - In :vlopt:`--debug` mode, by default Verilator intentionally leaks + In :vlopt:`--debug` mode, by default, Verilator intentionally leaks AstNode instances instead of freeing them, so that each node pointer is unique in the resulting tree files and dot files. @@ -294,18 +293,18 @@ Summary: Verilating large models in :vlopt:`--debug` mode. Outside of :vlopt:`--debug` mode, AstNode instances should never be - leaked and this option has no effect. + leaked, and this option has no effect. .. option:: --debugi - Rarely needed - for developer use. Set internal debugging level + Rarely needed - for developer use. Set the internal debugging level globally to the specified debug level (1-10). Higher levels produce more detailed messages. .. option:: --debugi- Rarely needed - for developer use. Set the specified Verilator source - file to the specified level (e.g. + file to the specified level (e.g., :vlopt:`--debugi-V3Width 9 <--debugi>`). Higher levels produce more detailed messages. See :vlopt:`--debug` for other implications of enabling debug. @@ -313,13 +312,13 @@ Summary: .. option:: --no-decoration When creating output Verilated code, minimize comments, white space, - symbol names and other decorative items, at the cost of greatly reduced + symbol names, and other decorative items, at the cost of reduced readability. This may assist C++ compile times. This will not typically change the ultimate model's performance, but may in some cases. .. option:: --default-language - Select the language to be used by default when first processing each + Select the language used by default when first processing each Verilog file. The language value must be "VAMS", "1364-1995", "1364-2001", "1364-2001-noconfig", "1364-2005", "1800-2005", "1800-2009", "1800-2012", "1800-2017", or "1800+VAMS". @@ -331,7 +330,7 @@ Summary: The :vlopt:`--default-language` is only recommended for legacy code using the same language in all source files, as the preferable option is to edit the code to repair new keywords, or add appropriate - :code:`\`begin_keywords`. For legacy mixed language designs, the various + :code:`\`begin_keywords`. For legacy mixed-language designs, the various ``+ext+`` options should be used. If no language is specified, either by this option or ``+ext+`` @@ -343,13 +342,13 @@ Summary: .. option:: +define+=[+=][...] Defines the given preprocessor symbol, or multiple symbols if separated - by plus signs. Similar to :vlopt:`-D <-D>`; +define is fairly + by plus signs. Similar to :vlopt:`-D <-D>`; +define is relatively standard across Verilog tools while :vlopt:`-D <-D>` is similar to :command:`gcc -D`. .. option:: --dpi-hdr-only - Only generate the DPI header file. This option has no effect on the + Only generate the DPI header file. This option does not affect on the name or location of the emitted DPI header file, it is output in :vlopt:`--Mdir` as it would be without this option. @@ -378,7 +377,7 @@ Summary: .. option:: --dump-tree Rarely needed. Enable dumping Ast .tree debug files with dumping level 3, - which dumps the standard critical stages. For details on the format see + which dumps the standard critical stages. For details on the format, see the Verilator Internals manual. :vlopt:`--dump-tree` is enabled automatically with :vlopt:`--debug`, so :vlopt:`--debug --no-dump-tree <--dump-tree>` may be useful if the dump @@ -394,10 +393,10 @@ Summary: Rarely needed - for developer use. Replace AST node addresses with short identifiers in tree dumps to enhance readability. Each unique - pointer value is mapped to an unique identifier, but note that this is + pointer value is mapped to a unique identifier, but note that this is not necessarily unique per node instance as an address might get reused by a newly allocated node after a node with the same address has been - dumped then freed. + dumped and then freed. .. option:: --dump- @@ -406,7 +405,7 @@ Summary: .. option:: --dumpi-dfg - Rarely needed - for developer use. Set internal DfgGraph dumping level + Rarely needed - for developer use. Set the internal DfgGraph dumping level globally to the specified value. .. option:: --dumpi-graph @@ -422,9 +421,9 @@ Summary: .. option:: --dumpi- Rarely needed - for developer use. Set the dumping level in the - specified Verilator source file to the specified value (e.g. + specified Verilator source file to the specified value (e.g., `--dumpi-V3Order 9`). Level 0 disables dumps and is equivalent to - `--no-dump-`. Level 9 enables dumping of everything. + `--no-dump-`. Level 9 enables the dumping of everything. .. option:: -E @@ -441,7 +440,7 @@ Summary: After this number of errors are encountered during Verilator run, exit. Warnings are not counted in this limit. Defaults to 50. - Does not affect simulation runtime errors, for those see + It does not affect simulation runtime errors, for those, see :vlopt:`+verilator+error+limit+\`. .. option:: --exe @@ -461,16 +460,16 @@ Summary: Read the specified file, and act as if all text inside it was specified as command line arguments. Any relative paths are relative to the directory containing the specified file. See also :vlopt:`-f` - option. Note :option:`-F` is fairly standard across Verilog tools. + option. Note :option:`-F` is relatively standard across Verilog tools. .. option:: -f Read the specified file, and act as if all text inside it was specified as command line arguments. Any relative paths are relative to the current directory. See also :vlopt:`-F` option. Note :option:`-f` is - fairly standard across Verilog tools. + relatively standard across Verilog tools. - The file may contain :code:`//` comments which are ignored to the end of + The file may contain :code:`//` comments which are ignored until the end of the line. It may also contain :code:`/* .. */` comments which are ignored, be cautious that wildcards are not handled in -f files, and that :code:`directory/*` is the beginning of a comment, not a wildcard. @@ -488,9 +487,9 @@ Summary: .. option:: --flatten - Force flattening of the design's hierarchy, with all modules, tasks and - functions inlined. Typically used with :vlopt:`--xml-only`. Note - flattening large designs may require significant CPU time, memory and + Force flattening of the design's hierarchy, with all modules, tasks, and + functions inlined. Typically used with :vlopt:`--xml-only`. + Flattening large designs may require significant CPU time, memory and storage. .. option:: -fno-acyc-simp @@ -515,7 +514,7 @@ Summary: .. option:: -fno-dfg - Disable all use of the DFG based combinational logic optimizer. + Disable all use of the DFG-based combinational logic optimizer. Alias for :vlopt:`-fno-dfg-pre-inline` and :vlopt:`-fno-dfg-post-inline`. .. option:: -fno-dfg-peephole @@ -571,7 +570,7 @@ Summary: .. option:: -future0