Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / valgrind / be4015a1d5205a40e39f658557ff4e324b7de7a6 / . / coregrind / docs / skins.html
blob: fb92a745714a47d32b56a64bfb90e18cf4767718 [file] [log] [blame]
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]1<html>
2 <head>
3 <style type="text/css">
4 body { background-color: #ffffff;
5 color: #000000;
6 font-family: Times, Helvetica, Arial;
7 font-size: 14pt}
8 h4 { margin-bottom: 0.3em}
9 code { color: #000000;
10 font-family: Courier;
11 font-size: 13pt }
12 pre { color: #000000;
13 font-family: Courier;
14 font-size: 13pt }
15 a:link { color: #0000C0;
16 text-decoration: none; }
17 a:visited { color: #0000C0;
18 text-decoration: none; }
19 a:active { color: #0000C0;
20 text-decoration: none; }
21 </style>
22 <title>Valgrind</title>
23 </head>
24
25<body bgcolor="#ffffff">
26
27<a name="title">&nbsp;</a>
28<h1 align=center>Valgrind Skins</h1>
29<center>
30 A guide to writing new skins for Valgrind<br>
31 This guide was last updated on 20020926
32</center>
33<p>
34
35<center>
sewardj689cf192002-10-02 09:11:34 +0000[diff] [blame]36<a href="mailto:njn25@cam.ac.uk">njn25@cam.ac.uk</a><br>
37Nick Nethercote, October 2002
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]38<p>
39Valgrind is licensed under the GNU General Public License,
40version 2<br>
41An open-source tool for supervising execution of Linux-x86 executables.
42</center>
43
44<p>
45
46<hr width="100%">
47<a name="contents"></a>
48<h2>Contents of this manual</h2>
49
50<h4>1&nbsp; <a href="#intro">Introduction</a></h4>
51 1.1&nbsp; <a href="#supexec">Supervised Execution</a><br>
52 1.2&nbsp; <a href="#skins">Skins</a><br>
53 1.3&nbsp; <a href="#execspaces">Execution Spaces</a><br>
54
55<h4>2&nbsp; <a href="#writingaskin">Writing a Skin</a></h4>
56 2.1&nbsp; <a href="#whywriteaskin">Why write a skin?</a><br>
57 2.2&nbsp; <a href="#howskinswork">How skins work</a><br>
58 2.3&nbsp; <a href="#gettingcode">Getting the code</a><br>
59 2.4&nbsp; <a href="#gettingstarted">Getting started</a><br>
60 2.5&nbsp; <a href="#writingcode">Writing the code</a><br>
61 2.6&nbsp; <a href="#init">Initialisation</a><br>
62 2.7&nbsp; <a href="#instr">Instrumentation</a><br>
63 2.8&nbsp; <a href="#fini">Finalisation</a><br>
64 2.9&nbsp; <a href="#otherimportantinfo">Other important information</a><br>
65 2.10&nbsp; <a href="#wordsofadvice">Words of advice</a><br>
66
67<h4>3&nbsp; <a href="#advancedtopics">Advanced Topics</a></h4>
68 3.1&nbsp; <a href="#suppressions">Suppressions</a><br>
69 3.2&nbsp; <a href="#documentation">Documentation</a><br>
70 3.3&nbsp; <a href="#regressiontests">Regression tests</a><br>
71 3.4&nbsp; <a href="#profiling">Profiling</a><br>
72 3.5&nbsp; <a href="#othermakefilehackery">Other makefile hackery</a><br>
73
74<h4>4&nbsp; <a href="#finalwords">Final Words</a></h4>
75
76<hr width="100%">
77
78<a name="intro"></a>
79<h2>1&nbsp; Introduction</h2>
80
81<a name="supexec"></a>
82<h3>1.1&nbsp; Supervised Execution</h3>
83
84Valgrind provides a generic infrastructure for supervising the execution of
85programs. This is done by providing a way to instrument programs in very
86precise ways, making it relatively easy to support activities such as dynamic
87error detection and profiling.<p>
88
89Although writing a skin is not easy, and requires learning quite a few things
90about Valgrind, it is much easier than instrumenting a program from scratch
91yourself.
92
93<a name="skins"></a>
94<h3>1.2&nbsp; Skins</h3>
95The key idea behind Valgrind's architecture is the division between its
96``core'' and ``skins''.
97<p>
98The core provides the common low-level infrastructure to support program
99instrumentation, including the x86-to-x86 JIT compiler, low-level memory
100manager, signal handling and a scheduler (for pthreads). It also provides
101certain services that are useful to some but not all skins, such as support
102for error recording and suppression.
103<p>
104But the core leaves certain operations undefined, which must be filled by skins.
105Most notably, skins define how program code should be instrumented. They can
106also define certain variables to indicate to the core that they would like to
107use certain services, or be notified when certain interesting events occur.
108<p>
109Each skin that is written defines a new program supervision tool. Writing a
110new tool just requires writing a new skin. The core takes care of all the hard
111work.
112<p>
113
114<a name="execspaces"></a>
115<h3>1.3&nbsp; Execution Spaces</h3>
116An important concept to understand before writing a skin is that there are
117three spaces in which program code executes:
118
119<ol>
120 <li>User space: this covers most of the program's execution. The skin is
121 given the code and can instrument it any way it likes, providing (more or
122 less) total control over the code.<p>
123
124 Code executed in user space includes all the program code, almost all of
125 the C library (including things like the dynamic linker), and almost
126 all parts of all other libraries.
127 </li><p>
128
129 <li>Core space: a small proportion of the program's execution takes place
130 entirely within Valgrind's core. This includes:<p>
131
132 <ul>
133 <li>Dynamic memory management (<code>malloc()</code> etc.)</li>
134
135 <li>Pthread operations and scheduling</li>
136
137 <li>Signal handling</li>
138 </ul><p>
139
140 A skin has no control over these operations; it never ``sees'' the code
141 doing this work and thus cannot instrument it. However, the core
142 provides hooks so a skin can be notified when certain interesting events
143 happen, for example when when dynamic memory is allocated or freed, the
144 stack pointer is changed, or a pthread mutex is locked, etc.<p>
145
146 Note that these hooks only notify skins of events relevant to user
147 space. For example, when the core allocates some memory for its own use,
148 the skin is not notified of this, because it's not directly part of the
149 supervised program's execution.
150 </li><p>
151
152 <li>Kernel space: execution in the kernel. Two kinds:<p>
153
154 <ol>
155 <li>System calls: can't be directly observed by either the skin or the
156 core. But the core does have some idea of what happens to the
157 arguments, and it provides hooks for a skin to wrap system calls.
158 </li><p>
159
160 <li>Other: all other kernel activity (e.g. process scheduling) is
161 totally opaque and irrelevant to the program.
162 </li><p>
163 </ol>
164 </li><p>
165
166 It should be noted that a skin only has direct control over code executed in
167 user space. This is the vast majority of code executed, but it is not
168 absolutely all of it, so any profiling information recorded by a skin won't
169 be totally accurate.
170</ol>
171
172
173<a name="writingaskin"></a>
174<h2>2&nbsp; Writing a Skin</h2>
175
176<a name="whywriteaskin"</a>
177<h3>2.1&nbsp; Why write a skin?</h3>
178
179Before you write a skin, you should have some idea of what it should do. What
180is it you want to know about your programs of interest? Consider some existing
181skins:
182
183<ul>
184 <li>memcheck: among other things, performs fine-grained validity and
185 addressibility checks of every memory reference performed by the program
186 </li><p>
187
188 <li>addrcheck: performs lighterweight addressibility checks of every memory
189 reference performed by the program</li><p>
190
191 <li>cachegrind: tracks every instruction and memory reference to simulate
192 instruction and data caches, tracking cache accesses and misses that
193 occur on every line in the program</li><p>
194
195 <li>helgrind: tracks every memory access and mutex lock/unlock to determine
196 if a program contains any data races</li><p>
197
198 <li>lackey: does simple counting of various things: the number of calls to a
199 particular function (<code>_dl_runtime_resolve()</code>); the number of
200 basic blocks, x86 instruction, UCode instructions executed; the number
201 of branches executed and the proportion of those which were taken.</li><p>
202</ul>
203
204These examples give a reasonable idea of what kinds of things Valgrind can be
205used for. The instrumentation can range from very lightweight (e.g. counting
sewardj689cf192002-10-02 09:11:34 +0000[diff] [blame]206the number of times a particular function is called) to very intrusive (e.g.
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]207memcheck's memory checking).
208
209<a name="howskinswork"</a>
210<h3>2.2&nbsp; How skins work</h3>
211
212Skins must define various functions for instrumenting programs that are called
213by Valgrind's core, yet they must be implemented in such a way that they can be
214written and compiled without touching Valgrind's core. This is important,
215because one of our aims is to allow people to write and distribute their own
216skins that can be plugged into Valgrind's core easily.<p>
217
218This is achieved by packaging each skin into a separate shared object which is
219then loaded ahead of the core shared object <code>valgrind.so</code>, using the
220dynamic linker's <code>LD_PRELOAD</code> variable. Any functions defined in
221the skin that share the name with a function defined in core (such as
222the instrumentation function <code>SK_(instrument)()</code>) override the
223core's definition. Thus the core can call the necessary skin functions.<p>
224
225This magic is all done for you; the shared object used is chosen with the
226<code>--skin</code> option to the <code>valgrind</code> startup script. The
227default skin used is <code>memcheck</code>, Valgrind's original memory checker.
228
229<a name="gettingcode"</a>
230<h3>2.3&nbsp; Getting the code</h3>
231
232To write your own skin, you'll need to check out a copy of Valgrind from the
233CVS repository, rather than using a packaged distribution. This is because it
234contains several extra files needed for writing skins.<p>
235
236To check out the code from the CVS repository, first login:
237<blockquote><code>
238cvs -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind login
239</code></blockquote>
240
241Then checkout the code. To get a copy of the current development version
242(recommended for the brave only):
243<blockquote><code>
244cvs -z3 -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind co valgrind
245</code></blockquote>
246
247To get a copy of the stable released branch:
248<blockquote><code>
249cvs -z3 -d:pserver:anonymous@cvs.valgrind.sourceforge.net:/cvsroot/valgrind co -r <i>TAG</i> valgrind
250</code></blockquote>
251
252where <code><i>TAG</i></code> has the form <code>VALGRIND_X_Y_Z</code> for
253version X.Y.Z.
254
255<a name="gettingstarted"</a>
256<h3>2.4&nbsp; Getting started</h3>
257
258Valgrind uses GNU <code>automake</code> and <code>autoconf</code> for the
259creation of Makefiles and configuration. But don't worry, these instructions
260should be enough to get you started even if you know nothing about those
261tools.<p>
262
263In what follows, all filenames are relative to Valgrind's top-level directory
264<code>valgrind/</code>.
265
266<ol>
267 <li>Choose a name for the skin, and an abbreviation that can be used as a
268 short prefix. We'll use <code>foobar</code> and <code>fb</code> as an
269 example.
270 </li><p>
271
272 <li>Make a new directory <code>foobar/</code> which will hold the skin.
273 </li><p>
274
275 <li>Copy <code>example/Makefile.am</code> into <code>foobar/</code>.
276 Edit it by replacing all occurrences of the string
277 ``<code>example</code>'' with ``<code>foobar</code>'' and the one
278 occurrence of the string ``<code>ex_</code>'' with ``<code>fb_</code>''.
279 It might be worth trying to understand this file, at least a little; you
280 might have to do more complicated things with it later on. In
281 particular, the name of the <code>vgskin_foobar_so_SOURCES</code> variable
282 determines the name of the skin's shared object, which determines what
283 name must be passed to the <code>--skin</code> option to use the skin.
284 </li><p>
285
286 <li>Copy <code>example/ex_main.c</code> into
287 <code>foobar/</code>, renaming it as <code>fb_main.c</code>.
njnd04b7c62002-10-03 14:05:52 +0000[diff] [blame]288 Edit it by changing the five lines in <code>SK_(pre_clo_init)()</code>
289 to something appropriate for the skin. These fields are used in the
290 startup message, except for <code>bug_reports_to</code> which is used
291 if a skin assertion fails.
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]292 </li><p>
293
294 <li>Edit <code>Makefile.am</code>, adding the new directory
295 <code>foobar</code> to the <code>SUBDIRS</code> variable.
296 </li><p>
297
298 <li>Edit <code>configure.in</code>, adding <code>foobar/Makefile</code> to the
299 <code>AC_OUTPUT</code> list.
300 </li><p>
301
302 <li>Run:
303 <pre>
304 autogen.sh
305 ./configure --prefix=`pwd`/inst
306 make install</pre>
307
308 It should automake, configure and compile without errors, putting copies
309 of the skin's shared object <code>vgskin_foobar.so</code> in
310 <code>foobar/</code> and
311 <code>inst/lib/valgrind/</code>.
312 </li><p>
313
314 <li>You can test it with a command like
315 <pre>
316 inst/bin/valgrind --skin=foobar date</pre>
317
318 (almost any program should work; <code>date</code> is just an example).
319 The output should be something like this:
320 <pre>
njnd04b7c62002-10-03 14:05:52 +0000[diff] [blame]321==738== foobar-0.0.1, a foobarring tool for x86-linux.
322==738== Copyright (C) 2002, and GNU GPL'd, by J. Random Hacker.
323==738== Built with valgrind-1.1.0, a program execution monitor.
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]324==738== Copyright (C) 2000-2002, and GNU GPL'd, by Julian Seward.
325==738== Estimated CPU clock rate is 1400 MHz
326==738== For more details, rerun with: -v
327==738==
328Wed Sep 25 10:31:54 BST 2002
329==738==</pre>
330
331 The skin does nothing except run the program uninstrumented.
332 </li><p>
333</ol>
334
335These steps don't have to be followed exactly - you can choose different names
336for your source files, and use a different <code>--prefix</code> for
337<code>./configure</code>.<p>
338
339Now that we've setup, built and tested the simplest possible skin, onto the
340interesting stuff...
341
342
343<a name="writingcode"></a>
344<h3>2.5&nbsp; Writing the code</h3>
345
346A skin must define at least these four functions:
347<pre>
348 SK_(pre_clo_init)()
349 SK_(post_clo_init)()
350 SK_(instrument)()
351 SK_(fini)()
352</pre>
353
354In addition, if a skin wants to use some of the optional services provided by
355the core, it may have to define other functions.
356
357<a name="init"></a>
358<h3>2.6&nbsp; Initialisation</h3>
359
360Most of the initialisation should be done in <code>SK_(pre_clo_init)()</code>.
361Only use <code>SK_(post_clo_init)()</code> if a skin provides command line
362options and must do some initialisation after option processing takes place
363(``<code>clo</code>'' stands for ``command line options'').<p>
364
365The first argument to <code>SK_(pre_clo_init)()</code> must be initialised with
366the ``needs'' for a skin. Of these, <code>name</code> and
367<code>description</code> are compulsory. The rest are mostly booleans, and can
368be left untouched (they default to <code>False</code>). They determine whether
369a skin can do various things such as: record, report and suppress errors;
370process command line options; wrap system calls; record extra information
371about malloc'd blocks, etc.<p>
372
373For example, if a skin wants the core's help in recording and reporting errors,
374it must set the <code>skin_errors</code> need to <code>True</code>, and then
375provide definitions of six functions for comparing errors, printing out errors,
376reading suppressions from a suppressions file, etc. While writing these
377functions requires some work, it's much less than doing error handling from
378scratch because the core is doing most of the work. See the type
379<code>VgNeeds</code> in <code>include/vg_skin.h</code> for full details of all
380the needs.<p>
381
382The second argument to <code>SK_(pre_clo_init)()</code> must be initialised to
383indicate which events in core the skin wants to be notified about. These
384include things such as blocks of memory being malloc'd, the stack pointer
385changing, a mutex being locked, etc. If a skin wants to know about this,
386it should set the relevant pointer in the structure to point to a function,
387which will be called when that event happens.<p>
388
389For example, if the skin want to be notified when a new block of memory is
390malloc'd, it should set the <code>new_mem_heap</code> function pointer, and the
391assigned function will be called each time this happens. See the type
392<code>VgTrackEvents</code> in <code>include/vg_skin.h</code> for full details
393of all the trackable events.<p>
394
395<a name="instr"></a>
396<h3>2.7&nbsp; Instrumentation</h3>
397
398<code>SK_(instrument)()</code> is the interesting one. It allows you to
399instrument <i>UCode</i>, which is Valgrind's RISC-like intermediate language.
400UCode is described in the <a href="techdocs.html">technical docs</a>.
401
402The easiest way to instrument UCode is to insert calls to C functions when
403interesting things happen. See the skin ``lackey''
404(<code>lackey/lk_main.c</code>) for a simple example of this, or
405Cachegrind (<code>cachegrind/cg_main.c</code>) for a more complex
406example.<p>
407
408A much more complicated way to instrument UCode, albeit one that might result
409in faster instrumented programs, is to extend UCode with new UCode
410instructions. This is recommended for advanced Valgrind hackers only! See the
411``memcheck'' skin for an example.
412
413<a name="fini"></a>
414<h3>2.8&nbsp; Finalisation</h3>
415
416This is where you can present the final results, such as a summary of the
417information collected. Any log files should be written out at this point.
418
419<a name="otherimportantinfo"></a>
420<h3>2.9&nbsp; Other important information</h3>
421
422Please note that the core/skin split infrastructure is all very new, and not
423very well documented. Here are some important points, but there are
424undoubtedly many others that I should note but haven't thought of.<p>
425
426The file <code>include/vg_skin.h</code> contains all the types,
427macros, functions, etc. that a skin should (hopefully) need, and is the only
428<code>.h</code> file a skin should need to <code>#include</code>.<p>
429
430In particular, you probably shouldn't use anything from the C library (there
431are deep reasons for this, trust us). Valgrind provides an implementation of a
432reasonable subset of the C library, details of which are in
433<code>vg_skin.h</code>.<p>
434
435Similarly, when writing a skin, you shouldn't need to look at any of the code
436in Valgrind's core. Although it might be useful sometimes to help understand
437something.<p>
438
439<code>vg_skin.h</code> has a reasonable amount of documentation in it that
440should hopefully be enough to get you going. But ultimately, the skins
441distributed (memcheck, addrcheck, cachegrind, lackey, etc.) are probably the
442best documentation of all, for the moment.<p>
443
444Note that the <code>VG_</code> and <code>SK_</code> macros are used heavily.
445These just prepend longer strings in front of names to avoid potential
446namespace clashes. We strongly recommend using the <code>SK_</code> macro
447for any global functions and variables in your skin.<p>
448
449<a name="wordsofadvice"</a>
450<h3>2.10&nbsp; Words of Advice</h3>
451
452Writing and debugging skins is not trivial. Here are some suggestions for
453solving common problems.<p>
454
455If you are getting segmentation faults in C functions used by your skin, the
456usual GDB command:
457<blockquote><code>gdb <i>prog</i> core</code></blockquote>
458usually gives the location of the segmentation fault.<p>
459
460If you want to debug C functions used by your skin, you can attach GDB to
461Valgrind with some effort:
462<ul>
sewardj689cf192002-10-02 09:11:34 +0000[diff] [blame]463 <li>Enable the following code in <code>coregrind/vg_main.c</code> by
464 changing <code>if (0)</code> into <code>if (1)</code>:
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]465<pre>
466 /* Hook to delay things long enough so we can get the pid and
467 attach GDB in another shell. */
sewardj689cf192002-10-02 09:11:34 +0000[diff] [blame]468 if (0) {
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]469 Int p, q;
470 for (p = 0; p < 50000; p++)
471 for (q = 0; q < 50000; q++) ;
472 }
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]473 </li><p>
474 and rebuild Valgrind.
475
476 <li>Then run:
477 <blockquote><code>valgrind <i>prog</i></code></blockquote>
478
479 Valgrind starts the program, printing its process id, and then delays for
480 a few seconds (you may have to change the loop bounds to get a suitable
481 delay).</li><p>
482
483 <li>In a second shell run:
484
485 <blockquote><code>gdb <i>prog</i> <i>pid</i></code></blockquote></li><p>
486</ul>
487
sewardj689cf192002-10-02 09:11:34 +0000[diff] [blame]488GDB may be able to give you useful information. Note that by default
489most of the system is built with <code>-fomit-frame-pointer</code>,
490and you'll need to get rid of this to extract useful tracebacks from
491GDB.<p>
njn027c99c2002-09-27 10:29:51 +0000[diff] [blame]492
493If you just want to know whether a program point has been reached, using the
494<code>OINK</code> macro (in <code> include/vg_skin.h</code>) can be easier than
495using GDB.<p>
496
497If you are having problems with your UCode instrumentation, it's likely that
498GDB won't be able to help at all. In this case, Valgrind's
499<code>--trace-codegen</code> option is invaluable for observing the results of
500instrumentation.<p>
501
502The other debugging command line options can be useful too (run <code>valgrind
503-h</code> for the list).<p>
504
505<a name="advancedtopics"></a>
506<h2>3&nbsp; Advanced Topics</h2>
507
508Once a skin becomes more complicated, there are some extra things you may
509want/need to do.
510
511<a name="suppressions"</a>
512<h3>3.1&nbsp; Suppressions</h3>
513
514If your skin reports errors and you want to suppress some common ones, you can
515add suppressions to the suppression files. The relevant files are
516<code>valgrind/*.supp</code>; the final suppression file is aggregated from
517these files by combining the relevant <code>.supp</code> files depending on the
518versions of linux, X and glibc on a system.
519
520<a name="documentation"</a>
521<h3>3.2&nbsp; Documentation</h3>
522
523If you are feeling conscientious and want to write some HTML documentation for
524your skin, follow these steps (using <code>foobar</code> as the example skin
525name again):
526
527<ol>
528 <li>Make a directory <code>foobar/docs/</code>.
529 </li><p>
530
531 <li>Edit <code>foobar/Makefile.am</code>, adding <code>docs</code> to
532 the <code>SUBDIRS</code> variable.
533 </li><p>
534
535 <li>Edit <code>configure.in</code>, adding
536 <code>foobar/docs/Makefile</code> to the <code>AC_OUTPUT</code> list.
537 </li><p>
538
539 <li>Write <code>foobar/docs/Makefile.am</code>. Use
540 <code>memcheck/docs/Makefile.am</code> as an example.
541 </li>
542
543 <li>Write the documentation; the top-level file should be called
544 <code>foobar/docs/index.html</code>.
545 </li><p>
546
547 <li>(optional) Add a link in the main documentation index
548 <code>docs/index.html</code> to
549 <code>foobar/docs/index.html</code>
550 </li><p>
551</ol>
552
553<a name="regressiontests"</a>
554<h3>3.3&nbsp; Regression tests</h3>
555
556Valgrind has some support for regression tests. If you want to write
557regression tests for your skin:
558
559<ol>
560 <li>Make a directory <code>foobar/tests/</code>.
561 </li><p>
562
563 <li>Edit <code>foobar/Makefile.am</code>, adding <code>tests</code> to
564 the <code>SUBDIRS</code> variable.
565 </li><p>
566
567 <li>Edit <code>configure.in</code>, adding
568 <code>foobar/tests/Makefile</code> to the <code>AC_OUTPUT</code> list.
569 </li><p>
570
571 <li>Write <code>foobar/tests/Makefile.am</code>. Use
572 <code>memcheck/tests/Makefile.am</code> as an example.
573 </li><p>
574
575 <li>Write the tests, <code>.vgtest</code> test description files,
576 <code>.stdout.exp</code> and <code>.stderr.exp</code> expected output
577 files. (Note that Valgrind's output goes to stderr.) Some details
578 on writing and running tests are given in the comments at the top of the
579 testing script <code>tests/vg_regtest</code>.
580 </li><p>
581
582 <li>Write a filter for stderr results <code>foobar/tests/filter_stderr</code>.
583 It can call the existing filters in <code>tests/</code>. See
584 <code>memcheck/tests/filter_stderr</code> for an example; in particular
585 note the <code>$dir</code> trick that ensures the filter works correctly
586 from any directory.
587 </li><p>
588</ol>
589
590<a name="profiling"</a>
591<h3>3.4&nbsp; Profiling</h3>
592
593To do simple tick-based profiling of a skin, include the line
594<blockquote>
595#include "vg_profile.c"
596</blockquote>
597in the skin somewhere, and rebuild (you may have to <code>make clean</code>
598first). Then run Valgrind with the <code>--profile=yes</code> option.<p>
599
600The profiler is stack-based; you can register a profiling event with
601<code>VGP_(register_profile_event)()</code> and then use the
602<code>VGP_PUSHCC</code> and <code>VGP_POPCC</code> macros to record time spent
603doing certain things. New profiling event numbers must not overlap with the
604core profiling event numbers. See <code>include/vg_skin.h</code> for details
605and the ``memcheck'' skin for an example.
606
607
608<a name="othermakefilehackery"</a>
609<h3>3.5&nbsp; Other makefile hackery</h3>
610
611If you add any directories under <code>valgrind/foobar/</code>, you will
612need to add an appropriate <code>Makefile.am</code> to it, and add a
613corresponding entry to the <code>AC_OUTPUT</code> list in
614<code>valgrind/configure.in</code>.<p>
615
616If you add any scripts to your skin (see Cachegrind for an example) you need to
617add them to the <code>bin_SCRIPTS</code> variable in
618<code>valgrind/foobar/Makefile.am</code>.<p>
619
620
621<a name="finalwords"></a>
622<h2>4&nbsp; Final Words</h2>
623
624This whole core/skin business is very new and experimental, and under active
625development.<p>
626
627The first consequence of this is that the core/skin interface is quite
628immature. It will almost certainly change in the future; we have no intention
629of freezing it and then regretting the inevitable stupidities. Hopefully most
630of the future changes will be to add new features, hooks, functions, etc,
631rather than to change old ones, which should cause a minimum of trouble for
632existing skins, but we can't guarantee it. Just something to be aware of.<p>
633
634The second consequence of this is that we'd love to hear your feedback about
635it:
636
637<ul>
638 <li>If you love it or hate it</li><p>
639 <li>If you find bugs</li><p>
640 <li>If you write a skin</li><p>
641 <li>If you have suggestions for new features, needs, trackable events,
642 functions</li><p>
643 <li>If you have suggestions for making skins easier to write
644 </li><p>
645 <li>If you have suggestions for improving this documentation </li><p>
646 <li>If you don't understand something</li><p>
647</ul>
648
649or anything else!<p>
650
651Happy programming.
652