njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 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 | |
njn | 05a8917 | 2009-07-29 02:36:21 +0000 | [diff] [blame] | 7 | <title>Lackey: an example tool</title> |
sewardj | 8d9fec5 | 2005-11-15 20:56:23 +0000 | [diff] [blame] | 8 | |
| 9 | <para>To use this tool, you must specify |
njn | 7e5d4ed | 2009-07-30 02:57:52 +0000 | [diff] [blame] | 10 | <option>--tool=lackey</option> on the Valgrind |
sewardj | 8d9fec5 | 2005-11-15 20:56:23 +0000 | [diff] [blame] | 11 | command line.</para> |
| 12 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 13 | |
| 14 | <sect1 id="lk-manual.overview" xreflabel="Overview"> |
| 15 | <title>Overview</title> |
| 16 | |
njn | 6fb923b | 2009-08-05 06:57:45 +0000 | [diff] [blame] | 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> |
sewardj | 5d1c901 | 2007-02-12 08:42:13 +0000 | [diff] [blame] | 22 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 23 | </sect1> |
| 24 | |
| 25 | |
njn | a331164 | 2009-08-10 01:29:14 +0000 | [diff] [blame] | 26 | <sect1 id="lk-manual.options" xreflabel="Lackey Command-line Options"> |
| 27 | <title>Lackey Command-line Options</title> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 28 | |
njn | a331164 | 2009-08-10 01:29:14 +0000 | [diff] [blame] | 29 | <para>Lackey-specific command-line options are:</para> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 30 | |
| 31 | <!-- start of xi:include in the manpage --> |
| 32 | <variablelist id="lk.opts.list"> |
| 33 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 34 | <varlistentry id="opt.basic-counts" xreflabel="--basic-counts"> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 35 | <term> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 36 | <option><![CDATA[--basic-counts=<no|yes> [default: yes] ]]></option> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 37 | </term> |
| 38 | <listitem> |
njn | 6fb923b | 2009-08-05 06:57:45 +0000 | [diff] [blame] | 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 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 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> |
njn | 6fb923b | 2009-08-05 06:57:45 +0000 | [diff] [blame] | 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> |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 92 | </listitem> |
| 93 | </varlistentry> |
| 94 | |
sewardj | 5d1c901 | 2007-02-12 08:42:13 +0000 | [diff] [blame] | 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> |
njn | 6fb923b | 2009-08-05 06:57:45 +0000 | [diff] [blame] | 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> |
sewardj | 5d1c901 | 2007-02-12 08:42:13 +0000 | [diff] [blame] | 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> |
njn | 6fb923b | 2009-08-05 06:57:45 +0000 | [diff] [blame] | 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> |
sewardj | 5d1c901 | 2007-02-12 08:42:13 +0000 | [diff] [blame] | 131 | </listitem> |
| 132 | </varlistentry> |
| 133 | |
de | 03e0e7c | 2005-12-03 23:02:33 +0000 | [diff] [blame] | 134 | </variablelist> |
| 135 | <!-- end of xi:include in the manpage --> |
| 136 | |
| 137 | </sect1> |
| 138 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 139 | </chapter> |