Verilog::Verilog-Perl(3pm)

1Verilog-Perl(3)       User Contributed Perl Documentation      Verilog-Perl(3)
2
3
4

NAME

6       Verilog-Perl - Overview of Verilog language packages for Perl
7

DESCRIPTION

9       The Verilog-Perl distribution provides Perl parsing and utilities for
10       the Verilog Language.  This file provides an overview of the
11       distribution, for specific details on each component, see that
12       component's manpage.
13
14       You may also want to try the AUTO features present in
15       <http://www.veripool.org/verilog-mode> Verilog-Mode.
16

INSTALLATION

18       Skip this section if Verilog-Perl has already been installed.
19
20   Supported Systems
21       Verilog-Perl should run on any system with Perl, G++, Flex, and Bison.
22       It is known to work on at least:
23
24       ·   sparc-sun-solaris2.5.1
25
26       ·   i386-linux
27
28       ·   i686-w2k-cygwin
29
30   CPAN Installation
31           Easiest installation is using the "CPAN" command line that comes
32           with Perl.  After configuring CPAN the first time, simply
33
34              $ cpan
35              cpan> install Verilog-Perl
36
37           Read the rest of this file for details on the programs provided.
38
39   Manual Installation
40           Download the latest version from <http://www.perl.org/CPAN/>, or
41           from <http://www.veripool.org/verilog-perl>.
42
43           "cd" to the directory containing this README notice.
44
45           Type "perl Makefile.PL" to configure Verilog for your system.
46
47           Type "make" to compile Verilog.  Some Solaris users have had
48           trouble with "open" being redefined.  If this happens, try editing
49           the Makefile to change _FILE_OFFSET_BITS to 32 instead of 64.
50
51           Type "make test" to check the package.  If you don't have Synopsys'
52           VCS, the test will print a warning, which you can ignore.
53
54           Type "make install" to install the programs and any data files and
55           documentation.
56
57           Read the rest of this file for details on the programs provided.
58

SCRIPTS

60       The following scripts are installed by Verilog-Perl:
61
62       vhier
63           Vhier reads the Verilog files passed on the command line and
64           outputs a tree of all of the filenames, modules, and cells
65           referenced by that file.
66
67       vpassert
68           Vpassert will read the specified Verilog files and preprocess
69           special PLI assertions.
70
71       vppreproc
72           Vppreproc (Verilog-Perl Pre Processor) reads the Verilog files
73           passed on the command line and outputs preprocessed output.
74
75       vrename
76           Vrename will allow a signal to be changed across all levels of the
77           design hierarchy, or to create a cross reference of signal names.
78

PACKAGES

80       Verilog::Getopt
81           Verilog::Getopt provides standardized handling of options similar
82           to Verilog/VCS and cc/GCC.
83
84       Verilog::Language
85           Verilog::Language provides general utilities for using the Verilog
86           Language, such as parsing numbers or determining what keywords
87           exist.
88
89       Verilog::Netlist
90           Verilog::Netlist reads and holds interconnect information about a
91           whole design database.
92
93       Verilog::Netlist::Cell
94           A Verilog::Netlist::Cell object is created by Verilog::Netlist for
95           every instantiation in the current module.
96
97       Verilog::Netlist::ContAssign
98           A Verilog::Netlist::ContAssign object is created by
99           Verilog::Netlist for every continuous assignment in the current
100           module.
101
102       Verilog::Netlist::File
103           Verilog::Netlist::File allows Verilog::Netlist objects to be read
104           and written in Verilog format.
105
106       Verilog::Netlist::Module
107           A Verilog::Netlist::Module object is created by Verilog::Netlist
108           for every module in the design.
109
110       Verilog::Netlist::Net
111           A Verilog::Netlist::Net object is created by
112           Verilog::Netlist::Module for every signal and input/output
113           declaration in the current module.
114
115       Verilog::Netlist::Pin
116           A Verilog::Netlist::Pin object is created by Verilog::Netlist::Cell
117           for for each pin connection on a cell.
118
119       Verilog::Netlist::Port
120           A Verilog::Netlist::Port object is created by
121           Verilog::Netlist::Module for every port connection in the module.
122
123       Verilog::Netlist::Subclass
124           The Verilog::Netlist::Subclass is used as a base class for all
125           Verilog::Netlist::* structures.
126
127       Verilog::Parser
128           Verilog::Parser will tokenize a Verilog file and invoke various
129           callback methods.
130
131       Verilog::Preproc
132           Verilog::Preproc reads Verilog files, and preprocesses them
133           according to the Verilog specification.  Programs can be easily
134           converted from reading a IO::File into reading preprocessed output
135           from Verilog::Preproc.
136
137       Verilog::SigParse
138           Verilog::SigParser builds upon the Verilog::Parser package to
139           provide callbacks for when a signal is declared, a module
140           instantiated, or a module defined.
141

WHICH PARSER PACKAGE?

