Commentary

bin/verilator

@@ -1734,7 +1734,7 @@ Verilator RPM as the hardcoded value should be correct.
 =head1 CONNECTING TO C++
 
 Verilator creates a .h and .cpp file for the top level module and all
-modules under it.  See the test_c directory in the kit for an example.
+modules under it.  See the examples directory in the kit for examples.
 
 After the modules are completed, there will be a I<module>.mk file that may
 be used with Make to produce a I<module>__ALL.a file with all required
@@ -3651,24 +3651,24 @@ program above:
 
 =item Does it run under Windows?
 
-Yes, using Cygwin.  Verilated output should also compile under Microsoft
-Visual C++ Version 7 or newer, but this is not tested by the author.
+Yes, using Cygwin.  Verilated output also compiles under Microsoft Visual
+C++ Version 7 or newer, but this is not tested every release.
 
 =item Can you provide binaries?
 
-Verilator is available as a RPM for SuSE, Fedora, and perhaps other
-systems; this is done by porters and may slightly lag the primary
-distribution.  If there isn't a binary build for your distribution, how
-about you set one up?  Please contact the authors for assistance.
+Verilator is available as a RPM for Debian/Ubuntu, SuSE, Fedora, and
+perhaps other systems; this is done by porters and may slightly lag the
+primary distribution.  If there isn't a binary build for your distribution,
+how about you set one up?  Please contact the authors for assistance.
 
 Note people sometimes request binaries when they are having problems with
 their C++ compiler. Alas, binaries won't help this, as in the end a fully
 working C++ compiler is required to compile the output of Verilator.
 
-=item How can it be faster than (name-the-simulator)?
+=item How can it be faster than (name-the-commercial-simulator)?
 
-Generally, the implied part of the question is "... with all of their
-manpower they can put into it."
+Generally, the implied part is of the question is "... with all of the
+manpower they can put into developing it."
 
 Most commercial simulators have to be Verilog compliant, meaning event
 driven.  This prevents them from being able to reorder blocks and make
@@ -3701,17 +3701,18 @@ source code available.
 As is standard with Open Source, contributions back to Verilator will be
 placed under the Verilator copyright and LGPL/Artistic license.  Small test
 cases will be released into the public domain so they can be used anywhere,
-large tests under the LGPL/Artistic, unless requested otherwise.
+and large tests under the LGPL/Artistic, unless requested otherwise.
 
 =item Why is Verilation so slow?
 
 Verilator needs more memory than the resulting simulator will require, as
-Verilator creates internally all of the state of the resulting simulator in
-order to optimize it.  If it takes more than a minute or so (and you're not
-using --debug since debug is disk bound), see if your machine is paging;
-most likely you need to run it on a machine with more memory.  Verilator is
-a full 64-bit application and may use more than 4GB, but about 1GB is the
-maximum typically needed.
+Verilator creates internally all of the state of the resulting generated
+simulator in order to optimize it.  If it takes more than a minute or so
+(and you're not using --debug since debug is disk bound), see if your
+machine is paging; most likely you need to run it on a machine with more
+memory.  Verilator is a full 64-bit application and may use more than 4GB,
+but about 1GB is the maximum typically needed, and very large commercial
+designs have topped 16GB.
 
 =item How do I generate waveforms (traces) in C++?
 
@@ -3721,7 +3722,7 @@ Add the --trace switch to Verilator, and in your top level C code, call
 Verilated::traceEverOn(true).  Then create a VerilatedVcdC object, and
 in your main loop call "trace_object->dump(time)" every time step, and
 finally call "trace_object->close()".  For an example, see below and the
-test_c/sim_main.cpp file of the distribution.
+examples/tracing_c/sim_main.cpp file of the distribution.
 
 You also need to compile verilated_vcd_c.cpp and add it to your link,
 preferably by adding the dependencies in $(VK_GLOBAL_OBJS) to your
@@ -3747,15 +3748,13 @@ trace file if you want all data to land in the same output file.
         tfp->close();
     }
 
-Also see the examples/tracing_cc directory in the distribution.
-
 =item How do I generate waveforms (traces) in SystemC?
 
 Add the --trace switch to Verilator, and in your top level C sc_main code,
 include verilated_vcd_sc.h.  Then call Verilated::traceEverOn(true).  Then
 create a VerilatedVcdSc object as you would create a normal SystemC trace
 file.  For an example, see the call to VerilatedVcdSc in the
