github/verilator
1
0
Fork 1
mirror of https://github.com/verilator/verilator.git synced 2024-12-29 10:47:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Convert README to POD format, and add internals.txt readme

Browse Source
This commit is contained in:
Wilson Snyder 2009-11-03 09:22:47 -05:00
parent 3edbeb8902
commit 3236607be4
6 changed files with 346 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored
View File

@ -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

26
Makefile.in
View File

@ -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)

20
TODO
View File

@ -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<width> //<< 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)

2
bin/verilator
View File

@ -2668,6 +2668,8 @@ Major concepts by Paul Wasson and Duane Galbi.
L<verilator_profcfunc>, L<systemperl>, L<vcoverage>, L<make>
And verilator_internals.txt in the distribution.
=cut
######################################################################

164
internals.pod Normal file
View File

@ -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<http://www.graphviz.org/> 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<http://zvtm.sourceforge.net/zgrviewer.html>. 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 <e1> {0} w0
1: MODULE 0x912b20 <e8822> {8} w0 top L2 [P]
*1:2: VAR 0x91a780 <e74#> {22} w70 out_wide [O] WIRE
1:2:1: BASICDTYPE 0x91a3c0 <e73> {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.
"<e74>" 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 <e####> line in the tree dumps):
watch AstNode::s_editCntGbl==####
=head1 DISTRIBUTION
The latest version is available from L<http://www.veripool.org/>.
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
######################################################################

164
readme.pod Normal file
View File

@ -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<http://www.veripool.org/>.)
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<http://www.veripool.org/projects/verilator/wiki/Installing>.
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<http://www.veripool.org/verilator>.
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<http://www.systemc.org>. 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<http://www.veripool.org/verilog-perl>.
=item
If you will be using SystemC, download and install System-Perl,
L<http://www.veripool.org/systemperl>. Note you'll need to set a
C<SYSTEMPERL> environment variable to point to the downloaded kit.
Optionally also set C<SYSTEMPERL_INCLUDE> to point to the installed
headers.
=item
C<cd> 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<make> to compile Verilator.
Type C<make test_c> to check the compilation.
Type C<make test> 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<bin/verilator --help>) for limitations.