.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Verilog-Perl 3pm" .TH Verilog-Perl 3pm "2020-01-10" "perl v5.30.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Verilog\-Perl \- Overview of Verilog language packages for Perl .SH "DESCRIPTION" .IX Header "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. .PP You may also want to try the \s-1AUTO\s0 features present in Verilog-Mode. .SH "INSTALLATION" .IX Header "INSTALLATION" Skip this section if Verilog-Perl has already been installed. .SS "Supported Systems" .IX Subsection "Supported Systems" Verilog-Perl should run on any system with Perl, G++, Flex, and Bison. It is known to work on at least: .IP "\(bu" 4 sparc\-sun\-solaris2.5.1 .IP "\(bu" 4 i386\-linux .IP "\(bu" 4 i686\-w2k\-cygwin .SS "\s-1CPAN\s0 Installation" .IX Subsection "CPAN Installation" .RS 4 Easiest installation is using the \*(L"\s-1CPAN\*(R"\s0 command line that comes with Perl. After configuring \s-1CPAN\s0 the first time, simply .Sp .Vb 2 \& $ cpan \& cpan> install Verilog\-Perl .Ve .Sp Read the rest of this file for details on the programs provided. .RE .SS "Manual Installation" .IX Subsection "Manual Installation" .RS 4 Download the latest version from , or from . .Sp \&\f(CW\*(C`cd\*(C'\fR to the directory containing this \s-1README\s0 notice. .Sp Type \f(CW\*(C`perl Makefile.PL\*(C'\fR to configure Verilog for your system. .Sp Type \f(CW\*(C`make\*(C'\fR to compile Verilog. Some Solaris users have had trouble with \*(L"open\*(R" being redefined. If this happens, try editing the Makefile to change _FILE_OFFSET_BITS to 32 instead of 64. .Sp Type \f(CW\*(C`make test\*(C'\fR to check the package. If you don't have Synopsys' \s-1VCS,\s0 the test will print a warning, which you can ignore. .Sp Type \f(CW\*(C`make install\*(C'\fR to install the programs and any data files and documentation. .Sp Read the rest of this file for details on the programs provided. .RE .SH "SCRIPTS" .IX Header "SCRIPTS" The following scripts are installed by Verilog-Perl: .IP "vhier" 4 .IX Item "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. .IP "vpassert" 4 .IX Item "vpassert" Vpassert will read the specified Verilog files and preprocess special \&\s-1PLI\s0 assertions. .IP "vppreproc" 4 .IX Item "vppreproc" Vppreproc (Verilog-Perl Pre Processor) reads the Verilog files passed on the command line and outputs preprocessed output. .IP "vrename" 4 .IX Item "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. .SH "PACKAGES" .IX Header "PACKAGES" .IP "Verilog::Getopt" 4 .IX Item "Verilog::Getopt" Verilog::Getopt provides standardized handling of options similar to Verilog/VCS and cc/GCC. .IP "Verilog::Language" 4 .IX Item "Verilog::Language" Verilog::Language provides general utilities for using the Verilog Language, such as parsing numbers or determining what keywords exist. .IP "Verilog::Netlist" 4 .IX Item "Verilog::Netlist" Verilog::Netlist reads and holds interconnect information about a whole design database. .IP "Verilog::Netlist::Cell" 4 .IX Item "Verilog::Netlist::Cell" A Verilog::Netlist::Cell object is created by Verilog::Netlist for every instantiation in the current module. .IP "Verilog::Netlist::ContAssign" 4 .IX Item "Verilog::Netlist::ContAssign" A Verilog::Netlist::ContAssign object is created by Verilog::Netlist for every continuous assignment in the current module. .IP "Verilog::Netlist::File" 4 .IX Item "Verilog::Netlist::File" Verilog::Netlist::File allows Verilog::Netlist objects to be read and written in Verilog format. .IP "Verilog::Netlist::Module" 4 .IX Item "Verilog::Netlist::Module" A Verilog::Netlist::Module object is created by Verilog::Netlist for every module in the design. .IP "Verilog::Netlist::Net" 4 .IX Item "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. .IP "Verilog::Netlist::Pin" 4 .IX Item "Verilog::Netlist::Pin" A Verilog::Netlist::Pin object is created by Verilog::Netlist::Cell for for each pin connection on a cell. .IP "Verilog::Netlist::Port" 4 .IX Item "Verilog::Netlist::Port" A Verilog::Netlist::Port object is created by Verilog::Netlist::Module for every port connection in the module. .IP "Verilog::Netlist::Subclass" 4 .IX Item "Verilog::Netlist::Subclass" The Verilog::Netlist::Subclass is used as a base class for all Verilog::Netlist::* structures. .IP "Verilog::Parser" 4 .IX Item "Verilog::Parser" Verilog::Parser will tokenize a Verilog file and invoke various callback methods. .IP "Verilog::Preproc" 4 .IX Item "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. .IP "Verilog::SigParse" 4 .IX Item "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. .SH "WHICH PARSER PACKAGE?" .IX Header "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. .IP "VParseBison.y" 4 .IX Item "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). .IP "Verilog::Preproc" 4 .IX Item "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. .IP "Verilog::Parser" 4 .IX Item "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. .IP "Abstract Syntax Tree" 4 .IX Item "Abstract Syntax Tree" Verilog::Parser knows enough to make a complete Abstract Syntax Tree (\s-1AST\s0) of Verilog syntax. This represents all major constructs such as a \*(L"module\*(R" as a data structure, but does not interconnect the \s-1AST\s0 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 \s-1XML\s0 output (below). .IP "Verilog::SigParser" 4 .IX Item "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). .IP "Verilog::Netlist" 4 .IX Item "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). .IP "\s-1VPI\s0" 4 .IX Item "VPI" Using the \s-1VPI\s0 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 \s-1VPI,\s0 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 \s-1VPI\s0 can operate \s-1ONLY\s0 on an elaborated design (where all parameters are resolved). Walking a \s-1VPI\s0 tree general requires a good deal of work compared to simple scripting (though little work compared to writing a parser from scratch). .IP "Verilator" 4 .IX Item "Verilator" The Verilator program also contains a very similar front end as Verilog-Perl and can create \s-1XML\s0 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. .Sp If you're looking to parse only synthesizable code this is the recommended route. .IP "Verilog-Mode for Emacs" 4 .IX Item "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 \s-1IP\s0 providers. .SH "FAQ" .IX Header "FAQ" .ie n .IP "Why do I get ""unexpected `do'"" or ""unexpected `bit'"" errors?" 4 .el .IP "Why do I get ``unexpected `do''' or ``unexpected `bit''' errors?" 4 .IX Item "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. .Sp .Vb 3 \& \`begin_keywords "1364\-2001" \& integer bit; initial bit = 1; \& \`end_keywords .Ve .Sp Alternatively use the \-\-language (for vhier) or Verilog::Language::language_standard call to specify \*(L"1364\-2001\*(R", or for really old code, \*(L"1364\-1995\*(R". .Sp But, again, you really should fix the Verilog code. .IP "With Verilog::Netlist how do I resolve signal widths that include parameters down to constants?" 4 .IX Item "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 \s-1VPI,\s0 see the sections above. .SH "DISTRIBUTION" .IX Header "DISTRIBUTION" Verilog-Perl is part of the free Verilog \s-1EDA\s0 software tool suite. The latest version is available from \s-1CPAN\s0 and from . .PP 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 \s-1GNU\s0 Lesser General Public License Version 3 or the Perl Artistic License Version 2.0. .PP This code is provided with no warranty of any kind, and is used entirely at your own risk. .SH "AUTHORS" .IX Header "AUTHORS" Wilson Snyder .SH "SEE ALSO" .IX Header "SEE ALSO" vhier, vpassert, vppreproc, vrename .PP Verilog::EditFiles, Verilog::Getopt, Verilog::Language Verilog::Netlist, Verilog::Parser, Verilog::Preproc, Verilog::SigParser .PP 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, .PP And the Verilog-Mode package for Emacs.