-test_sc/sc_main.cpp file of the distribution, and below.
+examples/tracing_sc/sc_main.cpp file of the distribution, and below.
 
 Alternatively you may use the C++ trace mechanism described in the previous
 question, however the timescale and timeprecision will not inherited from
@@ -3783,8 +3782,6 @@ trace file if you want all data to land in the same output file.
         tfp->close();
     }
 
-Also see the examples/tracing_cc directory in the distribution.
-
 =item How do I view waveforms (traces)?
 
 Verilator makes standard VCD (Value Change Dump) files.  They are viewable
@@ -3803,8 +3800,8 @@ want to trace (such as perhaps library cells).  Finally, use the
 --trace-depth option to limit the depth of tracing, for example
 --trace-depth 1 to see only the top level signals.
 
-Also be sure you write your trace files to a local disk, instead of to a
-network disk.  Network disks are generally far slower.
+Also be sure you write your trace files to a local solid-state disk,
+instead of to a network disk.  Network disks are generally far slower.
 
 =item How do I do coverage analysis?
 
@@ -3826,7 +3823,7 @@ Verilator_coverage reads the logs/coverage.pl file(s), and creates an
 annotated source code listing showing code coverage details.
 
 For an example, after running 'make test' in the Verilator distribution,
-see the test_sc/logs directory.  Grep for lines starting
+see the examples/tracing_c/logs directory.  Grep for lines starting
 with '%' to see what lines Verilator believes need more coverage.
 
 =item Where is the translate_off command?  (How do I ignore a construct?)
@@ -3840,6 +3837,8 @@ the "VERILATOR" define for you, so just wrap the code in an ifndef region:
       Something_Verilator_Dislikes;
    `endif
 
+Most synthesis tools similarly define SYNTHESIS for you.
+
 =item Why do I get "unexpected `do'" or "unexpected `bit'" errors?
 
 Do, bit, ref, return, and other words are now SystemVerilog keywords.  You
@@ -3876,7 +3875,7 @@ simulator knows the current time.  See the "CONNECTING TO C++" examples.
 You need to link your compiled Verilated code against the verilated.cpp
 file found in the include directory of the Verilator kit.  This is one
 target in the $(VK_GLOBAL_OBJS) make variable, which should be part of your
-Makefile's link rule.
+Makefile's link rule.  If you use --exe, this is done for you.
 
 =item Is the PLI supported?
 
@@ -3898,13 +3897,14 @@ test_regress/t/t_extend_class files show an example of how to do this.
 
 =item How do I get faster build times?
 
-Between GCC 3.0 to 3.3, each compiled progressively slower, thus if you can
-use GCC 2.95, or GCC 3.4 you'll have faster builds.  Two ways to cheat are
-to compile on parallel machines and avoid compilations altogether.  See the
---output-split option, and the web for the ccache, distcc and icecream
-packages. ccache will skip GCC runs between identical source builds, even
-across different users.  You can use the OBJCACHE environment variable to
-use these CC wrappers.
+Use a recent compiler.  Newer compilers tend do be faster, with the
+now relatively old GCC 3.0 to 3.3 being horrible.
+
+Compile in parallel on many machines and use caching; see the web for the
+ccache, distcc and icecream packages. ccache will skip GCC runs between
+identical source builds, even across different users.  You can use the
+OBJCACHE environment variable to use these CC wrappers. Also see the
+--output-split option.
 
 To reduce the compile time of classes that use a Verilated module (e.g. a
 top CPP file) you may wish to add /*verilator no_inline_module*/ to your
@@ -4050,7 +4050,7 @@ License.)
 In 2001, Wilson Snyder took the kit, and added a SystemC mode, and
 called it Verilator2.  This was the first packaged public release.
 
-In 2002, Wilson Snyder created Verilator3 by rewriting Verilator from
+In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator from
 scratch in C++.  This added many optimizations, yielding about a 2-5x
 performance gain.
 
@@ -4082,50 +4082,59 @@ Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus Networks Inc.,
 and SiCortex Inc.
 
 The people who have contributed major functionality are Byron Bradley,
-Jeremy Bennett, Jie Xu, Lane Brooks, Duane Galbi, Paul Wasson, and Wilson
-Snyder.  Major testers include Jeff Dutton, Jonathon Donaldson, Ralf Karge,
-David Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov, Sebastien Van
-Cauwenberghe, Gene Weber, and Clifford Wolf.
+Jeremy Bennett, Jie Xu, Lane Brooks, John Coiner, Duane Galbi, Paul Wasson,
+and Wilson Snyder.  Major testers included Jeff Dutton, Jonathon Donaldson,
+Ralf Karge, David Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov,
+Sebastien Van Cauwenberghe, Gene Weber, and Clifford Wolf.
 
 Some of the people who have provided ideas and feedback for Verilator
