From cae6ec16ba1a6f489a2f586196a277ddc69bfe4b Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Sat, 26 Apr 2014 13:59:50 -0400 Subject: [PATCH] Commentary --- bin/verilator | 10 +++++----- internals.pod | 39 +++++++++++++++++++++++++++++++++++---- 2 files changed, 40 insertions(+), 9 deletions(-) diff --git a/bin/verilator b/bin/verilator index 0b8d0801c..099d3bac7 100755 --- a/bin/verilator +++ b/bin/verilator @@ -628,7 +628,7 @@ large and not desired. =item --dump-treei Rarely needed. Enable writing .tree debug files with a specific dumping -level, 0 disbles dumps and is equivelent to "--no-dump-tree". Level 9 +level, 0 disbles dumps and is equivalent to "--no-dump-tree". Level 9 enables dumping of every stage. =item -E @@ -921,7 +921,7 @@ break the loop. In addition produces a GraphViz DOT file of the entire strongly connected components within the source associated with each loop. This is produced irrespective of whether --dump-tree is set. Such graphs may help in -analysing the problem, but can be very large indeed. +analyzing the problem, but can be very large indeed. Various commands exist for viewing and manipulating DOT files. For example the I command can be used to convert a DOT file to a PDF for @@ -1187,7 +1187,7 @@ so the above C block would not trigger. While it is not good practice, there are some designs that rely on X E 0 triggering a C, particularly in reset sequences. Using ---x-initial-edge with Verilator will replicate this behaviour. It will also +--x-initial-edge with Verilator will replicate this behavior. It will also ensure that X E 1 triggers a C. B Some users have reported that using this option can affect @@ -1972,7 +1972,7 @@ please file a bug if a feature you need is missing. Verilator implements a very small subset of Verilog AMS (Verilog Analog and Mixed-Signal Extensions) with the subset corresponding to those VMS -keywords with near equivelents in the Verilog 2005 or SystemVerilog 2009 +keywords with near equivalents in the Verilog 2005 or SystemVerilog 2009 languages. AMS parsing is enabled with "--language VAMS" or "--language 1800+VAMS". @@ -2432,7 +2432,7 @@ reset works. (Note this is what the hardware will really do.) In practice, just setting all variables to one at startup finds most problems. B --x-assign applies to variables explicitly initialized or assigned to -X. Unititialized clocks are initialized to zero, while all other state holding +X. Uninitialized clocks are initialized to zero, while all other state holding variables are initialized to a random value. Event driven simulators will generally trigger an edge on a transition from X diff --git a/internals.pod b/internals.pod index 77f5c800e..1a458ba55 100644 --- a/internals.pod +++ b/internals.pod @@ -341,6 +341,37 @@ C in turn. =back +=head3 Caution on Using Iterators When Child Changes + +Visitors often replace one node with another node; V3Width and V3Const are +major examples. A visitor which is the parent of such a replacement needs +to be aware that calling iteration may cause the children to change. For +example: + + // nodep->lhsp() is 0x1234000 + nodep->lhsp()->iterateAndNext(...); // and under covers nodep->lhsp() changes + // nodep->lhsp() is 0x5678400 + nodep->lhsp()->iterateAndNext(...); + +Will work fine, as even if the first iterate causes a new node to take the +place of the lhsp(), that edit will update nodep->lhsp() and the second +call will correctly see the change. Alternatively: + + lp = nodep->lhsp(); + // nodep->lhsp() is 0x1234000, lp is 0x1234000 + lp->iterateAndNext(...); **lhsp=NULL;** // and under covers nodep->lhsp() changes + // nodep->lhsp() is 0x5678400, lp is 0x1234000 + lp->iterateAndNext(...); + +This will cause bugs or a core dump, as lp is a dangling pointer. Thus it +is advisable to set lhsp=NULL shown in the *'s above to make sure these +dangles are avoided. Another alternative used in special cases mostly in +V3Width is to use acceptSubtreeReturnEdits, which operates on a single node +and returns the new pointer if any. Note acceptSubtreeReturnEdits does not +follow nextp() links. + + lp = lp->acceptSubtreeReturnEdits() + =head2 Identifying derived classes A common requirement is to identify the specific C class we are @@ -372,7 +403,7 @@ Verilator primary manual. It is important to add tests for failures as well as success (for example to check that an error message is correctly triggered). -Tests that fail should by convenition have the suffix C<_bad> in their name, +Tests that fail should by convention have the suffix C<_bad> in their name, and include C 1> in either their C or C step as appropriate. @@ -388,7 +419,7 @@ For convenience, a summary of the most commonly used features is provided here. All drivers require a call to C subroutine to compile the test. For run-time tests, this is followed by a call to the C subroutine. Both of these functions can optionally be provided with a hash -table as argument specifying additonal options. +table as argument specifying additional options. The test driver assumes by default that the source Verilog file name matches the PERL driver name. So a test whose driver is C @@ -608,8 +639,8 @@ Shows the value of the node's user1p...user5p, if non-NULL. Many nodes have an explicit data type. "@dt=0x..." indicates the address of the data type (AstNodeDType) this node uses. -If a data type is present and is numberic, it then prints the width of the -item. This field is a squence of flag characters and width data as follows: +If a data type is present and is numeric, it then prints the width of the +item. This field is a sequence of flag characters and width data as follows: C if the node is signed.