| <?xml version="1.0"?> <!-- -*- sgml -*- --> |
| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <chapter id="lk-manual" xreflabel="Lackey"> |
| |
| <title>Lackey: an example tool</title> |
| |
| <para>To use this tool, you must specify |
| <option>--tool=lackey</option> on the Valgrind |
| command line.</para> |
| |
| |
| <sect1 id="lk-manual.overview" xreflabel="Overview"> |
| <title>Overview</title> |
| |
| <para>Lackey is a simple Valgrind tool that does various kinds of basic |
| program measurement. It adds quite a lot of simple instrumentation to the |
| program's code. It is primarily intended to be of use as an example tool, |
| and consequently emphasises clarity of implementation over |
| performance.</para> |
| |
| </sect1> |
| |
| |
| <sect1 id="lk-manual.options" xreflabel="Lackey Command-line Options"> |
| <title>Lackey Command-line Options</title> |
| |
| <para>Lackey-specific command-line options are:</para> |
| |
| <!-- start of xi:include in the manpage --> |
| <variablelist id="lk.opts.list"> |
| |
| <varlistentry id="opt.basic-counts" xreflabel="--basic-counts"> |
| <term> |
| <option><![CDATA[--basic-counts=<no|yes> [default: yes] ]]></option> |
| </term> |
| <listitem> |
| <para>When enabled, Lackey prints the following statistics and |
| information about the execution of the client program:</para> |
| |
| <orderedlist> |
| |
| <listitem> |
| <para>The number of calls to the function specified by the |
| <option>--fnname</option> option (the default is |
| <computeroutput>main</computeroutput>). |
| If the program has had its symbols stripped, the count will always |
| be zero.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The number of conditional branches encountered and the |
| number and proportion of those taken.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The number of superblocks entered and completed by the |
| program. Note that due to optimisations done by the JIT, this |
| is not at all an accurate value.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The number of guest (x86, amd64, ppc, etc.) instructions and IR |
| statements executed. IR is Valgrind's RISC-like intermediate |
| representation via which all instrumentation is done. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para>Ratios between some of these counts.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The exit code of the client program.</para> |
| </listitem> |
| |
| </orderedlist> |
| |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="opt.detailed-counts" xreflabel="--detailed-counts"> |
| <term> |
| <option><![CDATA[--detailed-counts=<no|yes> [default: no] ]]></option> |
| </term> |
| <listitem> |
| <para>When enabled, Lackey prints a table containing counts of loads, |
| stores and ALU operations, differentiated by their IR types. |
| The IR types are identified by their IR name ("I1", "I8", ... "I128", |
| "F32", "F64", and "V128").</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="opt.trace-mem" xreflabel="--trace-mem"> |
| <term> |
| <option><![CDATA[--trace-mem=<no|yes> [default: no] ]]></option> |
| </term> |
| <listitem> |
| <para>When enabled, Lackey prints the size and address of almost every |
| memory access made by the program. See the comments at the top of |
| the file <computeroutput>lackey/lk_main.c</computeroutput> for details |
| about the output format, how it works, and inaccuracies in the address |
| trace. Note that this option produces immense amounts of output.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="opt.trace-superblocks" xreflabel="--trace-superblocks"> |
| <term> |
| <option><![CDATA[--trace-superblocks=<no|yes> [default: no] ]]></option> |
| </term> |
| <listitem> |
| <para>When enabled, |
| Lackey prints out the address of every superblock |
| (a single entry, multiple exit, linear chunk of code) executed by the |
| program. This is primarily of interest to Valgrind developers. See |
| the comments at the top of the file |
| <computeroutput>lackey/lk_main.c</computeroutput> for details about |
| the output format. Note that this option produces large amounts of |
| output.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="opt.fnname" xreflabel="--fnname"> |
| <term> |
| <option><![CDATA[--fnname=<name> [default: main] ]]></option> |
| </term> |
| <listitem> |
| <para>Changes the function for which calls are counted when |
| <option>--basic-counts=yes</option> is specified.</para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| <!-- end of xi:include in the manpage --> |
| |
| </sect1> |
| |
| </chapter> |