-include: Yves Mathieu, David Addison, Nikana Anastasiadis, Hans Van
-Antwerpen, Vasu Arasanipalai, Jens Arm, Sharad Bagri, Andrew Bardsley,
-Geoff Barrett, J Baxter, Julius Baxter, Jeremy Bennett, Michael Berman,
-David Binderman, David Black, Daniel Bone, Gregg Bouchard, Christopher
-Boumenot, Nick Bowler, Byron Bradley, Bryan Brady, Charlie Brej, Lane
-Brooks, John Brownlee, Jeff Bush, Lawrence Butcher, Ted Campbell, Chris
-Candler, Lauren Carlson, Donal Casey, Terry Chen, Robert A. Clark, Allan
-Cochrane, Gunter Dannoritzer, Ashutosh Das, Bernard Deadman, Mike Denio,
-John Deroo, Philip Derrick, John Dickol, R. Diez, Ruben Diez, Danny Ding,
-Ivan Djordjevic, Jonathon Donaldson, Alex Duller, Jeff Dutton, Chandan
-Egbert, Joe Eiler, Ahmed El-Mahmoudy, Robert Farrell, Eugen Fekete,
-Fabrizio Ferrandi, Andrea Foletto, Bob Fredieu, Christian Gelinek, Glen
-Gibb, Shankar Giri, Sam Gladstone, Amir Gonnen, Chitlesh Goorah, Neil
-Hamilton, Junji Hashimoto, Thomas Hawkins, David Hewson, Hiroki Honda, Alex
-Hornung, Jae Hossell, Ben Jackson, Krzysztof Jankowski, HyungKi Jeong,
-Iztok Jeras, James Johnson, Christophe Joly, Franck Jullien, Mike Kagen,
-Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi, Patricio Kaplan, Ralf
-Karge, Dan Katz, Sol Katzman, Jonathan Kimmitt, Sobhan Klnv, Gernot Koch,
-Soon Koh, Steve Kolecki, Brett Koonce, Wojciech Koszek, Varun Koyyalagunta,
-David Kravitz, Roland Kruse, Ed Lander, Steve Lang, Stephane Laurent,
-Walter Lavino, Christian Leber, Igor Lesik, John Li, Eivind Liland, Charlie
-Lind, Andrew Ling, Paul Liu, Derek Lockhart, Arthur Low, Stefan Ludwig, Dan
-Lussier, Fred Ma, Duraid Madina, Mark Marshall, Jason McMullan, Wim
-Michiels, Wai Sum Mong, Sean Moore, Dennis Muhlestein, John Murphy, Richard
-Myers, Dimitris Nalbantis, Bob Newgard, Cong Van Nguyen, Paul Nitza, Pete
-Nixon, Lisa Noack, Mark Nodine, Andreas Olofsson, Brad Parker, David
-Pierce, Dominic Plunkett, David Poole, Rich Porter, Niranjan Prabhu, Usha
-Priyadharshini, Mark Jackson Pulver, Prateek Puri, Chris Randall, Frederic
-Requin, Alberto Del Rio, Oleg Rodionov, Jan Egil Ruud, John Sanguinetti,
-Salman Sheikh, Mike Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Rodney
-Sinclair, Steven Slatter, Brian Small, Wilson Snyder, Alex Solomatnikov,
-Art Stamness, John Stevenson, Todd Strader, John Stroebel, Emerson
+include: Ahmed El-Mahmoudy, David Addison, Tariq B. Ahmad, Nikana
+Anastasiadis, Hans Van Antwerpen, Vasu Arasanipalai, Jens Arm, Sharad
+Bagri, Andrew Bardsley, Matthew Barr, Geoff Barrett, Julius Baxter, Jeremy
+Bennett, Michael Berman, David Binderman, Johan Bjork, David Black, Daniel
+Bone, Gregg Bouchard, Christopher Boumenot, Nick Bowler, Byron Bradley,
+Bryan Brady, Charlie Brej, J Briquet, Lane Brooks, John Brownlee, Jeff
+Bush, Lawrence Butcher, Ted Campbell, Chris Candler, Lauren Carlson, Donal
+Casey, Terry Chen, Enzo Chi, Robert A. Clark, Allan Cochrane, John Coiner,
+Gunter Dannoritzer, Ashutosh Das, Bernard Deadman, John Demme, Mike Denio,
+John Deroo, Philip Derrick, John Dickol, Ruben Diez, Danny Ding, Ivan
+Djordjevic, Jonathon Donaldson, Sebastian Dressler, Alex Duller, Jeff
+Dutton, Usuario Eda, Chandan Egbert, Joe Eiler, Ahmed El-Mahmoudy, Robert
+Farrell, Eugen Fekete, Fabrizio Ferrandi, Brian Flachs, Andrea Foletto, Bob
+Fredieu, Christian Gelinek, Glen Gibb, Shankar Giri, Dan Gisselquist, Sam
+Gladstone, Amir Gonnen, Chitlesh Goorah, Xuan Guo, Neil Hamilton, Jannis
+Harder, Junji Hashimoto, Thomas Hawkins, Robert Henry, David Hewson, Jamey
+Hicks, Hiroki Honda, Alex Hornung, David Horton, Jae Hossell, Alan Hunter,
+Jamie Iles, Ben Jackson, Shareef Jalloq, Krzysztof Jankowski, HyungKi
+Jeong, Iztok Jeras, James Johnson, Christophe Joly, Franck Jullien, Mike
+Kagen, Arthur Kahlich, Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi,
+Patricio Kaplan, Ralf Karge, Dan Katz, Sol Katzman, Jonathan Kimmitt, Olof
+Kindgren, Sobhan Klnv, Gernot Koch, Soon Koh, Steve Kolecki, Brett Koonce,
+Wojciech Koszek, Varun Koyyalagunta, David Kravitz, Roland Kruse, Sergey
+Kvachonok, Ed Lander, Steve Lang, Stephane Laurent, Walter Lavino,
+Christian Leber, Igor Lesik, John Li, Eivind Liland, Charlie Lind, Andrew
+Ling, Paul Liu, Derek Lockhart, Arthur Low, Stefan Ludwig, Dan Lussier,
+Fred Ma, Duraid Madina, Mark Marshall, Alfonso Martinez, Yves Mathieu,
+Patrick Maupin, Jason McMullan, Elliot Mednick, Wim Michiels, Miodrag
+Milanovic, Wai Sum Mong, Sean Moore, Dennis Muhlestein, John Murphy,
+Richard Myers, Dimitris Nalbantis, Bob Newgard, Cong Van Nguyen, Paul
+Nitza, Pete Nixon, Lisa Noack, Mark Nodine, Andreas Olofsson, James
+Pallister, Brad Parker, Maciej Piechotka, David Pierce, Dominic Plunkett,
+David Poole, Mike Popoloski, Rich Porter, Niranjan Prabhu, Usha
+Priyadharshini, Mark Jackson Pulver, Prateek Puri, Chris Randall, Anton
+Rapp, Odd Magne Reitan, Frederic Requin, Alberto Del Rio, Oleg Rodionov,
+Paul Rolfe, Jan Egil Ruud, John Sanguinetti, Galen Seitz, Salman Sheikh,
+Mike Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Rodney Sinclair, Steven
+Slatter, Brian Small, Alex Solomatnikov, Wei Song, Art Stamness, John
+Stevenson, Rob Stoddard, Todd Strader, John Stroebel, Sven Stucki, Emerson
 Suguimoto, Gene Sullivan, Renga Sundararajan, Yutetsu Takatsukasa, Peter
-Tengstrand, Stefan Thiede, Gary Thomas, Kevin Thompson, Mike Thyer, Steve
-Tong, Holger Waechtler, Stefan Wallentowitz, Shawn Wang, Greg Waters,
-Thomas Watts, Eugene Weber, David Welch, Leon Wildman, Gerald Williams,
-Trevor Williams, Jeff Winston, Joshua Wise, Clifford Wolf, Johan Wouters,
-Ding Xiaoliang, Jie Xu, and Amir Yazdanbakhsh.
+Tengstrand, Wesley Terpstra, Stefan Thiede, Gary Thomas, Kevin Thompson,
+Ian Thompson, Mike Thyer, Hans Tichelaar, Steve Tong, Michael Tresidder,
+Holger Waechtler, Stefan Wallentowitz, Shawn Wang, Greg Waters, Thomas
+Watts, Eugene Weber, David Welch, Thomas J Whatson, Leon Wildman, Gerald
+Williams, Trevor Williams, Jeff Winston, Joshua Wise, Clifford Wolf, Johan
+Wouters, Ding Xiaoliang, Jie Xu, Mandy Xu, Luke Yang, and Amir
+Yazdanbakhsh.
 
 Thanks to them, and all those we've missed including above.