From 3236607be4a2af2c3315097414488e4fd6351afe Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Tue, 3 Nov 2009 09:22:47 -0500 Subject: [PATCH] Convert README to POD format, and add internals.txt readme --- .gitignore | 5 +- Makefile.in | 26 ++++---- TODO | 20 ------ bin/verilator | 2 + internals.pod | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++ readme.pod | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 346 insertions(+), 35 deletions(-) create mode 100644 internals.pod create mode 100644 readme.pod diff --git a/.gitignore b/.gitignore index e8d2525d8..fdc4102ff 100644 --- a/.gitignore +++ b/.gitignore @@ -10,12 +10,13 @@ *.tex /Makefile README +autom4te.cache config.cache config.status configure dddrun* gdbrun* -verilator.txt +internals.txt verilator.pdf +verilator.txt verilator_bin* -autom4te.cache diff --git a/Makefile.in b/Makefile.in index 6125101ac..1446e3642 100644 --- a/Makefile.in +++ b/Makefile.in @@ -58,7 +58,7 @@ INSTALL = @INSTALL@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_DATA = @INSTALL_DATA@ MAKEINFO = makeinfo -TEXI2DVI = texi2dvi +POD2TEXT = pod2text PERL = @PERL@ # Destination prefix for RPMs @@ -97,7 +97,7 @@ SHELL = /bin/sh SUBDIRS = src test_verilated test_c test_sc test_sp test_regress test_vcs -INFOS = README verilator.txt verilator.html verilator.1 verilator.pdf +INFOS = README internals.txt verilator.txt verilator.html verilator.1 verilator.pdf # Files that can be generated, but should be up to date for a distribution. DISTDEP = info Makefile @@ -106,10 +106,10 @@ DISTBIN = $(wildcard bin/verilator-*) DISTFILES_INC = $(INFOS) .gitignore Artistic COPYING COPYING.LESSER \ *.in *.ac \ - Changes README TODO \ + Changes TODO \ MANIFEST.SKIP \ bin/* \ - install-sh configure mkinstalldirs *.texi \ + install-sh configure mkinstalldirs *.pod \ include/verilated*.[chv]* \ include/*.in \ include/.*ignore \ @@ -207,7 +207,7 @@ verilator.1: bin/verilator pod2man $< $@ verilator.txt: bin/verilator - pod2text $< $@ + $(POD2TEXT) $< $@ verilator.html: bin/verilator pod2html $< >$@ @@ -228,13 +228,13 @@ verilator.pdf: bin/verilator $(DISTCONFIG) pdflatex verilator.tex -rm -f verilator.toc verilator.aux verilator.idx verilator.out -INSTALL: install.texi - $(MAKEINFO) -I$(srcdir) $(srcdir)/install.texi --output=$@ \ - --no-headers --no-validate +README: readme.pod + -rm -f $@ + $(POD2TEXT) --loose $< > $@ -README: readme.texi - $(MAKEINFO) -I$(srcdir) $(srcdir)/readme.texi --output=$@ \ - --no-headers --no-validate +internals.txt: internals.pod + -rm -f $@ + $(POD2TEXT) --loose $< > $@ # See uninstall also VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg \ @@ -337,7 +337,7 @@ configure: configure.ac maintainer-clean:: @echo "This command is intended for maintainers to use;" @echo "rebuilding the deleted files requires makeinfo." - rm -f *.info* $(INFOS) faq.html verilator.html configure + rm -f *.info* $(INFOS) configure clean mostlyclean distclean maintainer-clean maintainer-copy:: for dir in $(SUBDIRS); do \ @@ -357,7 +357,7 @@ distclean maintainer-clean:: rm -f include/verilated.mk TAGFILES=${srcdir}/*/*.cpp ${srcdir}/*/*.h ${srcdir}/*/[a-z]*.in \ - ${srcdir}/[a-z]*.in ${srcdir}/*.texi + ${srcdir}/[a-z]*.in ${srcdir}/*.pod TAGS: $(TAGFILES) etags $(TAGFILES) diff --git a/TODO b/TODO index 5fa09fbe2..77528bbdb 100644 --- a/TODO +++ b/TODO @@ -7,11 +7,8 @@ Features: - Finish 3.400 new ordering fixes Latch optimizations {Need here} Task I/Os connecting to non-simple variables. - Fix nested casez statements expanding into to huge C++. [JeanPaul Vanitegem] - Fix FileLine memory inefficiency Fix ordering of each bit separately in a signal (mips) assign b[3:0] = b[7:4]; assign b[7:4] = in; Support gate primitives/ cell libraries from xilinx, etc @@ -20,8 +17,6 @@ Features: Support generated clocks (correctness) ?gcov coverage Selectable SystemC types based on widths (see notes below) - Compile time - Inline first level trace routines Coverage Points should be per-scope like everything else rather then per-module Expression coverage (see notes) @@ -39,7 +34,6 @@ Long-term Features Tristate support SystemPerl integration Multithreaded execution - Front end parser integration into Verilog-Perl like Netlist Testing: Capture all inputs into global "rerun it" file @@ -115,20 +109,6 @@ Performance: the space. This will greatly reduce the data footprint. -//********************************************************************** -//* Detailed notes on 'todo' features - -Selectable SystemC types based on widths (see notes below) - Statements: - verilator sc_type uint32_t {override specific I/O signals} - verilator sc_typedef width 1 bool - verilator sc_typedef width 2-32 uint32_t - verilator sc_typedef width 33-64 uint64_t - verilator sc_typedef width 65+ sc_bv //<< programmable width - Replace `systemc_clock, --pins64 - Have accessor function with type overloading to get or set the pin value. - (Get rid of getdatap mess?) - //********************************************************************** //* Eventual tristate bus Stuff allowed (old verilator) diff --git a/bin/verilator b/bin/verilator index 265240e99..8a42d7de7 100755 --- a/bin/verilator +++ b/bin/verilator @@ -2668,6 +2668,8 @@ Major concepts by Paul Wasson and Duane Galbi. L, L, L, L +And verilator_internals.txt in the distribution. + =cut ###################################################################### diff --git a/internals.pod b/internals.pod new file mode 100644 index 000000000..a3af3a9ae --- /dev/null +++ b/internals.pod @@ -0,0 +1,164 @@ +# DESCRIPTION: DOCUMENT source run through perl to produce internals.txt file +# Use 'make internals.txt' to produce the output file + +=pod + +=head1 NAME + +Verilator Internals + +=head1 INTRODUCTION + +This file discusses internal and programming details for Verilator. It's +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, there's notes on +this in the forum and in the verilator.txt manual. + +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 DEBUG OUTPUT/ TREE FILES + +When you run with --debug there are two primary output file types placed into +the obj_dir, .tree and .dot files. + +=head2 .dot output + +Dot files are dumps of internal graphs in Graphviz +L dot format. When a dot file is dumped, +Verilator will also print a line on stdout that can be used to format the +output, for example: + + dot -Tps -o ~/a.ps obj_dir/Vtop_foo.dot + +You can then print a.ps. You may prefer gif format, which doesn't get +scaled so can be more useful with large graphs. + +For dynamic graph viewing consider ZGRViewer +L. If you know of better +viewers let us know; ZGRViewer isn't great for large graphs. + +=head2 .tree output + +Tree files are dumps of the AST Tree and are produced between every major +algorithmic stage. An example: + + NETLIST 0x90fb00 {0} w0 + 1: MODULE 0x912b20 {8} w0 top L2 [P] + *1:2: VAR 0x91a780 {22} w70 out_wide [O] WIRE + 1:2:1: BASICDTYPE 0x91a3c0 {22} w70 [logic] + +=over 4 + +"1:2:" indicates the hiearchy the VAR is op2p under the MODULE. + +"VAR" is the AstNodeType. + +"0x91a780" is the address of this node. + +"" means the 74th edit to the netlist was the last modification to +this node. A trailing # indicates this node changed since the last tree +dump was made. You can gdb break on this edit; see below. + +"{22}" indicates this node is related to line 22 in the source. + +"w70" indicates the width is 70 bits. sw70 would be signed 70 bits. + +"out_wide" is the name of the node, in this case the name of the variable. + +"[O]" are flags which vary with the type of node, in this case it means the +variable is an output. + +=back + +=head1 VISITOR FUNCTIONS + +=head2 Passing Variables + +There's three ways data is passed between visitor functions. + +1. A visitor-class member variable. This is generally for passing "parent" +information down to children. m_modp is a common example. It's set to +NULL in the constructor, where that node (AstModule visitor) sets it, then +the children are iterated, then it's cleared. Children under an AstModule +will see it set, while nodes elsewhere will see it clear. If there can be +nested items (for example an AstFor under an AstFor) the variable needs to +be save-set-restored in the AstFor visitor, otherwise exiting the lower for +will loose the upper for's setting. + +2. User() attributes. Each node has 4 ->user() number or ->userp() pointer +utility values (a common technique lifted from graph traversal packages). +A visitor first clears the one it wants to use by calling +AstNode::user#ClearTree(), then it can mark any node's user() with whatever +data it wants. Readers just call nodep->user(), but may need to cast +appropriately, so you'll often see nodep->userp()->castSOMETYPE(). At the +top of each visitor are comments describing how the user() stuff applies to +that visitor class. For example: + + // NODE STATE + // Cleared entire netlist + // AstModule::user1p() // bool. True to inline this module + +This says that at the AstNetlist user1ClearTree() is called. Each +AstModule's is user1() is used to indicate if we're going to inline it. + +These comments are important to make sure a user#() on a given AstNode type +is never being used for two different purposes. + +Note that calling user#ClearTree is fast, it doesn't walk the tree, so it's +ok to call fairly often. For example, it's commonly called on every +module. + +3. Parameters can be passed between the visitors in close to the "normal" +function caller to callee way. This is the second "vup" parameter that is +ignored on most of the visitor functions. V3Width does this, but it proved +more messy than the above and is deprecated. (V3Width was nearly the first +module written. Someday this scheme may be removed, as it slows the +program down to have to pass vup everywhere.) + +=head1 DEBUGGING WITH GDB + +The test_regress/driver.pl script accepts --debug --gdb to start Verilator +under gdb. You can also use --debug --gdbbt to just backtrace and then +exit gdb. + +To break at a specific edit number which changed a node (presumably to find +what made a line in the tree dumps): + + watch AstNode::s_editCntGbl==#### + +=head1 DISTRIBUTION + +The latest version is available from L. + +Copyright 2008-2009 by Wilson Snyder. Verilator is free software; you can +redistribute it and/or modify it under the terms of either the GNU Lesser +General Public License Version 3 or the Perl Artistic License Version 2.0. + +=cut + +###################################################################### diff --git a/readme.pod b/readme.pod new file mode 100644 index 000000000..a320bf2e1 --- /dev/null +++ b/readme.pod @@ -0,0 +1,164 @@ +# DESCRIPTION: DOCUMENT source run through perl to produce README file +# Use 'make README' to produce the output file + +=pod + +=head1 NAME + +This is the Verilator Package README file. + +=head1 DISTRIBUTION + +This package is Copyright 2003-2009 by Wilson Snyder. (Report bugs to +L.) + +Verilator is free software; you can redistribute it and/or modify it under +the terms of either the GNU Lesser General Public License Version 3 or the +Perl Artistic License Version 2.0. (See the documentation for more +details.) + +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +more details. + +=head1 DESCRIPTION + +Verilator converts synthesizable (not behavioral) Verilog code into C++ or +SystemC code. It is not a complete simulator, just a translator. + +Verilator is invoked with parameters similar to GCC or Synopsys's VCS. It +reads the specified Verilog code, lints it, and optionally adds coverage +code. For C++ format, it outputs .cpp and .h files. For SystemC format, +it outputs .sp files for the SystemPerl preprocessor available at +http://www.veripool.org. + +The resulting files are then compiled with C++. The user writes a little +C++ wrapper file, which instantiates the top level module. This is +compiled in C++, and linked with the Verilated files. + +The resulting executable will perform the actual simulation. + +=head1 SUPPORTED SYSTEMS + +This version of verilator has been built and tested on: + + SuSE AMD64 i686-linux-2.6.5 + +Other users report success with Redhat Linux, Windows under Cygwin, Macs, +HPUX and Solaris. It should run with minor porting on any Linixish +platform. + +=head1 INSTALLATION + +For more details see +L. + +If you will be modifying Verilator, you should use the "git" method as it +will let you track changes. + +=over 4 + +=item + +The latest version is available at L. + +Download the latest package from that site, and decompress. + + tar xvzf verilator_version.tgz + +=item + +If you will be using SystemC (vs straight C++ output), download SystemC +2.0.1 from L. Follow their installation +instructions. As described in the System-Perl README, you will need to set +SYSTEMC and/or SYSTEMC_KIT to point to this download. Also, set +SYSTEMC_ARCH to the architecture name you used with SystemC, generally +'linux' or 'cygwin'. + +=item + +If you will be using SystemC, download and install Verilog-Perl, +L. + +=item + +If you will be using SystemC, download and install System-Perl, +L. Note you'll need to set a +C environment variable to point to the downloaded kit. +Optionally also set C to point to the installed +headers. + +=item + +C to the Verilator directory containing this README. + +=item + +Type C<./configure> to configure Verilator for your system. + +If you are configuring Verilator to be part of a RPM or other distribution +package system, you may want to use the --enable-defenv configure flag. +This will take the current value of VERILATOR_ROOT, SYSTEMC, SYSTEMC_ARCH, +SYSTEMPERL, and SYSTEMPERL_INCLUDE and build them as defaults into the +executable. + +=item + +Type C to compile Verilator. + +Type C to check the compilation. + +Type C for a more complete test. You may get a error about the +Bit::Vector Perl package. You will need to install it and SystemPerl if +you want all tests to pass. + +You may get a error about a typedef conflict for uint32_t. Edit +verilated.h to change the typedef to work, probably to @samp{typedef +unsigned long uint32_t;}. + +=item + +There is no installation at present; this package runs from the +distribution directory. Programs should set the environment variable +VERILATOR_ROOT to point to this distribution, then execute +$VERILATOR_ROOT/bin/verilator, which will find the path to all needed +files. + +Verilator assumes you did a make in the SystemC kit directory. If not, you +will need to populate C<$SYSTEMC/include> and C<$SYSTEMC/lib-linux> +appropriately. + +=back + +=head1 USAGE DOCUMENTATION + +Detailed documentation and the man page can be seen by running: + + bin/verilator --help + +or reading verilator.txt in the same directory as this README. + +=head1 DIRECTORY STRUCTURE + +The directories in the kit de-taring are as follows: + + bin/verilator => Compiler Wrapper invoked on user Verilog code + include/ => Files that should be in your -I compiler path + include/verilated.cpp => Global routines to link into your simulator + include/verilated.h => Global headers + include/verilated.v => Stub defines for linting + include/verilated.mk => Common makefile + src/ => Translator source code + test_v => Example Verilog code for other test dirs + test_c => Example Verilog->C++ conversion + test_sc => Example Verilog->SystemC conversion + test_sp => Example Verilog->SystemPerl conversion + test_vcs => Example Verilog->VCS conversion (test the test) + test_verilated => Internal tests + test_regress => Internal tests + +=head1 LIMITATIONS + +See verilator.txt (or execute C) for limitations. +