File: Verilog-Perl.pod

package info (click to toggle)
libverilog-perl 3.460-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 4,188 kB
  • sloc: perl: 8,640; yacc: 3,362; cpp: 2,262; lex: 1,487; makefile: 8; fortran: 3
file content (353 lines) | stat: -rw-r--r-- 11,203 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
# -*- Perl -*-
# See copyright, etc in below POD section.
######################################################################

=pod

=head1 NAME

Verilog-Perl - Overview of Verilog language packages for Perl

=head1 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
L<http://www.veripool.org/verilog-mode> Verilog-Mode.

=head1 INSTALLATION

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

=head2 Supported Systems

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

=over 4

=item * sparc-sun-solaris2.5.1

=item * i386-linux

=item * i686-w2k-cygwin

=back

=head2 CPAN Installation

=over 4

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.

=back

=head2 Manual Installation

=over 4

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

C<cd> to the directory containing this README notice.

Type C<perl Makefile.PL> to configure Verilog for your system.

Type C<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 C<make test> to check the package.  If you don't have
Synopsys' VCS, the test will print a warning, which you can ignore.

Type C<make install> to install the programs and any data files and
documentation.

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

=back

=head1 SCRIPTS

The following scripts are installed by Verilog-Perl:

=over 4

=item L<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.

=item L<vpassert>

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

=item L<vppreproc>

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

=item L<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.

=back

=head1 PACKAGES

=over 4

=item L<Verilog::Getopt|Verilog::Getopt>

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

=item L<Verilog::Language|Verilog::Language>

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

=item L<Verilog::Netlist|Verilog::Netlist>

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

=item L<Verilog::Netlist::Cell|Verilog::Netlist::Cell>

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

=item L<Verilog::Netlist::ContAssign|Verilog::Netlist::ContAssign>

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

=item L<Verilog::Netlist::File|Verilog::Netlist::File>

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

=item L<Verilog::Netlist::Module|Verilog::Netlist::Module>

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

=item L<Verilog::Netlist::Net|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.

=item L<Verilog::Netlist::Pin|Verilog::Netlist::Pin>

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

=item L<Verilog::Netlist::Port|Verilog::Netlist::Port>

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

=item L<Verilog::Netlist::Subclass|Verilog::Netlist::Subclass>

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

=item L<Verilog::Parser|Verilog::Parser>

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

=item L<Verilog::Preproc|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.

=item L<Verilog::SigParse|Verilog::SigParser>

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

=back

=head1 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.

=over 4

=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).

=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.

=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.

=item 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).

=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).

=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).

=item 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).

=item 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.

=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 IP providers.

=back

=head1 FAQ

=over 4

=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.

   `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.

=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 VPI, see the sections above.

=back

=head1 DISTRIBUTION

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

Copyright 2000-2019 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.

=head1 AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>

=head1 SEE ALSO

L<vhier>,
L<vpassert>,
L<vppreproc>,
L<vrename>

L<Verilog::EditFiles>,
L<Verilog::Getopt>,
L<Verilog::Language>
L<Verilog::Netlist>,
L<Verilog::Parser>,
L<Verilog::Preproc>,
L<Verilog::SigParser>

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

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

=cut