This is the SystemC Perl Package, aka SystemPerl.

Copyright
=========

   This package is Copyright 2001 by Wilson Snyder
<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,
with the exception that it cannot be placed on a CD-ROM or similar
media for commercial distribution without the prior approval of the
author.

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

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

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 `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
dependancies 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:

         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");

   Netlist 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."  ");
             }
         }

SystemPerl Example
==================

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

   Becomes:

     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

Obtaining Distribution
======================

   The latest version is available at `http://www.perl.org/CPAN/'

   Download the latest package from that site, and decompress.  `gunzip
SystemPerl_version.tar.gz ; tar xvf SystemPerl_version.tar'

Supported Systems
=================

   This version of SystemC has been built and tested on:

   * i386-linux

   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 is the version supported for tracing, other versions should
work without tracing.

Installation
============

  1. `cd' to the directory containing this README notice.

  2. Type `perl Makefile.PL' to configure SystemC for your system.
     (Note this package will probably run slower if you are still using
     perl 5.005.)

  3. Type `make' to compile SystemC.

  4. Type `make test' to check the compilation.

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

  6. Type `make install' to install the programs and any data files and
     documentation.

  7. Install `src/systemperl.h' somewhere in your project's build path.
     The best place is probably the $SYSTEMC/include directory.

  8. If you wish to trace ports, you must edit the SystemC library.
     Search the header files for "get_cur_value", and add a public:
     declaration before it.  After doing so, create a
     $SYSTEMC/systemperl_patched file.  (SystemPerl will see this file
     and allow port tracing.)