Documentation changes only.
Added a couple of links to the "Valgrind skins" doc, because there were none.
Added a section "suggested skins" in the "Valgrind skins" doc, just in case it
inspires anyone in user-land.
MERGE TO STABLE
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@1482 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/coregrind/docs/coregrind_intro.html b/coregrind/docs/coregrind_intro.html
index 373bec6..f2d4197 100644
--- a/coregrind/docs/coregrind_intro.html
+++ b/coregrind/docs/coregrind_intro.html
@@ -149,7 +149,8 @@
The skins each have their own chapters in this manual. You only need
to read the documentation for the core services and for the skin(s)
you actually use, although you may find it helpful to be at least a
-little bit familar with what all skins do.
+little bit familar with what all skins do. If you want to write a new
+skin, read <A HREF="coregrind_skins.html">this</A>.
<p>
If you're new to all this, you're most likely to be using the Memcheck
diff --git a/coregrind/docs/coregrind_skins.html b/coregrind/docs/coregrind_skins.html
index 1559098..291dd3a 100644
--- a/coregrind/docs/coregrind_skins.html
+++ b/coregrind/docs/coregrind_skins.html
@@ -28,13 +28,13 @@
<h1 align=center>Valgrind Skins</h1>
<center>
A guide to writing new skins for Valgrind<br>
- This guide was last updated on 20020926
+ This guide was last updated on 20030325
</center>
<p>
<center>
<a href="mailto:njn25@cam.ac.uk">njn25@cam.ac.uk</a><br>
-Nick Nethercote, October 2002
+Nick Nethercote
<p>
Valgrind is licensed under the GNU General Public License,
version 2<br>
@@ -54,15 +54,16 @@
<h4>2 <a href="#writingaskin">Writing a Skin</a></h4>
2.1 <a href="#whywriteaskin">Why write a skin?</a><br>
- 2.2 <a href="#howskinswork">How skins work</a><br>
- 2.3 <a href="#gettingcode">Getting the code</a><br>
- 2.4 <a href="#gettingstarted">Getting started</a><br>
- 2.5 <a href="#writingcode">Writing the code</a><br>
- 2.6 <a href="#init">Initialisation</a><br>
- 2.7 <a href="#instr">Instrumentation</a><br>
- 2.8 <a href="#fini">Finalisation</a><br>
- 2.9 <a href="#otherimportantinfo">Other important information</a><br>
- 2.10 <a href="#wordsofadvice">Words of advice</a><br>
+ 2.2 <a href="#suggestedskins">Suggested skins</a><br>
+ 2.3 <a href="#howskinswork">How skins work</a><br>
+ 2.4 <a href="#gettingcode">Getting the code</a><br>
+ 2.5 <a href="#gettingstarted">Getting started</a><br>
+ 2.6 <a href="#writingcode">Writing the code</a><br>
+ 2.7 <a href="#init">Initialisation</a><br>
+ 2.8 <a href="#instr">Instrumentation</a><br>
+ 2.9 <a href="#fini">Finalisation</a><br>
+ 2.10 <a href="#otherimportantinfo">Other important information</a><br>
+ 2.11 <a href="#wordsofadvice">Words of advice</a><br>
<h4>3 <a href="#advancedtopics">Advanced Topics</a></h4>
3.1 <a href="#suppressions">Suppressions</a><br>
@@ -207,8 +208,79 @@
the number of times a particular function is called) to very intrusive (e.g.
memcheck's memory checking).
+
+<a name="suggestedskins"</a>
+<h3>2.2 Suggested skins</h3>
+
+Here is a list of ideas we have had for skins that should not be too hard to
+implement.
+
+<ul>
+ <li>branch profiler: A machine's branch prediction hardware could be
+ simulated, and each branch annotated with the number of predicted and
+ mispredicted branches. Would be implemented quite similarly to
+ Cachegrind, and could reuse the <code>cg_annotate</code> script to
+ annotate source code.<p>
+
+ The biggest difficulty with this is the simulation; the chip-makers
+ are very cagey about how their chips do branch prediction. But
+ implementing one or more of the basic algorithms could still give good
+ information.
+ </li><p>
+
+ <li>coverage tool: Cachegrind can already be used for doing test coverage,
+ but it's massive overkill to use it just for that.<p>
+
+ It would be easy to write a coverage tool that records how many times
+ each basic block was recorded. Again, the <code>cg_annotate</code>
+ script could be used for annotating source code with the gathered
+ information. Although, <code>cg_annotate</code> is only designed for
+ working with single program runs. It could be extended relatively easily
+ to deal with multiple runs of a program, so that the coverage of a whole
+ test suite could be determined.<p>
+
+ In addition to the standard coverage information, such a tool could
+ record extra information that would help a user generate test cases to
+ exercise unexercised paths. For example, for each conditional branch,
+ the skin could record all inputs to the conditional test, and print these
+ out when annotating.<p>
+
+ <li>run-time type checking: A nice example of a dynamic checker is given
+ in this paper:
+
+ <blockquote>
+ Debugging via Run-Time Type Checking<br>
+ Alexey Loginov, Suan Hsi Yong, Susan Horwitz and Thomas Reps<br>
+ Proceedings of Proceedings of Fundamental Approaches to Software
+ Engineering<br>
+ April 2001.
+ </blockquote>
+
+ This approach can find quite a range of bugs in C and C++ programs.<p>
+
+ This could be implemented quite nicely as a Valgrind skin. One
+ complication is that the described tool works directly on C code, and
+ Valgrind skins work on UCode, but the approach can hopefully still be
+ used with only minor modifications.<p>
+
+ Ways to speed up this run-time type checking are described in this paper:
+
+ <blockquote>
+ Reducing the Overhead of Dynamic Analysis<br>
+ Suan Hsi Yong and Susan Horwitz<br>
+ Proceedings of Runtime Verification '02<br>
+ July 2002.
+ </blockquote>
+
+ Valgrind's client requests could be used to pass information to a skin
+ about which elements need instrumentation and which don't.
+ </li><p>
+</ul>
+
+We would love to hear from anyone who implements these or other skins.
+
<a name="howskinswork"</a>
-<h3>2.2 How skins work</h3>
+<h3>2.3 How skins work</h3>
Skins must define various functions for instrumenting programs that are called
by Valgrind's core, yet they must be implemented in such a way that they can be
@@ -228,7 +300,7 @@
default skin used is <code>memcheck</code>, Valgrind's original memory checker.
<a name="gettingcode"</a>
-<h3>2.3 Getting the code</h3>
+<h3>2.4 Getting the code</h3>
To write your own skin, you'll need to check out a copy of Valgrind from the
CVS repository, rather than using a packaged distribution. This is because it
@@ -254,7 +326,7 @@
version X.Y.Z.
<a name="gettingstarted"</a>
-<h3>2.4 Getting started</h3>
+<h3>2.5 Getting started</h3>
Valgrind uses GNU <code>automake</code> and <code>autoconf</code> for the
creation of Makefiles and configuration. But don't worry, these instructions
@@ -342,7 +414,7 @@
<a name="writingcode"></a>
-<h3>2.5 Writing the code</h3>
+<h3>2.6 Writing the code</h3>
A skin must define at least these four functions:
<pre>
@@ -362,7 +434,7 @@
the core, it may have to define other functions.
<a name="init"></a>
-<h3>2.6 Initialisation</h3>
+<h3>2.7 Initialisation</h3>
Most of the initialisation should be done in <code>SK_(pre_clo_init)()</code>.
Only use <code>SK_(post_clo_init)()</code> if a skin provides command line
@@ -407,7 +479,7 @@
found in <code>include/vg_skin.h</code>.<p>
<a name="instr"></a>
-<h3>2.7 Instrumentation</h3>
+<h3>2.8 Instrumentation</h3>
<code>SK_(instrument)()</code> is the interesting one. It allows you to
instrument <i>UCode</i>, which is Valgrind's RISC-like intermediate language.
@@ -425,13 +497,13 @@
``memcheck'' skin for an example.
<a name="fini"></a>
-<h3>2.8 Finalisation</h3>
+<h3>2.9 Finalisation</h3>
This is where you can present the final results, such as a summary of the
information collected. Any log files should be written out at this point.
<a name="otherimportantinfo"></a>
-<h3>2.9 Other important information</h3>
+<h3>2.10 Other important information</h3>
Please note that the core/skin split infrastructure is all very new, and not
very well documented. Here are some important points, but there are
@@ -461,7 +533,7 @@
for any global functions and variables in your skin.<p>
<a name="wordsofadvice"</a>
-<h3>2.10 Words of Advice</h3>
+<h3>2.11 Words of Advice</h3>
Writing and debugging skins is not trivial. Here are some suggestions for
solving common problems.<p>
diff --git a/docs/manual.html b/docs/manual.html
index 4ba4947..b4668cb 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -100,14 +100,23 @@
<h4>6 <a href="hg_main.html#hg-top">
Helgrind: a data-race detector</a></h4>
+<p>
+The following is not part of the user manual. It describes how you can
+write skins for Valgrind, in order to make new program supervision
+tools.
+
+<h4>7 <a href="coregrind_skins.html">
+ Valgrind Skins</a></h4>
+
+<p>
The following are not part of the user manual. They describe internal
details of how Valgrind works. Reading them may rot your mind. You
have been warned.
-<h4>7 <a href="mc_techdocs.html#mc-techdocs">
+<h4>8 <a href="mc_techdocs.html#mc-techdocs">
The design and implementation of Valgrind</a></h4>
-<h4>8 <a href="cg_techdocs.html#cg-techdocs">
+<h4>9 <a href="cg_techdocs.html#cg-techdocs">
How Cachegrind works</a></h4>
<hr width="100%">