Provided by: libverilog-perl_3.470-1build1_amd64 bug

NAME

       Verilog-Perl - Overview of Verilog language packages for Perl

DESCRIPTION

       The Verilog-Perl distribution provides Perl parsing and utilities for the Verilog
       Language.  This file provides an overview of the distribution, for specific details on
       each component, see that component's manpage.

       You may also want to try the AUTO features present in
       <http://www.veripool.org/verilog-mode> Verilog-Mode.

INSTALLATION

       Skip this section if Verilog-Perl has already been installed.

   Supported Systems
       Verilog-Perl should run on any system with Perl, G++, Flex, and Bison.  It is known to
       work on at least:

       •   sparc-sun-solaris2.5.1

       •   i386-linux

       •   i686-w2k-cygwin

   CPAN Installation
           Easiest installation is using the "CPAN" command line that comes with Perl.  After
           configuring CPAN the first time, simply

              $ cpan
              cpan> install Verilog-Perl

           Read the rest of this file for details on the programs provided.

   Manual Installation
           Download the latest version from <http://www.perl.org/CPAN/>, or from
           <http://www.veripool.org/verilog-perl>.

           "cd" to the directory containing this README notice.

           Type "perl Makefile.PL" to configure Verilog for your system.

           Type "make" to compile Verilog.  Some Solaris users have had trouble with "open" being
           redefined.  If this happens, try editing the Makefile to change _FILE_OFFSET_BITS to
           32 instead of 64.

           Type "make test" to check the package.  If you don't have Synopsys' VCS, the test will
           print a warning, which you can ignore.

           Type "make install" to install the programs and any data files and documentation.

           Read the rest of this file for details on the programs provided.

SCRIPTS

       The following scripts are installed by Verilog-Perl:

       vhier
           Vhier reads the Verilog files passed on the command line and outputs a tree of all of
           the filenames, modules, and cells referenced by that file.

       vpassert
           Vpassert will read the specified Verilog files and preprocess special PLI assertions.

       vppreproc
           Vppreproc (Verilog-Perl Pre Processor) reads the Verilog files passed on the command
           line and outputs preprocessed output.

       vrename
           Vrename will allow a signal to be changed across all levels of the design hierarchy,
           or to create a cross reference of signal names.

PACKAGES

       Verilog::Getopt
           Verilog::Getopt provides standardized handling of options similar to Verilog/VCS and
           cc/GCC.

       Verilog::Language
           Verilog::Language provides general utilities for using the Verilog Language, such as
           parsing numbers or determining what keywords exist.

       Verilog::Netlist
           Verilog::Netlist reads and holds interconnect information about a whole design
           database.

       Verilog::Netlist::Cell
           A Verilog::Netlist::Cell object is created by Verilog::Netlist for every instantiation
           in the current module.

       Verilog::Netlist::ContAssign
           A Verilog::Netlist::ContAssign object is created by Verilog::Netlist for every
           continuous assignment in the current module.

       Verilog::Netlist::File
           Verilog::Netlist::File allows Verilog::Netlist objects to be read and written in
           Verilog format.

       Verilog::Netlist::Module
           A Verilog::Netlist::Module object is created by Verilog::Netlist for every module in
           the design.

       Verilog::Netlist::Net
           A Verilog::Netlist::Net object is created by Verilog::Netlist::Module for every signal
           and input/output declaration in the current module.

       Verilog::Netlist::Pin
           A Verilog::Netlist::Pin object is created by Verilog::Netlist::Cell for for each pin
           connection on a cell.

       Verilog::Netlist::Port
           A Verilog::Netlist::Port object is created by Verilog::Netlist::Module for every port
           connection in the module.

       Verilog::Netlist::Subclass
           The Verilog::Netlist::Subclass is used as a base class for all Verilog::Netlist::*
           structures.

       Verilog::Parser
           Verilog::Parser will tokenize a Verilog file and invoke various callback methods.

       Verilog::Preproc
           Verilog::Preproc reads Verilog files, and preprocesses them according to the Verilog
           specification.  Programs can be easily converted from reading a IO::File into reading
           preprocessed output from Verilog::Preproc.

       Verilog::SigParse
           Verilog::SigParser builds upon the Verilog::Parser package to provide callbacks for
           when a signal is declared, a module instantiated, or a module defined.

