diff options
Diffstat (limited to 'ghc/docs/users_guide')
| -rw-r--r-- | ghc/docs/users_guide/debugging.vsgml | 28 | ||||
| -rw-r--r-- | ghc/docs/users_guide/profiling.vsgml | 109 | ||||
| -rw-r--r-- | ghc/docs/users_guide/runtime_control.vsgml | 10 |
3 files changed, 143 insertions, 4 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> %************************************************************************ |