-----------------------------------------------
-- Title   : The 'loopstr' MachSUIF pass     --
-- Author  : Nikolaos Kavvadias              --
-- Contact : nkavv@skiathos.physics.auth.gr  --
-- Date    : 19 July 2004                    --
-- Version : 1.0 (initial release)           --
-----------------------------------------------

INTRODUCTION

'loopstr' is an analysis pass built to be used with the SUIF2/MachSUIF2 
compiler infrastructure. This pass generates a textual representation for the 
loop structure of each given C procedure.

This pass uses the cfa library of MachSUIF. What it actually generates is the 
natural loop analysis report for the procedure. The format of such file is 
shown below:

Loop info:
  node depth begin end exit
   int: int   Y/N  Y/N  Y/N
   ...................................

where:
  - node  : the number of the corresponding basic block (integer)
  - depth : the loop nesting depth (integer)
  - begin : a boolean flag to report if a loop begins at the specified node
  - end   : a boolean flag to report if a loop ends at the specified node
  - exit  : a boolean flag to report if an exit from the loop is possible
            from that node

This pass works for the SUIFvm instruction set as well as other MachSUIF 
backends. The 'loopstr' pass has been tested with MachSUIF 2.02.07.15.


INSTALLATION

Unpack the loopstr archive wherever you like, e.g. in $MACHSUIFHOME/cfa/loopstr.
You don't need to modify anything in the Makefile, if you have a working
MachSUIF 2 installation.

The program binary (do_loopstr) will be installed at $NCIHOME/bin and the
shared library (libloopstr.so) at $NCIHOME/solib, where NCIHOME is the SUIF 2
top-level directory.


USAGE DETAILS

The pass accepts an input file in CFG form to operate. Textual output is 
generated, written to stdout by default.

Usage synopsys:
%do_loopstr test.cfg


NOTES

Feel free to contact me at <nkavv@skiathos.physics.auth.gr> for any discussion
on the 'loopstr' pass or the usage of MachSUIF in general.

