cad/p5-Verilog-Perl/Verilog-Perl-3.478

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.

    Verilog-Perl is currently a mature tool. Bugs are fixed and IEEE
    language capabilities updated as needed, but the basic features and API
    are not expected to change.

    For general information see <https://www.veripool.org/verilog-perl>.

    For specific details on each component, see that component's manpage.

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

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). For these applications
        consider 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.

INSTALLATION

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

    Verilog-Perl should run on any system with Perl, G++, Flex, and Bison.
    It is known to work on most Linux distributions, plus Cygwin.

    You may install using either CPAN, or the sources. If you plan to do any
    development on Verilog-Perl, use the sources.

  CPAN Installation

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

       cpan install Verilog-Perl
       # And see the documentation
       man Verilog-Perl
       # Or, sometimes the capitalization is changed
       man verilog-perl

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

  Manual Installation from Repository

    Option 2: Build any version using the source development repository
    with:

       git clone http://git.veripool.org/git/Verilog-Perl  # Only first time
       cd Verilog-Perl
       git pull        # Make sure we're up-to-date
       git tag         # See what versions exist (recent GITs only)
       #git checkout master      # Use development branch (e.g. recent bug fix)
       #git checkout stable      # Use most recent release
       #git checkout v{version}  # Switch to specified release version

       perl Makefile.PL
       # Ignore warning about README, this file will be generated
       make
       make test
       make install

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

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 <https://www.veripool.org/> free Verilog EDA
    software tool suite. The latest version is available from CPAN and from
    <https://www.veripool.org/verilog-perl>.

    Copyright 2000-2021 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 <https://www.veripool.org/verilog-mode>Verilog-Mode package for
    Emacs.
Name		Date	Size	#Lines	LOC
..		03-May-2022	-
Netlist/	H	06-Jun-2021	-	4,165	2,172
Parser/	H	03-May-2022	-	16,850	12,691
Preproc/	H	03-May-2022	-	7,694	5,933
t/	H	06-Jun-2021	-	12,051	11,043
verilog/	H	06-Jun-2021	-	2,643	1,859
.clang-format	H A D	13-Apr-2021	3.1 KiB	112	110
.gitignore	H A D	02-Feb-2018	124	18	17
COPYING	H A D	02-Feb-2018	8.9 KiB	198	154
Changes	H A D	06-Jun-2021	39.5 KiB	1,484	711
EditFiles.pm	H A D	06-Jun-2021	10.8 KiB	400	206
Getopt.pm	H A D	06-Jun-2021	22 KiB	831	502
Language.pm	H A D	06-Jun-2021	20.9 KiB	730	502
MANIFEST	H A D	13-Apr-2021	3.5 KiB	195	194
MANIFEST.SKIP	H A D	29-Mar-2021	608	45	44
META.yml	H A D	06-Jun-2021	783	28	26
Makefile.PL	H A D	03-May-2022	5.4 KiB	149	114
Netlist.pm	H A D	06-Jun-2021	19.3 KiB	727	276
README	H A D	05-Jun-2021	11.5 KiB	292	220
README.pod	H A D	13-Apr-2021	11 KiB	341	231
Std.pm	H A D	06-Jun-2021	3.2 KiB	136	56
vhier	H A D	06-Jun-2021	16.6 KiB	607	334
vpassert	H A D	06-Jun-2021	50.1 KiB	1,706	1,122
vppreproc	H A D	06-Jun-2021	7.4 KiB	295	91
vrename	H A D	06-Jun-2021	19.4 KiB	730	461
vsplitmodule	H A D	25-Jan-2019	3.3 KiB	93	31