[project @ 1999-05-11 16:42:29 by keithw]

(this is number 5b of 9 commits to be applied together)

  The major purpose of this commit is to introduce usage information
  and usage analysis into the compiler, per the paper _Once Upon a
  Polymorphic Type_ (Keith Wansbrough and Simon Peyton Jones, POPL'99,
  and Glasgow TR-1998-19).

  An analysis is provided that annotates a Core program with optimal
  usage annotations.  This analysis is performed by -fusagesp
  (=CoreDoUSPInf), and requires -fusagesp-on (=opt_UsageSPOn).  This
  latter performs an analysis in tidyCorePgm, immediately before
  CoreToStg is done.  The driver flag -fusagesp currently provides hsc
  with -fusagesp-on, and if -O is on does a single -fusagesp early on
  in the Core-to-Core sequence.  Please change this as desired.

  *NB*: For now, -fusagesp with -O requires -fno-specialise.  Sorry.

  The flags -ddump-usagesp (=opt_D_dump_usagesp) and -dusagesp-lint
  (=opt_DoUSPLinting) (also -dnousagesp-lint to the driver) have been
  added and are documented in the User Guide.

4 files changed, 158 insertions, 7 deletions

diff --git a/ghc/docs/users_guide/debugging.vsgml b/ghc/docs/users_guide/debugging.vsgml
index cdf951c9cc..78842c7f57 100644
--- a/ghc/docs/users_guide/debugging.vsgml
+++ b/ghc/docs/users_guide/debugging.vsgml
@@ -109,6 +109,7 @@ need a short form...).  Some of the most useful ones are:
 @-ddump-ds@ | desugarer output @@
 @-ddump-simpl@ | simplifer output (Core-to-Core passes) @@
 @-ddump-stranal@ | strictness analyser output @@
