3/*--- The core/tool interface.                pub_tool_tooliface.h ---*/
7   This file is part of Valgrind, a dynamic binary instrumentation
8   framework.
10   Copyright (C) 2000-2013 Julian Seward
11      jseward@acm.org
13   This program is free software; you can redistribute it and/or
14   modify it under the terms of the GNU General Public License as
15   published by the Free Software Foundation; either version 2 of the
16   License, or (at your option) any later version.
18   This program is distributed in the hope that it will be useful, but
19   WITHOUT ANY WARRANTY; without even the implied warranty of
21   General Public License for more details.
23   You should have received a copy of the GNU General Public License
24   along with this program; if not, write to the Free Software
25   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
26   02111-1307, USA.
28   The GNU General Public License is contained in the file COPYING.
34#include "pub_tool_errormgr.h"   // for Error, Supp
35#include "libvex.h"              // for all Vex stuff
37/* ------------------------------------------------------------------ */
38/* The interface version */
40/* Initialise tool.   Must do the following:
41   - initialise the `details' struct, via the VG_(details_*)() functions
42   - register the basic tool functions, via VG_(basic_tool_funcs)().
43   May do the following:
44   - initialise the `needs' struct to indicate certain requirements, via
45     the VG_(needs_*)() functions
46   - any other tool-specific initialisation
48extern void (*VG_(tl_pre_clo_init)) ( void );
50/* Every tool must include this macro somewhere, exactly once.  The
51   interface version is no longer relevant, but we kept the same name
52   to avoid requiring changes to tools.
54#define VG_DETERMINE_INTERFACE_VERSION(pre_clo_init) \
55   void (*VG_(tl_pre_clo_init)) ( void ) = pre_clo_init;
57/* ------------------------------------------------------------------ */
58/* Basic tool functions */
60/* The tool_instrument function is passed as a callback to
61   LibVEX_Translate.  VgCallbackClosure carries additional info
62   which the instrumenter might like to know, but which is opaque to
63   Vex.
66   struct {
67      Addr64   nraddr; /* non-redirected guest address */
68      Addr64   readdr; /* redirected guest address */
69      ThreadId tid;    /* tid requesting translation */
70   }
71   VgCallbackClosure;
73extern void VG_(basic_tool_funcs)(
74   // Do any initialisation that can only be done after command line
75   // processing.
76   void  (*post_clo_init)(void),
78   // Instrument a basic block.  Must be a true function, ie. the same
79   // input always results in the same output, because basic blocks
80   // can be retranslated, unless you're doing something really
81   // strange.  Anyway, the arguments.  Mostly they are straightforward
82   // except for the distinction between redirected and non-redirected
83   // guest code addresses, which is important to understand.
84   //
85   // VgCallBackClosure* closure contains extra arguments passed
86   // from Valgrind to the instrumenter, which Vex doesn't know about.
87   // You are free to look inside this structure.
88   //
89   // * closure->tid is the ThreadId of the thread requesting the
90   //   translation.  Not sure why this is here; perhaps callgrind
91   //   uses it.
92   //
93   // * closure->nraddr is the non-redirected guest address of the
94   //   start of the translation.  In other words, the translation is
95   //   being constructed because the guest program jumped to
96   //   closure->nraddr but no translation of it was found.
97   //
98   // * closure->readdr is the redirected guest address, from which
99   //   the translation was really made.
100   //
101   //   To clarify this, consider what happens when, in Memcheck, the
102   //   first call to malloc() happens.  The guest program will be
103   //   trying to jump to malloc() in libc; hence ->nraddr will contain
104   //   that address.  However, Memcheck intercepts and replaces
105   //   malloc, hence ->readdr will be the address of Memcheck's
106   //   malloc replacement in
107   //   coregrind/m_replacemalloc/vg_replacemalloc.c.  It follows
108   //   that the first IMark in the translation will be labelled as
109   //   from ->readdr rather than ->nraddr.
110   //
111   //   Since most functions are not redirected, the majority of the
112   //   time ->nraddr will be the same as ->readdr.  However, you
113   //   cannot assume this: if your tool has metadata associated
114   //   with code addresses it will get into deep trouble if it does
115   //   make this assumption.
116   //
117   // IRSB* sb_in is the incoming superblock to be instrumented,
118   // in flat IR form.
119   //
120   // VexGuestLayout* layout contains limited info on the layout of
121   // the guest state: where the stack pointer and program counter
122   // are, and which fields should be regarded as 'always defined'.
123   // Memcheck uses this.
124   //
125   // VexGuestExtents* vge points to a structure which states the
126   // precise byte ranges of original code from which this translation
127   // was made (there may be up to three different ranges involved).
128   // Note again that these are the real addresses from which the code
129   // came.  And so it should be the case that closure->readdr is the
130   // same as vge->base[0]; indeed Cachegrind contains this assertion.
131   //
132   // Tools which associate shadow data with code addresses
133   // (cachegrind, callgrind) need to be particularly clear about
134   // whether they are making the association with redirected or
135   // non-redirected code addresses.  Both approaches are viable
136   // but you do need to understand what's going on.  See comments
137   // below on discard_basic_block_info().
138   //
139   // IRType gWordTy and IRType hWordTy contain the types of native
140   // words on the guest (simulated) and host (real) CPUs.  They will
141   // by either Ity_I32 or Ity_I64.  So far we have never built a
142   // cross-architecture Valgrind so they should always be the same.
143   //
144   /* --- Further comments about the IR that your --- */
145   /* --- instrumentation function will receive. --- */
146   /*
147      In the incoming IRSB, the IR for each instruction begins with an
148      IRStmt_IMark, which states the address and length of the
149      instruction from which this IR came.  This makes it easy for
150      profiling-style tools to know precisely which guest code
151      addresses are being executed.
153      However, before the first IRStmt_IMark, there may be other IR
154      statements -- a preamble.  In most cases this preamble is empty,
155      but when it isn't, what it contains is some supporting IR that
156      the JIT uses to ensure control flow works correctly.  This
157      preamble does not modify any architecturally defined guest state
158      (registers or memory) and so does not contain anything that will
159      be of interest to your tool.
161      You should therefore
163      (1) copy any IR preceding the first IMark verbatim to the start
164          of the output IRSB.
166      (2) not try to instrument it or modify it in any way.
168      For the record, stuff that may be in the preamble at
169      present is:
171      - A self-modifying-code check has been requested for this block.
172        The preamble will contain instructions to checksum the block,
173        compare against the expected value, and exit the dispatcher
174        requesting a discard (hence forcing a retranslation) if they
175        don't match.
177      - This block is known to be the entry point of a wrapper of some
178        function F.  In this case the preamble contains code to write
179        the address of the original F (the fn being wrapped) into a
180        'hidden' guest state register _NRADDR.  The wrapper can later
181        read this register using a client request and make a
182        non-redirected call to it using another client-request-like
183        magic macro.
185      - For platforms that use the AIX ABI (including ppc64-linux), it
186        is necessary to have a preamble even for replacement functions
187        (not just for wrappers), because it is necessary to switch the
188        R2 register (constant-pool pointer) to a different value when
189        swizzling the program counter.
191        Hence the preamble pushes both R2 and LR (the return address)
192        on a small 16-entry stack in the guest state and sets R2 to an
193        appropriate value for the wrapper/replacement fn.  LR is then
194        set so that the wrapper/replacement fn returns to a magic IR
195        stub which restores R2 and LR and returns.
197        It's all hugely ugly and fragile.  And it places a stringent
198        requirement on m_debuginfo to find out the correct R2 (toc
199        pointer) value for the wrapper/replacement function.  So much
200        so that m_redir will refuse to honour a redirect-to-me request
201        if it cannot find (by asking m_debuginfo) a plausible R2 value
202        for 'me'.
204        Because this mechanism maintains a shadow stack of (R2,LR)
205        pairs in the guest state, it will fail if the
206        wrapper/redirection function, or anything it calls, longjumps
207        out past the wrapper, because then the magic return stub will
208        not be run and so the shadow stack will not be popped.  So it
209        will quickly fill up.  Fortunately none of this applies to
210        {x86,amd64,ppc32}-linux; on those platforms, wrappers can
211        longjump and recurse arbitrarily and everything should work
212        fine.
214      Note that copying the preamble verbatim may cause complications
215      for your instrumenter if you shadow IR temporaries.  See big
216      comment in MC_(instrument) in memcheck/mc_translate.c for
217      details.
218   */
219   IRSB*(*instrument)(VgCallbackClosure* closure,
220                      IRSB*              sb_in,
221                      VexGuestLayout*    layout,
222                      VexGuestExtents*   vge,
223                      VexArchInfo*       archinfo_host,
224                      IRType             gWordTy,
225                      IRType             hWordTy),
227   // Finish up, print out any results, etc.  `exitcode' is program's exit
228   // code.  The shadow can be found with VG_(get_exit_status_shadow)().
229   void  (*fini)(Int)
232/* ------------------------------------------------------------------ */
233/* Details */
235/* Default value for avg_translations_sizeB (in bytes), indicating typical
236   code expansion of about 6:1. */
237#define VG_DEFAULT_TRANS_SIZEB   172
239/* Information used in the startup message.  `name' also determines the
240   string used for identifying suppressions in a suppression file as
241   belonging to this tool.  `version' can be NULL, in which case (not
242   surprisingly) no version info is printed; this mechanism is designed for
243   tools distributed with Valgrind that share a version number with
244   Valgrind.  Other tools not distributed as part of Valgrind should
245   probably have their own version number.  */
246extern void VG_(details_name)                  ( const HChar* name );
247extern void VG_(details_version)               ( const HChar* version );
248extern void VG_(details_description)           ( const HChar* description );
249extern void VG_(details_copyright_author)      ( const HChar* copyright_author );
251/* Average size of a translation, in bytes, so that the translation
252   storage machinery can allocate memory appropriately.  Not critical,
253   setting is optional. */
254extern void VG_(details_avg_translation_sizeB) ( UInt size );
256/* String printed if an `tl_assert' assertion fails or VG_(tool_panic)
257   is called.  Should probably be an email address. */
258extern void VG_(details_bug_reports_to)   ( const HChar* bug_reports_to );
260/* ------------------------------------------------------------------ */
261/* Needs */
263/* Should __libc_freeres() be run?  Bugs in it can crash the tool. */
264extern void VG_(needs_libc_freeres) ( void );
266/* Want to have errors detected by Valgrind's core reported?  Includes:
267   - pthread API errors (many;  eg. unlocking a non-locked mutex)
268     [currently disabled]
269   - invalid file descriptors to syscalls like read() and write()
270   - bad signal numbers passed to sigaction()
271   - attempt to install signal handler for SIGKILL or SIGSTOP */
272extern void VG_(needs_core_errors) ( void );
274/* Booleans that indicate extra operations are defined;  if these are True,
275   the corresponding template functions (given below) must be defined.  A
276   lot like being a member of a type class. */
278/* Want to report errors from tool?  This implies use of suppressions, too. */
279extern void VG_(needs_tool_errors) (
280   // Identify if two errors are equal, or close enough.  This function is
281   // only called if e1 and e2 will have the same error kind.  `res' indicates
282   // how close is "close enough".  `res' should be passed on as necessary,
283   // eg. if the Error's `extra' part contains an ExeContext, `res' should be
284   // passed to VG_(eq_ExeContext)() if the ExeContexts are considered.  Other
285   // than that, probably don't worry about it unless you have lots of very
286   // similar errors occurring.
287   Bool (*eq_Error)(VgRes res, Error* e1, Error* e2),
289   // We give tools a chance to have a look at errors
290   // just before they are printed.  That is, before_pp_Error is
291   // called just before pp_Error itself.  This gives the tool a
292   // chance to look at the just-about-to-be-printed error, so as to
293   // emit any arbitrary output if wants to, before the error itself
294   // is printed.  This functionality was added to allow Helgrind to
295   // print thread-announcement messages immediately before the
296   // errors that refer to them.
297   void (*before_pp_Error)(Error* err),
299   // Print error context.
300   void (*pp_Error)(Error* err),
302   // Should the core indicate which ThreadId each error comes from?
303   Bool show_ThreadIDs_for_errors,
305   // Should fill in any details that could be postponed until after the
306   // decision whether to ignore the error (ie. details not affecting the
307   // result of VG_(tdict).tool_eq_Error()).  This saves time when errors
308   // are ignored.
309   // Yuk.
310   // Return value: must be the size of the `extra' part in bytes -- used by
311   // the core to make a copy.
312   UInt (*update_extra)(Error* err),
314   // Return value indicates recognition.  If recognised, must set skind using
315   // VG_(set_supp_kind)().
316   Bool (*recognised_suppression)(const HChar* name, Supp* su),
318   // Read any extra info for this suppression kind.  Most likely for filling
319   // in the `extra' and `string' parts (with VG_(set_supp_{extra, string})())
320   // of a suppression if necessary.  Should return False if a syntax error
321   // occurred, True otherwise.
322   // fd, bufpp, nBufp and lineno are the same as for VG_(get_line).
323   Bool (*read_extra_suppression_info)(Int fd, HChar** bufpp, SizeT* nBufp,
324                                       Int* lineno, Supp* su),
326   // This should just check the kinds match and maybe some stuff in the
327   // `string' and `extra' field if appropriate (using VG_(get_supp_*)() to
328   // get the relevant suppression parts).
329   Bool (*error_matches_suppression)(Error* err, Supp* su),
331   // This should return the suppression name, for --gen-suppressions, or NULL
332   // if that error type cannot be suppressed.  This is the inverse of
333   // VG_(tdict).tool_recognised_suppression().
334   const HChar* (*get_error_name)(Error* err),
336   // This should print into buf[0..nBuf-1] any extra info for the
337   // error, for --gen-suppressions, but not including any leading
338   // spaces nor a trailing newline.  When called, buf[0 .. nBuf-1]
339   // will be zero filled, and it is expected and checked that the
340   // last element is still zero after the call.  In other words the
341   // tool may not overrun the buffer, and this is checked for.  If
342   // there is any info printed in the buffer, return True, otherwise
343   // do nothing, and return False.  This function is the inverse of
344   // VG_(tdict).tool_read_extra_suppression_info().
345   Bool (*print_extra_suppression_info)(Error* err,
346                                        /*OUT*/HChar* buf, Int nBuf),
348   // This is similar to print_extra_suppression_info, but is used
349   // to print information such as additional statistical counters
350   // as part of the used suppression list produced by -v.
351   Bool (*print_extra_suppression_use)(Supp* su,
352                                       /*OUT*/HChar* buf, Int nBuf),
354   // Called by error mgr once it has been established that err
355   // is suppressed by su. update_extra_suppression_use typically
356   // can be used to update suppression extra information such as
357   // some statistical counters that will be printed by
358   // print_extra_suppression_use.
359   void (*update_extra_suppression_use)(Error* err, Supp* su)
362/* Is information kept by the tool about specific instructions or
363   translations?  (Eg. for cachegrind there are cost-centres for every
364   instruction, stored in a per-translation fashion.)  If so, the info
365   may have to be discarded when translations are unloaded (eg. due to
366   .so unloading, or otherwise at the discretion of m_transtab, eg
367   when the table becomes too full) to avoid stale information being
368   reused for new translations. */
369extern void VG_(needs_superblock_discards) (
370   // Discard any information that pertains to specific translations
371   // or instructions within the address range given.  There are two
372   // possible approaches.
373   // - If info is being stored at a per-translation level, use orig_addr
374   //   to identify which translation is being discarded.  Each translation
375   //   will be discarded exactly once.
376   //   This orig_addr will match the closure->nraddr which was passed to
377   //   to instrument() (see extensive comments above) when this
378   //   translation was made.  Note that orig_addr won't necessarily be
379   //   the same as the first address in "extents".
380   // - If info is being stored at a per-instruction level, you can get
381   //   the address range(s) being discarded by stepping through "extents".
382   //   Note that any single instruction may belong to more than one
383   //   translation, and so could be covered by the "extents" of more than
384   //   one call to this function.
385   // Doing it the first way (as eg. Cachegrind does) is probably easier.
386   void (*discard_superblock_info)(Addr64 orig_addr, VexGuestExtents extents)
389/* Tool defines its own command line options? */
390extern void VG_(needs_command_line_options) (
391   // Return True if option was recognised, False if it wasn't (but also see
392   // below).  Presumably sets some state to record the option as well.
393   //
394   // Nb: tools can assume that the argv will never disappear.  So they can,
395   // for example, store a pointer to a string within an option, rather than
396   // having to make a copy.
397   //
398   // Options (and combinations of options) should be checked in this function
399   // if possible rather than in post_clo_init(), and if they are bad then
400   // VG_(fmsg_bad_option)() should be called.  This ensures that the
401   // messaging is consistent with command line option errors from the core.
402   Bool (*process_cmd_line_option)(const HChar* argv),
404   // Print out command line usage for options for normal tool operation.
405   void (*print_usage)(void),
407   // Print out command line usage for options for debugging the tool.
408   void (*print_debug_usage)(void)
411/* Tool defines its own client requests? */
412extern void VG_(needs_client_requests) (
413   // If using client requests, the number of the first request should be equal
414   // to VG_USERREQ_TOOL_BASE('X', 'Y'), where 'X' and 'Y' form a suitable two
415   // character identification for the string.  The second and subsequent
416   // requests should follow.
417   //
418   // This function should use the VG_IS_TOOL_USERREQ macro (in
419   // include/valgrind.h) to first check if it's a request for this tool.  Then
420   // should handle it if it's recognised (and return True), or return False if
421   // not recognised.  arg_block[0] holds the request number, any further args
422   // from the request are in arg_block[1..].  'ret' is for the return value...
423   // it should probably be filled, if only with 0.
424   Bool (*handle_client_request)(ThreadId tid, UWord* arg_block, UWord* ret)
427/* Tool does stuff before and/or after system calls? */
428// Nb: If either of the pre_ functions malloc() something to return, the
429// corresponding post_ function had better free() it!
430// Also, the args are the 'original args' -- that is, it may be
431// that the syscall pre-wrapper will modify the args before the
432// syscall happens.  So these args are the original, un-modified
433// args.  Finally, nArgs merely indicates the length of args[..],
434// it does not indicate how many of those values are actually
435// relevant to the syscall.  args[0 .. nArgs-1] is guaranteed
436// to be defined and to contain all the args for this syscall,
437// possibly including some trailing zeroes.
438extern void VG_(needs_syscall_wrapper) (
439               void (* pre_syscall)(ThreadId tid, UInt syscallno,
440                                    UWord* args, UInt nArgs),
441               void (*post_syscall)(ThreadId tid, UInt syscallno,
442                                    UWord* args, UInt nArgs, SysRes res)
445/* Are tool-state sanity checks performed? */
446// Can be useful for ensuring a tool's correctness.  cheap_sanity_check()
447// is called very frequently;  expensive_sanity_check() is called less
448// frequently and can be more involved.
449extern void VG_(needs_sanity_checks) (
450   Bool(*cheap_sanity_check)(void),
451   Bool(*expensive_sanity_check)(void)
454/* Can the tool produce stats during execution? */
455extern void VG_(needs_print_stats) (
456   // Print out tool status. Note that the stats at end of execution
457   // should be output by the VG_(basic_tool_funcs) "fini" function.
458   void (*print_stats)(void)
461/* Has the tool a tool specific function to retrieve and print location info
462   of an address ? */
463extern void VG_(needs_info_location) (
464   // Get and pp information about Addr
465   void (*info_location)(Addr)
468/* Do we need to see variable type and location information? */
469extern void VG_(needs_var_info) ( void );
471/* Does the tool replace malloc() and friends with its own versions?
472   This has to be combined with the use of a vgpreload_<tool>.so module
473   or it won't work.  See massif/Makefile.am for how to build it. */
474// The 'p' prefix avoids GCC complaints about overshadowing global names.
475extern void VG_(needs_malloc_replacement)(
476   void* (*pmalloc)               ( ThreadId tid, SizeT n ),
477   void* (*p__builtin_new)        ( ThreadId tid, SizeT n ),
478   void* (*p__builtin_vec_new)    ( ThreadId tid, SizeT n ),
479   void* (*pmemalign)             ( ThreadId tid, SizeT align, SizeT n ),
480   void* (*pcalloc)               ( ThreadId tid, SizeT nmemb, SizeT size1 ),
481   void  (*pfree)                 ( ThreadId tid, void* p ),
482   void  (*p__builtin_delete)     ( ThreadId tid, void* p ),
483   void  (*p__builtin_vec_delete) ( ThreadId tid, void* p ),
484   void* (*prealloc)              ( ThreadId tid, void* p, SizeT new_size ),
485   SizeT (*pmalloc_usable_size)   ( ThreadId tid, void* p),
486   SizeT client_malloc_redzone_szB
489/* Can the tool do XML output?  This is a slight misnomer, because the tool
490 * is not requesting the core to do anything, rather saying "I can handle
491 * it". */
492extern void VG_(needs_xml_output) ( void );
494/* Does the tool want to have one final pass over the IR after tree
495   building but before instruction selection?  If so specify the
496   function here. */
497extern void VG_(needs_final_IR_tidy_pass) ( IRSB*(*final_tidy)(IRSB*) );
500/* ------------------------------------------------------------------ */
501/* Core events to track */
503/* Part of the core from which this call was made.  Useful for determining
504   what kind of error message should be emitted. */
506   enum { Vg_CoreStartup=1, Vg_CoreSignal, Vg_CoreSysCall,
507          // This is for platforms where syscall args are passed on the
508          // stack; although pre_mem_read is the callback that will be
509          // called, such an arg should be treated (with respect to
510          // presenting information to the user) as if it was passed in a
511          // register, ie. like pre_reg_read.
512          Vg_CoreSysCallArgInMem,
513          Vg_CoreTranslate, Vg_CoreClientReq
514   } CorePart;
516/* Events happening in core to track.  To be notified, pass a callback
517   function to the appropriate function.  To ignore an event, don't do
518   anything (the default is for events to be ignored).
520   Note that most events aren't passed a ThreadId.  If the event is one called
521   from generated code (eg. new_mem_stack_*), you can use
522   VG_(get_running_tid)() to find it.  Otherwise, it has to be passed in,
523   as in pre_mem_read, and so the event signature will require changing.
525   Memory events (Nb: to track heap allocation/freeing, a tool must replace
526   malloc() et al.  See above how to do this.)
528   These ones occur at startup, upon some signals, and upon some syscalls.
530   For new_mem_brk and new_mem_stack_signal, the supplied ThreadId
531   indicates the thread for whom the new memory is being allocated.
533   For new_mem_startup and new_mem_mmap, the di_handle argument is a
534   handle which can be used to retrieve debug info associated with the
535   mapping or allocation (because it is of a file that Valgrind has
536   decided to read debug info from).  If the value is zero, there is
537   no associated debug info.  If the value exceeds zero, it can be
538   supplied as an argument to selected queries in m_debuginfo.
540void VG_(track_new_mem_startup)     (void(*f)(Addr a, SizeT len,
541                                              Bool rr, Bool ww, Bool xx,
542                                              ULong di_handle));
543void VG_(track_new_mem_stack_signal)(void(*f)(Addr a, SizeT len, ThreadId tid));
544void VG_(track_new_mem_brk)         (void(*f)(Addr a, SizeT len, ThreadId tid));
545void VG_(track_new_mem_mmap)        (void(*f)(Addr a, SizeT len,
546                                              Bool rr, Bool ww, Bool xx,
547                                              ULong di_handle));
549void VG_(track_copy_mem_remap)      (void(*f)(Addr from, Addr to, SizeT len));
550void VG_(track_change_mem_mprotect) (void(*f)(Addr a, SizeT len,
551                                              Bool rr, Bool ww, Bool xx));
552void VG_(track_die_mem_stack_signal)(void(*f)(Addr a, SizeT len));
553void VG_(track_die_mem_brk)         (void(*f)(Addr a, SizeT len));
554void VG_(track_die_mem_munmap)      (void(*f)(Addr a, SizeT len));
556/* These ones are called when SP changes.  A tool could track these itself
557   (except for ban_mem_stack) but it's much easier to use the core's help.
559   The specialised ones are called in preference to the general one, if they
560   are defined.  These functions are called a lot if they are used, so
561   specialising can optimise things significantly.  If any of the
562   specialised cases are defined, the general case must be defined too.
564   Nb: all the specialised ones must use the VG_REGPARM(n) attribute.
566   For the _new functions, a tool may specify with with-ECU
567   (ExeContext Unique) or without-ECU version for each size, but not
568   both.  If the with-ECU version is supplied, then the core will
569   arrange to pass, as the ecu argument, a 32-bit int which uniquely
570   identifies the instruction moving the stack pointer down.  This
571   32-bit value is as obtained from VG_(get_ECU_from_ExeContext).
572   VG_(get_ExeContext_from_ECU) can then be used to retrieve the
573   associated depth-1 ExeContext for the location.  All this
574   complexity is provided to support origin tracking in Memcheck.
576void VG_(track_new_mem_stack_4_w_ECU)  (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
577void VG_(track_new_mem_stack_8_w_ECU)  (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
578void VG_(track_new_mem_stack_12_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
579void VG_(track_new_mem_stack_16_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
580void VG_(track_new_mem_stack_32_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
581void VG_(track_new_mem_stack_112_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
582void VG_(track_new_mem_stack_128_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
583void VG_(track_new_mem_stack_144_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
584void VG_(track_new_mem_stack_160_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
585void VG_(track_new_mem_stack_w_ECU)                  (void(*f)(Addr a, SizeT len,
586                                                                       UInt ecu));
588void VG_(track_new_mem_stack_4)  (VG_REGPARM(1) void(*f)(Addr new_ESP));
589void VG_(track_new_mem_stack_8)  (VG_REGPARM(1) void(*f)(Addr new_ESP));
590void VG_(track_new_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr new_ESP));
591void VG_(track_new_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr new_ESP));
592void VG_(track_new_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr new_ESP));
593void VG_(track_new_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr new_ESP));
594void VG_(track_new_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr new_ESP));
595void VG_(track_new_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr new_ESP));
596void VG_(track_new_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr new_ESP));
597void VG_(track_new_mem_stack)                  (void(*f)(Addr a, SizeT len));
599void VG_(track_die_mem_stack_4)  (VG_REGPARM(1) void(*f)(Addr die_ESP));
600void VG_(track_die_mem_stack_8)  (VG_REGPARM(1) void(*f)(Addr die_ESP));
601void VG_(track_die_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr die_ESP));
602void VG_(track_die_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr die_ESP));
603void VG_(track_die_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr die_ESP));
604void VG_(track_die_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr die_ESP));
605void VG_(track_die_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr die_ESP));
606void VG_(track_die_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr die_ESP));
607void VG_(track_die_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr die_ESP));
608void VG_(track_die_mem_stack)                  (void(*f)(Addr a, SizeT len));
610/* Used for redzone at end of thread stacks */
611void VG_(track_ban_mem_stack)      (void(*f)(Addr a, SizeT len));
613/* These ones occur around syscalls, signal handling, etc */
614void VG_(track_pre_mem_read)       (void(*f)(CorePart part, ThreadId tid,
615                                             const HChar* s, Addr a, SizeT size));
616void VG_(track_pre_mem_read_asciiz)(void(*f)(CorePart part, ThreadId tid,
617                                             const HChar* s, Addr a));
618void VG_(track_pre_mem_write)      (void(*f)(CorePart part, ThreadId tid,
619                                             const HChar* s, Addr a, SizeT size));
620void VG_(track_post_mem_write)     (void(*f)(CorePart part, ThreadId tid,
621                                             Addr a, SizeT size));
623/* Register events.  Use VG_(set_shadow_state_area)() to set the shadow regs
624   for these events.  */
625void VG_(track_pre_reg_read)  (void(*f)(CorePart part, ThreadId tid,
626                                        const HChar* s, PtrdiffT guest_state_offset,
627                                        SizeT size));
628void VG_(track_post_reg_write)(void(*f)(CorePart part, ThreadId tid,
629                                        PtrdiffT guest_state_offset,
630                                        SizeT size));
632/* This one is called for malloc() et al if they are replaced by a tool. */
633void VG_(track_post_reg_write_clientcall_return)(
634      void(*f)(ThreadId tid, PtrdiffT guest_state_offset, SizeT size, Addr f));
637/* Scheduler events (not exhaustive) */
639/* Called when 'tid' starts or stops running client code blocks.
640   Gives the total dispatched block count at that event.  Note, this
641   is not the same as 'tid' holding the BigLock (the lock that ensures
642   that only one thread runs at a time): a thread can hold the lock
643   for other purposes (making translations, etc) yet not be running
644   client blocks.  Obviously though, a thread must hold the lock in
645   order to run client code blocks, so the times bracketed by
646   'start_client_code'..'stop_client_code' are a subset of the times
647   when thread 'tid' holds the cpu lock.
649void VG_(track_start_client_code)(
650        void(*f)(ThreadId tid, ULong blocks_dispatched)
651     );
652void VG_(track_stop_client_code)(
653        void(*f)(ThreadId tid, ULong blocks_dispatched)
654     );
657/* Thread events (not exhaustive)
659   ll_create: low level thread creation.  Called before the new thread
660   has run any instructions (or touched any memory).  In fact, called
661   immediately before the new thread has come into existence; the new
662   thread can be assumed to exist when notified by this call.
664   ll_exit: low level thread exit.  Called after the exiting thread
665   has run its last instruction.
667   The _ll_ part makes it clear these events are not to do with
668   pthread_create or pthread_exit/pthread_join (etc), which are a
669   higher level abstraction synthesised by libpthread.  What you can
670   be sure of from _ll_create/_ll_exit is the absolute limits of each
671   thread's lifetime, and hence be assured that all memory references
672   made by the thread fall inside the _ll_create/_ll_exit pair.  This
673   is important for tools that need a 100% accurate account of which
674   thread is responsible for every memory reference in the process.
676   pthread_create/join/exit do not give this property.  Calls/returns
677   to/from them happen arbitrarily far away from the relevant
678   low-level thread create/quit event.  In general a few hundred
679   instructions; hence a few hundred(ish) memory references could get
680   misclassified each time.
682   pre_thread_first_insn: is called when the thread is all set up and
683   ready to go (stack in place, etc) but has not executed its first
684   instruction yet.  Gives threading tools a chance to ask questions
685   about the thread (eg, what is its initial client stack pointer)
686   that are not easily answered at pre_thread_ll_create time.
688   For a given thread, the call sequence is:
689      ll_create (in the parent's context)
690      first_insn (in the child's context)
691      ll_exit (in the child's context)
693void VG_(track_pre_thread_ll_create) (void(*f)(ThreadId tid, ThreadId child));
694void VG_(track_pre_thread_first_insn)(void(*f)(ThreadId tid));
695void VG_(track_pre_thread_ll_exit)   (void(*f)(ThreadId tid));
698/* Signal events (not exhaustive)
700   ... pre_send_signal, post_send_signal ...
702   Called before a signal is delivered;  `alt_stack' indicates if it is
703   delivered on an alternative stack.  */
704void VG_(track_pre_deliver_signal) (void(*f)(ThreadId tid, Int sigNo,
705                                             Bool alt_stack));
706/* Called after a signal is delivered.  Nb: unfortunately, if the signal
707   handler longjmps, this won't be called.  */
708void VG_(track_post_deliver_signal)(void(*f)(ThreadId tid, Int sigNo));
710#endif   // __PUB_TOOL_TOOLIFACE_H
713/*--- end                                                          ---*/