lackey/docs/lk-manual.xml

<?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: a simple profiler and memory tracer</title>

<para>To use this tool, you must specify
<computeroutput>--tool=lackey</computeroutput> 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 some 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.</para>

<para>It measures and reports various things.</para>

<orderedlist>

 <listitem>
  <para>When command line option
  <computeroutput>--basic-counts=yes</computeroutput> is specified,
  it prints the following statistics and information about the execution of
  the client program:

  <orderedlist>

   <listitem>
    <para>The number of calls to
    <computeroutput>_dl_runtime_resolve()</computeroutput>, the
    function in glibc's dynamic linker that resolves function
    references to shared objects.</para>
    <para>You can change the name of the function tracekd with command line
    option <computeroutput>--fnname=&lt;name&gt;</computeroutput>.</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 basic blocks entered and completed by the
    program.  Note that due to optimisations done by the JIT, this
    is not really 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>
  <para>When command line option
  <computeroutput>--detailed-counts=yes</computeroutput> is
  specified, a table is printed with counts of loads, stores and ALU
  operations for various types of operands.</para>

  <para>The types are identified by their IR name ("I1" ... "I128",
  "F32", "F64", and "V128").</para>
 </listitem>

 <listitem>
  <para>When command line option
  <computeroutput>--trace-mem=yes</computeroutput> is
  specified, it prints out the size and address of almost every load and
  store 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.
  </para>
 </listitem>

</orderedlist>

<para>Note that Lackey runs quite slowly, especially when
<computeroutput>--detailed-counts=yes</computeroutput> is specified.
It could be made to run a lot faster by doing a slightly more
sophisticated job of the instrumentation, but that would undermine
its role as a simple example tool.  Hence we have chosen not to do
so.</para>

</sect1>


<sect1 id="lk-manual.options" xreflabel="Lackey Options">
<title>Lackey Options</title>

<para>Lackey-specific options are:</para>

<!-- start of xi:include in the manpage -->
<variablelist id="lk.opts.list">

  <varlistentry id="opt.fnname" xreflabel="--fnname">
    <term>
      <option><![CDATA[--fnname=<name> [default: _dl_runtime_resolve()] ]]></option>
    </term>
    <listitem>
      <para>Count calls to &lt;name&gt;.</para>
    </listitem>
  </varlistentry>

  <varlistentry id="opt.detailed-counts" xreflabel="--detailed-counts">
    <term>
      <option><![CDATA[--detailed-counts=<no|yes> [default: no] ]]></option>
    </term>
    <listitem>
      <para>Count loads, stores and alu ops.</para>
    </listitem>
  </varlistentry>

</variablelist>
<!-- end of xi:include in the manpage -->

</sect1>

</chapter>