Tweaked the tool-writing docs.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7237

diff --git a/docs/internals/roadmap.txt b/docs/internals/roadmap.txt
index 8c520cdec33ab1222ad6d01b28a87bfd98bd2b93..c57eb1a50034b750ffbf435a7040f1bc5c0daa2f 100644 (file)
--- a/docs/internals/roadmap.txt
+++ b/docs/internals/roadmap.txt
@@ -13,8 +13,6 @@ Scheduled for mid-to-late 2007?
 
 * Add ppc{32,64}/AIX5 support [Done by Julian]
 
-* Add some more experimental tools?
-
 * Rework Massif [Done by Nick]
 
 * Rework Helgrind [Done by Julian]

diff --git a/docs/xml/manual-writing-tools.xml b/docs/xml/manual-writing-tools.xml
index 55da11522f193a896f33e8e9aeea92a9b1f0dead..6833b5bdfcfc08bd0a5c228293919cd13592c834 100644 (file)
--- a/docs/xml/manual-writing-tools.xml
+++ b/docs/xml/manual-writing-tools.xml
@@ -158,16 +158,17 @@ top-level directory <computeroutput>valgrind/</computeroutput>.</para>
    The output should be something like this:</para>
 <programlisting><![CDATA[
   ==738== foobar-0.0.1, a foobarring tool for x86-linux.
-  ==738== Copyright (C) 1066AD, and GNU GPL'd, by J. Random Hacker.
-  ==738== Built with valgrind-1.1.0, a program execution monitor.
-  ==738== Copyright (C) 2000-2003, and GNU GPL'd, by Julian Seward.
-  ==738== Estimated CPU clock rate is 1400 MHz
+  ==738== Copyright (C) 2002-2007, and GNU GPL'd, by Julian Seward et al.
+  ==738== Using LibVEX rev 1791, a library for dynamic binary translation.
+  ==738== Copyright (C) 2004-2007, and GNU GPL'd, by OpenWorks LLP.
+  ==738== Using valgrind-3.3.0, a dynamic binary instrumentation framework.
+  ==738== Copyright (C) 2000-2007, and GNU GPL'd, by Julian Seward et al.
   ==738== For more details, rerun with: -v
-  ==738== Wed Sep 25 10:31:54 BST 2002
+  ==738==
+  Tue Nov 27 12:40:49 EST 2007
   ==738==]]></programlisting>
 
-   <para>The tool does nothing except run the program
-   uninstrumented.</para>
+   <para>The tool does nothing except run the program uninstrumented.</para>
   </listitem>
 
 </orderedlist>
@@ -270,8 +271,9 @@ can be found in
 
 <para><function>instrument()</function> is the interesting one.  It
 allows you to instrument <emphasis>VEX IR</emphasis>, which is
-Valgrind's RISC-like intermediate language.  VEX IR is best described in
-the header file <filename>VEX/pub/libvex_ir.h</filename>.</para>
+Valgrind's RISC-like intermediate language.  VEX IR is described fairly well
+in the comments of the header file
+<filename>VEX/pub/libvex_ir.h</filename>.</para>
 
 <para>The easiest way to instrument VEX IR is to insert calls to C
 functions when interesting things happen.  See the tool "Lackey"
@@ -305,29 +307,33 @@ thought of.</para>
 <para>The files <filename>include/pub_tool_*.h</filename> contain all the
 types, macros, functions, etc. that a tool should (hopefully) need, and are
 the only <filename>.h</filename> files a tool should need to
-<computeroutput>#include</computeroutput>.</para>
+<computeroutput>#include</computeroutput>.  They have a reasonable amount of
+documentation in it that should hopefully be enough to get you going.</para>
 
-<para>In particular, you can't use anything from the C library (there
+<para>Note that you can't use anything from the C library (there
 are deep reasons for this, trust us).  Valgrind provides an
 implementation of a reasonable subset of the C library, details of which
 are in <filename>pub_tool_libc*.h</filename>.</para>
 
-<para>Similarly, when writing a tool, you shouldn't need to look at any
-of the code in Valgrind's core.  Although it might be useful sometimes
-to help understand something.</para>
+<para>When writing a tool, you shouldn't need to look at any of the code in
+Valgrind's core.  Although it might be useful sometimes to help understand
+something.</para>
 
-<para>The <filename>pub_tool_*.h</filename> files have a reasonable
-amount of documentation in it that should hopefully be enough to get
-you going.  
-Also, <filename>VEX/pub/libvex_basictypes.h</filename> and
-<filename>VEX/pub/libvex_ir.h</filename> have some more details that are
-worth reading, particularly about VEX IR.  But ultimately, the tools
-distributed (Memcheck, Cachegrind, Lackey, etc.) are probably the best
-documentation of all, for the moment.</para>
+<para>The <filename>include/pub_tool_basics.h</filename> and
+<filename>VEX/pub/libvex_basictypes.h</filename> files file have some basic
+types that are widely used.</para>
+
+<para>Ultimately, the tools distributed (Memcheck, Cachegrind, Lackey, etc.)
+are probably the best documentation of all, for the moment.</para>
 
 <para>Note that the <computeroutput>VG_</computeroutput> macro is used
 heavily.  This just prepends a longer string in front of names to avoid
-potential namespace clashes.</para>
+potential namespace clashes.  It is defined in
+<filename>include/pub_tool_basics_asm.h</filename>.</para>
+
+<para>There are some assorted notes about various aspects of the
+implementation in <filename>docs/internals/</filename>.  Much of it
+isn't that relevant to tool-writers, however.</para>
 
 </sect2>
 
@@ -654,6 +660,10 @@ write regression tests for your tool:</para>
 <para>To profile a tool, use Cachegrind on it.  Read README_DEVELOPERS for
 details on running Valgrind under Valgrind.</para>
 
+<para>Alternatively, you can use OProfile.  In most cases, it is better than
+Cachegrind because it's much faster, and gives real times, as opposed to
+instruction and cache hit/miss counts.</para>
+
 </sect2>