WHICH PARSER PACKAGE?

       If you are starting a new application which needs to parse the Verilog language you have
       several tools available to you.  Which you pick depends on how low level and complete the
       information you need is.

       VParseBison.y
           The low level VParse* source files may be of use when you need a starting point for
           your own a full C++ SystemVerilog grammar parser, using Bison and Flex.  It
           understands most of the SystemVerilog 2017 grammar (1800-2017 Appendix A).

       Verilog::Preproc
           Verilog::Preproc is useful when you need only post-preprocessed text output, or a list
           of defines, includes, etc.  It can preprocess a file, or be used to provide the
           Verilog macro language on top of synthesis scripts.  It understands and implements all
           preprocessor features of SystemVerilog 2017.

       Verilog::Parser
           Verilog::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,
           and generates callbacks.  It understands all SystemVerilog 2017 keywords.

       Abstract Syntax Tree
           Verilog::Parser knows enough to make a complete Abstract Syntax Tree (AST) of Verilog
           syntax. This represents all major constructs such as a "module" as a data structure,
           but does not interconnect the AST nodes as would be needed to follow signals.  Not all
           keywords have been implemented; many are parsed but otherwise ignored.  A complete Ast
           tree would allow any arbitrary transformation of Verilog syntax (everything is known
           excluding whitespace).  Long term the authors would be interested in collaborating on
           a general parser, but for now, applications can leverate the C++ code or use
           Verilator's XML output (below).

       Verilog::SigParser
           Verilog::SigParser is useful when you need a list of modules, signals, ports,
           functions, etc.  It requires a preprocessed file (from Verilog::Preproc), and can
           parse all SystemVerilog 2017 files, but only provides callbacks on certain interesting
           things.  The SigParser operates only on a file at a time; it does not interconnect
           signals nor perform any elaboration (resolution of parameters).

       Verilog::Netlist
           Verilog::Netlist is useful for when you need the hierarchy, and a list of signals per
           module, pins per cell, etc.  It builds upon the output of Verilog::SigParser, so
           requires preprocessed files (from Verilog::Preproc).  It parses all SystemVerilog 2017
           files, but not all SystemVerilog constructs are loaded into objects. Verilog::Netlist
           interconnects modules with instantiations but does not perform any elaboration
           (resolution of parameters).

       VPI Using the VPI is the best way to access the behavior of the design.  It is not part of
           this package as it requires a compliant simulator and C++ code to call the VPI, and
           understands as much of the language as the simulator supports.  This allows writing
           lint checks and full knowledge of all parts of the code.  The VPI can operate ONLY on
           an elaborated design (where all parameters are resolved).  Walking a VPI tree general
           requires a good deal of work compared to simple scripting (though little work compared
           to writing a parser from scratch).

       Verilator
           The Verilator program also contains a very similar front end as Verilog-Perl and can
           create XML output showing the abstract syntax tree.  Verilator also understands how to
           elaborate and connect complex pins and types, but supports mostly only the synthesis
           subset of SystemVerilog.

           If you're looking to parse only synthesizable code this is the recommended route.

       Verilog-Mode for Emacs
           Although not a parser, a common requested use of Verilog-Perl is to automatically make
           shell modules and interconnect modules.  Verilog-Mode is a better solution to this
           problem, as it results in completely portable code; the program (Verilog-Mode) isn't
           needed for others to update the design.  It's also in very common usage, including by
           many IP providers.

FAQ

       Why do I get "unexpected `do'" or "unexpected `bit'" errors?
           Do, bit, ref, return, and other words are now SystemVerilog keywords.  You should
           change your code to not use them to insure it works with newer tools.  Alternatively,
           surround them by the Verilog 2005/SystemVerilog begin_keywords pragma to indicate
           Verilog 2001 code.

              `begin_keywords "1364-2001"
                 integer bit; initial bit = 1;
              `end_keywords

           Alternatively use the --language (for vhier) or Verilog::Language::language_standard
           call to specify "1364-2001", or for really old code, "1364-1995".

           But, again, you really should fix the Verilog code.

       With Verilog::Netlist how do I resolve signal widths that include parameters down to
       constants?
           Unfortunately parameter resolution is part of elaboration.  Verilog-Perl doesn't do
           elaboration as it requires a good fraction of a complete simulator implementation.
           Many applications can work around this limitation, if yours still requires elaboration
           you're stuck with using Verilator or the VPI, see the sections above.

DISTRIBUTION

       Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA software tool
       suite.  The latest version is available from CPAN and from
       <http://www.veripool.org/verilog-perl>.

       Copyright 2000-2020 by Wilson Snyder.  This package 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.

       This code is provided with no warranty of any kind, and is used entirely at your own risk.

AUTHORS

       Wilson Snyder <wsnyder@wsnyder.org>

SEE ALSO

       vhier, vpassert, vppreproc, vrename

       Verilog::EditFiles, Verilog::Getopt, Verilog::Language Verilog::Netlist, Verilog::Parser,
       Verilog::Preproc, Verilog::SigParser

       Verilog::Netlist::Cell, Verilog::Netlist::ContAssign, Verilog::Netlist::File,
       Verilog::Netlist::Interface, Verilog::Netlist::ModPort, Verilog::Netlist::Module,
       Verilog::Netlist::Net, Verilog::Netlist::Pin, Verilog::Netlist::Port,
       Verilog::Netlist::Subclass,

       And the <http://www.veripool.org/verilog-mode>Verilog-Mode package for Emacs.