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
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
7
<chapter id="writing-tools" xreflabel="Writing a New Valgrind Tool">
8
<title>Writing a New Valgrind Tool</title>
10
<sect1 id="writing-tools.intro" xreflabel="Introduction">
11
<title>Introduction</title>
13
<sect2 id="writing-tools.supexec" xreflabel="Supervised Execution">
14
<title>Supervised Execution</title>
16
<para>Valgrind provides a generic infrastructure for supervising
17
the execution of programs. This is done by providing a way to
18
instrument programs in very precise ways, making it relatively
19
easy to support activities such as dynamic error detection and
22
<para>Although writing a tool is not easy, and requires learning
23
quite a few things about Valgrind, it is much easier than
24
instrumenting a program from scratch yourself.</para>
26
<para>[Nb: What follows is slightly out of date.]</para>
31
<sect2 id="writing-tools.tools" xreflabel="Tools">
34
<para>The key idea behind Valgrind's architecture is the division
35
between its "core" and "tools".</para>
37
<para>The core provides the common low-level infrastructure to
38
support program instrumentation, including the JIT
39
compiler, low-level memory manager, signal handling and a
40
scheduler (for pthreads). It also provides certain services that
41
are useful to some but not all tools, such as support for error
42
recording and suppression.</para>
44
<para>But the core leaves certain operations undefined, which
45
must be filled by tools. Most notably, tools define how program
46
code should be instrumented. They can also call certain
47
functions to indicate to the core that they would like to use
48
certain services, or be notified when certain interesting events
49
occur. But the core takes care of all the hard work.</para>
54
<sect2 id="writing-tools.execspaces" xreflabel="Execution Spaces">
55
<title>Execution Spaces</title>
57
<para>An important concept to understand before writing a tool is
58
that there are three spaces in which program code executes:</para>
64
<para>User space: this covers most of the program's execution.
65
The tool is given the code and can instrument it any way it
66
likes, providing (more or less) total control over the
69
<para>Code executed in user space includes all the program
70
code, almost all of the C library (including things like the
71
dynamic linker), and almost all parts of all other
76
<para>Core space: a small proportion of the program's execution
77
takes place entirely within Valgrind's core. This includes:</para>
80
<para>Dynamic memory management
81
(<computeroutput>malloc()</computeroutput> etc.)</para>
84
<para>Thread scheduling</para>
87
<para>Signal handling</para>
91
<para>A tool has no control over these operations; it never
92
"sees" the code doing this work and thus cannot instrument it.
93
However, the core provides hooks so a tool can be notified
94
when certain interesting events happen, for example when
95
dynamic memory is allocated or freed, the stack pointer is
96
changed, or a pthread mutex is locked, etc.</para>
98
<para>Note that these hooks only notify tools of events
99
relevant to user space. For example, when the core allocates
100
some memory for its own use, the tool is not notified of this,
101
because it's not directly part of the supervised program's
106
<para>Kernel space: execution in the kernel. Two kinds:</para>
109
<para>System calls: can't be directly observed by either
110
the tool or the core. But the core does have some idea of
111
what happens to the arguments, and it provides hooks for a
112
tool to wrap system calls.</para>
115
<para>Other: all other kernel activity (e.g. process
116
scheduling) is totally opaque and irrelevant to the
123
<para>It should be noted that a tool only has direct control
124
over code executed in user space. This is the vast majority
125
of code executed, but it is not absolutely all of it, so any
126
profiling information recorded by a tool won't be totally
138
<sect1 id="writing-tools.writingatool" xreflabel="Writing a Tool">
139
<title>Writing a Tool</title>
142
<sect2 id="writing-tools.whywriteatool" xreflabel="Why write a tool?">
143
<title>Why write a tool?</title>
145
<para>Before you write a tool, you should have some idea of what
146
it should do. What is it you want to know about your programs of
147
interest? Consider some existing tools:</para>
152
<para><command>memcheck</command>: among other things, performs
153
fine-grained validity and addressibility checks of every memory
154
reference performed by the program.</para>
158
<para><command>cachegrind</command>: tracks every instruction
159
and memory reference to simulate instruction and data caches,
160
tracking cache accesses and misses that occur on every line in
165
<para><command>helgrind</command>: tracks every memory access
166
and mutex lock/unlock to determine if a program contains any
171
<para><command>lackey</command>: does simple counting of
172
various things: the number of calls to a particular function
173
(<computeroutput>_dl_runtime_resolve()</computeroutput>); the
174
number of basic blocks, guest instructions, VEX instructions
175
executed; the number of branches executed and the proportion of
176
them which were taken.</para>
180
<para>These examples give a reasonable idea of what kinds of
181
things Valgrind can be used for. The instrumentation can range
182
from very lightweight (e.g. counting the number of times a
183
particular function is called) to very intrusive (e.g.
184
memcheck's memory checking).</para>
189
<sect2 id="writing-tools.suggestedtools" xreflabel="Suggested tools">
190
<title>Suggested tools</title>
192
<para>Here is a list of ideas we have had for tools that should
193
not be too hard to implement.</para>
197
<para><command>branch profiler</command>: A machine's branch
198
prediction hardware could be simulated, and each branch
199
annotated with the number of predicted and mispredicted
200
branches. Would be implemented quite similarly to Cachegrind,
202
<computeroutput>cg_annotate</computeroutput> script to annotate
205
<para>The biggest difficulty with this is the simulation; the
206
chip-makers are very cagey about how their chips do branch
207
prediction. But implementing one or more of the basic
208
algorithms could still give good information.</para>
212
<para><command>coverage tool</command>: Cachegrind can already
213
be used for doing test coverage, but it's massive overkill to
214
use it just for that.</para>
216
<para>It would be easy to write a coverage tool that records
217
how many times each basic block was recorded. Again, the
218
<computeroutput>cg_annotate</computeroutput> script could be
219
used for annotating source code with the gathered information.
220
Although, <computeroutput>cg_annotate</computeroutput> is only
221
designed for working with single program runs. It could be
222
extended relatively easily to deal with multiple runs of a
223
program, so that the coverage of a whole test suite could be
226
<para>In addition to the standard coverage information, such a
227
tool could record extra information that would help a user
228
generate test cases to exercise unexercised paths. For
229
example, for each conditional branch, the tool could record all
230
inputs to the conditional test, and print these out when
235
<para><command>run-time type checking</command>: A nice example
236
of a dynamic checker is given in this paper:</para>
237
<address>Debugging via Run-Time Type Checking
238
Alexey Loginov, Suan Hsi Yong, Susan Horwitz and Thomas Reps
239
Proceedings of Fundamental Approaches to Software Engineering
243
<para>Similar is the tool described in this paper:</para>
244
<address>Run-Time Type Checking for Binary Programs
245
Michael Burrows, Stephen N. Freund, Janet L. Wiener
246
Proceedings of the 12th International Conference on Compiler Construction (CC 2003)
250
<para>This approach can find quite a range of bugs,
251
particularly in C and C++ programs, and could be implemented
252
quite nicely as a Valgrind tool.</para>
254
<para>Ways to speed up this run-time type checking are
255
described in this paper:</para>
256
<address>Reducing the Overhead of Dynamic Analysis
257
Suan Hsi Yong and Susan Horwitz
258
Proceedings of Runtime Verification '02
262
<para>Valgrind's client requests could be used to pass
263
information to a tool about which elements need instrumentation
264
and which don't.</para>
268
<para>We would love to hear from anyone who implements these or
274
<sect2 id="writing-tools.howtoolswork" xreflabel="How tools work">
275
<title>How tools work</title>
277
<para>Tools must define various functions for instrumenting programs
278
that are called by Valgrind's core. They are then linked against the
279
coregrind library (<filename>libcoregrind.a</filename>) that valgrind
280
provides as well as the VEX library (<filename>libvex.a</filename>) that
281
also comes with valgrind and provides the JIT engine.</para>
283
<para>Each tool is linked as a statically linked program and placed in
284
the valgrind library directory from where valgrind will load it
285
automatically when the <option>--tool</option> option is used to select
291
<sect2 id="writing-tools.gettingcode" xreflabel="Getting the code">
292
<title>Getting the code</title>
294
<para>To write your own tool, you'll need the Valgrind source code. A
295
normal source distribution should do, although you might want to check
296
out the latest code from the Subversion repository. See the information
297
about how to do so at <ulink url="&vg-svn-repo;">the Valgrind
298
website</ulink>.</para>
303
<sect2 id="writing-tools.gettingstarted" xreflabel="Getting started">
304
<title>Getting started</title>
306
<para>Valgrind uses GNU <computeroutput>automake</computeroutput> and
307
<computeroutput>autoconf</computeroutput> for the creation of Makefiles
308
and configuration. But don't worry, these instructions should be enough
309
to get you started even if you know nothing about those tools.</para>
311
<para>In what follows, all filenames are relative to Valgrind's
312
top-level directory <computeroutput>valgrind/</computeroutput>.</para>
316
<para>Choose a name for the tool, and an abbreviation that can be used
317
as a short prefix. We'll use <computeroutput>foobar</computeroutput>
318
and <computeroutput>fb</computeroutput> as an example.</para>
322
<para>Make a new directory <computeroutput>foobar/</computeroutput>
323
which will hold the tool.</para>
327
<para>Copy <filename>none/Makefile.am</filename> into
328
<computeroutput>foobar/</computeroutput>. Edit it by replacing all
329
occurrences of the string <computeroutput>"none"</computeroutput> with
330
<computeroutput>"foobar"</computeroutput> and the one occurrence of
331
the string <computeroutput>"nl_"</computeroutput> with
332
<computeroutput>"fb_"</computeroutput>. It might be worth trying to
333
understand this file, at least a little; you might have to do more
334
complicated things with it later on. In particular, the name of the
335
<computeroutput>foobar_SOURCES</computeroutput> variable determines
336
the name of the tool, which determines what name must be passed to the
337
<option>--tool</option> option to use the tool.</para>
341
<para>Copy <filename>none/nl_main.c</filename> into
342
<computeroutput>foobar/</computeroutput>, renaming it as
343
<filename>fb_main.c</filename>. Edit it by changing the lines in
344
<function>pre_clo_init()</function> to something appropriate for the
345
tool. These fields are used in the startup message, except for
346
<computeroutput>bug_reports_to</computeroutput> which is used if a
347
tool assertion fails.</para>
351
<para>Edit <filename>Makefile.am</filename>, adding the new directory
352
<computeroutput>foobar</computeroutput> to the
353
<computeroutput>SUBDIRS</computeroutput> variable.</para>
357
<para>Edit <filename>configure.in</filename>, adding
358
<filename>foobar/Makefile</filename> to the
359
<computeroutput>AC_OUTPUT</computeroutput> list.</para>
364
<programlisting><![CDATA[
366
./configure --prefix=`pwd`/inst
367
make install]]></programlisting>
369
<para>It should automake, configure and compile without errors,
370
putting copies of the tool in
371
<computeroutput>foobar/</computeroutput> and
372
<computeroutput>inst/lib/valgrind/</computeroutput>.</para>
376
<para>You can test it with a command like:</para>
377
<programlisting><![CDATA[
378
inst/bin/valgrind --tool=foobar date]]></programlisting>
380
<para>(almost any program should work;
381
<computeroutput>date</computeroutput> is just an example).
382
The output should be something like this:</para>
383
<programlisting><![CDATA[
384
==738== foobar-0.0.1, a foobarring tool for x86-linux.
385
==738== Copyright (C) 1066AD, and GNU GPL'd, by J. Random Hacker.
386
==738== Built with valgrind-1.1.0, a program execution monitor.
387
==738== Copyright (C) 2000-2003, and GNU GPL'd, by Julian Seward.
388
==738== Estimated CPU clock rate is 1400 MHz
389
==738== For more details, rerun with: -v
390
==738== Wed Sep 25 10:31:54 BST 2002
391
==738==]]></programlisting>
393
<para>The tool does nothing except run the program
394
uninstrumented.</para>
399
<para>These steps don't have to be followed exactly - you can choose
400
different names for your source files, and use a different
401
<option>--prefix</option> for
402
<computeroutput>./configure</computeroutput>.</para>
404
<para>Now that we've setup, built and tested the simplest possible tool,
405
onto the interesting stuff...</para>
411
<sect2 id="writing-tools.writingcode" xreflabel="Writing the Code">
412
<title>Writing the code</title>
414
<para>A tool must define at least these four functions:</para>
415
<programlisting><![CDATA[
419
fini()]]></programlisting>
421
<para>Also, it must use the macro
422
<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> exactly
423
once in its source code. If it doesn't, you will get a link error
424
involving <computeroutput>VG_(tool_interface_version)</computeroutput>.
425
This macro is used to ensure the core/tool interface used by the core
426
and a plugged-in tool are binary compatible.</para>
428
<para>In addition, if a tool wants to use some of the optional services
429
provided by the core, it may have to define other functions and tell the
430
code about them.</para>
436
<sect2 id="writing-tools.init" xreflabel="Initialisation">
437
<title>Initialisation</title>
439
<para>Most of the initialisation should be done in
440
<function>pre_clo_init()</function>. Only use
441
<function>post_clo_init()</function> if a tool provides command line
442
options and must do some initialisation after option processing takes
443
place (<computeroutput>"clo"</computeroutput> stands for "command line
446
<para>First of all, various "details" need to be set for a tool, using
447
the functions <function>VG_(details_*)()</function>. Some are all
448
compulsory, some aren't. Some are used when constructing the startup
449
message, <computeroutput>detail_bug_reports_to</computeroutput> is used
450
if <computeroutput>VG_(tool_panic)()</computeroutput> is ever called, or
451
a tool assertion fails. Others have other uses.</para>
453
<para>Second, various "needs" can be set for a tool, using the functions
454
<function>VG_(needs_*)()</function>. They are mostly booleans, and can
455
be left untouched (they default to <varname>False</varname>). They
456
determine whether a tool can do various things such as: record, report
457
and suppress errors; process command line options; wrap system calls;
458
record extra information about malloc'd blocks, etc.</para>
460
<para>For example, if a tool wants the core's help in recording and
461
reporting errors, it must call
462
<function>VG_(needs_tool_errors)</function> and provide definitions of
463
eight functions for comparing errors, printing out errors, reading
464
suppressions from a suppressions file, etc. While writing these
465
functions requires some work, it's much less than doing error handling
466
from scratch because the core is doing most of the work. See the
467
function <function>VG_(needs_tool_errors)</function> in
468
<filename>include/pub_tool_tooliface.h</filename> for full details of
469
all the needs.</para>
471
<para>Third, the tool can indicate which events in core it wants to be
472
notified about, using the functions <function>VG_(track_*)()</function>.
473
These include things such as blocks of memory being malloc'd, the stack
474
pointer changing, a mutex being locked, etc. If a tool wants to know
475
about this, it should provide a pointer to a function, which will be
476
called when that event happens.</para>
478
<para>For example, if the tool want to be notified when a new block of
479
memory is malloc'd, it should call
480
<function>VG_(track_new_mem_heap)()</function> with an appropriate
481
function pointer, and the assigned function will be called each time
484
<para>More information about "details", "needs" and "trackable events"
486
<filename>include/pub_tool_tooliface.h</filename>.</para>
492
<sect2 id="writing-tools.instr" xreflabel="Instrumentation">
493
<title>Instrumentation</title>
495
<para><function>instrument()</function> is the interesting one. It
496
allows you to instrument <emphasis>VEX IR</emphasis>, which is
497
Valgrind's RISC-like intermediate language. VEX IR is described in
498
<xref linkend="mc-tech-docs.ucode"/>.</para>
500
<para>The easiest way to instrument VEX IR is to insert calls to C
501
functions when interesting things happen. See the tool "Lackey"
502
(<filename>lackey/lk_main.c</filename>) for a simple example of this, or
503
Cachegrind (<filename>cachegrind/cg_main.c</filename>) for a more
504
complex example.</para>
510
<sect2 id="writing-tools.fini" xreflabel="Finalisation">
511
<title>Finalisation</title>
513
<para>This is where you can present the final results, such as a summary
514
of the information collected. Any log files should be written out at
521
<sect2 id="writing-tools.otherinfo" xreflabel="Other Important Information">
522
<title>Other Important Information</title>
524
<para>Please note that the core/tool split infrastructure is quite
525
complex and not brilliantly documented. Here are some important points,
526
but there are undoubtedly many others that I should note but haven't
529
<para>The files <filename>include/pub_tool_*.h</filename> contain all
530
the types, macros, functions, etc. that a tool should (hopefully) need,
531
and are the only <filename>.h</filename> files a tool should need to
532
<computeroutput>#include</computeroutput>.</para>
534
<para>In particular, you can't use anything from the C library (there
535
are deep reasons for this, trust us). Valgrind provides an
536
implementation of a reasonable subset of the C library, details of which
537
are in <filename>pub_tool_libc*.h</filename>.</para>
539
<para>Similarly, when writing a tool, you shouldn't need to look at any
540
of the code in Valgrind's core. Although it might be useful sometimes
541
to help understand something.</para>
543
<para>The <filename>pub_tool_*.h</filename> files have a reasonable
544
amount of documentation in it that should hopefully be enough to get
545
you going. But ultimately, the tools distributed (Memcheck,
546
Cachegrind, Lackey, etc.) are probably the best
547
documentation of all, for the moment.</para>
549
<para>Note that the <computeroutput>VG_</computeroutput> macro is used
550
heavily. This just prepends a longer string in front of names to avoid
551
potential namespace clashes.</para>
556
<sect2 id="writing-tools.advice" xreflabel="Words of Advice">
557
<title>Words of Advice</title>
559
<para>Writing and debugging tools is not trivial. Here are some
560
suggestions for solving common problems.</para>
563
<sect3 id="writing-tools.segfaults">
564
<title>Segmentation Faults</title>
566
<para>If you are getting segmentation faults in C functions used by your
567
tool, the usual GDB command:</para>
570
gdb <prog> core]]></screen>
571
<para>usually gives the location of the segmentation fault.</para>
576
<sect3 id="writing-tools.debugfns">
577
<title>Debugging C functions</title>
579
<para>If you want to debug C functions used by your tool, you can
580
achieve this by following these steps:</para>
583
<para>Set <computeroutput>VALGRIND_LAUNCHER</computeroutput> to
584
<computeroutput><![CDATA[<prefix>/bin/valgrind]]></computeroutput>:</para>
586
export VALGRIND_LAUNCHER=/usr/local/bin/valgrind</programlisting>
590
<para>Then run <computeroutput><![CDATA[ gdb <prefix>/lib/valgrind/<platform>/<tool>:]]></computeroutput></para>
592
gdb /usr/local/lib/valgrind/ppc32-linux/lackey</programlisting>
596
<para>Do <computeroutput>handle SIGSEGV SIGILL nostop
597
noprint</computeroutput> in GDB to prevent GDB from stopping on a
598
SIGSEGV or SIGILL:</para>
600
(gdb) handle SIGILL SIGSEGV nostop noprint</programlisting>
604
<para>Set any breakpoints you want and proceed as normal for GDB:</para>
606
(gdb) b vgPlain_do_exec</programlisting>
607
<para>The macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you
608
want to set a breakpoint VG_(do_exec), you could do like this in
613
<para>Run the tool with required options:</para>
615
(gdb) run `pwd`</programlisting>
620
<para>GDB may be able to give you useful information. Note that by
621
default most of the system is built with
622
<option>-fomit-frame-pointer</option>, and you'll need to get rid of
623
this to extract useful tracebacks from GDB.</para>
628
<sect3 id="writing-tools.ucode-probs">
629
<title>UCode Instrumentation Problems</title>
631
<para>If you are having problems with your VEX UIR instrumentation, it's
632
likely that GDB won't be able to help at all. In this case, Valgrind's
633
<option>--trace-flags</option> option is invaluable for observing the
634
results of instrumentation.</para>
639
<sect3 id="writing-tools.misc">
640
<title>Miscellaneous</title>
642
<para>If you just want to know whether a program point has been reached,
643
using the <computeroutput>OINK</computeroutput> macro (in
644
<filename>include/pub_tool_libcprint.h</filename>) can be easier than
647
<para>The other debugging command line options can be useful too (run
648
<computeroutput>valgrind --help-debug</computeroutput> for the
659
<sect1 id="writing-tools.advtopics" xreflabel="Advanced Topics">
660
<title>Advanced Topics</title>
662
<para>Once a tool becomes more complicated, there are some extra
663
things you may want/need to do.</para>
665
<sect2 id="writing-tools.suppressions" xreflabel="Suppressions">
666
<title>Suppressions</title>
668
<para>If your tool reports errors and you want to suppress some common
669
ones, you can add suppressions to the suppression files. The relevant
670
files are <filename>valgrind/*.supp</filename>; the final suppression
671
file is aggregated from these files by combining the relevant
672
<filename>.supp</filename> files depending on the versions of linux, X
673
and glibc on a system.</para>
675
<para>Suppression types have the form
676
<computeroutput>tool_name:suppression_name</computeroutput>. The
677
<computeroutput>tool_name</computeroutput> here is the name you specify
678
for the tool during initialisation with
679
<function>VG_(details_name)()</function>.</para>
684
<sect2 id="writing-tools.docs" xreflabel="Documentation">
685
<title>Documentation</title>
687
<para>As of version 3.0.0, Valgrind documentation has been converted to
688
XML. Why? See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
692
<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
693
<title>The XML Toolchain</title>
695
<para>If you are feeling conscientious and want to write some
696
documentation for your tool, please use XML. The Valgrind
697
Docs use the following toolchain and versions:</para>
700
xmllint: using libxml version 20607
701
xsltproc: using libxml 20607, libxslt 10102 and libexslt 802
702
pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
703
pdftops: version 3.00
707
<para><command>Latency:</command> you should note that latency is
708
a big problem: DocBook is constantly being updated, but the tools
709
tend to lag behind somewhat. It is important that the versions
710
get on with each other, so if you decide to upgrade something,
711
then you need to ascertain whether things still work nicely -
712
this *cannot* be assumed.</para>
714
<para><command>Stylesheets:</command> The Valgrind docs use
715
various custom stylesheet layers, all of which are in
716
<computeroutput>valgrind/docs/lib/</computeroutput>. You
717
shouldn't need to modify these in any way.</para>
719
<para><command>Catalogs:</command> Catalogs provide a mapping from
720
generic addresses to specific local directories on a given machine.
721
Most recent Linux distributions have adopted a common place for storing
722
catalogs (<filename>/etc/xml/</filename>). Assuming that you have the
723
various tools listed above installed, you probably won't need to modify
724
your catalogs. But if you do, then just add another
725
<computeroutput>group</computeroutput> to this file, reflecting your
726
local installation.</para>
731
<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
732
<title>Writing the Documentation</title>
734
<para>Follow these steps (using <computeroutput>foobar</computeroutput>
735
as the example tool name again):</para>
740
<para>Make a directory
741
<computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
745
<para>Copy the XML documentation file for the tool Nulgrind from
746
<filename>valgrind/none/docs/nl-manual.xml</filename> to
747
<computeroutput>foobar/docs/</computeroutput>, and rename it to
748
<filename>foobar/docs/fb-manual.xml</filename>.</para>
750
<para><command>Note</command>: there is a *really stupid* tetex bug
751
with underscores in filenames, so don't use '_'.</para>
755
<para>Write the documentation. There are some helpful bits and
756
pieces on using xml markup in
757
<filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
761
<para>Include it in the User Manual by adding the relevant entry to
762
<filename>valgrind/docs/xml/manual.xml</filename>. Copy and edit an
763
existing entry.</para>
767
<para>Validate <filename>foobar/docs/fb-manual.xml</filename> using
768
the following command from within <filename>valgrind/docs/</filename>:
774
<para>You will probably get errors that look like this:</para>
777
./xml/index.xml:5: element chapter: validity error : No declaration for
778
attribute base of element chapter
781
<para>Ignore (only) these -- they're not important.</para>
783
<para>Because the xml toolchain is fragile, it is important to ensure
784
that <filename>fb-manual.xml</filename> won't break the documentation
785
set build. Note that just because an xml file happily transforms to
786
html does not necessarily mean the same holds true for pdf/ps.</para>
790
<para>You can (re-)generate the HTML docs while you are writing
791
<filename>fb-manual.xml</filename> to help you see how it's looking.
792
The generated files end up in
793
<filename>valgrind/docs/html/</filename>. Use the following
794
command, within <filename>valgrind/docs/</filename>:</para>
801
<para>When you have finished, also generate pdf and ps output to
802
check all is well, from within <filename>valgrind/docs/</filename>:
808
<para>Check the output <filename>.pdf</filename> and
809
<filename>.ps</filename> files in
810
<computeroutput>valgrind/docs/print/</computeroutput>.</para>
820
<sect2 id="writing-tools.regtests" xreflabel="Regression Tests">
821
<title>Regression Tests</title>
823
<para>Valgrind has some support for regression tests. If you want to
824
write regression tests for your tool:</para>
828
<para>Make a directory
829
<computeroutput>foobar/tests/</computeroutput>. Make sure the name
830
of the directory is <computeroutput>tests/</computeroutput> as the
831
build system assumes that any tests for the tool will be in a
832
directory by that name.</para>
836
<para>Edit <filename>configure.in</filename>, adding
837
<filename>foobar/tests/Makefile</filename> to the
838
<computeroutput>AC_OUTPUT</computeroutput> list.</para>
842
<para>Write <filename>foobar/tests/Makefile.am</filename>. Use
843
<filename>memcheck/tests/Makefile.am</filename> as an
848
<para>Write the tests, <computeroutput>.vgtest</computeroutput> test
849
description files, <computeroutput>.stdout.exp</computeroutput> and
850
<computeroutput>.stderr.exp</computeroutput> expected output files.
851
(Note that Valgrind's output goes to stderr.) Some details on
852
writing and running tests are given in the comments at the top of
854
<computeroutput>tests/vg_regtest</computeroutput>.</para>
858
<para>Write a filter for stderr results
859
<computeroutput>foobar/tests/filter_stderr</computeroutput>. It can
860
call the existing filters in
861
<computeroutput>tests/</computeroutput>. See
862
<computeroutput>memcheck/tests/filter_stderr</computeroutput> for an
863
example; in particular note the
864
<computeroutput>$dir</computeroutput> trick that ensures the filter
865
works correctly from any directory.</para>
874
<sect2 id="writing-tools.profiling" xreflabel="Profiling">
875
<title>Profiling</title>
877
<para>To profile a tool, use Cachegrind on it. Read README_DEVELOPERS for
878
details on running Valgrind under Valgrind.</para>
880
<para>To do simple tick-based profiling of a tool, include the
882
<programlisting><![CDATA[
883
#include "vg_profile.c"]]></programlisting>
885
<para>in the tool somewhere, and rebuild (you may have to
886
<computeroutput>make clean</computeroutput> first). Then run Valgrind
887
with the <option>--profile=yes</option> option.</para>
889
<para>The profiler is stack-based; you can register a profiling event
890
with <function>VG_(register_profile_event)()</function> and then use the
891
<computeroutput>VGP_PUSHCC</computeroutput> and
892
<computeroutput>VGP_POPCC</computeroutput> macros to record time spent
893
doing certain things. New profiling event numbers must not overlap with
894
the core profiling event numbers. See
895
<filename>include/pub_tool_profile.h</filename> for details and Memcheck
896
for an example.</para>
902
<sect2 id="writing-tools.mkhackery" xreflabel="Other Makefile Hackery">
903
<title>Other Makefile Hackery</title>
905
<para>If you add any directories under
906
<computeroutput>valgrind/foobar/</computeroutput>, you will need to add
907
an appropriate <filename>Makefile.am</filename> to it, and add a
908
corresponding entry to the <computeroutput>AC_OUTPUT</computeroutput>
909
list in <filename>valgrind/configure.in</filename>.</para>
911
<para>If you add any scripts to your tool (see Cachegrind for an
912
example) you need to add them to the
913
<computeroutput>bin_SCRIPTS</computeroutput> variable in
914
<filename>valgrind/foobar/Makefile.am</filename>.</para>
920
<sect2 id="writing-tools.ifacever" xreflabel="Core/tool Interface Versions">
921
<title>Core/tool Interface Versions</title>
923
<para>In order to allow for the core/tool interface to evolve over time,
924
Valgrind uses a basic interface versioning system. All a tool has to do
926
<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> macro
927
exactly once in its code. If not, a link error will occur when the tool
930
<para>The interface version number has the form X.Y. Changes in Y
931
indicate binary compatible changes. Changes in X indicate binary
932
incompatible changes. If the core and tool has the same major version
933
number X they should work together. If X doesn't match, Valgrind will
934
abort execution with an explanation of the problem.</para>
936
<para>This approach was chosen so that if the interface changes in the
937
future, old tools won't work and the reason will be clearly explained,
938
instead of possibly crashing mysteriously. We have attempted to
939
minimise the potential for binary incompatible changes by means such as
940
minimising the use of naked structs in the interface.</para>
948
<sect1 id="writing-tools.finalwords" xreflabel="Final Words">
949
<title>Final Words</title>
951
<para>This whole core/tool business is under active development,
952
although it's slowly maturing.</para>
954
<para>The first consequence of this is that the core/tool interface will
955
continue to change in the future; we have no intention of freezing it
956
and then regretting the inevitable stupidities. Hopefully most of the
957
future changes will be to add new features, hooks, functions, etc,
958
rather than to change old ones, which should cause a minimum of trouble
959
for existing tools, and we've put some effort into future-proofing the
960
interface to avoid binary incompatibility. But we can't guarantee
961
anything. The versioning system should catch any incompatibilities.
962
Just something to be aware of.</para>
964
<para>The second consequence of this is that we'd love to hear your
965
feedback about it:</para>
969
<para>If you love it or hate it</para>
972
<para>If you find bugs</para>
975
<para>If you write a tool</para>
978
<para>If you have suggestions for new features, needs, trackable
979
events, functions</para>
982
<para>If you have suggestions for making tools easier to
986
<para>If you have suggestions for improving this
990
<para>If you don't understand something</para>
994
<para>or anything else!</para>
996
<para>Happy programming.</para>
added
removed
docs/xml/writing-tools.xml
