1 SystemPerl
************

This is the SystemC Perl Package, aka SystemPerl.

1.1 Copyright
=============

This package is Copyright 2001-2009 by Wilson Snyder
<wsnyder@wsnyder.org>.

   You may distribute under the terms of either the GNU Lesser General
Public License or the Perl 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.

1.2 Summary
===========

The publicly licensed SystemPerl package provides several extensions to
SystemC.  It provides sp_preproc, extending the language for AUTOmatic
connection of hierarchy 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.org/systemperl

1.3 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 hierarchy 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 SystemC::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:

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

1.4 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

1.5 Obtaining Distribution
==========================

SystemPerl is part of the L<http://www.veripool.org/> free SystemC
software tool suite.  The latest version is available from
`http://www.perl.org/CPAN/' and from
`http://www.veripool.org/systemperl'.

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

1.6 Supported Systems
=====================

This version of SystemPerl 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, 2.0.1, 2.1 and 2.2 are the versions supported for tracing,
other versions should work without tracing or with minor editing.

1.7 Installation
================

  1. `cd' to the directory containing this README notice.  Some files
     will permanently live in this directory, so make sure it's in a
     site wide area.

  2. Make sure the `SYSTEMC' environment variable points to your
     SystemC installed directory.  If using bash, this would consist of
     the line     `export SYSTEMC=/path/to/systemc' in your `~/.bashrc'
     file.

     If different than the above, make sure the `SYSTEMC_KIT'
     environment variable points to your original SystemC source code
     kit.

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

     You may get a warning message about needing Verilog::Netlist, if
     so you need to install or upgrade the `verilog-perl' package from
     CPAN.

  4. To trace sc_bv's, you must patch the SystemC library.  Type as root
     `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.)

     This will also patch SystemC to work with Redhat 9 distributions
     (GCC 3.2.2).  If you were not able to compile SystemC due to
     compile errors, it may now work.

  5. Type `make' to compile SystemPerl.

     If you get a error message "y.tab.c: error: parse error before
     goto," there is a problem between Bison and GCC.  The simplest fix
     is to edit y.tab.c to comment out "__attribute__ ((unused))".

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

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

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

  9. Add a `SYSTEMPERL' environment variable that points to the
     directory of this kit (the directory you typed "make install"
     inside, not your site-perl directory.)  If using bash, this would
     consist of the line   `export SYSTEMPERL=/path/to/systemperl' in
     your `~/.bashrc' file.


