From 61ff7039b491b39de836459136eb14bc45e9ffda Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Sun, 28 Jun 2020 18:37:42 -0400 Subject: [PATCH] Commentary (#2439) --- bin/verilator | 105 +++++++++++++++++++++++++++++--------------------- 1 file changed, 62 insertions(+), 43 deletions(-) diff --git a/bin/verilator b/bin/verilator index f6b2babc3..091c92593 100755 --- a/bin/verilator +++ b/bin/verilator @@ -224,6 +224,7 @@ __END__ Verilator - Translate and simulate SystemVerilog code using C++/SystemC + =head1 SYNOPSIS verilator --help @@ -232,30 +233,43 @@ Verilator - Translate and simulate SystemVerilog code using C++/SystemC verilator --sc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so] verilator --lint-only -Wall [source_files.v]... + =head1 DESCRIPTION -Verilator converts synthesizable or limited behavioral Verilog, some -SystemVerilog, a small subset of Verilog AMS and some Synthesis directives into -a C++ or SystemC model. It is not a traditional simulator, but a compiler. +The "Verilator" package converts all synthesizable, and many behavioral, +Verilog and SystemVerilog designs into a C++ or SystemC model that after +compiling can be executed. Verilator is not a traditional simulator, but a +compiler. -Verilator is invoked with parameters similar to GCC, Cadence -Verilog-XL/NC-Verilog, or Synopsys VCS. It reads the specified Verilog code, -lints it, optionally adds coverage and waveform tracing support, and compiles -the design into a source level C++ or SystemC model of the top-level module. -The resulting C++ or SystemC code is output as .cpp and .h files. +Verilator is typically used as follows: -The files created by Verilator are then compiled with a C++ compiler. For -simulation, a small user written C++ wrapper file is required. This wrapper -defines `main` and instantiates the Verilated model of the top-level module. -The resulting executable will perform the actual simulation. +1. The C executable is invoked with parameters similar to GCC, +Cadence Verilog-XL/NC-Verilog, or Synopsys VCS. C reads the +specified user's SystemVerilog code, lints it, optionally adds coverage and +waveform tracing support, and compiles the design into a source level C++ +or SystemC "model". The resulting model's C++ or SystemC code is output as +.cpp and .h files. This is referred to as "verilating" and the process is +"to verilate"; the output is a "verilated" model. + +2. For simulation, a small user written C++ wrapper file is required, the +"wrapper". This wrapper defines the C++ function `main()` which +instantiates the Verilated model as a C++/SystemC object. + +3. The user main wrapper, the files created by Verilator, a "runtime +library" provided by Verilator, and if applicable the SystemC libraries are +then compiled using a C++ compiler to create a simulation executable. + +4. The resulting executable will perform the actual simulation, during +"simulation runtime". To get started, jump down to the L section. =head1 ARGUMENT SUMMARY -This is a short summary of the arguments to Verilator itself. See the -detailed descriptions in L for more information. +This is a short summary of the arguments to the "verilator" executable. +See L for the detailed descriptions of these +arguments. {file.v} Verilog package, module and top module filenames {file.c/cc/cpp} Optional C++ files to compile in @@ -274,7 +288,7 @@ detailed descriptions in L for more information. --bbox-unsup Blackbox unsupported language features --bin Override Verilator binary --build Build model executable/library after Verilation - -CFLAGS C++ Compiler flags for makefile + -CFLAGS C++ compiler flags for makefile --cc Create C++ output --cdc Clock domain crossing analysis --clk Mark specified signal as clock @@ -307,7 +321,7 @@ detailed descriptions in L for more information. -f Parse options from a file -FI Force include of a file --flatten Force inlining of all modules, tasks and functions - -G= Overwrite toplevel parameter + -G= Overwrite top-level parameter --gdb Run Verilator under GDB interactively --gdbbt Run Verilator under GDB for backtrace --generate-key Create random key for --protect-key @@ -416,9 +430,9 @@ detailed descriptions in L for more information. --xml-output XML output filename -y Directory to search for modules -This is a short summary of the arguments to simulation runtime Verilated -arguments. detailed descriptions in L for -more information. +This is a short summary of the simulation runtime arguments, i.e. for the +final Verilated simulation runtime models. See L for the detailed description of these arguments. +verilator+debug Enable debugging +verilator+debugi+ Enable debugging at a level @@ -435,7 +449,8 @@ more information. =head1 VERILATION ARGUMENTS -The following are the arguments that may be passed to Verilator itself. +The following are the arguments that may be passed to the "verilator" +executable. =over 4 @@ -617,7 +632,7 @@ flags, but it may in the future. =item clang Tune for clang. This may reduce execution speed as it enables several -workarounds to avoid silly hardcoded limits in clang. This includes +workarounds to avoid silly hard-coded limits in clang. This includes breaking deep structures as for msvc as described below. =item gcc @@ -628,7 +643,7 @@ compliant C++ compiler. Currently the default. =item msvc Tune for Microsoft Visual C++. This may reduce execution speed as it -enables several workarounds to avoid silly hardcoded limits in MSVC++. +enables several workarounds to avoid silly hard-coded limits in MSVC++. This includes breaking deeply nested parenthesized expressions into sub-expressions to avoid error C1009, and breaking deep blocks into functions to avoid error C1061. @@ -1061,7 +1076,7 @@ Prevent the specified signal from being marked as clock. See C<--clk>. =item --no-decoration -When creating output Verilated code, minimize comments, whitespace, symbol +When creating output Verilated code, minimize comments, white space, symbol names and other decorative items, at the cost of greatly reduced readability. This may assist C++ compile times. This will not typically change the ultimate model's performance, but may in some cases. @@ -1733,14 +1748,14 @@ whatever is best for performance. C<--x-assign 0> converts all Xs to 0s, and is also fast. C<--x-assign 1> converts all Xs to 1s, this is nearly as fast as 0, but more likely to find reset bugs as active high logic will fire. Using C<--x-assign unique> will result in all explicit Xs being replaced by a -constant value determined at run-time. The value is determined by calling a +constant value determined at runtime. The value is determined by calling a function at initialization time. This enables randomization of Xs with different seeds on different executions. This method is the slowest, but safest for finding reset bugs. If using --x-assign unique, you may want to seed your random number generator such that each regression run gets a different randomization sequence. The -simplest is to use the +verilator+seed run-time option. Alternatively use the +simplest is to use the +verilator+seed runtime option. Alternatively use the system's srand48() or for Windows srand() function to do this. You'll probably also want to print any seeds selected, and code to enable rerunning with that same seed so you can reproduce bugs. @@ -2120,7 +2135,7 @@ applies to slow-path code, which executes rarely, often only once at the beginning or end of simulation. Note that OPT_SLOW is ignored if VM_PARALLEL_BUILDS is not 1, in which case all generated code will be compiled in a single compilation unit using OPT_FAST. See also the C<--output-split> -option. The OPT_GLOBAL variable applies to common code in the run-time library +option. The OPT_GLOBAL variable applies to common code in the runtime library used by Verilated models (shipped in $VERILATOR_ROOT/include). Additional C++ files passed on the verilator command line use OPT_FAST. The OPT variable applies to all compilation units in addition to the specific OPT_* variables @@ -2141,8 +2156,8 @@ controlled by OPT_SLOW have little effect on performance and therefore OPT_SLOW is empty by default (equivalent to "-O0") for improved compilation speed. In common use-cases there should be little benefit in changing OPT_SLOW. OPT_GLOBAL is set to "-Os" by default and there should rarely be a need to -change it. As the run-time library is small in comparison to a lot of Verilated -models, disabling optimization on the run-time library should not have a +change it. As the runtime library is small in comparison to a lot of Verilated +models, disabling optimization on the runtime library should not have a serious effect on overall compilation time, but may have detrimental effect on simulation speed, especially with tracing. In addition to the above, for best results use OPT="-march=native", the latest Clang compiler (about 10% faster @@ -2324,7 +2339,7 @@ Specifies the directory containing the distribution kit. This is used to find the executable, Perl library, and include files. If not specified, it will come from a default optionally specified at configure time (before Verilator was compiled). It should not be specified if using a pre-compiled -Verilator package as the hardcoded value should be correct. +Verilator package as the hard-coded value should be correct. =back @@ -2738,9 +2753,9 @@ the SystemC include an library path. (same as above). - When using Accellera's SystemC with CMake support, a CMake target is -available that will easen above steps. This will only work if the SystemC -installation can be found by CMake. This can be configured by setting the -CMAKE_PREFIX_PATH variable during CMake configuration. +available that simplifies the above steps. This will only work if the +SystemC installation can be found by CMake. This can be configured by +setting the CMAKE_PREFIX_PATH variable during CMake configuration. Don't forget to set the same C++ standard for the Verilated sources as the SystemC library. This can be specified using the SYSTEMC_CXX_FLAGS environment @@ -2759,10 +2774,10 @@ List of Verilog files to Verilate. Must have at least one file. =item PREFIX Optional. Sets the Verilator output prefix. Defaults to the name of the -first hdl source with a "V" prepended. Must be unique in each call to +first source file with a "V" prepended. Must be unique in each call to verilate(), so this is necessary if you build a module multiple times with different parameters. Must be a valid C++ identifier, i.e. contains no -whitespace and only characters A-Z, a-z, 0-9 or _. +white space and only characters A-Z, a-z, 0-9 or _. =item TOP_MODULE @@ -2800,7 +2815,7 @@ Optional. Set compiler flags for the fast path. =item OPT_GLOBAL -Optional. Set compiler flags for the common run-time library used by Verilated +Optional. Set compiler flags for the common runtime library used by Verilated models. =item DIRECTORY @@ -2815,6 +2830,7 @@ here, use DIRECTORY or PREFIX. =back + =head1 MULTITHREADING Verilator supports multithreaded simulation models. @@ -2916,6 +2932,7 @@ thread. =back + =head1 CONFIGURATION FILES In addition to the command line, warnings and other features may be @@ -3732,13 +3749,14 @@ side is a constant. This may make the expression yield a different result compared to a four state simulator. An === comparison to X will always be false, so that Verilog code which checks for uninitialized logic will not fire. -Assigning X to a variable will actually assign a constant value as determined -by the --x-assign switch. This allows run-time randomization, thus if the -value is actually used, the random value should cause downstream errors. -Integers also get randomized, even though the Verilog 2001 specification says -they initialize to zero. Note however that randomization happens at -initialziation time and hence during a single simulation run, the same constant -(but random) value will be used every time the assignment is executed. +Assigning X to a variable will actually assign a constant value as +determined by the --x-assign switch. This allows runtime randomization, +thus if the value is actually used, the random value should cause +downstream errors. Integers also get randomized, even though the Verilog +2001 specification says they initialize to zero. Note however that +randomization happens at initialization time and hence during a single +simulation run, the same constant (but random) value will be used every +time the assignment is executed. All variables, depending on --x-initial setting, are typically randomly initialized using a function. By running several random simulation runs @@ -4147,7 +4165,7 @@ simulators. Warns that a backslash is followed by a space then a newline. Likely the intent was to have a backslash directly followed by a newline (e.g. when -making a `define) and there's accidentally whitespace at the end of the +making a `define) and there's accidentally white space at the end of the line. If the space is not accidental, suggest removing the backslash in the code as it serves no function. @@ -5547,6 +5565,7 @@ released as Creative Commons Public Domain (CC0). Many example files and test files are likewise released under CC0 into effectively the Public Domain as described in the files themselves. + =head1 SEE ALSO L, L, L, L,