|
From: Mark W. <ma...@so...> - 2020-05-14 11:04:45
|
https://sourceware.org/git/gitweb.cgi?p=valgrind.git;h=c0916494f651a33822be64bf264459bb2c452097 commit c0916494f651a33822be64bf264459bb2c452097 Author: Mark Wielaard <ma...@kl...> Date: Thu May 14 12:43:39 2020 +0200 docbook xml doesn't allow xref inside option, use link instead Diff: --- cachegrind/docs/cg-manual.xml | 2 +- callgrind/docs/cl-manual.xml | 89 +++++++++++++++++++++++++------------------ dhat/docs/dh-manual.xml | 2 +- exp-bbv/docs/bbv-manual.xml | 4 +- massif/docs/ms-manual.xml | 4 +- memcheck/docs/mc-manual.xml | 5 ++- 6 files changed, 60 insertions(+), 46 deletions(-) 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 <option>%p</option> and <option>%q</option> 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><xref linkend="opt.log-file"/></option>. + option <option><link linkend="opt.log-file">--log-file</link></option>. </para> </listitem> </varlistentry> 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.</para> <para>If you are additionally interested in measuring the cache behavior of your program, use Callgrind with the option - <option><xref linkend="clopt.cache-sim"/>=yes</option>. For - branch prediction simulation, use <option><xref linkend="clopt.branch-sim"/>=yes</option>. + <option><link linkend="clopt.cache-sim">--cache-sim=yes</link></option>. + For branch prediction simulation, use + <option><link linkend="clopt.branch-sim">--branch-sim=yes</link></option>. Expect a further slow down approximately by a factor of 2.</para> <para>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.</para> <emphasis>fast forward</emphasis> to this section without any profiling, and then enable profiling. This is achieved by using the command line option - <option><xref linkend="opt.instr-atstart"/>=no</option> + <option><link linkend="opt.instr-atstart">--instr-atstart=no</link></option> and running, in a shell: <computeroutput>callgrind_control -i on</computeroutput> 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.</para> <computeroutput><link linkend="cr.start-instr">CALLGRIND_START_INSTRUMENTATION</link></computeroutput>.</para> <para>If you want to be able to see assembly code level annotation, specify - <option><xref linkend="opt.dump-instr"/>=yes</option>. This will produce - profile data at instruction granularity. Note that the resulting profile - data + <option><link linkend="opt.dump-instr">--dump-instr=yes</link></option>. + 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 - <option><xref linkend="opt.collect-jumps"/>=yes</option>.</para> + <option><link linkend="opt.collect-jumps">--collect-jumps=yes</link></option>. + </para> </sect2> @@ -228,7 +230,9 @@ callgrind.out.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threa dump (".part" is skipped for the dump at program termination), and <emphasis>threadID</emphasis> is a thread identification ("-threadID" is only used if you request dumps of individual - threads with <option><xref linkend="opt.separate-threads"/>=yes</option>).</para> + threads with + <option><link linkend="opt.separate-threads">--separate-threads=yes</link></option>). + </para> <para>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.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threa <listitem> <para><command>Periodic dumping after execution of a specified number of basic blocks</command>. For this, use the command line - option <option><xref linkend="opt.dump-every-bb"/>=count</option>. + option <option><link linkend="opt.dump-every-bb">--dump-every-bb=count</link></option>. </para> </listitem> <listitem> <para><command>Dumping at enter/leave of specified functions.</command> Use the - option <option><xref linkend="opt.dump-before"/>=function</option> - and <option><xref linkend="opt.dump-after"/>=function</option>. + option <option><link linkend="opt.dump-before">--dump-before=function</link></option> + and <option><link linkend="opt.dump-after">--dump-after=function</link></option>. To zero cost counters before entering a function, use - <option><xref linkend="opt.zero-before"/>=function</option>.</para> + <option><link linkend="opt.zero-before">--zero-before=function</link></option>.</para> <para>You can specify these options multiple times for different functions. Function specifications support wildcards: e.g. use - <option><xref linkend="opt.dump-before"/>='foo*'</option> to + <option><link linkend="opt.dump-before">--dump-before='foo*'</link></option> to generate dumps before entering any function starting with <emphasis>foo</emphasis>.</para> </listitem> @@ -297,7 +301,8 @@ callgrind.out.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threa </itemizedlist> <para>If you are running a multi-threaded application and specify the - command line option <option><xref linkend="opt.separate-threads"/>=yes</option>, + command line option + <option><link linkend="opt.separate-threads">--separate-threads=yes</link></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.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threa </para> <para>Callgrind can start with instrumentation mode switched off by - specifying - option <option><xref linkend="opt.instr-atstart"/>=no</option>. + specifying option + <option><link linkend="opt.instr-atstart">--instr-atstart=no</link></option>. Afterwards, instrumentation can be controlled in two ways: first, interactively with: <screen>callgrind_control -i on</screen> (and switching off again by specifying "off" instead of "on"). Second, @@ -370,12 +375,12 @@ callgrind.out.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threa </para> <para>Similarly, the collection state at program start can be - switched off - by <option><xref linkend="opt.instr-atstart"/>=no</option>. During - execution, it can be controlled programmatically with the + switched off by + <option><link linkend="opt.instr-atstart">--instr-atstart=no</link></option>. + During execution, it can be controlled programmatically with the macro <computeroutput>CALLGRIND_TOGGLE_COLLECT;</computeroutput>. Further, you can limit event collection to a specific function by - using <option><xref linkend="opt.toggle-collect"/>=function</option>. + using <option><link linkend="opt.toggle-collect">--toggle-collect=function</link></option>. 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.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threa "global bus events" is used.</para> <para>The short name of the event type used for global bus events is "Ge". - To count global bus events, use <option><xref linkend="clopt.collect-bus"/>=yes</option>. + To count global bus events, use + <option><link linkend="clopt.collect-bus">--collect-bus=yes</link></option>. </para> </sect2> @@ -475,32 +481,34 @@ callgrind.out.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>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 - <option><xref linkend="opt.fn-skip"/>=function</option>. Aside from - possibly breaking cycles, this is used in Callgrind to skip + <option><link linkend="opt.fn-skip">--fn-skip=function</link></option>. + 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 <option><xref linkend="opt.skip-plt"/>=no</option>. + if you profile with + <option><link linkend="opt.skip-plt">--skip-plt=no</link></option>. If a call is ignored, its cost events will be propagated to the enclosing function.</para> <para>If you have a recursive function, you can distinguish the first 10 recursion levels by specifying - <option><xref linkend="opt.separate-recs-num"/>=function</option>. + <option><link linkend="opt.separate-recs-num">--separate-recs10=function</link></option>. Or for all functions with - <option><xref linkend="opt.separate-recs"/>=10</option>, but this will + <option><link linkend="opt.separate-recs">--separate-recs=10</link></option>, + 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.</para> <para>If you have call chains "A > B > C" and "A > C > B" in your program, you usually get a "false" cycle "B <> C". Use - <option><xref linkend="opt.separate-callers-num"/>=B</option> - <option><xref linkend="opt.separate-callers-num"/>=C</option>, + <option><link linkend="opt.separate-callers-num">--separate-callers2=B</link></option> + <option><link linkend="opt.separate-callers-num">--separate-callers2=C</link></option>, 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 - <option><xref linkend="opt.separate-callers"/>=2</option> to get a 2-caller + <option><link linkend="opt.separate-callers">--separate-callers=2</link></option> to get a 2-caller dependency for all functions. Note that doing this will increase the size of profile data files.</para> @@ -539,9 +547,9 @@ In the following, options are grouped into classes. </para> <para> Some options allow the specification of a function/symbol name, such as -<option><xref linkend="opt.dump-before"/>=function</option>, or -<option><xref linkend="opt.fn-skip"/>=function</option>. All these options -can be specified multiple times for different functions. +<option><link linkend="opt.dump-before">--dump-before=function</link></option>, or +<option><link linkend="opt.fn-skip">--fn-skip=function</link></option>. +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. <option>%p</option> and <option>%q</option> 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><xref linkend="opt.log-file"/></option>. + option + <option><link linkend="opt.log-file">--log-file</link></option>. When multiple dumps are made, the file name is modified further; see below.</para> </listitem> @@ -762,7 +771,7 @@ Also see <xref linkend="cl-manual.limits"/>.</para> dumps is not practical here.</para> <para>Collection state can be toggled at entry and exit of a given function with the - option <option><xref linkend="opt.toggle-collect"/></option>. If you + option <option><link linkend="opt.toggle-collect">--toggle-collect</link></option>. If you use this option, collection state should be disabled at the beginning. Note that the specification of <option>--toggle-collect</option> @@ -1198,8 +1207,9 @@ their arguments.</para> <listitem> <para>Toggle the collection state. This allows to ignore events with regard to profile counters. See also options - <option><xref linkend="opt.collect-atstart"/></option> and - <option><xref linkend="opt.toggle-collect"/></option>.</para> + <option><link linkend="opt.collect-atstart">--collect-atstart</link></option> + and + <option><link linkend="opt.toggle-collect">--toggle-collect</link></option>.</para> </listitem> </varlistentry> @@ -1212,7 +1222,9 @@ their arguments.</para> 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><xref linkend="opt.instr-atstart"/></option>.</para> + option + <option><link linkend="opt.instr-atstart">--instr-atstart</link></option>. + </para> </listitem> </varlistentry> @@ -1228,7 +1240,8 @@ their arguments.</para> speed up the Callgrind run for uninteresting code parts. Use <computeroutput><link linkend="cr.start-instr">CALLGRIND_START_INSTRUMENTATION</link></computeroutput> to enable instrumentation again. See also option - <option><xref linkend="opt.instr-atstart"/></option>.</para> + <option><link linkend="opt.instr-atstart">--instr-atstart</link></option>. + </para> </listitem> </varlistentry> 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.</para> <option>%p</option> and <option>%q</option> 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><xref linkend="opt.log-file"/></option>. + option <option><link linkend="opt.log-file">--log-file</link></option>. </para> </listitem> </varlistentry> 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.</para> <option>%p</option> and <option>%q</option> 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><xref linkend="opt.log-file"/></option>. + <option><link linkend="opt.log-file">--log-file</link></option>. </para> </listitem> </varlistentry> @@ -148,7 +148,7 @@ command line.</para> <option>%p</option> and <option>%q</option> 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><xref linkend="opt.log-file"/></option>. + <option><link linkend="opt.log-file">--log-file</link></option>. </para> </listitem> </varlistentry> 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:</para> 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><xref linkend="opt.alignment"/></option> option. + <option><link linkend="opt.alignment">--alignment</link></option> option. </para></listitem> <listitem><para>The size of the stack(s). By default, stack profiling is @@ -866,7 +866,7 @@ various places online. <option>%p</option> and <option>%q</option> 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><xref linkend="opt.log-file"/></option>. + <option><link linkend="opt.log-file">--log-file</link></option>. </para> </listitem> </varlistentry> 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><xref -linkend="opt.read-var-info"/></option> option Memcheck will run more slowly +block was allocated. If you use the <option><link +linkend="opt.read-var-info">--read-var-info</link></option> option +Memcheck will run more slowly but may give a more detailed description of any illegal address.</para> <para>In this example, Memcheck can't identify the address. Actually |