+@-ddump-usagesp@ | UsageSP inference pre-inf and output @@
 @-ddump-occur-anal@ | `occurrence analysis' output @@
 @-ddump-spec@ | dump specialisation info @@
 @-ddump-stg@ | output of STG-to-STG passes @@
@@ -124,6 +125,7 @@ need a short form...).  Some of the most useful ones are:
 <nidx>-ddump-deriv option</nidx>%
 <nidx>-ddump-ds option</nidx>%
 <nidx>-ddump-simpl option</nidx>%
+<nidx>-ddump-usagesp option</nidx>%
 <nidx>-ddump-stranal option</nidx>%
 <nidx>-ddump-occur-anal option</nidx>%
 <nidx>-ddump-spec option</nidx>%
@@ -191,6 +193,32 @@ Have the renamer report what imports does not contribute.
 %-ddump-asm-globals-info
 
 %----------------------------------------------------------------------
+<sect2>Checking for consistency
+<label id="checking-consistency">
+<p>
+<nidx>consistency checks</nidx>
+<nidx>lint</nidx>
+
+<descrip>
+<tag>@-dcore-lint@:</tag>
+<nidx>-dcore-lint option</nidx>
+Turn on heavyweight intra-pass sanity-checking within GHC, at Core
+level.  (It checks GHC's sanity, not yours.)
+
+<tag>@-dstg-lint@:</tag>
+<nidx>-dstg-lint option</nidx>
+Ditto for STG level.
+
+<tag>@-dusagesp-lint@:</tag>
+<nidx>-dstg-lint option</nidx>
+Turn on checks around UsageSP inference (@-fusagesp@).  This verifies
+various simple properties of the results of the inference, and also
+warns if any identifier with a used-once annotation before the
+inference has a used-many annotation afterwards; this could indicate a
+non-worksafe transformation is being applied.
+</descrip>
+
+%----------------------------------------------------------------------
 <sect2>How to read Core syntax (from some @-ddump-*@ flags)
 <p>
 <nidx>reading Core syntax</nidx>
diff --git a/ghc/docs/users_guide/profiling.vsgml b/ghc/docs/users_guide/profiling.vsgml
index e83c726985..5b82b5515b 100644
--- a/ghc/docs/users_guide/profiling.vsgml
+++ b/ghc/docs/users_guide/profiling.vsgml
@@ -502,4 +502,111 @@ appropriate libraries and things when you made the system.  See
 ``Customising what libraries to build,'' in the installation guide.
 
 To get your compiled program to spit out the ticky-ticky numbers, use
-a @-r@ RTS option<nidx>-r RTS option</nidx>.
+a @-r@ RTS option<nidx>-r RTS option</nidx>.  See Section <ref
+name="Running a compiled program" id="runtime-control">.
+
+Compiling your program with the @-ticky@ switch yields an executable
+that performs these counts.  Here is a sample ticky-ticky statistics
+file, generated by the invocation @foo +RTS -rfoo.ticky@.
+
+<tscreen> <verb>
+foo +RTS -rfoo.ticky
+
+
+ALLOCATIONS: 3964631 (11330900 words total: 3999476 admin, 6098829 goods, 1232595 slop)
+				total words:	    2     3     4     5    6+
+  69647 (  1.8%) function values		 50.0  50.0   0.0   0.0   0.0
+2382937 ( 60.1%) thunks				  0.0  83.9  16.1   0.0   0.0
+1477218 ( 37.3%) data values			 66.8  33.2   0.0   0.0   0.0
+      0 (  0.0%) big tuples
+      2 (  0.0%) black holes			  0.0 100.0   0.0   0.0   0.0
+      0 (  0.0%) prim things
+  34825 (  0.9%) partial applications		  0.0   0.0   0.0 100.0   0.0
+      2 (  0.0%) thread state objects		  0.0   0.0   0.0   0.0 100.0
+
+Total storage-manager allocations: 3647137 (11882004 words)
+	[551104 words lost to speculative heap-checks]
+
+STACK USAGE:
+
+ENTERS: 9400092  of which 2005772 (21.3%) direct to the entry code
+		  [the rest indirected via Node's info ptr]
+1860318 ( 19.8%) thunks
+3733184 ( 39.7%) data values
+3149544 ( 33.5%) function values
+		  [of which 1999880 (63.5%) bypassed arg-satisfaction chk]
+ 348140 (  3.7%) partial applications
+ 308906 (  3.3%) normal indirections
+      0 (  0.0%) permanent indirections
+
+RETURNS: 5870443
+2137257 ( 36.4%) from entering a new constructor
+		  [the rest from entering an existing constructor]
+2349219 ( 40.0%) vectored [the rest unvectored]
+
+RET_NEW:         2137257:  32.5% 46.2% 21.3%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
+RET_OLD:         3733184:   2.8% 67.9% 29.3%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
+RET_UNBOXED_TUP:       2:   0.0%  0.0%100.0%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
+
+RET_VEC_RETURN : 2349219:   0.0%  0.0%100.0%  0.0%  0.0%  0.0%  0.0%  0.0%  0.0%
+
+UPDATE FRAMES: 2241725 (0 omitted from thunks)
+SEQ FRAMES:    1
+CATCH FRAMES:  1
+UPDATES: 2241725
+      0 (  0.0%) data values
+  34827 (  1.6%) partial applications
+		  [2 in place, 34825 allocated new space]
+2206898 ( 98.4%) updates to existing heap objects (46 by squeezing)
+UPD_CON_IN_NEW:         0:       0      0      0      0      0      0      0      0      0
+UPD_PAP_IN_NEW:     34825:       0      0      0  34825      0      0      0      0      0
+
+NEW GEN UPDATES: 2274700 ( 99.9%)
+
+OLD GEN UPDATES: 1852 (  0.1%)
+
+Total bytes copied during GC: 190096
+
+**************************************************
+3647137 ALLOC_HEAP_ctr
+11882004 ALLOC_HEAP_tot
+  69647 ALLOC_FUN_ctr
+  69647 ALLOC_FUN_adm
+  69644 ALLOC_FUN_gds
+  34819 ALLOC_FUN_slp
+  34831 ALLOC_FUN_hst_0
+  34816 ALLOC_FUN_hst_1
+      0 ALLOC_FUN_hst_2
+      0 ALLOC_FUN_hst_3
+      0 ALLOC_FUN_hst_4
+2382937 ALLOC_UP_THK_ctr
+      0 ALLOC_SE_THK_ctr
+ 308906 ENT_IND_ctr
+      0 E!NT_PERM_IND_ctr requires +RTS -Z
+[... lots more info omitted ...]
+      0 GC_SEL_ABANDONED_ctr
+      0 GC_SEL_MINOR_ctr
+      0 GC_SEL_MAJOR_ctr
+      0 GC_FAILED_PROMOTION_ctr
+  47524 GC_WORDS_COPIED_ctr
+</verb> </tscreen>
+
+The formatting of the information above the row of asterisks is
+subject to change, but hopefully provides a useful human-readable
+summary.  Below the asterisks <em>all counters</em> maintained by the
+ticky-ticky system are dumped, in a format intended to be
+machine-readable: zero or more spaces, an integer, a space, the
+counter name, and a newline.
+
+In fact, not <em>all</em> counters are necessarily dumped; compile- or
+run-time flags can render certain counters invalid.  In this case,
+either the counter will simply not appear, or it will appear with a
+modified counter name, possibly along with an explanation for the
+omission (notice @ENT_PERM_IND_ctr@ appears with an inserted @!@
+above).  Software analysing this output should always check that it
+has the counters it expects.  Also, beware: some of the counters can
+have <em>large</em> values!
+<p>
+
+
+
diff --git a/ghc/docs/users_guide/runtime_control.vsgml b/ghc/docs/users_guide/runtime_control.vsgml
index 1ab72dc683..464483aa24 100644
--- a/ghc/docs/users_guide/runtime_control.vsgml
+++ b/ghc/docs/users_guide/runtime_control.vsgml
@@ -251,7 +251,9 @@ The @<file>@ business works just like on the @-S@ RTS option (above).
 @-ticky@<nidx>-ticky option</nidx> (a.k.a. ``ticky-ticky profiling''),
 and, for it to be really useful, linked with suitable system
 libraries.  Not a trivial undertaking: consult the installation guide
-on how to set things up for easy ``ticky-ticky'' profiling.
+on how to set things up for easy ``ticky-ticky'' profiling.  For more
+information, see Section <ref name="Using ``ticky-ticky'' profiling
+(for implementors)" id="ticky-ticky">.
 
 <tag>@-D<num>@:</tag>
 <nidx>-D RTS option</nidx>
@@ -275,8 +277,10 @@ bits are set in @<num>@.  Only works if the RTS was compiled with the
 
 <tag>@-Z@:</tag>
 <nidx>-Z RTS option</nidx>
-Turn <em>off</em> ``update-frame squeezing'' at garbage-collection time.
-(There's no particularly good reason to turn it off.)
+Turn <em>off</em> ``update-frame squeezing'' at garbage-collection
+time.  (There's no particularly good reason to turn it off, except to
+ensure the accuracy of certain data collected regarding thunk entry
+counts.)
 </descrip>
 
 %************************************************************************
diff --git a/ghc/driver/ghc.lprl b/ghc/driver/ghc.lprl
index 868bfeff6a..8dbeef2e52 100644
--- a/ghc/driver/ghc.lprl
+++ b/ghc/driver/ghc.lprl
@@ -231,6 +231,7 @@ sub setupOptFlags {
    $Oopt_FB_Support		  = ''; # was '-fdo-arity-expand';
 #  $Oopt_FoldrBuildWW		  = 0; # Off by default
    $Oopt_FoldrBuildInline	  = ''; # was '-fdo-inline-foldr-build';
+   $Oopt_UsageSPInf               = ''; # Off by default
    $Oopt_ShowSimplifierProgress   = '';
 } # end of setupOptFlags
 
@@ -438,6 +439,7 @@ $OptLevel      = 0; # no -O == 0; -O == 1; -O2 == 2; -Ofile == 3
 $MinusO2ForC   = 0; # set to 1 if -O2 should be given to C compiler
 $StolenX86Regs = 4; # **HACK*** of the very worst sort
 $CoreLint      = '';
+$USPLint       = '';
 $StgLint       = '';
 
 @Import_dir	= ('.'); #-i things
@@ -733,7 +735,7 @@ sub setupOptimiseFlags {
 	  ']',
 	$Oopt_AddAutoSccs,
 #	'-ffull-laziness',	# removed 95/04 WDP following Andr\'e's lead
-	
+
 	$Oopt_FinalStgProfilingMassage
       );
 
@@ -785,6 +787,9 @@ sub setupOptimiseFlags {
 	  $Oopt_DoSpecialise,
 	) : (),
 
+        $Oopt_UsageSPInf, # infer usage information here in case we need it later.
+                          # (add more of these where you need them --KSW 1999-04)
+
 	'-fsimplify', 		# need dependency anal after specialiser ...
 	  '[', 			# need tossing before calc-inlinings ...
 	  $Oopt_FB_Support,
@@ -1900,13 +1905,13 @@ sub runHsc {
 
       local($to_do_opts) = "$Tmp_prefix.opts";
       open(OPTS, "> $Tmp_prefix.opts") || &tidy_up_and_die(1,"Can't open $Tmp_prefix.opts\n");
-      print OPTS "$dump @HsC_flags $CoreLint $StgLint $Verbose";
+      print OPTS "$dump @HsC_flags $CoreLint $USPLint $StgLint $Verbose";
       close(OPTS);
       $to_do = "$HsC @HsP_flags ,$hscpp_hsc \@$Tmp_prefix.opts $output +RTS @HsC_rts_flags";
 
     } else {
 
-      $to_do = "$HsC @HsP_flags ,$hscpp_hsc $dump @HsC_flags $CoreLint $StgLint $Verbose $output +RTS @HsC_rts_flags";
+      $to_do = "$HsC @HsP_flags ,$hscpp_hsc $dump @HsC_flags $CoreLint $USPLint $StgLint $Verbose $output +RTS @HsC_rts_flags";
     }
     &run_something($to_do, 'Haskell compiler');
 
@@ -3216,6 +3221,10 @@ arg: while($_ = $Args[0]) {
     /^-fno-speciali[sz]e$/
 		&& do { $Oopt_DoSpecialise = ''; next arg; };
 
+    /^-fusagesp$/
+                && do {  $Oopt_UsageSPInf = '-fusagesp';
+                         push (@HsC_flags, '-fusagesp-on'); next arg; };
+
     /^-fcompiling-prelude$/ && do { $CompilingPrelude=1; push(@HsC_flags, $_); next arg; };
 
 # Now the foldr/build options, which are *on* by default (for -O).
@@ -3323,6 +3332,9 @@ arg: while($_ = $Args[0]) {
     # -d(no-)core-lint is done this way so it is turn-off-able.
     /^-dcore-lint/       && do { $CoreLint = '-dcore-lint'; next arg; };
     /^-dno-core-lint/    && do { $CoreLint = '';    	    next arg; };
+    # Ditto for USP lint
+    /^-dusagesp-lint/    && do { $USPLint = '-dusagesp-lint'; next arg; };
+    /^-dno-usagesp-lint/ && do { $USPLint = '';               next arg; };
     # Ditto for STG lint
     /^-dstg-lint/       && do { $StgLint = '-dstg-lint'; next arg; };
     /^-dno-stg-lint/    && do { $StgLint = '';           next arg; };