lackey/docs/lk-manual.xml

   1 <?xml version="1.0"?> <!-- -*- sgml -*- -->
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4
   5 <chapter id="lk-manual" xreflabel="Lackey">
   6
   7 <title>Lackey: an example tool</title>
   8
   9 <para>To use this tool, you must specify
  10 <option>--tool=lackey</option> on the Valgrind
  11 command line.</para>
  12
  13
  14 <sect1 id="lk-manual.overview" xreflabel="Overview">
  15 <title>Overview</title>
  16
  17 <para>Lackey is a simple Valgrind tool that does various kinds of basic
  18 program measurement.  It adds quite a lot of simple instrumentation to the
  19 program's code.  It is primarily intended to be of use as an example tool,
  20 and consequently emphasises clarity of implementation over
  21 performance.</para>
  22
  23 </sect1>
  24
  25
  26 <sect1 id="lk-manual.options" xreflabel="Lackey Command-line Options">
  27 <title>Lackey Command-line Options</title>
  28
  29 <para>Lackey-specific command-line options are:</para>
  30
  31 <!-- start of xi:include in the manpage -->
  32 <variablelist id="lk.opts.list">
  33
  34   <varlistentry id="opt.basic-counts" xreflabel="--basic-counts">
  35     <term>
  36       <option><![CDATA[--basic-counts=<no|yes> [default: yes] ]]></option>
  37     </term>
  38     <listitem>
  39       <para>When enabled, Lackey prints the following statistics and
  40       information about the execution of the client program:</para>
  41
  42       <orderedlist>
  43
  44        <listitem>
  45         <para>The number of calls to the function specified by the
  46         <option>--fnname</option> option (the default is
  47         <computeroutput>main</computeroutput>).
  48         If the program has had its symbols stripped, the count will always
  49         be zero.</para>
  50        </listitem>
  51
  52        <listitem>
  53         <para>The number of conditional branches encountered and the
  54         number and proportion of those taken.</para>
  55        </listitem>
  56
  57        <listitem>
  58         <para>The number of superblocks entered and completed by the
  59         program.  Note that due to optimisations done by the JIT, this
  60         is not at all an accurate value.</para>
  61        </listitem>
  62
  63        <listitem>
  64         <para>The number of guest (x86, amd64, ppc, etc.) instructions and IR
  65         statements executed.  IR is Valgrind's RISC-like intermediate
  66         representation via which all instrumentation is done.
  67         </para>
  68        </listitem>
  69
  70        <listitem>
  71         <para>Ratios between some of these counts.</para>
  72        </listitem>
  73
  74        <listitem>
  75         <para>The exit code of the client program.</para>
  76        </listitem>
  77
  78       </orderedlist>
  79
  80     </listitem>
  81   </varlistentry>
  82
  83   <varlistentry id="opt.detailed-counts" xreflabel="--detailed-counts">
  84     <term>
  85       <option><![CDATA[--detailed-counts=<no|yes> [default: no] ]]></option>
  86     </term>
  87     <listitem>
  88       <para>When enabled, Lackey prints a table containing counts of loads,
  89       stores and ALU operations, differentiated by their IR types.
  90       The IR types are identified by their IR name ("I1", "I8", ... "I128",
  91       "F32", "F64", and "V128").</para>
  92     </listitem>
  93   </varlistentry>
  94
  95   <varlistentry id="opt.trace-mem" xreflabel="--trace-mem">
  96     <term>
  97       <option><![CDATA[--trace-mem=<no|yes> [default: no] ]]></option>
  98     </term>
  99     <listitem>
 100       <para>When enabled, Lackey prints the size and address of almost every
 101       memory access made by the program.  See the comments at the top of
 102       the file <computeroutput>lackey/lk_main.c</computeroutput> for details
 103       about the output format, how it works, and inaccuracies in the address
 104       trace.  Note that this option produces immense amounts of output.</para>
 105     </listitem>
 106   </varlistentry>
 107
 108   <varlistentry id="opt.trace-superblocks" xreflabel="--trace-superblocks">
 109     <term>
 110       <option><![CDATA[--trace-superblocks=<no|yes> [default: no] ]]></option>
 111     </term>
 112     <listitem>
 113       <para>When enabled,
 114       Lackey prints out the address of every superblock
 115       (a single entry, multiple exit, linear chunk of code) executed by the
 116       program.  This is primarily of interest to Valgrind developers.  See
 117       the comments at the top of the file
 118       <computeroutput>lackey/lk_main.c</computeroutput> for details about
 119       the output format.  Note that this option produces large amounts of
 120       output.</para>
 121     </listitem>
 122   </varlistentry>
 123
 124   <varlistentry id="opt.fnname" xreflabel="--fnname">
 125     <term>
 126       <option><![CDATA[--fnname=<name> [default: main] ]]></option>
 127     </term>
 128     <listitem>
 129       <para>Changes the function for which calls are counted when
 130       <option>--basic-counts=yes</option> is specified.</para>
 131     </listitem>
 132   </varlistentry>
 133
 134 </variablelist>
 135 <!-- end of xi:include in the manpage -->
 136
 137 </sect1>
 138
 139 </chapter>