From: Nicholas Nethercote Date: Tue, 27 Nov 2007 01:59:02 +0000 (+0000) Subject: Tweaked the tool-writing docs. X-Git-Tag: svn/VALGRIND_3_3_0~55 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5293c35183262e410248e0e48ea4292e52622c4a;p=thirdparty%2Fvalgrind.git 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 8c520cdec3..c57eb1a500 100644 --- 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 55da11522f..6833b5bdfc 100644 --- a/docs/xml/manual-writing-tools.xml +++ b/docs/xml/manual-writing-tools.xml @@ -158,16 +158,17 @@ top-level directory valgrind/. The output should be something like this: - The tool does nothing except run the program - uninstrumented. + The tool does nothing except run the program uninstrumented. @@ -270,8 +271,9 @@ can be found in instrument() is the interesting one. It allows you to instrument VEX IR, which is -Valgrind's RISC-like intermediate language. VEX IR is best described in -the header file VEX/pub/libvex_ir.h. +Valgrind's RISC-like intermediate language. VEX IR is described fairly well +in the comments of the header file +VEX/pub/libvex_ir.h. 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. The files include/pub_tool_*.h contain all the types, macros, functions, etc. that a tool should (hopefully) need, and are the only .h files a tool should need to -#include. +#include. They have a reasonable amount of +documentation in it that should hopefully be enough to get you going. -In particular, you can't use anything from the C library (there +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 pub_tool_libc*.h. -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. +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. -The pub_tool_*.h files have a reasonable -amount of documentation in it that should hopefully be enough to get -you going. -Also, VEX/pub/libvex_basictypes.h and -VEX/pub/libvex_ir.h 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. +The include/pub_tool_basics.h and +VEX/pub/libvex_basictypes.h files file have some basic +types that are widely used. + +Ultimately, the tools distributed (Memcheck, Cachegrind, Lackey, etc.) +are probably the best documentation of all, for the moment. Note that the VG_ macro is used heavily. This just prepends a longer string in front of names to avoid -potential namespace clashes. +potential namespace clashes. It is defined in +include/pub_tool_basics_asm.h. + +There are some assorted notes about various aspects of the +implementation in docs/internals/. Much of it +isn't that relevant to tool-writers, however. @@ -654,6 +660,10 @@ write regression tests for your tool: To profile a tool, use Cachegrind on it. Read README_DEVELOPERS for details on running Valgrind under Valgrind. +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. +