Home | History | Annotate | Download | only in include
      1 
      2 /*--------------------------------------------------------------------*/
      3 /*--- The core/tool interface.                pub_tool_tooliface.h ---*/
      4 /*--------------------------------------------------------------------*/
      5 
      6 /*
      7    This file is part of Valgrind, a dynamic binary instrumentation
      8    framework.
      9 
     10    Copyright (C) 2000-2015 Julian Seward
     11       jseward (at) acm.org
     12 
     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.
     17 
     18    This program is distributed in the hope that it will be useful, but
     19    WITHOUT ANY WARRANTY; without even the implied warranty of
     20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     21    General Public License for more details.
     22 
     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.
     27 
     28    The GNU General Public License is contained in the file COPYING.
     29 */
     30 
     31 #ifndef __PUB_TOOL_TOOLIFACE_H
     32 #define __PUB_TOOL_TOOLIFACE_H
     33 
     34 #include "pub_tool_errormgr.h"   // for Error, Supp
     35 #include "libvex.h"              // for all Vex stuff
     36 
     37 /* ------------------------------------------------------------------ */
     38 /* The interface version */
     39 
     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
     47 */
     48 extern void (*VG_(tl_pre_clo_init)) ( void );
     49 
     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.
     53 */
     54 #define VG_DETERMINE_INTERFACE_VERSION(pre_clo_init) \
     55    void (*VG_(tl_pre_clo_init)) ( void ) = pre_clo_init;
     56 
     57 /* ------------------------------------------------------------------ */
     58 /* Basic tool functions */
     59 
     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.
     64 */
     65 typedef
     66    struct {
     67       Addr     nraddr; /* non-redirected guest address */
     68       Addr     readdr; /* redirected guest address */
     69       ThreadId tid;    /* tid requesting translation */
     70    }
     71    VgCallbackClosure;
     72 
     73 extern 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),
     77 
     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.
    152 
    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.
    160 
    161       You should therefore
    162 
    163       (1) copy any IR preceding the first IMark verbatim to the start
    164           of the output IRSB.
    165 
    166       (2) not try to instrument it or modify it in any way.
    167 
    168       For the record, stuff that may be in the preamble at
    169       present is:
    170 
    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.
    176 
    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.
    184 
    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.
    190 
    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.
    196 
    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'.
    203 
    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.
    213 
    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                       const VexGuestLayout*  layout,
    222                       const VexGuestExtents* vge,
    223                       const VexArchInfo*     archinfo_host,
    224                       IRType             gWordTy,
    225                       IRType             hWordTy),
    226 
    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)
    230 );
    231 
    232 /* ------------------------------------------------------------------ */
    233 /* Details */
    234 
    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
    238 
    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.  */
    246 extern void VG_(details_name)                  ( const HChar* name );
    247 extern void VG_(details_version)               ( const HChar* version );
    248 extern void VG_(details_description)           ( const HChar* description );
    249 extern void VG_(details_copyright_author)      ( const HChar* copyright_author );
    250 
    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. */
    254 extern void VG_(details_avg_translation_sizeB) ( UInt size );
    255 
    256 /* String printed if an `tl_assert' assertion fails or VG_(tool_panic)
    257    is called.  Should probably be an email address. */
    258 extern void VG_(details_bug_reports_to)   ( const HChar* bug_reports_to );
    259 
    260 /* ------------------------------------------------------------------ */
    261 /* Needs */
    262 
    263 /* Should __libc_freeres() be run?  Bugs in it can crash the tool. */
    264 extern void VG_(needs_libc_freeres) ( void );
    265 
    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 */
    272 extern void VG_(needs_core_errors) ( void );
    273 
    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. */
    277 
    278 /* Want to report errors from tool?  This implies use of suppressions, too. */
    279 extern 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, const Error* e1, const Error* e2),
    288 
    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)(const Error* err),
    298 
    299    // Print error context.
    300    void (*pp_Error)(const Error* err),
    301 
    302    // Should the core indicate which ThreadId each error comes from?
    303    Bool show_ThreadIDs_for_errors,
    304 
    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)(const Error* err),
    313 
    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),
    317 
    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),
    325 
    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)(const Error* err, const Supp* su),
    330 
    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)(const Error* err),
    335 
    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.  The string needs to be null
    339    // terminated. If the buffer is large enough to hold the string
    340    // including the terminating null character the function shall
    341    // return the value that strlen would return for the string.
    342    // If the buffer is too small the function shall return nBuf.
    343    SizeT (*print_extra_suppression_info)(const Error* err,
    344                                          /*OUT*/HChar* buf, Int nBuf),
    345 
    346    // This is similar to print_extra_suppression_info, but is used
    347    // to print information such as additional statistical counters
    348    // as part of the used suppression list produced by -v.
    349    SizeT (*print_extra_suppression_use)(const Supp* su,
    350                                         /*OUT*/HChar* buf, Int nBuf),
    351 
    352    // Called by error mgr once it has been established that err
    353    // is suppressed by su. update_extra_suppression_use typically
    354    // can be used to update suppression extra information such as
    355    // some statistical counters that will be printed by
    356    // print_extra_suppression_use.
    357    void (*update_extra_suppression_use)(const Error* err, const Supp* su)
    358 );
    359 
    360 /* Is information kept by the tool about specific instructions or
    361    translations?  (Eg. for cachegrind there are cost-centres for every
    362    instruction, stored in a per-translation fashion.)  If so, the info
    363    may have to be discarded when translations are unloaded (eg. due to
    364    .so unloading, or otherwise at the discretion of m_transtab, eg
    365    when the table becomes too full) to avoid stale information being
    366    reused for new translations. */
    367 extern void VG_(needs_superblock_discards) (
    368    // Discard any information that pertains to specific translations
    369    // or instructions within the address range given.  There are two
    370    // possible approaches.
    371    // - If info is being stored at a per-translation level, use orig_addr
    372    //   to identify which translation is being discarded.  Each translation
    373    //   will be discarded exactly once.
    374    //   This orig_addr will match the closure->nraddr which was passed to
    375    //   to instrument() (see extensive comments above) when this
    376    //   translation was made.  Note that orig_addr won't necessarily be
    377    //   the same as the first address in "extents".
    378    // - If info is being stored at a per-instruction level, you can get
    379    //   the address range(s) being discarded by stepping through "extents".
    380    //   Note that any single instruction may belong to more than one
    381    //   translation, and so could be covered by the "extents" of more than
    382    //   one call to this function.
    383    // Doing it the first way (as eg. Cachegrind does) is probably easier.
    384    void (*discard_superblock_info)(Addr orig_addr, VexGuestExtents extents)
    385 );
    386 
    387 /* Tool defines its own command line options? */
    388 extern void VG_(needs_command_line_options) (
    389    // Return True if option was recognised, False if it wasn't (but also see
    390    // below).  Presumably sets some state to record the option as well.
    391    //
    392    // Nb: tools can assume that the argv will never disappear.  So they can,
    393    // for example, store a pointer to a string within an option, rather than
    394    // having to make a copy.
    395    //
    396    // Options (and combinations of options) should be checked in this function
    397    // if possible rather than in post_clo_init(), and if they are bad then
    398    // VG_(fmsg_bad_option)() should be called.  This ensures that the
    399    // messaging is consistent with command line option errors from the core.
    400    Bool (*process_cmd_line_option)(const HChar* argv),
    401 
    402    // Print out command line usage for options for normal tool operation.
    403    void (*print_usage)(void),
    404 
    405    // Print out command line usage for options for debugging the tool.
    406    void (*print_debug_usage)(void)
    407 );
    408 
    409 /* Tool defines its own client requests? */
    410 extern void VG_(needs_client_requests) (
    411    // If using client requests, the number of the first request should be equal
    412    // to VG_USERREQ_TOOL_BASE('X', 'Y'), where 'X' and 'Y' form a suitable two
    413    // character identification for the string.  The second and subsequent
    414    // requests should follow.
    415    //
    416    // This function should use the VG_IS_TOOL_USERREQ macro (in
    417    // include/valgrind.h) to first check if it's a request for this tool.  Then
    418    // should handle it if it's recognised (and return True), or return False if
    419    // not recognised.  arg_block[0] holds the request number, any further args
    420    // from the request are in arg_block[1..].  'ret' is for the return value...
    421    // it should probably be filled, if only with 0.
    422    Bool (*handle_client_request)(ThreadId tid, UWord* arg_block, UWord* ret)
    423 );
    424 
    425 /* Tool does stuff before and/or after system calls? */
    426 // Nb: If either of the pre_ functions malloc() something to return, the
    427 // corresponding post_ function had better free() it!
    428 // Also, the args are the 'original args' -- that is, it may be
    429 // that the syscall pre-wrapper will modify the args before the
    430 // syscall happens.  So these args are the original, un-modified
    431 // args.  Finally, nArgs merely indicates the length of args[..],
    432 // it does not indicate how many of those values are actually
    433 // relevant to the syscall.  args[0 .. nArgs-1] is guaranteed
    434 // to be defined and to contain all the args for this syscall,
    435 // possibly including some trailing zeroes.
    436 extern void VG_(needs_syscall_wrapper) (
    437                void (* pre_syscall)(ThreadId tid, UInt syscallno,
    438                                     UWord* args, UInt nArgs),
    439                void (*post_syscall)(ThreadId tid, UInt syscallno,
    440                                     UWord* args, UInt nArgs, SysRes res)
    441 );
    442 
    443 /* Are tool-state sanity checks performed? */
    444 // Can be useful for ensuring a tool's correctness.  cheap_sanity_check()
    445 // is called very frequently;  expensive_sanity_check() is called less
    446 // frequently and can be more involved.
    447 extern void VG_(needs_sanity_checks) (
    448    Bool(*cheap_sanity_check)(void),
    449    Bool(*expensive_sanity_check)(void)
    450 );
    451 
    452 /* Can the tool produce stats during execution? */
    453 extern void VG_(needs_print_stats) (
    454    // Print out tool status. Note that the stats at end of execution
    455    // should be output by the VG_(basic_tool_funcs) "fini" function.
    456    void (*print_stats)(void)
    457 );
    458 
    459 /* Has the tool a tool specific function to retrieve and print location info
    460    of an address ? */
    461 extern void VG_(needs_info_location) (
    462    // Get and pp information about Addr
    463    void (*info_location)(Addr)
    464 );
    465 
    466 /* Do we need to see variable type and location information? */
    467 extern void VG_(needs_var_info) ( void );
    468 
    469 /* Does the tool replace malloc() and friends with its own versions?
    470    This has to be combined with the use of a vgpreload_<tool>.so module
    471    or it won't work.  See massif/Makefile.am for how to build it. */
    472 // The 'p' prefix avoids GCC complaints about overshadowing global names.
    473 extern void VG_(needs_malloc_replacement)(
    474    void* (*pmalloc)               ( ThreadId tid, SizeT n ),
    475    void* (*p__builtin_new)        ( ThreadId tid, SizeT n ),
    476    void* (*p__builtin_vec_new)    ( ThreadId tid, SizeT n ),
    477    void* (*pmemalign)             ( ThreadId tid, SizeT align, SizeT n ),
    478    void* (*pcalloc)               ( ThreadId tid, SizeT nmemb, SizeT size1 ),
    479    void  (*pfree)                 ( ThreadId tid, void* p ),
    480    void  (*p__builtin_delete)     ( ThreadId tid, void* p ),
    481    void  (*p__builtin_vec_delete) ( ThreadId tid, void* p ),
    482    void* (*prealloc)              ( ThreadId tid, void* p, SizeT new_size ),
    483    SizeT (*pmalloc_usable_size)   ( ThreadId tid, void* p),
    484    SizeT client_malloc_redzone_szB
    485 );
    486 
    487 /* Can the tool do XML output?  This is a slight misnomer, because the tool
    488  * is not requesting the core to do anything, rather saying "I can handle
    489  * it". */
    490 extern void VG_(needs_xml_output) ( void );
    491 
    492 /* Does the tool want to have one final pass over the IR after tree
    493    building but before instruction selection?  If so specify the
    494    function here. */
    495 extern void VG_(needs_final_IR_tidy_pass) ( IRSB*(*final_tidy)(IRSB*) );
    496 
    497 
    498 /* ------------------------------------------------------------------ */
    499 /* Core events to track */
    500 
    501 /* Part of the core from which this call was made.  Useful for determining
    502    what kind of error message should be emitted. */
    503 typedef
    504    enum { Vg_CoreStartup=1, Vg_CoreSignal, Vg_CoreSysCall,
    505           // This is for platforms where syscall args are passed on the
    506           // stack; although pre_mem_read is the callback that will be
    507           // called, such an arg should be treated (with respect to
    508           // presenting information to the user) as if it was passed in a
    509           // register, ie. like pre_reg_read.
    510           Vg_CoreSysCallArgInMem,
    511           Vg_CoreTranslate, Vg_CoreClientReq
    512    } CorePart;
    513 
    514 /* Events happening in core to track.  To be notified, pass a callback
    515    function to the appropriate function.  To ignore an event, don't do
    516    anything (the default is for events to be ignored).
    517 
    518    Note that most events aren't passed a ThreadId.  If the event is one called
    519    from generated code (eg. new_mem_stack_*), you can use
    520    VG_(get_running_tid)() to find it.  Otherwise, it has to be passed in,
    521    as in pre_mem_read, and so the event signature will require changing.
    522 
    523    Memory events (Nb: to track heap allocation/freeing, a tool must replace
    524    malloc() et al.  See above how to do this.)
    525 
    526    These ones occur at startup, upon some signals, and upon some syscalls.
    527 
    528    For new_mem_brk and new_mem_stack_signal, the supplied ThreadId
    529    indicates the thread for whom the new memory is being allocated.
    530 
    531    For new_mem_startup and new_mem_mmap, the di_handle argument is a
    532    handle which can be used to retrieve debug info associated with the
    533    mapping or allocation (because it is of a file that Valgrind has
    534    decided to read debug info from).  If the value is zero, there is
    535    no associated debug info.  If the value exceeds zero, it can be
    536    supplied as an argument to selected queries in m_debuginfo.
    537 */
    538 void VG_(track_new_mem_startup)     (void(*f)(Addr a, SizeT len,
    539                                               Bool rr, Bool ww, Bool xx,
    540                                               ULong di_handle));
    541 void VG_(track_new_mem_stack_signal)(void(*f)(Addr a, SizeT len, ThreadId tid));
    542 void VG_(track_new_mem_brk)         (void(*f)(Addr a, SizeT len, ThreadId tid));
    543 void VG_(track_new_mem_mmap)        (void(*f)(Addr a, SizeT len,
    544                                               Bool rr, Bool ww, Bool xx,
    545                                               ULong di_handle));
    546 
    547 void VG_(track_copy_mem_remap)      (void(*f)(Addr from, Addr to, SizeT len));
    548 void VG_(track_change_mem_mprotect) (void(*f)(Addr a, SizeT len,
    549                                               Bool rr, Bool ww, Bool xx));
    550 void VG_(track_die_mem_stack_signal)(void(*f)(Addr a, SizeT len));
    551 void VG_(track_die_mem_brk)         (void(*f)(Addr a, SizeT len));
    552 void VG_(track_die_mem_munmap)      (void(*f)(Addr a, SizeT len));
    553 
    554 /* These ones are called when SP changes.  A tool could track these itself
    555    (except for ban_mem_stack) but it's much easier to use the core's help.
    556 
    557    The specialised ones are called in preference to the general one, if they
    558    are defined.  These functions are called a lot if they are used, so
    559    specialising can optimise things significantly.  If any of the
    560    specialised cases are defined, the general case must be defined too.
    561 
    562    Nb: all the specialised ones must use the VG_REGPARM(n) attribute.
    563 
    564    For the _new functions, a tool may specify with with-ECU
    565    (ExeContext Unique) or without-ECU version for each size, but not
    566    both.  If the with-ECU version is supplied, then the core will
    567    arrange to pass, as the ecu argument, a 32-bit int which uniquely
    568    identifies the instruction moving the stack pointer down.  This
    569    32-bit value is as obtained from VG_(get_ECU_from_ExeContext).
    570    VG_(get_ExeContext_from_ECU) can then be used to retrieve the
    571    associated depth-1 ExeContext for the location.  All this
    572    complexity is provided to support origin tracking in Memcheck.
    573 */
    574 void VG_(track_new_mem_stack_4_w_ECU)  (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    575 void VG_(track_new_mem_stack_8_w_ECU)  (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    576 void VG_(track_new_mem_stack_12_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    577 void VG_(track_new_mem_stack_16_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    578 void VG_(track_new_mem_stack_32_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    579 void VG_(track_new_mem_stack_112_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    580 void VG_(track_new_mem_stack_128_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    581 void VG_(track_new_mem_stack_144_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    582 void VG_(track_new_mem_stack_160_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu));
    583 void VG_(track_new_mem_stack_w_ECU)                  (void(*f)(Addr a, SizeT len,
    584                                                                        UInt ecu));
    585 
    586 void VG_(track_new_mem_stack_4)  (VG_REGPARM(1) void(*f)(Addr new_ESP));
    587 void VG_(track_new_mem_stack_8)  (VG_REGPARM(1) void(*f)(Addr new_ESP));
    588 void VG_(track_new_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr new_ESP));
    589 void VG_(track_new_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr new_ESP));
    590 void VG_(track_new_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr new_ESP));
    591 void VG_(track_new_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr new_ESP));
    592 void VG_(track_new_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr new_ESP));
    593 void VG_(track_new_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr new_ESP));
    594 void VG_(track_new_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr new_ESP));
    595 void VG_(track_new_mem_stack)                  (void(*f)(Addr a, SizeT len));
    596 
    597 void VG_(track_die_mem_stack_4)  (VG_REGPARM(1) void(*f)(Addr die_ESP));
    598 void VG_(track_die_mem_stack_8)  (VG_REGPARM(1) void(*f)(Addr die_ESP));
    599 void VG_(track_die_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr die_ESP));
    600 void VG_(track_die_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr die_ESP));
    601 void VG_(track_die_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr die_ESP));
    602 void VG_(track_die_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr die_ESP));
    603 void VG_(track_die_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr die_ESP));
    604 void VG_(track_die_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr die_ESP));
    605 void VG_(track_die_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr die_ESP));
    606 void VG_(track_die_mem_stack)                  (void(*f)(Addr a, SizeT len));
    607 
    608 /* Used for redzone at end of thread stacks */
    609 void VG_(track_ban_mem_stack)      (void(*f)(Addr a, SizeT len));
    610 
    611 /* These ones occur around syscalls, signal handling, etc */
    612 void VG_(track_pre_mem_read)       (void(*f)(CorePart part, ThreadId tid,
    613                                              const HChar* s, Addr a, SizeT size));
    614 void VG_(track_pre_mem_read_asciiz)(void(*f)(CorePart part, ThreadId tid,
    615                                              const HChar* s, Addr a));
    616 void VG_(track_pre_mem_write)      (void(*f)(CorePart part, ThreadId tid,
    617                                              const HChar* s, Addr a, SizeT size));
    618 void VG_(track_post_mem_write)     (void(*f)(CorePart part, ThreadId tid,
    619                                              Addr a, SizeT size));
    620 
    621 /* Register events.  Use VG_(set_shadow_state_area)() to set the shadow regs
    622    for these events.  */
    623 void VG_(track_pre_reg_read)  (void(*f)(CorePart part, ThreadId tid,
    624                                         const HChar* s, PtrdiffT guest_state_offset,
    625                                         SizeT size));
    626 void VG_(track_post_reg_write)(void(*f)(CorePart part, ThreadId tid,
    627                                         PtrdiffT guest_state_offset,
    628                                         SizeT size));
    629 
    630 /* This one is called for malloc() et al if they are replaced by a tool. */
    631 void VG_(track_post_reg_write_clientcall_return)(
    632       void(*f)(ThreadId tid, PtrdiffT guest_state_offset, SizeT size, Addr f));
    633 
    634 /* Mem-to-reg or reg-to-mem copy functions, these ones occur around syscalls
    635    and signal handling when the VCPU state is saved to (or restored from) the
    636    client memory. */
    637 void VG_(track_copy_mem_to_reg)(void(*f)(CorePart part, ThreadId tid,
    638                                          Addr a, PtrdiffT guest_state_offset,
    639                                          SizeT size));
    640 void VG_(track_copy_reg_to_mem)(void(*f)(CorePart part, ThreadId tid,
    641                                          PtrdiffT guest_state_offset,
    642                                          Addr a, SizeT size));
    643 
    644 
    645 /* Scheduler events (not exhaustive) */
    646 
    647 /* Called when 'tid' starts or stops running client code blocks.
    648    Gives the total dispatched block count at that event.  Note, this
    649    is not the same as 'tid' holding the BigLock (the lock that ensures
    650    that only one thread runs at a time): a thread can hold the lock
    651    for other purposes (making translations, etc) yet not be running
    652    client blocks.  Obviously though, a thread must hold the lock in
    653    order to run client code blocks, so the times bracketed by
    654    'start_client_code'..'stop_client_code' are a subset of the times
    655    when thread 'tid' holds the cpu lock.
    656 */
    657 void VG_(track_start_client_code)(
    658         void(*f)(ThreadId tid, ULong blocks_dispatched)
    659      );
    660 void VG_(track_stop_client_code)(
    661         void(*f)(ThreadId tid, ULong blocks_dispatched)
    662      );
    663 
    664 
    665 /* Thread events (not exhaustive)
    666 
    667    ll_create: low level thread creation.  Called before the new thread
    668    has run any instructions (or touched any memory).  In fact, called
    669    immediately before the new thread has come into existence; the new
    670    thread can be assumed to exist when notified by this call.
    671 
    672    ll_exit: low level thread exit.  Called after the exiting thread
    673    has run its last instruction.
    674 
    675    The _ll_ part makes it clear these events are not to do with
    676    pthread_create or pthread_exit/pthread_join (etc), which are a
    677    higher level abstraction synthesised by libpthread.  What you can
    678    be sure of from _ll_create/_ll_exit is the absolute limits of each
    679    thread's lifetime, and hence be assured that all memory references
    680    made by the thread fall inside the _ll_create/_ll_exit pair.  This
    681    is important for tools that need a 100% accurate account of which
    682    thread is responsible for every memory reference in the process.
    683 
    684    pthread_create/join/exit do not give this property.  Calls/returns
    685    to/from them happen arbitrarily far away from the relevant
    686    low-level thread create/quit event.  In general a few hundred
    687    instructions; hence a few hundred(ish) memory references could get
    688    misclassified each time.
    689 
    690    pre_thread_first_insn: is called when the thread is all set up and
    691    ready to go (stack in place, etc) but has not executed its first
    692    instruction yet.  Gives threading tools a chance to ask questions
    693    about the thread (eg, what is its initial client stack pointer)
    694    that are not easily answered at pre_thread_ll_create time.
    695 
    696    For a given thread, the call sequence is:
    697       ll_create (in the parent's context)
    698       first_insn (in the child's context)
    699       ll_exit (in the child's context)
    700 */
    701 void VG_(track_pre_thread_ll_create) (void(*f)(ThreadId tid, ThreadId child));
    702 void VG_(track_pre_thread_first_insn)(void(*f)(ThreadId tid));
    703 void VG_(track_pre_thread_ll_exit)   (void(*f)(ThreadId tid));
    704 
    705 
    706 /* Signal events (not exhaustive)
    707 
    708    ... pre_send_signal, post_send_signal ...
    709 
    710    Called before a signal is delivered;  `alt_stack' indicates if it is
    711    delivered on an alternative stack.  */
    712 void VG_(track_pre_deliver_signal) (void(*f)(ThreadId tid, Int sigNo,
    713                                              Bool alt_stack));
    714 /* Called after a signal is delivered.  Nb: unfortunately, if the signal
    715    handler longjmps, this won't be called.  */
    716 void VG_(track_post_deliver_signal)(void(*f)(ThreadId tid, Int sigNo));
    717 
    718 #endif   // __PUB_TOOL_TOOLIFACE_H
    719 
    720 /*--------------------------------------------------------------------*/
    721 /*--- end                                                          ---*/
    722 /*--------------------------------------------------------------------*/
    723