\input texinfo @c -*-texinfo-*-
@c $Revision: #22 $$Date: 2003/08/12 $$Author: wsnyder $
@c %**start of header
@setfilename readme.info
@settitle Perl SystemC Installation
@c %**end of header

@c DESCRIPTION: TexInfo: DOCUMENT source run through texinfo to produce README file
@c Use 'make README' to produce the output file

@node Top, Copyright, (dir), (dir)

This is the SystemC Perl Package, aka SystemPerl.

@menu
* Copyright::                   
* Summary::                     
* Description::                 
* SystemPerl Example::          
* Obtaining Distribution::      
* Supported Systems::           
* Installation::                
@end menu

@node Copyright, Summary, Top, Top
@section Copyright

This package is Copyright 2001 by Wilson Snyder @email{wsnyder@@wsnyder.org}.

You may distribute under the terms of either the GNU General Public License
or the Artistic License, as specified in the Perl README file.

This code is provided with no warranty of any kind, and is used entirely at
your own risk.

@node Summary, Description, Copyright, Top
@section Summary

The publicly licensed SystemPerl package provides several extensions to
SystemC.  It provides sp_preproc, extending the language for AUTOmatic
connection of hiearchy like my Verilog-Mode, trace files and netlist
linting.  Its netlist and parsing utilities are general enough for
writing your own tools.  Two additional tools provide for speeding up
GCC compiles and dependency correction.  You can download SystemC from
the link off of http://www.veripool.com/systemperl.html

@node Description, SystemPerl Example, Summary, Top
@section Description

This package provides several major sub-packages.  The SystemC::Parser
understands how to read SystemC files, and extract tokens and such,
similar to Verilog::Parser.

SystemC::Netlist builds netlists out of SystemC files.  This allows easy
scripts to determine things such as the hiearchy of SC_MODULEs.  The
netlist database may also be extended to support other languages.

sp_preproc provides extensions to the SystemC language, called the
SystemPerl language.  This allows most of the Tedium to be removed from
SystemC coding, just as the author's /*AUTO*/ comments did for the
Verilog language.  See @samp{man SystemPerl} after installation.

sp_include shows a technique for speeding up SystemC compiles using GCC.
sp_makecheck allows for cleaning up dependency files when dependencies
have been removed or changed.

Finally, the src directory contains useful C++ utilities for simulation,
such as changing cout to send to both the screen and a file.

Parsing example:

@example
    package Trialparser;
    @@ISA = qw(SystemC::Parser);

    sub module @{
        my $self = shift;
        my $module = shift;
        print $self->filename.":".$self->lineno().": ";
        print "Contains the module declaration for $module\n";
    @}

    package main;
    my $sp = Trialparser->new();
    $sp->read ("test.sp");
@end example

Netlist example:

@example
  use SystemC::Netlist;

    my $nl = new SystemC::Netlist ();
    foreach my $file ('testnetlist.sp') @{
        $nl->read_file (filename=>$file,
                        strip_autos=>1);
    @}
    $nl->link();
    $nl->autos();
    $nl->lint();
    $nl->exit_if_error();

    foreach my $mod ($nl->modules_sorted) @{
        show_hier ($mod, "  ");
    @}

    sub show_hier @{
        my $mod = shift;
        my $indent = shift;
        print $indent,"Module ",$mod->name,"\n";
        foreach my $cell ($mod->cells_sorted) @{
            show_hier ($cell->submod, $indent."  ".$cell->name."  ");
        @}
    @}
@end example

@node SystemPerl Example, Obtaining Distribution, Description, Top
@section SystemPerl Example

@example
SC_MODULE(mod) @{
    /*AUTOSIGNAL*/
    SC_CTOR(mod) @{
	SP_CELL (sub, submod);
	  /*AUTOINST*/
@end example

Becomes:

@example
SC_MODULE(mod) @{
    /*AUTOSIGNAL*/
    // Beginning of SystemPerl automatic signals
    sc_signal<bool>             a;       // For submod
    // End of SystemPerl automatic signals

    SC_CTOR(mod) @{
	SP_CELL (sub, submod);
	  /*AUTOINST*/
          // Beginning of SystemPerl automatic pins
	  SP_PIN (sub, a,	a);
          // End of SystemPerl automatic pins
@end example


@node Obtaining Distribution, Supported Systems, SystemPerl Example, Top
@section Obtaining Distribution

The latest version is available at 
@uref{http://www.perl.org/CPAN/}

Download the latest package from that site, and decompress.
@samp{gunzip SystemPerl_version.tar.gz ; tar xvf SystemPerl_version.tar}

@node Supported Systems, Installation, Obtaining Distribution, Top
@section Supported Systems

This version of SystemPerl has been built and tested on:

@itemize @bullet
@item i386-linux
@end itemize

It should run on any system with Perl, a C compiler, bison, and flex.

SystemC must be installed to get the complete function.  Currently
1.2.1beta and 2.0.1 are the versions supported for tracing, other
versions should work without tracing.

@node Installation,  , Supported Systems, Top
@section Installation

@enumerate
@item
@code{cd} to the directory containing this README notice.

@item
Type @samp{perl Makefile.PL} to configure SystemPerl for your system.
(Note this package will probably run slower if you are still using perl
5.005.)

@item
Type @samp{patch <patch-2-0-1.diff} if you are using SystemC 2.0.1.

@item
Type @samp{patch <patch-2-0-1-redhat9.diff} to fix the warnings in
SystemC 2.0.1 if you are using Redhat 9.  (SystemC.org still needs to
cleanup the libraries for Redhat 9; this mearly disables the warning
message.)

@item
If you wish to trace sc_bv's, and you got a informational message when
you did the above step, you must patch the SystemC library.  Type
@samp{make sc_patch} and this will be done for you.  What this does is
add an accessor function for getting at the raw data in the sc_bv
class.  (Using the preexisting public functions would require too much
computational overhead.)

@item
Type @samp{make} to compile SystemPerl.

@item
Type @samp{make test} to check the compilation.

@item
You can see examples under the test_dir directory.  The *.sp files are
"inline" converted, while the *.h and *.cpp files are expanded from the
.sp files.

@item
Type @samp{make install} to install the programs and any data files and
documentation.

@item
Install @samp{src/systemperl.h} somewhere in your project's build path.
The best place is probably the $SYSTEMC/include directory.

@end enumerate


