ftmemsim-valgrind/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, and consequently emphasises clarity of implementation
over performance.</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:</para>

  <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 tracked 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 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>

 <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>

 <listitem>
  <para>When command line option
  <computeroutput>--trace-superblocks=yes</computeroutput> is
  specified, it prints out the address of every superblock 
  (extended basic block) 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.
  </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>

<para>Note also that <computeroutput>--trace-mem=yes</computeroutput>
and <computeroutput>--trace-superblocks=yes</computeroutput> create
immense amounts of output.  If you are saving the output in a file,
you can eat up tens of gigabytes of disk space very quickly.
As a result of printing out so much stuff, they also cause the program
to run absolutely utterly unbelievably slowly.</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.basic-counts" xreflabel="--basic-counts">
    <term>
      <option><![CDATA[--basic-counts=<no|yes> [default: yes] ]]></option>
    </term>
    <listitem>
      <para>Count basic events, as described above.</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, differentiated by their
            IR types.</para>
    </listitem>
  </varlistentry>

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

  <varlistentry id="opt.trace-mem" xreflabel="--trace-mem">
    <term>
      <option><![CDATA[--trace-mem=<no|yes> [default: no] ]]></option>
    </term>
    <listitem>
      <para>Produce a log of all memory references, as described
      above.</para>
    </listitem>
  </varlistentry>

  <varlistentry id="opt.trace-superblocks" xreflabel="--trace-superblocks">
    <term>
      <option><![CDATA[--trace-superblocks=<no|yes> [default: no] ]]></option>
    </term>
    <listitem>
      <para>Print a line of text giving the address of each superblock
            (single entry, multiple exit chunk of code) executed
            by the program.</para>
    </listitem>
  </varlistentry>

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

</sect1>

</chapter>