# -*- Perl -*-# See copyright, etc in below POD section.######################################################################=pod=head1 NAMEVerilog-Perl - Overview of Verilog language packages for Perl=head1 DESCRIPTIONThe Verilog-Perl distribution provides Perl parsing and utilities for theVerilog Language.  This file provides an overview of the distribution, forspecific details on each component, see that component's manpage.You may also want to try the AUTO features present inL<http://www.veripool.org/verilog-mode> Verilog-Mode.=head1 INSTALLATIONSkip this section if Verilog-Perl has already been installed.=head2 Supported SystemsVerilog-Perl should run on any system with Perl, G++, Flex, and Bison.  Itis known to work on at least:=over 4=item * sparc-sun-solaris2.5.1=item * i386-linux=item * i686-w2k-cygwin=back=head2 CPAN Installation=over 4Easiest installation is using the "CPAN" command line that comes with Perl.After configuring CPAN the first time, simply   $ cpan   cpan> install Verilog-PerlRead the rest of this file for details on the programs provided.=back=head2 Manual Installation=over 4Download the latest version from L<http://www.perl.org/CPAN/>, orfrom L<http://www.veripool.org/verilog-perl>.C<cd> to the directory containing this README notice.Type C<perl Makefile.PL> to configure Verilog for your system.Type C<make> to compile Verilog.  Some Solaris users have hadtrouble with "open" being redefined.  If this happens, try editingthe Makefile to change _FILE_OFFSET_BITS to 32 instead of 64.Type C<make test> to check the package.  If you don't haveSynopsys' VCS, the test will print a warning, which you can ignore.Type C<make install> to install the programs and any data files anddocumentation.Read the rest of this file for details on the programs provided.=back=head1 SCRIPTSThe following scripts are installed by Verilog-Perl:=over 4=item L<vhier>Vhier reads the Verilog files passed on the command line and outputs a treeof all of the filenames, modules, and cells referenced by that file.=item L<vpassert>Vpassert will read the specified Verilog files and preprocess specialPLI assertions.=item L<vppreproc>Vppreproc (Verilog-Perl Pre Processor) reads the Verilog files passed on thecommand line and outputs preprocessed output.=item L<vrename>Vrename will allow a signal to be changed across all levels of the designhierarchy, or to create a cross reference of signal names.=back=head1 PACKAGES=over 4=item L<Verilog::Getopt|Verilog::Getopt>Verilog::Getopt provides standardized handling of options similar toVerilog/VCS and cc/GCC.=item L<Verilog::Language|Verilog::Language>Verilog::Language provides general utilities for using the VerilogLanguage, such as parsing numbers or determining what keywords exist.=item L<Verilog::Netlist|Verilog::Netlist>Verilog::Netlist reads and holds interconnect information about a wholedesign database.=item L<Verilog::Netlist::Cell|Verilog::Netlist::Cell>A Verilog::Netlist::Cell object is created by Verilog::Netlist for everyinstantiation in the current module.=item L<Verilog::Netlist::File|Verilog::Netlist::File>Verilog::Netlist::File allows Verilog::Netlist objects to be read andwritten in Verilog format.=item L<Verilog::Netlist::Module|Verilog::Netlist::Module>A Verilog::Netlist::Module object is created by Verilog::Netlist for everymodule in the design.=item L<Verilog::Netlist::Net|Verilog::Netlist::Net>A Verilog::Netlist::Net object is created by Verilog::Netlist::Module forevery signal and input/output declaration in the current module.=item L<Verilog::Netlist::Pin|Verilog::Netlist::Pin>A Verilog::Netlist::Pin object is created by Verilog::Netlist::Cell for foreach pin connection on a cell.=item L<Verilog::Netlist::Port|Verilog::Netlist::Port>A Verilog::Netlist::Port object is created by Verilog::Netlist::Module forevery port connection in the module.=item L<Verilog::Netlist::Subclas|Verilog::Netlist::Subclass>The Verilog::Netlist::Subclass is used as a base class for allVerilog::Netlist::* structures.=item L<Verilog::Parser|Verilog::Parser>Verilog::Parser will tokenize a Verilog file and invoke various callbackmethods.=item L<Verilog::Preproc|Verilog::Preproc>Verilog::Preproc reads Verilog files, and preprocesses them according tothe Verilog specification.  Programs can be easily converted from reading aIO::File into reading preprocessed output from Verilog::Preproc.=item L<Verilog::SigParse|Verilog::SigParser>Verilog::SigParser builds upon the Verilog::Parser package to providecallbacks for when a signal is declared, a module instantiated, or a moduledefined.=back=head1 WHICH PARSER PACKAGE?If you are starting a new application which needs to parse the Veriloglanguage you have several tools available to you.  Which you pick dependson how low level and complete the information you need is.=over 4=item Verilog::PreprocVerilog::Preproc is useful when you need only text out, or a list ofdefines, etc.  It can preprocess a file, or be used to provide the Verilogmacro language on top of synthesis scripts.  It understands the fullSystemVerilog 2005 preprocessor syntax.=item Verilog::ParserVerilog::Parser is useful when you need to tokenize or write source filters(where you need everything including whitespace).  It can take raw files,or preprocessed input.  It understands all SystemVerilog 2005 keywords.=item Verilog::SigParserVerilog::SigParser is useful when you need a list of modules, signals,ports, functions, etc.  It requires a preprocessed file, and can parse mostVerilog 2005 files, but only provides callbacks on certain interestingthings.  It does not have SystemVerilog support yet; try contacting theauthor with your requirements.=item Verilog::NetlistVerilog::Netlist is useful for when you need the hierarchy, and a list ofsignals per module, pins per cell, etc.  It builds upon the output ofVerilog::SigParser, so requires preprocessed files.  It does not haveSystemVerilog support yet.This is probably the most popular choice.=item VPIUsing the VPI is the best way to access the behavior of the design.  It isnot part of this package as it requires a compliant simulator and C++ codeto call the VPI, and understands as much of the language as the simulatorsupports.  This allows writing lint checks and full knowledge of all partsof the code, but generally requires the most work (short of writing aparser from scratch.)=back=head1 DISTRIBUTIONVerilog-Perl is part of the L<http://www.veripool.org/> free Verilog EDAsoftware tool suite.  The latest version is available from CPAN and fromL<http://www.veripool.org/verilog-perl>.Copyright 2000-2009 by Wilson Snyder.  This package is free software; youcan redistribute it and/or modify it under the terms of either the GNULesser General Public License or the Perl Artistic License.This code is provided with no warranty of any kind, and is used entirely atyour own risk.=head1 AUTHORSWilson Snyder <wsnyder@wsnyder.org>=head1 SEE ALSOL<vhier>,L<vpassert>,L<vppreproc>,L<vrename>L<Verilog::EditFiles>,L<Verilog::Getopt>,L<Verilog::Language>L<Verilog::Netlist>,L<Verilog::Parser>,L<Verilog::Preproc>,L<Verilog::SigParser>L<Verilog::Netlist::Cell>,L<Verilog::Netlist::File>,L<Verilog::Netlist::Module>,L<Verilog::Netlist::Net>,L<Verilog::Netlist::Pin>,L<Verilog::Netlist::Port>,L<Verilog::Netlist::Subclass>,And the L<http://www.veripool.org/verilog-mode>Verilog-Mode package for Emacs.=cut