Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Verilog::CodeGen.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CodeGen 3"
.TH CodeGen 3 "2003-05-09" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Verilog::CodeGen;
.Ve
.PP
.Vb 2
\&  mkdir 'DeviceLibs/Objects/YourDesign', 0755;
\&  chdir 'DeviceLibs/Objects/YourDesign';
.Ve
.PP
.Vb 3
\&  # if the directory YourDesign exists, the second argument can be omitted 
\&  # create YourModule.pl in YourDesign 
\&  &create_template_file('YourModule','YourDesign');
.Ve
.PP
.Vb 2
\&  # create a device library for testing in DeviceLibs/Objects/DeviceLibs
\&  &make_module('YourModule','YourDesign');
.Ve
.PP
.Vb 2
\&  # create the final device library in DeviceLibs (once YourModule code is clean)
\&  &make_module('','YourDesign');
.Ve
.SH "USAGE"
.IX Header "USAGE"
The most efficient way to use the code generator is using the \s-1GUI\s0 (\*(L"gui.pl\*(R" in scripts in the distribution). Read the documentation in Verilog::CodeGen::Gui.pm). Alternatively, you can use the scripts that the \s-1GUI\s0 uses to do the work (in the scripts/GUI folder). If you want to make your own, follow the \s-1SYNOPSIS\s0.
.PP
Then edit the file YourModule.pl in the folder DeviceLibs/Objects/YourDesign. 
.PP
For example:
.PP
.Vb 3
\&        sub gen_YourModule {    
\&        my $objref=shift;
\&        my $par=$objref->{parname}||1;
.Ve
.PP
.Vb 1
\&        # Create Objects
.Ve
.PP
.Vb 1
\&        my $submodule=new('SubModule',parname1=>$par);
.Ve
.PP
.Vb 1
\&        # Instantiate
.Ve
.PP
.Vb 14
\&        my $pins="(A,Z)";
\&        my $modname=$objref->{modulename};
\&        my $code = "
\&        module $modname $pins;
\&        input A;
\&        output Z;
\&        ";
\&        $code.=$submodule->inst('suffix',P1=>'A');
\&        $code .="
\&        endmodule // $modname
\&        ";
\&        $objref->{pins}=$pins;
\&        return $code;
\&        } # END of gen_YourModule
.Ve
.PP
Then run \f(CW\*(C`perl YourModule.pl\*(C'\fR to check if the code produces valid a Verilog module.
.PP
If this is the case, add YourModule to the device library with \f(CW\*(C`&make_module()\*(C'\fR
.PP
Next, create a testbench test_YourModule.pl in a directory on the same level as DeviceLibs (TestObj if you use the \s-1GUI\s0):
.PP
.Vb 2
\&        use lib '..';
\&        use DeviceLibs::YourDesign;
.Ve
.PP
.Vb 1
\&        my $device=new("S_buffer_demux",depth=>7,);
.Ve
.PP
.Vb 1
\&        open (VER,">test_S_buffer_demux.v");
.Ve
.PP
.Vb 1
\&        output(*VER);
.Ve
.PP
.Vb 1
\&        modules();
.Ve
.PP
.Vb 6
\&        print VER "
\&        module test_S_buffer_demux;
\&           wire A;
\&           wire [7:0] S;
\&           wire [6:0] Z;
\&           wire D;
.Ve
.PP
.Vb 2
\&           reg a;
\&           reg [7:0] s;
.Ve
.PP
.Vb 2
\&        assign    A=   a;
\&        assign     S=    s;
.Ve
.PP
.Vb 4
\&        reg _ck;
\&        ";
\&        $device->instance();
\&        my $x=$device->{""};
.Ve
.PP
.Vb 5
\&        print VER "
\&        // clock generator
\&        always begin: clock_wave
\&           #10 _ck = 0;
\&           #10 _ck = 1;
.Ve
.PP
.Vb 1
\&        end
.Ve
.PP
.Vb 4
\&        always @(posedge _ck)
\&        begin
\&        \e$display(\e" \e%0d  \e%b \e%b \e",\e$time,$x.   Z,$x.   D);
\&        end
.Ve
.PP
.Vb 14
\&        initial 
\&        begin
\&        \e$display(\e"Time     Z    D\e");
\&        a<=1;
\&        #25;
\&        a<=0;
\&        #25;
\&        \e$finish;
\&        end
\&        endmodule
\&        ";
\&        close VER;
\&        run("test_S_buffer_demux.v");
\&        #plot("test_S_buffer_demux.v");
.Ve
.PP
Execute the testbench script with \f(CW\*(C`perl test_YourModule.pl\*(C'\fR.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides an  object-oriented environment to generate Verilog code for modules and testbenches. The Verilog::CodeGen module provides two functions, one to create a code template and another to create a Perl module which contains the device library. This module , DeviceLibs::YourDesign, provides the class methods and contains the objects for every Verilog module; the objects are created based on a fixed template.
The purpose of this module is to allow the generation of customized Verilog modules. A Verilog module can have a large number of parameters like input and output bus width, buffer depth, signal delay etc. The code generator allows to create an object that will generate the Verilog module code for arbitraty values of the parameters.
.SH "UTILITY SCRIPTS"
.IX Header "UTILITY SCRIPTS"
With the Perl module distribution come a number of utility scripts. The most important one is gui.pl, a \s-1GUI\s0 frontend for Verilog development using the code generator.
.SH "MAIN METHODS"
.IX Header "MAIN METHODS"
.Sh "\fBnew\fP(\fI$object_name\fP[,%attributes]);"
.IX Subsection "new($object_name[,%attributes]);"
Create a new Verilog module object. The object attributes are optional, the object should provide reasonable defaults.
.Sh "\fBoutput([*filehandle_ref||$filename])\fP"
.IX Subsection "output([*filehandle_ref||$filename])"
\&\fIoutput()\fR takes a reference to a filehandle or a filename as argument. These are stored in the global \f(CW%printcfg\fR. Without arguments, this defaults to \s-1STDOUT\s0.
If \fIoutput()\fR is called with as argument a string containing \en and/or \es, this string is printed on the current filehandle.
.Sh "\fBmodules\fP"
.IX Subsection "modules"
The code generator stores all submodules of a given module in the global \f(CW%modules\fR. Calling \fImodules()\fR prints the code for these modules on the current filehandle.
.Sh "\fBinstance([$instance_suffix,%connectivity])\fP"
.IX Subsection "instance([$instance_suffix,%connectivity])"
The \fIinstance()\fR method will print the code for the instantiation of the object on the current filehandle. An optional instance suffix can be specified (to distinguish between different instances of the same module), as well as the pin connectivity. If the connectivity for a pin is not specified, it defaults to the pin name. 
.Sh "\fBinst([$instance_suffix,%connectivity])\fP"
.IX Subsection "inst([$instance_suffix,%connectivity])"
The \fIinst()\fR method will return the code for the instantiation of the object as a string. An optional instance suffix can be specified (to distinguish between different instances of the same module), as well as the pin connectivity. If the connectivity for a pin is not specified, it defaults to the pin name. 
.Sh "\fBrun([$filename])\fP"
.IX Subsection "run([$filename])"
Run the netlist through the Icarus Verilog (http://www.icarus.com) open source verilog simulator. The filename is optional if it was specified with the \fIoutput()\fR method.
.Sh "\fBplot([$filename])\fP"
.IX Subsection "plot([$filename])"
Plot the result of the simulation with gtkwave. For this purpose, the \e$dumpvar and \e$dumpfile compiler directives must be present in the testbench code. The filename is optional if it was specified with the \fIoutput()\fR method.
.Sh "\fBmodule('modulename')\fP"
.IX Subsection "module('modulename')"
This method can be used to print the code for a specified module on the current filehandle.
.Sh "\fBsearch(/pattern/)\fP"
.IX Subsection "search(/pattern/)"
Search the verilog code for a given pattern.
.Sh "\fBfind_inst(/pattern/)\fP"
.IX Subsection "find_inst(/pattern/)"
Find all instances matching /pattern/ in the netlist.
.SH "MAIN ATTRIBUTES"
.IX Header "MAIN ATTRIBUTES"
.Sh "\fB{$instance_suffix}\fP"
.IX Subsection "{$instance_suffix}"
Returns the full instance name of the object. 
\&\f(CW$x\fR=$object\->{$instance_suffix};
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Convert the utility scripts to functions to be called from Verilog::CodeGen.
.IP "\(bu" 4
Put the \s-1GUI\s0 scripts in a module Gui.pm.
.IP "\(bu" 4
Separate the code for testing purposes from the module object code.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Icarus Verilog <http://icarus.com/eda/verilog/index.html>
.SH "AUTHOR"
.IX Header "AUTHOR"
W. Vanderbauwhede \fBwim@motherearth.org\fR.
.PP
<http://www.comms.eee.strath.ac.uk/~wim>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2002 Wim Vanderbauwhede. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.