@-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 @@
<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>%
%-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>
``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>
+
+
+
@-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>
<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>
%************************************************************************
$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
$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
']',
$Oopt_AddAutoSccs,
# '-ffull-laziness', # removed 95/04 WDP following Andr\'e's lead
-
+
$Oopt_FinalStgProfilingMassage
);
$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,
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');
/^-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).
# -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; };