From: Tom Hughes Date: Fri, 4 Nov 2005 14:11:05 +0000 (+0000) Subject: Make the tool writing documentation align a bit more closely X-Git-Tag: svn/VALGRIND_3_1_0~233 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8c0b48e4b9ff019acdc7faae50da7f2d7e23c665;p=thirdparty%2Fvalgrind.git Make the tool writing documentation align a bit more closely with reality. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@4999 --- diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml index cd74ea055c..84d37c60b4 100644 --- a/docs/xml/writing-tools.xml +++ b/docs/xml/writing-tools.xml @@ -35,7 +35,7 @@ instrumenting a program from scratch yourself. between its "core" and "tools". The core provides the common low-level infrastructure to -support program instrumentation, including the x86-to-x86 JIT +support program instrumentation, including the JIT compiler, low-level memory manager, signal handling and a scheduler (for pthreads). It also provides certain services that are useful to some but not all tools, such as support for error @@ -43,8 +43,8 @@ recording and suppression. But the core leaves certain operations undefined, which must be filled by tools. Most notably, tools define how program -code should be instrumented. They can also define certain -variables to indicate to the core that they would like to use +code should be instrumented. They can also call certain +functions to indicate to the core that they would like to use certain services, or be notified when certain interesting events occur. But the core takes care of all the hard work. @@ -81,7 +81,7 @@ that there are three spaces in which program code executes: (malloc() etc.) - Pthread operations and scheduling + Thread scheduling Signal handling @@ -177,7 +177,7 @@ interest? Consider some existing tools: lackey: does simple counting of various things: the number of calls to a particular function (_dl_runtime_resolve()); the - number of basic blocks, x86 instruction, UCode instructions + number of basic blocks, guest instructions, VEX instructions executed; the number of branches executed and the proportion of them which were taken. @@ -281,28 +281,17 @@ other tools. How tools work Tools 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 written and compiled -without touching Valgrind's core. This is important, because one -of our aims is to allow people to write and distribute their own -tools that can be plugged into Valgrind's core easily. - -This is achieved by packaging each tool into a separate -shared object which is then loaded ahead of the core shared -object valgrind.so, using the -dynamic linker's LD_PRELOAD -variable. Any functions defined in the tool that share the name -with a function defined in core (such as the instrumentation -function instrument()) -override the core's definition. Thus the core can call the -necessary tool functions. - -This magic is all done for you; the shared object used is -chosen with the --tool option to -the valgrind startup script. -The default tool used is -memcheck, Valgrind's original -memory checker. +programs that are called by Valgrind's core. They are then linked +against the coregrind library +(libcoregrind.a) that valgrind +provides as well as the VEX library +(libvex.a) that also comes with +valgrind and provides the JIT engine. + +Each tool is linked as a statically linked program and placed +in the valgrind library directory from where valgrind will load it +automatically when the --tool option +is used to select it. @@ -357,8 +346,8 @@ top-level directory valgrind/. trying to understand this file, at least a little; you might have to do more complicated things with it later on. In particular, the name of the - vgtool_foobar_so_SOURCES - variable determines the name of the tool's shared object, which + foobar_SOURCES + variable determines the name of the tool, which determines what name must be passed to the --tool option to use the tool. @@ -396,8 +385,7 @@ top-level directory valgrind/. make install]]> It should automake, configure and compile without - errors, putting copies of the tool's shared object - vgtool_foobar.so in + errors, putting copies of the tool in foobar/ and inst/lib/valgrind/. @@ -458,7 +446,7 @@ core and a plugged-in tool are binary compatible. In addition, if a tool wants to use some of the optional services provided by the core, it may have to define other -functions. +functions and tell the code about them. @@ -509,9 +497,8 @@ to be notified about, using the functions VG_(track_*)(). These include things such as blocks of memory being malloc'd, the stack pointer changing, a mutex being locked, etc. If a tool wants to know -about this, it should set the relevant pointer in the structure -to point to a function, which will be called when that event -happens. +about this, it should provide a pointer to a function, which will +be called when that event happens. For example, if the tool want to be notified when a new block of memory is malloc'd, it should call @@ -532,21 +519,16 @@ events" can be found in instrument() is the interesting one. It allows you to instrument -UCode, which is Valgrind's RISC-like -intermediate language. UCode is described in +VEX IR, which is Valgrind's RISC-like +intermediate language. VEX IR is described in . -The easiest way to instrument UCode is to insert calls to C +The easiest way to instrument VEX IR is to insert calls to C functions when interesting things happen. See the tool "Lackey" (lackey/lk_main.c) for a simple example of this, or Cachegrind (cachegrind/cg_main.c) for a more complex example. -A much more complicated way to instrument UCode, albeit one -that might result in faster instrumented programs, is to extend -UCode with new UCode instructions. This is recommended for -advanced Valgrind hackers only! See Memcheck for an example. - @@ -576,7 +558,7 @@ all the types, macros, functions, etc. that a tool should a tool should need to #include. -In particular, you probably shouldn't use anything from the +In particular, 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 @@ -592,13 +574,9 @@ you going. But ultimately, the tools distributed (Memcheck, Addrcheck, Cachegrind, Lackey, etc.) are probably the best documentation of all, for the moment. -Note that the VG_ and -TL_ macros are used heavily. -These just prepend longer strings in front of names to avoid -potential namespace clashes. We strongly recommend using the -TL_ macro for any global -functions and variables in your tool, or writing a similar -macro. +Note that the VG_ macro is used +heavily. This just prepends a longer string in front of names to +avoid potential namespace clashes. @@ -672,9 +650,9 @@ need to get rid of this to extract useful tracebacks from GDB. UCode Instrumentation Problems -If you are having problems with your UCode instrumentation, +If you are having problems with your VEX UIR instrumentation, it's likely that GDB won't be able to help at all. In this case, -Valgrind's --trace-codegen +Valgrind's --trace-flags option is invaluable for observing the results of instrumentation. @@ -690,7 +668,7 @@ reached, using the OINK macro than using GDB. The other debugging command line options can be useful too -(run valgrind -h for the +(run valgrind --help-debug for the list).