From: Mark Wielaard Date: Thu, 14 May 2020 10:43:39 +0000 (+0200) Subject: docbook xml doesn't allow xref inside option, use link instead X-Git-Tag: VALGRIND_3_16_0~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c0916494f651a33822be64bf264459bb2c452097;p=thirdparty%2Fvalgrind.git docbook xml doesn't allow xref inside option, use link instead --- diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 7a44e489f2..adff8aa730 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -860,7 +860,7 @@ small differences like these; it works in the same way as and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core - option . + option . diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index 10da8d973a..d8b65f8021 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -176,8 +176,9 @@ has to rely on heuristics to detect calls and returns. If you are additionally interested in measuring the cache behavior of your program, use Callgrind with the option - . For - branch prediction simulation, use . + . + For branch prediction simulation, use + . Expect a further slow down approximately by a factor of 2. If the program section you want to profile is somewhere in the @@ -185,7 +186,7 @@ has to rely on heuristics to detect calls and returns. fast forward to this section without any profiling, and then enable profiling. This is achieved by using the command line option - + and running, in a shell: callgrind_control -i on just before the interesting code section is executed. To exactly specify @@ -193,13 +194,14 @@ has to rely on heuristics to detect calls and returns. CALLGRIND_START_INSTRUMENTATION. If you want to be able to see assembly code level annotation, specify - . This will produce - profile data at instruction granularity. Note that the resulting profile - data + . + This will produce profile data at instruction granularity. + Note that the resulting profile data can only be viewed with KCachegrind. For assembly annotation, it also is interesting to see more details of the control flow inside of functions, i.e. (conditional) jumps. This will be collected by further specifying - . + . + @@ -228,7 +230,9 @@ callgrind.out.pid.part-threa dump (".part" is skipped for the dump at program termination), and threadID is a thread identification ("-threadID" is only used if you request dumps of individual - threads with ). + threads with + ). + There are different ways to generate multiple profile dumps while a program is running under Callgrind's supervision. Nevertheless, @@ -265,20 +269,20 @@ callgrind.out.pid.part-threa Periodic dumping after execution of a specified number of basic blocks. For this, use the command line - option . + option . Dumping at enter/leave of specified functions. Use the - option - and . + option + and . To zero cost counters before entering a function, use - . + . You can specify these options multiple times for different functions. Function specifications support wildcards: e.g. use - to + to generate dumps before entering any function starting with foo. @@ -297,7 +301,8 @@ callgrind.out.pid.part-threa If you are running a multi-threaded application and specify the - command line option , + command line option + , every thread will be profiled on its own and will create its own profile dump. Thus, the last two methods will only generate one dump of the currently running thread. With the other methods, you will get @@ -359,8 +364,8 @@ callgrind.out.pid.part-threa Callgrind can start with instrumentation mode switched off by - specifying - option . + specifying option + . Afterwards, instrumentation can be controlled in two ways: first, interactively with: callgrind_control -i on (and switching off again by specifying "off" instead of "on"). Second, @@ -370,12 +375,12 @@ callgrind.out.pid.part-threa Similarly, the collection state at program start can be - switched off - by . During - execution, it can be controlled programmatically with the + switched off by + . + During execution, it can be controlled programmatically with the macro CALLGRIND_TOGGLE_COLLECT;. Further, you can limit event collection to a specific function by - using . + using . This will toggle the collection state on entering and leaving the specified function. When this option is in effect, the default collection state at program start is "off". Only events happening @@ -401,7 +406,8 @@ callgrind.out.pid.part-threa "global bus events" is used. The short name of the event type used for global bus events is "Ge". - To count global bus events, use . + To count global bus events, use + . @@ -475,32 +481,34 @@ callgrind.out.pid.part-threa also skips any call information from and to an ignored function, and thus can break a cycle. Candidates for this typically are dispatcher functions in event driven code. The option to ignore calls to a function is - . Aside from - possibly breaking cycles, this is used in Callgrind to skip + . + Aside from possibly breaking cycles, this is used in Callgrind to skip trampoline functions in the PLT sections for calls to functions in shared libraries. You can see the difference - if you profile with . + if you profile with + . If a call is ignored, its cost events will be propagated to the enclosing function. If you have a recursive function, you can distinguish the first 10 recursion levels by specifying - . + . Or for all functions with - , but this will + , + but this will give you much bigger profile data files. In the profile data, you will see the recursion levels of "func" as the different functions with names "func", "func'2", "func'3" and so on. If you have call chains "A > B > C" and "A > C > B" in your program, you usually get a "false" cycle "B <> C". Use - - , + + , and functions "B" and "C" will be treated as different functions depending on the direct caller. Using the apostrophe for appending this "context" to the function name, you get "A > B'A > C'B" and "A > C'A > B'C", and there will be no cycle. Use - to get a 2-caller + to get a 2-caller dependency for all functions. Note that doing this will increase the size of profile data files. @@ -539,9 +547,9 @@ In the following, options are grouped into classes. Some options allow the specification of a function/symbol name, such as -, or -. All these options -can be specified multiple times for different functions. +, or +. +All these options can be specified multiple times for different functions. In addition, the function specifications actually are patterns by supporting the use of wildcards '*' (zero or more arbitrary characters) and '?' (exactly one arbitrary character), similar to file name globbing in the @@ -572,7 +580,8 @@ These options influence the name and format of the profile data files. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core - option . + option + . When multiple dumps are made, the file name is modified further; see below. @@ -762,7 +771,7 @@ Also see . dumps is not practical here. Collection state can be toggled at entry and exit of a given function with the - option . If you + option . If you use this option, collection state should be disabled at the beginning. Note that the specification of @@ -1198,8 +1207,9 @@ their arguments. Toggle the collection state. This allows to ignore events with regard to profile counters. See also options - and - . + + and + . @@ -1212,7 +1222,9 @@ their arguments. When cache simulation is done, this will flush the simulated cache and lead to an artificial cache warmup phase afterwards with cache misses which would not have happened in reality. See also - option . + option + . + @@ -1228,7 +1240,8 @@ their arguments. speed up the Callgrind run for uninteresting code parts. Use CALLGRIND_START_INSTRUMENTATION to enable instrumentation again. See also option - . + . + diff --git a/dhat/docs/dh-manual.xml b/dhat/docs/dh-manual.xml index e1d2ac6141..eeb6080551 100644 --- a/dhat/docs/dh-manual.xml +++ b/dhat/docs/dh-manual.xml @@ -689,7 +689,7 @@ triggered. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core - option . + option . diff --git a/exp-bbv/docs/bbv-manual.xml b/exp-bbv/docs/bbv-manual.xml index f6ba05439b..7141e07c2f 100644 --- a/exp-bbv/docs/bbv-manual.xml +++ b/exp-bbv/docs/bbv-manual.xml @@ -128,7 +128,7 @@ command line. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core option - . + . @@ -148,7 +148,7 @@ command line. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core option - . + . diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index f8637de807..8d41286cff 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -391,7 +391,7 @@ a small amount of information is recorded for each one: larger number, usually 8 or 16. This is required to ensure that elements within the block are suitably aligned. If N bytes are asked for, Massif rounds N up to the nearest multiple of the value specified by the - option. + option. The size of the stack(s). By default, stack profiling is @@ -866,7 +866,7 @@ various places online. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core option - . + . diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 5d6031376c..9d7d217221 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -104,8 +104,9 @@ which has already been freed, you'll be informed of this, and also where the block was freed. Likewise, if it should turn out to be just off the end of a heap block, a common result of off-by-one-errors in array subscripting, you'll be informed of this fact, and also where the -block was allocated. If you use the option Memcheck will run more slowly +block was allocated. If you use the option +Memcheck will run more slowly but may give a more detailed description of any illegal address. In this example, Memcheck can't identify the address. Actually