https://github.com/veripool/verilog-perl

Verilog parser, preprocessor, and related tools for the Verilog-Perl package
https://github.com/veripool/verilog-perl

Last synced: 2 months ago
JSON representation

Verilog parser, preprocessor, and related tools for the Verilog-Perl package

• Host: GitHub
• URL: https://github.com/veripool/verilog-perl
• Owner: veripool
• License: artistic-2.0
• Created: 2020-03-03T02:29:02.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2024-01-23T02:50:52.000Z (12 months ago)
• Last Synced: 2024-08-03T01:38:24.489Z (6 months ago)
• Language: Perl
• Homepage: https://www.veripool.org/verilog-perl
• Size: 1.8 MB
• Stars: 111
• Watchers: 12
• Forks: 32
• Open Issues: 7
• Metadata Files:
  • Readme: README.pod
  • Changelog: Changes
  • License: COPYING

Awesome Lists containing this project

README

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

Verilog-Perl is currently a mature tool. Bugs are fixed and IEEE language

capabilities updated as needed, but the basic features and API are not

expected to change.

For general information see L.

For specific details on each component, see that component's manpage.

You may also want to try the AUTO features present in

L Verilog-Mode.

=head1 SCRIPTS

The following scripts are installed by Verilog-Perl:

=over 4

=item L

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 will read the specified Verilog files and preprocess special

PLI assertions.

=item L

Vppreproc (Verilog-Perl Pre Processor) reads the Verilog files passed on the

command line and outputs preprocessed output.

=item L

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 provides standardized handling of options similar to

Verilog/VCS and cc/GCC.

=item L

Verilog::Language provides general utilities for using the Verilog

Language, such as parsing numbers or determining what keywords exist.

=item L

Verilog::Netlist reads and holds interconnect information about a whole

design database.

=item L

A Verilog::Netlist::Cell object is created by Verilog::Netlist for every

instantiation in the current module.

=item L

A Verilog::Netlist::ContAssign object is created by Verilog::Netlist for

every continuous assignment in the current module.

=item L

Verilog::Netlist::File allows Verilog::Netlist objects to be read and

written in Verilog format.

=item L

A Verilog::Netlist::Module object is created by Verilog::Netlist for every

module in the design.

=item L

A Verilog::Netlist::Net object is created by Verilog::Netlist::Module for

every signal and input/output declaration in the current module.

=item L

A Verilog::Netlist::Pin object is created by Verilog::Netlist::Cell for for

each pin connection on a cell.

=item L

A Verilog::Netlist::Port object is created by Verilog::Netlist::Module for

every port connection in the module.

=item L

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

Verilog::Netlist::* structures.

=item L

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

methods.

=item L

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::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 2023 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). For these applications consider 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 a subset of SystemVerilog.

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

=item slang

The SystemVerilog Language Services (slang) project L

provides various components for lexing, parsing, type checking, and

elaborating SystemVerilog code.  It's fast and supports UVM.

=item Surelog

The Surelog project L is a

SystemVerilog 2017 Pre-processor, Parser, Elaborator, and UHDM Compiler. It

handles UVM and provides an IEEE Design/TB C/C++ VPI and Python AST API.

=item SV-Parser

The Sv-parser project L is a

SystemVerilog parser library fully compliant with IEEE 1800-2017.  that

returns a concrete syntax tree.

=item Tree-Sitter-Verilog

The Tree-Sitter-Verilog project

L is a verilog grammar

for the JavaScript tree-sitter parser.

=item Verible

The Verible project L parses IEEE

1800-2017, with the ability to parse un-preprocessed source files.

=back

=head1 INSTALLATION

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

Verilog-Perl should run on any system with Perl, G++, Flex, and Bison.  It

is known to work on most Linux distributions, plus Cygwin.

You may install using either CPAN, or the sources.  If you plan to do any

development on Verilog-Perl, use the sources.

=head2 CPAN Installation

Option 1: Easiest installation is using the "CPAN" command line that comes

with Perl.  After configuring CPAN the first time, simply

   cpan install Verilog::Language

   # And see the documentation

   man Verilog-Perl

   # Or, sometimes the capitalization is changed

   man verilog-perl

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

=head2 Manual Installation from Repository

Option 2: Build any version using the source development repository with:

   git clone http://git.veripool.org/git/Verilog-Perl  # Only first time

   cd Verilog-Perl

   git pull        # Make sure we're up-to-date

   git tag         # See what versions exist (recent GITs only)

   #git checkout master      # Use development branch (e.g. recent bug fix)

   #git checkout stable      # Use most recent release

   #git checkout v{version}  # Switch to specified release version

   perl Makefile.PL

   # Ignore warning about README, this file will be generated

   make

   make test

   make install

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

=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 free Verilog EDA

software tool suite.  The latest version is available from CPAN and from

L.

Copyright 2000-2024 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 

=head1 SEE ALSO

L,

L,

L,

L

L,

L,

L

L,

L,

L,

L

L,

L,

L,

L,

L,

L,

L,

L,

L,

L,

And the LVerilog-Mode package for Emacs.

=cut