1<?xml version="1.0"?> <!-- -*- sgml -*- -->
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/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
11command 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
18program measurement.  It adds quite a lot of simple instrumentation to the
19program's code.  It is primarily intended to be of use as an example tool,
20and consequently emphasises clarity of implementation over
21performance.</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>
140