From: Josef Weidendorfer Date: Fri, 24 Oct 2008 18:50:04 +0000 (+0000) Subject: Callgrind manual: add section on client requests and note about fork(). X-Git-Tag: svn/VALGRIND_3_4_0~189 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f7757e3ac6c4403994e4b2a97596d8e5a986c985;p=thirdparty%2Fvalgrind.git Callgrind manual: add section on client requests and note about fork(). git-svn-id: svn://svn.valgrind.org/valgrind/trunk@8705 --- diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index 9d638ad8e8..e94d4e953e 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -197,7 +197,7 @@ on heuristics to detect calls and returns. callgrind_control -i on just before the interesting code section is executed. To exactly specify the code position where profiling should start, use the client request - CALLGRIND_START_INSTRUMENTATION. + . If you want to be able to see assembly code level annotation, specify . This will produce @@ -292,18 +292,13 @@ callgrind.out.pid.part-threa Program controlled dumping. - Put ]]> - into your source and add - CALLGRIND_DUMP_STATS; when you - want a dump to happen. Use - CALLGRIND_ZERO_STATS; to only - zero cost centers. - In Valgrind terminology, this method is called "Client - requests". The given macros generate a special instruction - pattern with no effect at all (i.e. a NOP). When run under - Valgrind, the CPU simulation engine detects the special - instruction pattern and triggers special actions like the ones - described above. + Insert + ; + at the position in your code where you want a profile dump to happen. Use + ; to only + zero profile counters. + See for more information on + Callgrind specific client requests. @@ -338,8 +333,8 @@ callgrind.out.pid.part-threa with callgrind_control -i on and off by specifying "off" instead of "on". Furthermore, instrumentation state can be programatically changed with - the macros CALLGRIND_START_INSTRUMENTATION; - and CALLGRIND_STOP_INSTRUMENTATION;. + the macros ; + and ;. In addition to enabling instrumentation, you must also enable @@ -471,6 +466,27 @@ callgrind.out.pid.part-threa + + Forking Programs + + If your program forks, the child will inherit all the profiling + data that has been gathered for the parent. To start with empty profile + counter values in the child, the client request + ; + can be inserted into code to be executed by the child, directly after + fork(). + + However, you will have to make sure that the output file format string + (controlled by ) does contain + (which is true by default). Otherwise, the + outputs from the parent and child will overwrite each other or will be + intermingled, which almost certainly is not what you want. + + You will be able to control the new child independently from + the parent via callgrind_control. + + + @@ -701,7 +717,7 @@ Also see . - + @@ -733,13 +749,9 @@ Also see . specification of --toggle-collect implicitly sets --collect-state=no. - Collection state can be toggled also by using a Valgrind - Client Request in your application. For this, include - valgrind/callgrind.h and specify - the macro - CALLGRIND_TOGGLE_COLLECT at the - needed positions. This only will have any effect if run under - supervision of the Callgrind tool. + Collection state can be toggled also by inserting the client request + ; + at the needed code positions. @@ -912,4 +924,94 @@ Also see . + +Callgrind specific client requests + +In Valgrind terminology, a client request is a C macro which +can be inserted into your code to request specific functionality when +run under Valgrind. For this, special instruction patterns resulting +in NOPs are used, but which can be detected by Valgrind. + +Callgrind provides the following specific client requests. +To use them, add the line +]]> +into your code for the macro definitions. +. + + + + + + CALLGRIND_DUMP_STATS + + + Force generation of a profile dump at specified position + in code, for the current thread only. Written counters will be reset + to zero. + + + + + + CALLGRIND_DUMP_STATS_AT(string) + + + Same as CALLGRIND_DUMP_STATS, but allows to specify a string + to be able to distinguish profile dumps. + + + + + + CALLGRIND_ZERO_STATS + + + Reset the profile counters for the current thread to zero. + + + + + + CALLGRIND_TOGGLE_COLLECT + + + Toggle the collection state. This allows to ignore events + with regard to profile counters. See also options + and + . + + + + + + CALLGRIND_START_INSTRUMENTATION + + + Start full Callgrind instrumentation if not already switched on. + When cache simulation is done, this will flush the simulated cache + and lead to an artifical cache warmup phase afterwards with + cache misses which would not have happened in reality. + See also option . + + + + + + CALLGRIND_STOP_INSTRUMENTATION + + + Stop full Callgrind instrumentation if not already switched off. + This flushes Valgrinds translation cache, and does no additional + instrumentation afterwards: it effectivly will run at the same + speed as the "none" tool, ie. at minimal slowdown. Use this to + speed up the Callgrind run for uninteresting code parts. Use + to switch on instrumentation again. + See also option . + + + + + + +