.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SigParser 3pm"
.TH SigParser 3pm 2024-01-27 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Verilog::SigParser \- Signal Parsing for Verilog language files
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use Verilog::Preproc;
\&  use Verilog::SigParser;
\&
\&  my $pp = Verilog::Preproc\->new(keep_comments=>0,);
\&
\&  my $parser = new Verilog::SigParser;
\&  $parser\->parse_preproc_file($pp);
\&  # The below described callbacks are then invoked
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Verilog::SigParser builds upon the Verilog::Parser module to provide
callbacks for when a signal is declared, a module instantiated, or a module
defined.
.PP
See the "Which Package" section of Verilog::Language if you are unsure
which parsing package to use for a new application.  For a higher level
interface to this package, see Verilog::Netlist.
.SH METHODS
.IX Header "METHODS"
The method interface to Verilog::SigParser is described in the
Verilog::Parser module which this package inherits.  You will probably want
to use the preprocessing option of Verilog::Parser with this package.
.SH CALLBACKS
.IX Header "CALLBACKS"
In order to make the parser do anything interesting, you must make a
subclass where you override one or more of the following methods as
appropriate.
.PP
Note Verilog::Parser callbacks also are invoked when SigParser is parsing.
.ie n .IP $self\->attribute($text) 4
.el .IP \f(CW$self\fR\->attribute($text) 4
.IX Item "$self->attribute($text)"
Scanned an attribute or meta-comment.  The parser inspects the first word
of each comment line (\f(CW\*(C`//key rest\*(C'\fR to end of line) or comment block
(\f(CW\*(C`/*key rest */).  It calls \*(C`$self\-\*(C'attribute( meta_text )\*(C'\fR
if the first word has a true value in hash \f(CW\*(C`$self\-\*(C'\fRmetacomment>.
.ie n .IP "$self\->class($token, $name, $virtual)" 4
.el .IP "\f(CW$self\fR\->class($token, \f(CW$name\fR, \f(CW$virtual\fR)" 4
.IX Item "$self->class($token, $name, $virtual)"
This method is called at a class.
.ie n .IP "$self\->covergroup($token, $name)" 4
.el .IP "\f(CW$self\fR\->covergroup($token, \f(CW$name\fR)" 4
.IX Item "$self->covergroup($token, $name)"
This method is called at a covergroup.
.ie n .IP "$self\->contassign($token, $lhs, $rhs)" 4
.el .IP "\f(CW$self\fR\->contassign($token, \f(CW$lhs\fR, \f(CW$rhs\fR)" 4
.IX Item "$self->contassign($token, $lhs, $rhs)"
This method is called at a continuous "assign" keyword, with the left and
right hand part of the assignment.  Note that "wire" initializations are
not considered assignments; those are received via the var callback's value
parameter.
.ie n .IP "$self\->defparam($token, $lhs, $rhs)" 4
.el .IP "\f(CW$self\fR\->defparam($token, \f(CW$lhs\fR, \f(CW$rhs\fR)" 4
.IX Item "$self->defparam($token, $lhs, $rhs)"
This method is called at a "defparam" keyword, with the left and right hand
part of the assignment.
.ie n .IP $self\->endcell($token) 4
.el .IP \f(CW$self\fR\->endcell($token) 4
.IX Item "$self->endcell($token)"
This method is called at the end of defining a cell. It is useful for
writing clean up routines.
.ie n .IP $self\->endgroup($token) 4
.el .IP \f(CW$self\fR\->endgroup($token) 4
.IX Item "$self->endgroup($token)"
This method is called at the end of defining a covergroup. It is useful for
writing clean up routines.
.ie n .IP $self\->endinterface($token) 4
.el .IP \f(CW$self\fR\->endinterface($token) 4
.IX Item "$self->endinterface($token)"
This method is called at a endinterface keyword. It is useful for writing
clean up routines.
.ie n .IP $self\->endclass($token) 4
.el .IP \f(CW$self\fR\->endclass($token) 4
.IX Item "$self->endclass($token)"
This method is called at a endclass keyword.  It is useful for writing
clean up routines.
.ie n .IP $self\->endtaskfunc($token) 4
.el .IP \f(CW$self\fR\->endtaskfunc($token) 4
.IX Item "$self->endtaskfunc($token)"
This method is called at a endfunction or endtask keyword.  It is useful
for writing clean up routines.
.ie n .IP $self\->endmodport($token) 4
.el .IP \f(CW$self\fR\->endmodport($token) 4
.IX Item "$self->endmodport($token)"
This method is called at a endmodport keyword. It is useful for writing
clean up routines.
.ie n .IP $self\->endmodule($token) 4
.el .IP \f(CW$self\fR\->endmodule($token) 4
.IX Item "$self->endmodule($token)"
This method is called at a endmodule keyword. It is useful for writing
clean up routines.
.ie n .IP $self\->endpackage($token) 4
.el .IP \f(CW$self\fR\->endpackage($token) 4
.IX Item "$self->endpackage($token)"
This method is called at a endpackage keyword. It is useful for writing
clean up routines.
.ie n .IP $self\->endprogram($token) 4
.el .IP \f(CW$self\fR\->endprogram($token) 4
.IX Item "$self->endprogram($token)"
This method is called at a endprogram keyword. It is useful for writing
clean up routines.
.ie n .IP "$self\->function($keyword, $name, $data\-type)" 4
.el .IP "\f(CW$self\fR\->function($keyword, \f(CW$name\fR, \f(CW$data\fR\-type)" 4
.IX Item "$self->function($keyword, $name, $data-type)"
This method is called when a function is defined.  Type is the output size
or typename, plus "signed", for example "", "[3:0]", "integer", or "signed
[2:0]".
.ie n .IP "$self\->import($package, $id)" 4
.el .IP "\f(CW$self\fR\->import($package, \f(CW$id\fR)" 4
.IX Item "$self->import($package, $id)"
This method is called when an import is defined.
.ie n .IP "$self\->instant($module, $cell, $range)" 4
.el .IP "\f(CW$self\fR\->instant($module, \f(CW$cell\fR, \f(CW$range\fR)" 4
.IX Item "$self->instant($module, $cell, $range)"
This method is called when a instantiation is defined.  The first parameter
is the name of the module being instantiated. The second parameter is the
name of the cell, which may be "" for primitives.  The third is the range
if the cell was arrayed.
.Sp
Prior to version 3.000, the name of the parameters were also included in
this callback. This has been replaced with the parampin callback.
.ie n .IP "$self\->interface($keyword, $name)" 4
.el .IP "\f(CW$self\fR\->interface($keyword, \f(CW$name\fR)" 4
.IX Item "$self->interface($keyword, $name)"
This method is called when an interface is defined.
.ie n .IP "$self\->modport($keyword, $name)" 4
.el .IP "\f(CW$self\fR\->modport($keyword, \f(CW$name\fR)" 4
.IX Item "$self->modport($keyword, $name)"
This method is called when an interface modport is defined.
.ie n .IP "$self\->module($keyword, $name, ignored, $in_celldefine)" 4
.el .IP "\f(CW$self\fR\->module($keyword, \f(CW$name\fR, ignored, \f(CW$in_celldefine\fR)" 4
.IX Item "$self->module($keyword, $name, ignored, $in_celldefine)"
This method is called when a module is defined.
.ie n .IP "$self\->package($keyword, $name)" 4
.el .IP "\f(CW$self\fR\->package($keyword, \f(CW$name\fR)" 4
.IX Item "$self->package($keyword, $name)"
This method is called when a package is defined.
.ie n .IP "$self\->parampin($name, $connection, $index)" 4
.el .IP "\f(CW$self\fR\->parampin($name, \f(CW$connection\fR, \f(CW$index\fR)" 4
.IX Item "$self->parampin($name, $connection, $index)"
This method is called when a parameter is connected to an instantiation, IE
the "#(...)" syntax.  It is also used for UDP delays (Three calls for
"#(delay0,delay1,delay2)"), as the parser does not know if the
instantiation is for an UDP versus a module.
.ie n .IP "$self\->pin($name, $connection, $index)" 4
.el .IP "\f(CW$self\fR\->pin($name, \f(CW$connection\fR, \f(CW$index\fR)" 4
.IX Item "$self->pin($name, $connection, $index)"
This method is called when a pin on an instant is defined and "use_pinselects"
is not set (the default, see \fBpinselects()\fR below.  If a pin name
was not provided and the connection is by position, name will be '' or
undef.
.Sp
If you do not need the pin nor var nor port callbacks, consider the
"$self\->new (... use_vars=>0 ...)"  option to accelerate parsing.
.ie n .IP "$self\->pinselects($name, $connections, $index)" 4
.el .IP "\f(CW$self\fR\->pinselects($name, \f(CW$connections\fR, \f(CW$index\fR)" 4
.IX Item "$self->pinselects($name, $connections, $index)"
If "$self\->new (... use_pinselects=>1 ...)" is used this function is called
instead of "$self\->pin (...)".  The difference is that the second parameter
("$connections") is a Perl hash that contains all connected nets in the
case of concatenations including the MSB and LSB bounds used at these
locations.
.ie n .IP "$self\->port($name, $objof, $direction, $data_type, $array, $pinnum)" 4
.el .IP "\f(CW$self\fR\->port($name, \f(CW$objof\fR, \f(CW$direction\fR, \f(CW$data_type\fR, \f(CW$array\fR, \f(CW$pinnum\fR)" 4
.IX Item "$self->port($name, $objof, $direction, $data_type, $array, $pinnum)"
This method is called when a module port is defined.  It may be called
twice on a port if the 1995 style is used; the first call is made at the
port header, the second call at the input/output declaration.
.Sp
The first argument \f(CW$name\fR, is the name of the port.  \f(CW$objof\fR is what the port
is an object of ('module', 'function', etc).  \f(CW$direction\fR is the port
direction ('input', 'output', 'inout', 'ref', 'const ref', or 'interface').
\&\f(CW$data_type\fR is the data type ('reg', 'user_type_t', 'signed [31:0]', etc, or
for interfaces the "{interface_id}.{modport_name}").  \f(CW$array\fR is the
arraying of the port ('[1:0][2:0]', '', etc).  \f(CW$pinnum\fR is set to the pin
number for ANSI style declarations, and 0 for Verilog 1995 declarations
made outside the port list.
.Sp
If you do not need the pin nor var nor port callbacks, consider the
"$self\->new (... use_vars=>0 ...)"  option to accelerate parsing.
.ie n .IP "$self\->program($keyword, $name)" 4
.el .IP "\f(CW$self\fR\->program($keyword, \f(CW$name\fR)" 4
.IX Item "$self->program($keyword, $name)"
This method is called when a program is defined.
.ie n .IP "$self\->signal_decl($keyword, $signame, $vector, $mem, $signed, $value)" 4
.el .IP "\f(CW$self\fR\->signal_decl($keyword, \f(CW$signame\fR, \f(CW$vector\fR, \f(CW$mem\fR, \f(CW$signed\fR, \f(CW$value\fR)" 4
.IX Item "$self->signal_decl($keyword, $signame, $vector, $mem, $signed, $value)"
This method is no longer used, see \f(CW$self\fR\->var.
.ie n .IP "$self\->task($keyword, $name)" 4
.el .IP "\f(CW$self\fR\->task($keyword, \f(CW$name\fR)" 4
.IX Item "$self->task($keyword, $name)"
This method is called when a task is defined.
.ie n .IP "$self\->var($kwd, $name, $objof, $nettype, $data_type, $array, $value)" 4
.el .IP "\f(CW$self\fR\->var($kwd, \f(CW$name\fR, \f(CW$objof\fR, \f(CW$nettype\fR, \f(CW$data_type\fR, \f(CW$array\fR, \f(CW$value\fR)" 4
.IX Item "$self->var($kwd, $name, $objof, $nettype, $data_type, $array, $value)"
This method is called when a variable or net is defined.
.Sp
The first argument \f(CW$kwd\fR is how it was declared ('port', 'var', 'genvar',
\&'parameter', 'localparam', 'typedef') or if applicable a net type
('supply0', 'wire', etc). \f(CW$name\fR is the name of the variable.  \f(CW$objof\fR is
what the variable is an object of ('module', 'function', etc).  \f(CW$nettype\fR is
the net type if any was defined ('', 'supply0', 'wire', 'tri', etc).
\&\f(CW$data_type\fR is the data type ('user_type_t', '[31:0] signed', etc).  \f(CW$array\fR
is the arraying of the variable which is the text AFTER the variable name
('[1:0][2:0]', '', etc).  \f(CW$value\fR is what the variable was assigned to ('',
or expression).
.Sp
Note typedefs are included here, because "parameter type" is both a
variable and a type declaration.
.Sp
If you do not need the pin nor var nor port callbacks, consider the
"$self\->new (... use_vars=>0 ...)"  option to accelerate parsing.
.Sp
Below are some example declarations and the callbacks:
.Sp
.Vb 12
\&   reg [4:0]  vect = 5\*(Aqb10100;
\&   # VAR  \*(Aqvar\*(Aq \*(Aqvect\*(Aq \*(Aqmodule\*(Aq \*(Aq\*(Aq \*(Aqreg [4:0]\*(Aq \*(Aq\*(Aq \*(Aq5\*(Aqb10100\*(Aq
\&   wire (weak0, weak1) value = pullval;
\&   # VAR  \*(Aqnet\*(Aq \*(Aqvalue\*(Aq \*(Aqmodule\*(Aq \*(Aqwire\*(Aq \*(Aq\*(Aq \*(Aq\*(Aq \*(Aqpullval\*(Aq
\&   reg [1:0] mem [12:2];
\&   # VAR  \*(Aqvar\*(Aq \*(Aqmem\*(Aq \*(Aqmodule\*(Aq \*(Aq\*(Aq \*(Aqreg [1:0]\*(Aq \*(Aq[12:2]\*(Aq \*(Aq\*(Aq
\&   int n[1:2][1:3] = \*(Aq{\*(Aq{0,1,2}, \*(Aq{3{4}}};
\&   # verilog/parser_sv.v:121: VAR  \*(Aqvar\*(Aq \*(Aqn\*(Aq \*(Aqmodule\*(Aq \*(Aq\*(Aq \*(Aqint\*(Aq \*(Aq[1:2][1:3]\*(Aq \*(Aq\*(Aq{\*(Aq{0,1,2},\*(Aq{3}}\*(Aq
\&   module ( output logic [SZ\-1:0] o_sized );
\&   # VAR  \*(Aqport\*(Aq \*(Aqo_sized\*(Aq \*(Aqmodule\*(Aq \*(Aq\*(Aq \*(Aqlogic [SZ\-1:0]\*(Aq \*(Aq\*(Aq \*(Aq\*(Aq
\&   struct packed signed { bit [7:0] m_b; };
\&   # VAR  \*(Aqmember\*(Aq \*(Aqm_b\*(Aq \*(Aqstruct\*(Aq \*(Aq\*(Aq \*(Aqbit [7:0]\*(Aq \*(Aq\*(Aq \*(Aq\*(Aq
.Ve
.SH BUGS
.IX Header "BUGS"
This is being distributed as a baseline for future contributions.  Don't
expect a lot, the Parser is still naive, and there are many awkward cases
that aren't covered.
.PP
Note the SigParser is focused on extracting signal information.  It does
NOT extract enough information to derive general interconnect; for example
the contents of 'assign' statements are not parsed.
.SH DISTRIBUTION
.IX Header "DISTRIBUTION"
Verilog-Perl is part of the <https://www.veripool.org/> free Verilog EDA
software tool suite.  The latest version is available from CPAN and from
<https://www.veripool.org/verilog\-perl>.
.PP
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.
.SH AUTHORS
.IX Header "AUTHORS"
Wilson Snyder <wsnyder@wsnyder.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Verilog-Perl,
Verilog::Parser,
Verilog::Language,
Verilog::Netlist,
Verilog::Getopt