143       If you are starting a new application which needs to parse the Verilog
144       language you have several tools available to you.  Which you pick
145       depends on how low level and complete the information you need is.
146
147       VParseBison.y
148           The low level VParse* source files may be of use when you need a
149           starting point for your own a full C++ SystemVerilog grammar
150           parser, using Bison and Flex.  It understands most of the
151           SystemVerilog 2017 grammar (1800-2017 Appendix A).
152
153       Verilog::Preproc
154           Verilog::Preproc is useful when you need only post-preprocessed
155           text output, or a list of defines, includes, etc.  It can
156           preprocess a file, or be used to provide the Verilog macro language
157           on top of synthesis scripts.  It understands and implements all
158           preprocessor features of SystemVerilog 2017.
159
160       Verilog::Parser
161           Verilog::Parser is useful when you need to tokenize or write source
162           filters (where you need everything including whitespace).  It can
163           take raw files, or preprocessed input, and generates callbacks.  It
164           understands all SystemVerilog 2017 keywords.
165
166       Abstract Syntax Tree
167           Verilog::Parser knows enough to make a complete Abstract Syntax
168           Tree (AST) of Verilog syntax. This represents all major constructs
169           such as a "module" as a data structure, but does not interconnect
170           the AST nodes as would be needed to follow signals.  Not all
171           keywords have been implemented; many are parsed but otherwise
172           ignored.  A complete Ast tree would allow any arbitrary
173           transformation of Verilog syntax (everything is known excluding
174           whitespace).  Long term the authors would be interested in
175           collaborating on a general parser, but for now, applications can
176           leverate the C++ code or use Verilator's XML output (below).
177
178       Verilog::SigParser
179           Verilog::SigParser is useful when you need a list of modules,
180           signals, ports, functions, etc.  It requires a preprocessed file
181           (from Verilog::Preproc), and can parse all SystemVerilog 2017
182           files, but only provides callbacks on certain interesting things.
183           The SigParser operates only on a file at a time; it does not
184           interconnect signals nor perform any elaboration (resolution of
185           parameters).
186
187       Verilog::Netlist
188           Verilog::Netlist is useful for when you need the hierarchy, and a
189           list of signals per module, pins per cell, etc.  It builds upon the
190           output of Verilog::SigParser, so requires preprocessed files (from
191           Verilog::Preproc).  It parses all SystemVerilog 2017 files, but not
192           all SystemVerilog constructs are loaded into objects.
193           Verilog::Netlist interconnects modules with instantiations but does
194           not perform any elaboration (resolution of parameters).
195
196       VPI Using the VPI is the best way to access the behavior of the design.
197           It is not part of this package as it requires a compliant simulator
198           and C++ code to call the VPI, and understands as much of the
199           language as the simulator supports.  This allows writing lint
200           checks and full knowledge of all parts of the code.  The VPI can
201           operate ONLY on an elaborated design (where all parameters are
202           resolved).  Walking a VPI tree general requires a good deal of work
203           compared to simple scripting (though little work compared to
204           writing a parser from scratch).
205
206       Verilator
207           The Verilator program also contains a very similar front end as
208           Verilog-Perl and can create XML output showing the abstract syntax
209           tree.  Verilator also understands how to elaborate and connect
210           complex pins and types, but supports mostly only the synthesis
211           subset of SystemVerilog.
212
213           If you're looking to parse only synthesizable code this is the
214           recommended route.
215
216       Verilog-Mode for Emacs
217           Although not a parser, a common requested use of Verilog-Perl is to
218           automatically make shell modules and interconnect modules.
219           Verilog-Mode is a better solution to this problem, as it results in
220           completely portable code; the program (Verilog-Mode) isn't needed
221           for others to update the design.  It's also in very common usage,
222           including by many IP providers.
223

FAQ

225       Why do I get "unexpected `do'" or "unexpected `bit'" errors?
226           Do, bit, ref, return, and other words are now SystemVerilog
227           keywords.  You should change your code to not use them to insure it
228           works with newer tools.  Alternatively, surround them by the
229           Verilog 2005/SystemVerilog begin_keywords pragma to indicate
230           Verilog 2001 code.
231
232              `begin_keywords "1364-2001"
233                 integer bit; initial bit = 1;
234              `end_keywords
235
236           Alternatively use the --language (for vhier) or
237           Verilog::Language::language_standard call to specify "1364-2001",
238           or for really old code, "1364-1995".
239
240           But, again, you really should fix the Verilog code.
241
242       With Verilog::Netlist how do I resolve signal widths that include
243       parameters down to constants?
244           Unfortunately parameter resolution is part of elaboration.
245           Verilog-Perl doesn't do elaboration as it requires a good fraction
246           of a complete simulator implementation.  Many applications can work
247           around this limitation, if yours still requires elaboration you're
248           stuck with using Verilator or the VPI, see the sections above.
249

DISTRIBUTION

251       Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA
252       software tool suite.  The latest version is available from CPAN and
253       from <http://www.veripool.org/verilog-perl>.
254
255       Copyright 2000-2019 by Wilson Snyder.  This package is free software;
256       you can redistribute it and/or modify it under the terms of either the
257       GNU Lesser General Public License Version 3 or the Perl Artistic
258       License Version 2.0.
259
260       This code is provided with no warranty of any kind, and is used
261       entirely at your own risk.
262

AUTHORS

264       Wilson Snyder <wsnyder@wsnyder.org>
265