1=pod
2
3=head1 NAME
4
5Verilog-Perl - Overview of Verilog language packages for Perl
6
7=head1 DESCRIPTION
8
9The Verilog-Perl distribution provides Perl parsing and utilities for the
10Verilog Language.  This file provides an overview of the distribution.
11
12Verilog-Perl is currently a mature tool. Bugs are fixed and IEEE language
13capabilities updated as needed, but the basic features and API are not
14expected to change.
15
16For general information see L<https://www.veripool.org/verilog-perl>.
17
18For specific details on each component, see that component's manpage.
19
20You may also want to try the AUTO features present in
21L<https://www.veripool.org/verilog-mode> Verilog-Mode.
22
23=head1 SCRIPTS
24
25The following scripts are installed by Verilog-Perl:
26
27=over 4
28
29=item L<vhier>
30
31Vhier reads the Verilog files passed on the command line and outputs a tree
32of all of the filenames, modules, and cells referenced by that file.
33
34=item L<vpassert>
35
36Vpassert will read the specified Verilog files and preprocess special
37PLI assertions.
38
39=item L<vppreproc>
40
41Vppreproc (Verilog-Perl Pre Processor) reads the Verilog files passed on the
42command line and outputs preprocessed output.
43
44=item L<vrename>
45
46Vrename will allow a signal to be changed across all levels of the design
47hierarchy, or to create a cross reference of signal names.
48
49=back
50
51=head1 PACKAGES
52
53=over 4
54
55=item L<Verilog::Getopt|Verilog::Getopt>
56
57Verilog::Getopt provides standardized handling of options similar to
58Verilog/VCS and cc/GCC.
59
60=item L<Verilog::Language|Verilog::Language>
61
62Verilog::Language provides general utilities for using the Verilog
63Language, such as parsing numbers or determining what keywords exist.
64
65=item L<Verilog::Netlist|Verilog::Netlist>
66
67Verilog::Netlist reads and holds interconnect information about a whole
68design database.
69
70=item L<Verilog::Netlist::Cell|Verilog::Netlist::Cell>
71
72A Verilog::Netlist::Cell object is created by Verilog::Netlist for every
73instantiation in the current module.
74
75=item L<Verilog::Netlist::ContAssign|Verilog::Netlist::ContAssign>
76
77A Verilog::Netlist::ContAssign object is created by Verilog::Netlist for
78every continuous assignment in the current module.
79
80=item L<Verilog::Netlist::File|Verilog::Netlist::File>
81
82Verilog::Netlist::File allows Verilog::Netlist objects to be read and
83written in Verilog format.
84
85=item L<Verilog::Netlist::Module|Verilog::Netlist::Module>
86
87A Verilog::Netlist::Module object is created by Verilog::Netlist for every
88module in the design.
89
90=item L<Verilog::Netlist::Net|Verilog::Netlist::Net>
91
92A Verilog::Netlist::Net object is created by Verilog::Netlist::Module for
93every signal and input/output declaration in the current module.
94
95=item L<Verilog::Netlist::Pin|Verilog::Netlist::Pin>
96
97A Verilog::Netlist::Pin object is created by Verilog::Netlist::Cell for for
98each pin connection on a cell.
99
100=item L<Verilog::Netlist::Port|Verilog::Netlist::Port>
101
102A Verilog::Netlist::Port object is created by Verilog::Netlist::Module for
103every port connection in the module.
104
105=item L<Verilog::Netlist::Subclass|Verilog::Netlist::Subclass>
106
107The Verilog::Netlist::Subclass is used as a base class for all
108Verilog::Netlist::* structures.
109
110=item L<Verilog::Parser|Verilog::Parser>
111
112Verilog::Parser will tokenize a Verilog file and invoke various callback
113methods.
114
115=item L<Verilog::Preproc|Verilog::Preproc>
116
117Verilog::Preproc reads Verilog files, and preprocesses them according to
118the Verilog specification.  Programs can be easily converted from reading a
119IO::File into reading preprocessed output from Verilog::Preproc.
120
121=item L<Verilog::SigParse|Verilog::SigParser>
122
123Verilog::SigParser builds upon the Verilog::Parser package to provide
124callbacks for when a signal is declared, a module instantiated, or a module
125defined.
126
127=back
128
129=head1 WHICH PARSER PACKAGE?
130
131If you are starting a new application which needs to parse the Verilog
132language you have several tools available to you.  Which you pick depends
133on how low level and complete the information you need is.
134
135=over 4
136
137=item VParseBison.y
138
139The low level VParse* source files may be of use when you need a starting
140point for your own a full C++ SystemVerilog grammar parser, using Bison and
141Flex.  It understands most of the SystemVerilog 2017 grammar (1800-2017
142Appendix A).
143
144=item Verilog::Preproc
145
146Verilog::Preproc is useful when you need only post-preprocessed text
147output, or a list of defines, includes, etc.  It can preprocess a file, or
148be used to provide the Verilog macro language on top of synthesis scripts.
149It understands and implements all preprocessor features of SystemVerilog
1502017.
151
152=item Verilog::Parser
153
154Verilog::Parser is useful when you need to tokenize or write source filters
155(where you need everything including whitespace).  It can take raw files,
156or preprocessed input, and generates callbacks.  It understands all
157SystemVerilog 2017 keywords.
158
159=item Abstract Syntax Tree
160
161Verilog::Parser knows enough to make a complete Abstract Syntax Tree (AST)
162of Verilog syntax. This represents all major constructs such as a "module"
163as a data structure, but does not interconnect the AST nodes as would be
164needed to follow signals.  Not all keywords have been implemented; many are
165parsed but otherwise ignored.  A complete Ast tree would allow any
166arbitrary transformation of Verilog syntax (everything is known excluding
167whitespace). For these applications consider Verilator's XML output
168(below).
169
170=item Verilog::SigParser
171
172Verilog::SigParser is useful when you need a list of modules, signals,
173ports, functions, etc.  It requires a preprocessed file (from
174Verilog::Preproc), and can parse all SystemVerilog 2017 files, but only
175provides callbacks on certain interesting things.  The SigParser operates
176only on a file at a time; it does not interconnect signals nor perform any
177elaboration (resolution of parameters).
178
179=item Verilog::Netlist
180
181Verilog::Netlist is useful for when you need the hierarchy, and a list of
182signals per module, pins per cell, etc.  It builds upon the output of
183Verilog::SigParser, so requires preprocessed files (from Verilog::Preproc).
184It parses all SystemVerilog 2017 files, but not all SystemVerilog
185constructs are loaded into objects. Verilog::Netlist interconnects modules
186with instantiations but does not perform any elaboration (resolution of
187parameters).
188
189=item VPI
190
191Using the VPI is the best way to access the behavior of the design.  It is
192not part of this package as it requires a compliant simulator and C++ code
193to call the VPI, and understands as much of the language as the simulator
194supports.  This allows writing lint checks and full knowledge of all parts
195of the code.  The VPI can operate ONLY on an elaborated design (where all
196parameters are resolved).  Walking a VPI tree general requires a good deal
197of work compared to simple scripting (though little work compared to
198writing a parser from scratch).
199
200=item Verilator
201
202The Verilator program also contains a very similar front end as
203Verilog-Perl and can create XML output showing the abstract syntax tree.
204Verilator also understands how to elaborate and connect complex pins and
205types, but supports mostly only the synthesis subset of SystemVerilog.
206
207If you're looking to parse only synthesizable code this is the recommended
208route.
209
210=item Verilog-Mode for Emacs
211
212Although not a parser, a common requested use of Verilog-Perl is to
213automatically make shell modules and interconnect modules.  Verilog-Mode is
214a better solution to this problem, as it results in completely portable
215code; the program (Verilog-Mode) isn't needed for others to update the
216design.  It's also in very common usage, including by many IP providers.
217
218=back
219
220=head1 INSTALLATION
221
222Skip this section if Verilog-Perl has already been installed.
223
224Verilog-Perl should run on any system with Perl, G++, Flex, and Bison.  It
225is known to work on most Linux distributions, plus Cygwin.
226
227You may install using either CPAN, or the sources.  If you plan to do any
228development on Verilog-Perl, use the sources.
229
230=head2 CPAN Installation
231
232Option 1: Easiest installation is using the "CPAN" command line that comes
233with Perl.  After configuring CPAN the first time, simply
234
235   cpan install Verilog-Perl
236   # And see the documentation
237   man Verilog-Perl
238   # Or, sometimes the capitalization is changed
239   man verilog-perl
240
241Read the rest of this file for details on the programs provided.
242
243=head2 Manual Installation from Repository
244
245Option 2: Build any version using the source development repository with:
246
247   git clone http://git.veripool.org/git/Verilog-Perl  # Only first time
248   cd Verilog-Perl
249   git pull        # Make sure we're up-to-date
250   git tag         # See what versions exist (recent GITs only)
251   #git checkout master      # Use development branch (e.g. recent bug fix)
252   #git checkout stable      # Use most recent release
253   #git checkout v{version}  # Switch to specified release version
254
255   perl Makefile.PL
256   # Ignore warning about README, this file will be generated
257   make
258   make test
259   make install
260
261Read the rest of this file for details on the programs provided.
262
263=head1 FAQ
264
265=over 4
266
267=item Why do I get "unexpected `do'" or "unexpected `bit'" errors?
268
269Do, bit, ref, return, and other words are now SystemVerilog keywords.  You
270should change your code to not use them to insure it works with newer
271tools.  Alternatively, surround them by the Verilog 2005/SystemVerilog
272begin_keywords pragma to indicate Verilog 2001 code.
273
274   `begin_keywords "1364-2001"
275      integer bit; initial bit = 1;
276   `end_keywords
277
278Alternatively use the --language (for vhier) or
279Verilog::Language::language_standard call to specify "1364-2001", or for
280really old code, "1364-1995".
281
282But, again, you really should fix the Verilog code.
283
284=item With Verilog::Netlist how do I resolve signal widths that include
285parameters down to constants?
286
287Unfortunately parameter resolution is part of elaboration.  Verilog-Perl
288doesn't do elaboration as it requires a good fraction of a complete
289simulator implementation.  Many applications can work around this
290limitation, if yours still requires elaboration you're stuck with using
291Verilator or the VPI, see the sections above.
292
293=back
294
295=head1 DISTRIBUTION
296
297Verilog-Perl is part of the L<https://www.veripool.org/> free Verilog EDA
298software tool suite.  The latest version is available from CPAN and from
299L<https://www.veripool.org/verilog-perl>.
300
301Copyright 2000-2021 by Wilson Snyder.  This package is free software; you
302can redistribute it and/or modify it under the terms of either the GNU
303Lesser General Public License Version 3 or the Perl Artistic License Version 2.0.
304
305This code is provided with no warranty of any kind, and is used entirely at
306your own risk.
307
308=head1 AUTHORS
309
310Wilson Snyder <wsnyder@wsnyder.org>
311
312=head1 SEE ALSO
313
314L<vhier>,
315L<vpassert>,
316L<vppreproc>,
317L<vrename>
318
319L<Verilog::EditFiles>,
320L<Verilog::Getopt>,
321L<Verilog::Language>
322L<Verilog::Netlist>,
323L<Verilog::Parser>,
324L<Verilog::Preproc>,
325L<Verilog::SigParser>
326
327L<Verilog::Netlist::Cell>,
328L<Verilog::Netlist::ContAssign>,
329L<Verilog::Netlist::File>,
330L<Verilog::Netlist::Interface>,
331L<Verilog::Netlist::ModPort>,
332L<Verilog::Netlist::Module>,
333L<Verilog::Netlist::Net>,
334L<Verilog::Netlist::Pin>,
335L<Verilog::Netlist::Port>,
336L<Verilog::Netlist::Subclass>,
337
338And the L<https://www.veripool.org/verilog-mode>Verilog-Mode package for Emacs.
339
340=cut
341