From: Nicholas Nethercote Date: Mon, 23 Oct 2006 21:24:55 +0000 (+0000) Subject: Updated docs on tool-writing. Moved them into the user manual. X-Git-Tag: svn/VALGRIND_3_2_2~61 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c4be9563de9a4942f67fd38c5807082327f4f8f8;p=thirdparty%2Fvalgrind.git Updated docs on tool-writing. Moved them into the user manual. MERGED FROM TRUNK git-svn-id: svn://svn.valgrind.org/valgrind/branches/VALGRIND_3_2_BRANCH@6340 --- diff --git a/docs/xml/Makefile.am b/docs/xml/Makefile.am index 0710d55a1d..7958b25887 100644 --- a/docs/xml/Makefile.am +++ b/docs/xml/Makefile.am @@ -4,8 +4,8 @@ EXTRA_DIST = \ index.xml \ licenses.xml \ manual.xml manual-intro.xml manual-core.xml \ + manual-writing-tools.xml\ quick-start-guide.xml \ - writing-tools.xml \ tech-docs.xml \ vg-entities.xml \ xml_help.txt diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml index a2058c970b..8431741a40 100644 --- a/docs/xml/manual-intro.xml +++ b/docs/xml/manual-intro.xml @@ -156,9 +156,9 @@ and profiling. This manual is structured similarly. it supports. Then, each tool has its own chapter in this manual. You only need to read the documentation for the core and for the tool(s) you actually use, although you may find it helpful to be at least a little -bit familar with what all tools do. If you're new to all this, you -probably want to run the Memcheck tool. If you want to write a new -tool, read . +bit familar with what all tools do. If you're new to all this, you probably +want to run the Memcheck tool. The final chapter explains how to write a +new tool. Be aware that the core understands some command line flags, and the tools have their own flags which they know about. This means there diff --git a/docs/xml/writing-tools.xml b/docs/xml/manual-writing-tools.xml similarity index 60% rename from docs/xml/writing-tools.xml rename to docs/xml/manual-writing-tools.xml index 9fa3645bf1..284d1d30c6 100644 --- a/docs/xml/writing-tools.xml +++ b/docs/xml/manual-writing-tools.xml @@ -10,29 +10,14 @@ Introduction - -Supervised Execution - -Valgrind provides a generic infrastructure for supervising -the execution of programs. This is done by providing a way to -instrument programs in very precise ways, making it relatively -easy to support activities such as dynamic error detection and -profiling. - -Although writing a tool is not easy, and requires learning -quite a few things about Valgrind, it is much easier than -instrumenting a program from scratch yourself. - -[Nb: What follows is slightly out of date.] - - - +So you want to write a Valgrind tool? Here are some instructions that may +help. They were last updated for Valgrind 3.2.2. Tools The key idea behind Valgrind's architecture is the division -between its "core" and "tools". +between its "core" and "tool plug-ins". The core provides the common low-level infrastructure to support program instrumentation, including the JIT @@ -50,87 +35,6 @@ occur. But the core takes care of all the hard work. - - -Execution Spaces - -An important concept to understand before writing a tool is -that there are three spaces in which program code executes: - - - - - - User space: this covers most of the program's execution. - The tool is given the code and can instrument it any way it - likes, providing (more or less) total control over the - code. - - Code executed in user space includes all the program - code, almost all of the C library (including things like the - dynamic linker), and almost all parts of all other - libraries. - - - - Core space: a small proportion of the program's execution - takes place entirely within Valgrind's core. This includes: - - - Dynamic memory management - (malloc() etc.) - - - Thread scheduling - - - Signal handling - - - - A tool has no control over these operations; it never - "sees" the code doing this work and thus cannot instrument it. - However, the core provides hooks so a tool can be notified - when certain interesting events happen, for example when - dynamic memory is allocated or freed, the stack pointer is - changed, or a pthread mutex is locked, etc. - - Note that these hooks only notify tools of events - relevant to user space. For example, when the core allocates - some memory for its own use, the tool is not notified of this, - because it's not directly part of the supervised program's - execution. - - - - Kernel space: execution in the kernel. Two kinds: - - - System calls: can't be directly observed by either - the tool or the core. But the core does have some idea of - what happens to the arguments, and it provides hooks for a - tool to wrap system calls. - - - Other: all other kernel activity (e.g. process - scheduling) is totally opaque and irrelevant to the - program. - - - - - - It should be noted that a tool only has direct control - over code executed in user space. This is the vast majority - of code executed, but it is not absolutely all of it, so any - profiling information recorded by a tool won't be totally - accurate. - - - - - - @@ -138,152 +42,13 @@ that there are three spaces in which program code executes: Writing a Tool - - -Why write a tool? - -Before you write a tool, you should have some idea of what -it should do. What is it you want to know about your programs of -interest? Consider some existing tools: - - - - - memcheck: among other things, performs - fine-grained validity and addressibility checks of every memory - reference performed by the program. - - - - cachegrind: tracks every instruction - and memory reference to simulate instruction and data caches, - tracking cache accesses and misses that occur on every line in - the program. - - - - helgrind: tracks every memory access - and mutex lock/unlock to determine if a program contains any - data races. - - - - lackey: does simple counting of - various things: the number of calls to a particular function - (_dl_runtime_resolve()); the - number of basic blocks, guest instructions, VEX instructions - executed; the number of branches executed and the proportion of - them which were taken. - - - -These examples give a reasonable idea of what kinds of -things Valgrind can be used for. The instrumentation can range -from very lightweight (e.g. counting the number of times a -particular function is called) to very intrusive (e.g. -memcheck's memory checking). - - - - - -Suggested tools - -Here is a list of ideas we have had for tools that should -not be too hard to implement. - - - - 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 - cg_annotate script to annotate - source code. - - 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. - - - - coverage tool: Cachegrind can already - be used for doing test coverage, but it's massive overkill to - use it just for that. - - It would be easy to write a coverage tool that records - how many times each basic block was recorded. Again, the - cg_annotate script could be - used for annotating source code with the gathered information. - Although, cg_annotate 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. - - 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 tool could record all - inputs to the conditional test, and print these out when - annotating. - - - - run-time type checking: A nice example - of a dynamic checker is given in this paper: -
Debugging via Run-Time Type Checking - Alexey Loginov, Suan Hsi Yong, Susan Horwitz and Thomas Reps - Proceedings of Fundamental Approaches to Software Engineering - April 2001. -
- - Similar is the tool described in this paper: -
Run-Time Type Checking for Binary Programs - Michael Burrows, Stephen N. Freund, Janet L. Wiener - Proceedings of the 12th International Conference on Compiler Construction (CC 2003) - April 2003. -
- - This approach can find quite a range of bugs, - particularly in C and C++ programs, and could be implemented - quite nicely as a Valgrind tool. - - Ways to speed up this run-time type checking are - described in this paper: -
Reducing the Overhead of Dynamic Analysis - Suan Hsi Yong and Susan Horwitz - Proceedings of Runtime Verification '02 - July 2002. -
- - Valgrind's client requests could be used to pass - information to a tool about which elements need instrumentation - and which don't. - - - -We would love to hear from anyone who implements these or -other tools. - - - - How tools work -Tools must define various functions for instrumenting 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 option is used to select -it. +Tool plug-ins must define various functions for instrumenting programs +that are called by Valgrind's core. They are then linked against +Valgrind's core to define a complete Valgrind tool which will be used +when the option is used to select it. @@ -291,10 +56,10 @@ it. Getting the code -To write your own tool, you'll need the Valgrind source code. A -normal source distribution should do, although you might want to check -out the latest code from the Subversion repository. See the information -about how to do so at the Valgrind +To write your own tool, you'll need the Valgrind source code. You'll +need a check-out of the Subversion repository for the automake/autoconf +build instructions to work. See the information about how to do check-out +from the repository at the Valgrind website. @@ -313,49 +78,59 @@ top-level directory valgrind/. - Choose a name for the tool, and an abbreviation that can be used - as a short prefix. We'll use foobar - and fb as an example. + Choose a name for the tool, and a two-letter abbreviation that can + be used as a short prefix. We'll use + foobar and + fb as an example. + + + + Make three new directories foobar/, + foobar/docs/ and + foobar/tests/. + - Make a new directory foobar/ - which will hold the tool. + Create empty files + foobar/docs/Makefile.am and + foobar/tests/Makefile.am. + Copy none/Makefile.am into - foobar/. Edit it by replacing all + foobar/. Edit it by replacing all occurrences of the string "none" with - "foobar" and the one occurrence of + "foobar", and all occurrences of the string "nl_" with - "fb_". It might be worth 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 - foobar_SOURCES variable determines - the name of the tool, which determines what name must be passed to the - option to use the tool. + "fb_". Copy none/nl_main.c into foobar/, renaming it as - fb_main.c. Edit it by changing the lines in - pre_clo_init() to something appropriate for the + fb_main.c. Edit it by changing the + details lines in + nl_pre_clo_init() to something appropriate for the tool. These fields are used in the startup message, except for bug_reports_to which is used if a - tool assertion fails. + tool assertion fails. Also replace the string + "nl_" with + "fb_" again. Edit Makefile.am, adding the new directory - foobar to the - SUBDIRS variable. + foobar to the + TOOLS variable. Edit configure.in, adding - foobar/Makefile to the + foobar/Makefile, + foobar/docs/Makefile and + foobar/tests/Makefile to the AC_OUTPUT list. @@ -368,8 +143,8 @@ top-level directory valgrind/. It should automake, configure and compile without errors, putting copies of the tool in - foobar/ and - inst/lib/valgrind/. + foobar/ and + inst/lib/valgrind/. @@ -418,16 +193,16 @@ onto the interesting stuff... instrument() fini()]]> -Also, it must use the macro -VG_DETERMINE_INTERFACE_VERSION exactly -once in its source code. If it doesn't, you will get a link error -involving VG_(tool_interface_version). -This macro is used to ensure the core/tool interface used by the core -and a plugged-in tool are binary compatible. +The names can be different to the above, but these are the usual +names. The first one is registered using the macro +VG_DETERMINE_INTERFACE_VERSION (which also +checks that the core/tool interface of the tool matches that of the core). +The last three are registered using the +VG_(basic_tool_funcs) function. In addition, if a tool wants to use some of the optional services provided by the core, it may have to define other functions and tell the -code about them. +core about them. @@ -494,8 +269,8 @@ 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 described in -. +Valgrind's RISC-like intermediate language. VEX IR is best described in +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" @@ -526,9 +301,9 @@ complex and not brilliantly documented. Here are some important points, but there are undoubtedly many others that I should note but haven't 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 +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. In particular, you can't use anything from the C library (there @@ -542,8 +317,11 @@ 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. But ultimately, the tools distributed (Memcheck, -Cachegrind, Lackey, etc.) are probably the best +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. Note that the VG_ macro is used @@ -626,9 +404,9 @@ this to extract useful tracebacks from GDB. -UCode Instrumentation Problems +IR Instrumentation Problems -If you are having problems with your VEX UIR instrumentation, it's +If you are having problems with your VEX IR instrumentation, it's likely that GDB won't be able to help at all. In this case, Valgrind's option is invaluable for observing the results of instrumentation. @@ -737,8 +515,15 @@ as the example tool name again): - Make a directory - valgrind/foobar/docs/. + The docs go in + valgrind/foobar/docs/, which you will + have created when you started writing the tool. + + + + Write foobar/docs/Makefile.am. Use + memcheck/docs/Makefile.am as an + example. @@ -825,17 +610,8 @@ write regression tests for your tool: - Make a directory - foobar/tests/. Make sure the name - of the directory is tests/ as the - build system assumes that any tests for the tool will be in a - directory by that name. - - - - Edit configure.in, adding - foobar/tests/Makefile to the - AC_OUTPUT list. + The tests go in foobar/tests/, + which you will have created when you started writing the tool. @@ -877,24 +653,6 @@ write regression tests for your tool: To profile a tool, use Cachegrind on it. Read README_DEVELOPERS for details on running Valgrind under Valgrind. -To do simple tick-based profiling of a tool, include the -line: - - -in the tool somewhere, and rebuild (you may have to -make clean first). Then run Valgrind -with the option. - -The profiler is stack-based; you can register a profiling event -with VG_(register_profile_event)() and then use the -VGP_PUSHCC and -VGP_POPCC macros to record time spent -doing certain things. New profiling event numbers must not overlap with -the core profiling event numbers. See -include/pub_tool_profile.h for details and Memcheck -for an example. - @@ -927,11 +685,10 @@ is use the exactly once in its code. If not, a link error will occur when the tool is built. -The interface version number has the form X.Y. Changes in Y -indicate binary compatible changes. Changes in X indicate binary -incompatible changes. If the core and tool has the same major version -number X they should work together. If X doesn't match, Valgrind will -abort execution with an explanation of the problem. +The interface version number is changed when binary incompatible +changes are made to the interface. If the core and tool has the same major +version number X they should work together. If X doesn't match, Valgrind +will abort execution with an explanation of the problem. This approach was chosen so that if the interface changes in the future, old tools won't work and the reason will be clearly explained, @@ -948,50 +705,14 @@ minimising the use of naked structs in the interface. Final Words -This whole core/tool business is under active development, -although it's slowly maturing. - -The first consequence of this is that the core/tool interface will -continue to change in the future; we have no intention of freezing it -and then regretting the inevitable stupidities. Hopefully most of the -future changes will be to add new features, hooks, functions, etc, -rather than to change old ones, which should cause a minimum of trouble -for existing tools, and we've put some effort into future-proofing the -interface to avoid binary incompatibility. But we can't guarantee -anything. The versioning system should catch any incompatibilities. -Just something to be aware of. - -The second consequence of this is that we'd love to hear your -feedback about it: - - - - If you love it or hate it - - - If you find bugs - - - If you write a tool - - - If you have suggestions for new features, needs, trackable - events, functions - - - If you have suggestions for making tools easier to - write - - - If you have suggestions for improving this - documentation - - - If you don't understand something - - +The core/tool interface is not fixed. It's pretty stable these days, +but it does change. We deliberately do not provide backward compatibility +with old interfaces, because it is too difficult and too restrictive. +The interface checking should catch any incompatibilities. We view this as +a good thing -- if we had to be backward compatible with earlier versions, +many improvements now in the system could not have been added. + -or anything else! Happy programming. diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml index 29f850d036..e65218194b 100644 --- a/docs/xml/manual.xml +++ b/docs/xml/manual.xml @@ -36,5 +36,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude" /> +