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