From 9309d0b00feaa8fabc2e3f22499b1de2d8847679 Mon Sep 17 00:00:00 2001 From: Jeremy Bennett Date: Sat, 25 Aug 2012 12:47:59 -0400 Subject: [PATCH] Commentary on internals.pod, bug554. Signed-off-by: Wilson Snyder --- internals.pod | 205 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 170 insertions(+), 35 deletions(-) diff --git a/internals.pod b/internals.pod index 0773a7543..d91480fec 100644 --- a/internals.pod +++ b/internals.pod @@ -14,32 +14,6 @@ the first for reference for developers and debugging problems. See also the Verilator internals presentation at http://www.veripool.org. -=head1 ADDING A NEW FEATURE - -Generally what would you do to add a new feature? - -=over 4 - -File a bug (if there isn't already) so others know what you're working on. - -Make a testcase in the test_regress/t/t_EXAMPLE format, see TESTING Below. - -If grammar changes are needed, look at the git version of VerilogPerl's -src/VParseGrammar.y, as this grammar supports the full SystemVerilog -language and has a lot of back-and-forth with Verilator's grammar. Copy -the appropriate rules to src/verilog.y and modify the productions. - -If a new Ast type is needed, add it to V3AstNodes.h. - -Now you can run "test_regress/t/t_{new testcase}.pl --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 below on debugging. - -Modify the later visitor functions to process the new feature as needed. - -=back - =head1 CODE FLOWS =head2 Verilator Flow @@ -93,6 +67,10 @@ Verilator finally writes the C++ modules. =head2 Key Classes Used in the Verilator Flow +=over 4 + +=item C + The AST is represented at the top level by the class C. This abstract class has derived classes for the individual components (e.g. C for a generate block) or groups of components (e.g. C for @@ -119,11 +97,64 @@ are at the top of the tree. By convention, each function/method uses the variable C as a pointer to the C currently being processed. +=item C + The passes are implemented by AST visitor classes (see L). These are implemented by subclasses of the abstract class, C. Each pass creates an instance of the visitor class, which in turn implements a method to perform the pass. +=item C + +A number of passes use graph algorithms, and the class C is provided +to represent those graphs. Graphs are directed, and algorithms are provided to +manipulate the graphs and to output them in I dot format (see +L). C provides documentation of this +class. + +=item C + +This is the base class for vertices in a graph. Vertices have an associated +C, C and C, which may be used in algorithms for ordering +the graph. A generic C/C member variable is also provided. + +Virtual methods are provided to specify the name, color, shape and style to be +used in dot output. Typically users provided derived classes from +C which will reimplement these methods. + +Iterators are provided to access in and out edges. Typically these are used in +the form: + + for (V3GraphEdge *edgep = vertexp->inBeginp(); + edgep; + edgep = edgep->inNextp()) { + +=item C + +This is the base class for directed edges between pairs of vertices. Edges +have an associated C and may also be made C. A generic +C/C member variable is also provided. + +Accessors, C and C return the "from" and "to" vertices +respectively. + +Virtual methods are provided to specify the label, color and style to be +used in dot output. Typically users provided derived classes from +C which will reimplement these methods. + +=item C + +This is the base class for graph algorithms. It implements a C method, +C which algorithms can use to decide whether an edge is +followed. This method returns true if the graph edge has weight greater than +one and a user function, C (supplied in the constructor) returns +C. + +A number of predefined derived algorithm classes and access methods are +provided and documented in C. + +=back + =head2 Verilated Flow The evaluation loop outputted by Verilator is designed to allow a single @@ -178,16 +209,15 @@ TREEOP macro. The original C++ source code is transformed into C++ code in the C and C sub-directories (the former for the optimized version of -verilator, the latter for the debug version). So for example C +Verilator, the latter for the debug version). So for example C into C. =head2 Visitor Functions -The verilator uses the I design pattern to implement its -refinement and optimization passes. This allows separation of the pass -algorithm from the AST on which it operates. Wikipedia provides an -introduction to the concept at -L. +Verilator uses the I design pattern to implement its refinement +and optimization passes. This allows separation of the pass algorithm from +the AST on which it operates. Wikipedia provides an introduction to the +concept at L. As noted above, all visitors are derived classes of C. All derived classes of C implement the C method, which takes @@ -339,7 +369,68 @@ AST. To write a test see the BUGS section of the Verilator primary manual, and the documentation in: - test_regress/t/driver.pl --help + test_regress/t/driver.pl --help + +Developers will also want to configure with two extra flags: + +=over 4 + +=item --enable-ccwarn + +Causes the build to stop on warnings as well as errors. A good way to +ensure no sloppy code gets added, however it can be painful when it comes +to testing, since third party code used in the tests (e.g. SystemC) may not +be warning free. + +=item --enable-long-tests + +In addition to the standard C, SystemC and SystemPerl tests also run the +tests in the C, C and C directories +when using I. This is disabled by default as SystemC/SystemPerl +installation problems would otherwise falsely indicate a Verilator problem. + +=back + +When enabling the long tests, some additional PERL modules are needed, which +you can install using cpan. + + cpan install Unix::Processors + +There are some traps to avoid when running regression tests + +=over 4 + +=item * + +The regression tests will assume that you have a version of SystemPerl to +match. Typically if working on Verilator from git, also use SystemPerl from +git. + +=item * + +When checking the MANIFEST, the test will barf on unexpected code in the +Verilator tree. So make sure to keep any such code outside the tree. + +=item * + +Not all Linux systems install Perldoc by default. This is needed for the +I<--help> option to Verilator, and also for regression testing. This can be +installed using cpan: + + cpan install Pod::Perldoc + +Many Linux systems also offer a standard package for this. Red +Hat/Fedora/Centos offer I, while Debian/Ubuntu/Linux Mint +offer I. + +=item * + +Running regression may exhaust resources on some Linux systems, particularly +file handles and user processes. Increase these to respectively 16,384 and +4,096. The method of doing this is system dependent, but on Fedora Linux it +would require editing the C file as root. + +=back =head1 DEBUGGING @@ -442,7 +533,7 @@ Of the form C<< >> or C<< >> , where C is the number of the last edit to modify this node. The trailing C<#> indicates the node has been edited since the last tree dump (which typically means in the last refinement or optimization pass). GDB can watch for this, see L below. +with GDB>. =item Source file and line @@ -501,7 +592,7 @@ under gdb and break when an error is hit or the program is about to exit. You can also use --debug --gdbbt to just backtrace and then exit gdb. To debug the Verilated executable, use --gdbsim. -If you wish to start verilator under GDB (or another debugger), then you +If you wish to start Verilator under GDB (or another debugger), then you can use --debug and look at the underlying invocation of verilator_dgb. For example @@ -551,6 +642,50 @@ backtrace. You will typically see a frame sequence something like visit() ... +=head1 ADDING A NEW FEATURE + +Generally what would you do to add a new feature? + +=over 4 + +=item 1. + +File a bug (if there isn't already) so others know what you're working on. + +=item 2. + +Make a testcase in the test_regress/t/t_EXAMPLE format, see L. + +=item 3. + +If grammar changes are needed, look at the git version of VerilogPerl's +src/VParseGrammar.y, as this grammar supports the full SystemVerilog +language and has a lot of back-and-forth with Verilator's grammar. Copy +the appropriate rules to src/verilog.y and modify the productions. + +=item 4. + +If a new Ast type is needed, add it to V3AstNodes.h. + +=back + +Now you can run "test_regress/t/t_{new testcase}.pl --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. + +Modify the later visitor functions to process the new feature as needed. + +=head2 Adding a new pass + +For more substantial changes you may need to add a new pass. The simplest way +to do this is to copy the C<.cpp> and C<.h> files from an existing +pass. You'll need to add a call into your pass from the C function +in C. + +To get your pass to build you'll need to add its binary filename to the list +in C and reconfigure. + =head1 DISTRIBUTION The latest version is available from L.