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-2017 Julian Seward 11 jseward@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 /* Should __gnu_cxx::__freeres() be run? Bugs in it can crash the tool. */ 267 extern void VG_(needs_cxx_freeres) ( void ); 268 269 /* Want to have errors detected by Valgrind's core reported? Includes: 270 - pthread API errors (many; eg. unlocking a non-locked mutex) 271 [currently disabled] 272 - invalid file descriptors to syscalls like read() and write() 273 - bad signal numbers passed to sigaction() 274 - attempt to install signal handler for SIGKILL or SIGSTOP */ 275 extern void VG_(needs_core_errors) ( void ); 276 277 /* Booleans that indicate extra operations are defined; if these are True, 278 the corresponding template functions (given below) must be defined. A 279 lot like being a member of a type class. */ 280 281 /* Want to report errors from tool? This implies use of suppressions, too. */ 282 extern void VG_(needs_tool_errors) ( 283 // Identify if two errors are equal, or close enough. This function is 284 // only called if e1 and e2 will have the same error kind. `res' indicates 285 // how close is "close enough". `res' should be passed on as necessary, 286 // eg. if the Error's `extra' part contains an ExeContext, `res' should be 287 // passed to VG_(eq_ExeContext)() if the ExeContexts are considered. Other 288 // than that, probably don't worry about it unless you have lots of very 289 // similar errors occurring. 290 Bool (*eq_Error)(VgRes res, const Error* e1, const Error* e2), 291 292 // We give tools a chance to have a look at errors 293 // just before they are printed. That is, before_pp_Error is 294 // called just before pp_Error itself. This gives the tool a 295 // chance to look at the just-about-to-be-printed error, so as to 296 // emit any arbitrary output if wants to, before the error itself 297 // is printed. This functionality was added to allow Helgrind to 298 // print thread-announcement messages immediately before the 299 // errors that refer to them. 300 void (*before_pp_Error)(const Error* err), 301 302 // Print error context. 303 void (*pp_Error)(const Error* err), 304 305 // Should the core indicate which ThreadId each error comes from? 306 Bool show_ThreadIDs_for_errors, 307 308 // Should fill in any details that could be postponed until after the 309 // decision whether to ignore the error (ie. details not affecting the 310 // result of VG_(tdict).tool_eq_Error()). This saves time when errors 311 // are ignored. 312 // Yuk. 313 // Return value: must be the size of the `extra' part in bytes -- used by 314 // the core to make a copy. 315 UInt (*update_extra)(const Error* err), 316 317 // Return value indicates recognition. If recognised, must set skind using 318 // VG_(set_supp_kind)(). 319 Bool (*recognised_suppression)(const HChar* name, Supp* su), 320 321 // Read any extra info for this suppression kind. Most likely for filling 322 // in the `extra' and `string' parts (with VG_(set_supp_{extra, string})()) 323 // of a suppression if necessary. Should return False if a syntax error 324 // occurred, True otherwise. 325 // fd, bufpp, nBufp and lineno are the same as for VG_(get_line). 326 Bool (*read_extra_suppression_info)(Int fd, HChar** bufpp, SizeT* nBufp, 327 Int* lineno, Supp* su), 328 329 // This should just check the kinds match and maybe some stuff in the 330 // `string' and `extra' field if appropriate (using VG_(get_supp_*)() to 331 // get the relevant suppression parts). 332 Bool (*error_matches_suppression)(const Error* err, const Supp* su), 333 334 // This should return the suppression name, for --gen-suppressions, or NULL 335 // if that error type cannot be suppressed. This is the inverse of 336 // VG_(tdict).tool_recognised_suppression(). 337 const HChar* (*get_error_name)(const Error* err), 338 339 // This should print into buf[0..nBuf-1] any extra info for the 340 // error, for --gen-suppressions, but not including any leading 341 // spaces nor a trailing newline. The string needs to be null 342 // terminated. If the buffer is large enough to hold the string 343 // including the terminating null character the function shall 344 // return the value that strlen would return for the string. 345 // If the buffer is too small the function shall return nBuf. 346 SizeT (*print_extra_suppression_info)(const Error* err, 347 /*OUT*/HChar* buf, Int nBuf), 348 349 // This is similar to print_extra_suppression_info, but is used 350 // to print information such as additional statistical counters 351 // as part of the used suppression list produced by -v. 352 SizeT (*print_extra_suppression_use)(const Supp* su, 353 /*OUT*/HChar* buf, Int nBuf), 354 355 // Called by error mgr once it has been established that err 356 // is suppressed by su. update_extra_suppression_use typically 357 // can be used to update suppression extra information such as 358 // some statistical counters that will be printed by 359 // print_extra_suppression_use. 360 void (*update_extra_suppression_use)(const Error* err, const Supp* su) 361 ); 362 363 /* Is information kept by the tool about specific instructions or 364 translations? (Eg. for cachegrind there are cost-centres for every 365 instruction, stored in a per-translation fashion.) If so, the info 366 may have to be discarded when translations are unloaded (eg. due to 367 .so unloading, or otherwise at the discretion of m_transtab, eg 368 when the table becomes too full) to avoid stale information being 369 reused for new translations. */ 370 extern void VG_(needs_superblock_discards) ( 371 // Discard any information that pertains to specific translations 372 // or instructions within the address range given. There are two 373 // possible approaches. 374 // - If info is being stored at a per-translation level, use orig_addr 375 // to identify which translation is being discarded. Each translation 376 // will be discarded exactly once. 377 // This orig_addr will match the closure->nraddr which was passed to 378 // to instrument() (see extensive comments above) when this 379 // translation was made. Note that orig_addr won't necessarily be 380 // the same as the first address in "extents". 381 // - If info is being stored at a per-instruction level, you can get 382 // the address range(s) being discarded by stepping through "extents". 383 // Note that any single instruction may belong to more than one 384 // translation, and so could be covered by the "extents" of more than 385 // one call to this function. 386 // Doing it the first way (as eg. Cachegrind does) is probably easier. 387 void (*discard_superblock_info)(Addr orig_addr, VexGuestExtents extents) 388 ); 389 390 /* Tool defines its own command line options? */ 391 extern void VG_(needs_command_line_options) ( 392 // Return True if option was recognised, False if it wasn't (but also see 393 // below). Presumably sets some state to record the option as well. 394 // 395 // Nb: tools can assume that the argv will never disappear. So they can, 396 // for example, store a pointer to a string within an option, rather than 397 // having to make a copy. 398 // 399 // Options (and combinations of options) should be checked in this function 400 // if possible rather than in post_clo_init(), and if they are bad then 401 // VG_(fmsg_bad_option)() should be called. This ensures that the 402 // messaging is consistent with command line option errors from the core. 403 Bool (*process_cmd_line_option)(const HChar* argv), 404 405 // Print out command line usage for options for normal tool operation. 406 void (*print_usage)(void), 407 408 // Print out command line usage for options for debugging the tool. 409 void (*print_debug_usage)(void) 410 ); 411 412 /* Tool defines its own client requests? */ 413 extern void VG_(needs_client_requests) ( 414 // If using client requests, the number of the first request should be equal 415 // to VG_USERREQ_TOOL_BASE('X', 'Y'), where 'X' and 'Y' form a suitable two 416 // character identification for the string. The second and subsequent 417 // requests should follow. 418 // 419 // This function should use the VG_IS_TOOL_USERREQ macro (in 420 // include/valgrind.h) to first check if it's a request for this tool. Then 421 // should handle it if it's recognised (and return True), or return False if 422 // not recognised. arg_block[0] holds the request number, any further args 423 // from the request are in arg_block[1..]. 'ret' is for the return value... 424 // it should probably be filled, if only with 0. 425 Bool (*handle_client_request)(ThreadId tid, UWord* arg_block, UWord* ret) 426 ); 427 428 /* Tool does stuff before and/or after system calls? */ 429 // Nb: If either of the pre_ functions malloc() something to return, the 430 // corresponding post_ function had better free() it! 431 // Also, the args are the 'original args' -- that is, it may be 432 // that the syscall pre-wrapper will modify the args before the 433 // syscall happens. So these args are the original, un-modified 434 // args. Finally, nArgs merely indicates the length of args[..], 435 // it does not indicate how many of those values are actually 436 // relevant to the syscall. args[0 .. nArgs-1] is guaranteed 437 // to be defined and to contain all the args for this syscall, 438 // possibly including some trailing zeroes. 439 extern void VG_(needs_syscall_wrapper) ( 440 void (* pre_syscall)(ThreadId tid, UInt syscallno, 441 UWord* args, UInt nArgs), 442 void (*post_syscall)(ThreadId tid, UInt syscallno, 443 UWord* args, UInt nArgs, SysRes res) 444 ); 445 446 /* Are tool-state sanity checks performed? */ 447 // Can be useful for ensuring a tool's correctness. cheap_sanity_check() 448 // is called very frequently; expensive_sanity_check() is called less 449 // frequently and can be more involved. 450 extern void VG_(needs_sanity_checks) ( 451 Bool(*cheap_sanity_check)(void), 452 Bool(*expensive_sanity_check)(void) 453 ); 454 455 /* Can the tool produce stats during execution? */ 456 extern void VG_(needs_print_stats) ( 457 // Print out tool status. Note that the stats at end of execution 458 // should be output by the VG_(basic_tool_funcs) "fini" function. 459 void (*print_stats)(void) 460 ); 461 462 /* Has the tool a tool specific function to retrieve and print location info 463 of an address ? */ 464 extern void VG_(needs_info_location) ( 465 // Get and pp information about Addr 466 void (*info_location)(Addr) 467 ); 468 469 /* Do we need to see variable type and location information? */ 470 extern void VG_(needs_var_info) ( void ); 471 472 /* Does the tool replace malloc() and friends with its own versions? 473 This has to be combined with the use of a vgpreload_<tool>.so module 474 or it won't work. See massif/Makefile.am for how to build it. */ 475 // The 'p' prefix avoids GCC complaints about overshadowing global names. 476 extern void VG_(needs_malloc_replacement)( 477 void* (*pmalloc) ( ThreadId tid, SizeT n ), 478 void* (*p__builtin_new) ( ThreadId tid, SizeT n ), 479 void* (*p__builtin_vec_new) ( ThreadId tid, SizeT n ), 480 void* (*pmemalign) ( ThreadId tid, SizeT align, SizeT n ), 481 void* (*pcalloc) ( ThreadId tid, SizeT nmemb, SizeT size1 ), 482 void (*pfree) ( ThreadId tid, void* p ), 483 void (*p__builtin_delete) ( ThreadId tid, void* p ), 484 void (*p__builtin_vec_delete) ( ThreadId tid, void* p ), 485 void* (*prealloc) ( ThreadId tid, void* p, SizeT new_size ), 486 SizeT (*pmalloc_usable_size) ( ThreadId tid, void* p), 487 SizeT client_malloc_redzone_szB 488 ); 489 490 /* Can the tool do XML output? This is a slight misnomer, because the tool 491 * is not requesting the core to do anything, rather saying "I can handle 492 * it". */ 493 extern void VG_(needs_xml_output) ( void ); 494 495 /* Does the tool want to have one final pass over the IR after tree 496 building but before instruction selection? If so specify the 497 function here. */ 498 extern void VG_(needs_final_IR_tidy_pass) ( IRSB*(*final_tidy)(IRSB*) ); 499 500 501 /* ------------------------------------------------------------------ */ 502 /* Core events to track */ 503 504 /* Part of the core from which this call was made. Useful for determining 505 what kind of error message should be emitted. */ 506 typedef 507 enum { Vg_CoreStartup=1, Vg_CoreSignal, Vg_CoreSysCall, 508 // This is for platforms where syscall args are passed on the 509 // stack; although pre_mem_read is the callback that will be 510 // called, such an arg should be treated (with respect to 511 // presenting information to the user) as if it was passed in a 512 // register, ie. like pre_reg_read. 513 Vg_CoreSysCallArgInMem, 514 Vg_CoreTranslate, Vg_CoreClientReq 515 } CorePart; 516 517 /* Events happening in core to track. To be notified, pass a callback 518 function to the appropriate function. To ignore an event, don't do 519 anything (the default is for events to be ignored). 520 521 Note that most events aren't passed a ThreadId. If the event is one called 522 from generated code (eg. new_mem_stack_*), you can use 523 VG_(get_running_tid)() to find it. Otherwise, it has to be passed in, 524 as in pre_mem_read, and so the event signature will require changing. 525 526 Memory events (Nb: to track heap allocation/freeing, a tool must replace 527 malloc() et al. See above how to do this.) 528 529 These ones occur at startup, upon some signals, and upon some syscalls. 530 531 For new_mem_brk and new_mem_stack_signal, the supplied ThreadId 532 indicates the thread for whom the new memory is being allocated. 533 534 For new_mem_startup and new_mem_mmap, the di_handle argument is a 535 handle which can be used to retrieve debug info associated with the 536 mapping or allocation (because it is of a file that Valgrind has 537 decided to read debug info from). If the value is zero, there is 538 no associated debug info. If the value exceeds zero, it can be 539 supplied as an argument to selected queries in m_debuginfo. 540 */ 541 void VG_(track_new_mem_startup) (void(*f)(Addr a, SizeT len, 542 Bool rr, Bool ww, Bool xx, 543 ULong di_handle)); 544 void VG_(track_new_mem_stack_signal)(void(*f)(Addr a, SizeT len, ThreadId tid)); 545 void VG_(track_new_mem_brk) (void(*f)(Addr a, SizeT len, ThreadId tid)); 546 void VG_(track_new_mem_mmap) (void(*f)(Addr a, SizeT len, 547 Bool rr, Bool ww, Bool xx, 548 ULong di_handle)); 549 550 void VG_(track_copy_mem_remap) (void(*f)(Addr from, Addr to, SizeT len)); 551 void VG_(track_change_mem_mprotect) (void(*f)(Addr a, SizeT len, 552 Bool rr, Bool ww, Bool xx)); 553 void VG_(track_die_mem_stack_signal)(void(*f)(Addr a, SizeT len)); 554 void VG_(track_die_mem_brk) (void(*f)(Addr a, SizeT len)); 555 void VG_(track_die_mem_munmap) (void(*f)(Addr a, SizeT len)); 556 557 /* These ones are called when SP changes. A tool could track these itself 558 (except for ban_mem_stack) but it's much easier to use the core's help. 559 560 The specialised ones are called in preference to the general one, if they 561 are defined. These functions are called a lot if they are used, so 562 specialising can optimise things significantly. If any of the 563 specialised cases are defined, the general case must be defined too. 564 565 Nb: all the specialised ones must use the VG_REGPARM(n) attribute. 566 567 For the _new functions, a tool may specify with with-ECU 568 (ExeContext Unique) or without-ECU version for each size, but not 569 both. If the with-ECU version is supplied, then the core will 570 arrange to pass, as the ecu argument, a 32-bit int which uniquely 571 identifies the instruction moving the stack pointer down. This 572 32-bit value is as obtained from VG_(get_ECU_from_ExeContext). 573 VG_(get_ExeContext_from_ECU) can then be used to retrieve the 574 associated depth-1 ExeContext for the location. All this 575 complexity is provided to support origin tracking in Memcheck. 576 */ 577 void VG_(track_new_mem_stack_4_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 578 void VG_(track_new_mem_stack_8_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 579 void VG_(track_new_mem_stack_12_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 580 void VG_(track_new_mem_stack_16_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 581 void VG_(track_new_mem_stack_32_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 582 void VG_(track_new_mem_stack_112_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 583 void VG_(track_new_mem_stack_128_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 584 void VG_(track_new_mem_stack_144_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 585 void VG_(track_new_mem_stack_160_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 586 void VG_(track_new_mem_stack_w_ECU) (void(*f)(Addr a, SizeT len, 587 UInt ecu)); 588 589 void VG_(track_new_mem_stack_4) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 590 void VG_(track_new_mem_stack_8) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 591 void VG_(track_new_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 592 void VG_(track_new_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 593 void VG_(track_new_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 594 void VG_(track_new_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 595 void VG_(track_new_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 596 void VG_(track_new_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 597 void VG_(track_new_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 598 void VG_(track_new_mem_stack) (void(*f)(Addr a, SizeT len)); 599 600 void VG_(track_die_mem_stack_4) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 601 void VG_(track_die_mem_stack_8) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 602 void VG_(track_die_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 603 void VG_(track_die_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 604 void VG_(track_die_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 605 void VG_(track_die_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 606 void VG_(track_die_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 607 void VG_(track_die_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 608 void VG_(track_die_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 609 void VG_(track_die_mem_stack) (void(*f)(Addr a, SizeT len)); 610 611 /* Used for redzone at end of thread stacks */ 612 void VG_(track_ban_mem_stack) (void(*f)(Addr a, SizeT len)); 613 614 /* These ones occur around syscalls, signal handling, etc */ 615 void VG_(track_pre_mem_read) (void(*f)(CorePart part, ThreadId tid, 616 const HChar* s, Addr a, SizeT size)); 617 void VG_(track_pre_mem_read_asciiz)(void(*f)(CorePart part, ThreadId tid, 618 const HChar* s, Addr a)); 619 void VG_(track_pre_mem_write) (void(*f)(CorePart part, ThreadId tid, 620 const HChar* s, Addr a, SizeT size)); 621 void VG_(track_post_mem_write) (void(*f)(CorePart part, ThreadId tid, 622 Addr a, SizeT size)); 623 624 /* Register events. Use VG_(set_shadow_state_area)() to set the shadow regs 625 for these events. */ 626 void VG_(track_pre_reg_read) (void(*f)(CorePart part, ThreadId tid, 627 const HChar* s, PtrdiffT guest_state_offset, 628 SizeT size)); 629 void VG_(track_post_reg_write)(void(*f)(CorePart part, ThreadId tid, 630 PtrdiffT guest_state_offset, 631 SizeT size)); 632 633 /* This one is called for malloc() et al if they are replaced by a tool. */ 634 void VG_(track_post_reg_write_clientcall_return)( 635 void(*f)(ThreadId tid, PtrdiffT guest_state_offset, SizeT size, Addr f)); 636 637 /* Mem-to-reg or reg-to-mem copy functions, these ones occur around syscalls 638 and signal handling when the VCPU state is saved to (or restored from) the 639 client memory. */ 640 void VG_(track_copy_mem_to_reg)(void(*f)(CorePart part, ThreadId tid, 641 Addr a, PtrdiffT guest_state_offset, 642 SizeT size)); 643 void VG_(track_copy_reg_to_mem)(void(*f)(CorePart part, ThreadId tid, 644 PtrdiffT guest_state_offset, 645 Addr a, SizeT size)); 646 647 648 /* Scheduler events (not exhaustive) */ 649 650 /* Called when 'tid' starts or stops running client code blocks. 651 Gives the total dispatched block count at that event. Note, this 652 is not the same as 'tid' holding the BigLock (the lock that ensures 653 that only one thread runs at a time): a thread can hold the lock 654 for other purposes (making translations, etc) yet not be running 655 client blocks. Obviously though, a thread must hold the lock in 656 order to run client code blocks, so the times bracketed by 657 'start_client_code'..'stop_client_code' are a subset of the times 658 when thread 'tid' holds the cpu lock. 659 */ 660 void VG_(track_start_client_code)( 661 void(*f)(ThreadId tid, ULong blocks_dispatched) 662 ); 663 void VG_(track_stop_client_code)( 664 void(*f)(ThreadId tid, ULong blocks_dispatched) 665 ); 666 667 668 /* Thread events (not exhaustive) 669 670 ll_create: low level thread creation. Called before the new thread 671 has run any instructions (or touched any memory). In fact, called 672 immediately before the new thread has come into existence; the new 673 thread can be assumed to exist when notified by this call. 674 675 ll_exit: low level thread exit. Called after the exiting thread 676 has run its last instruction. 677 678 The _ll_ part makes it clear these events are not to do with 679 pthread_create or pthread_exit/pthread_join (etc), which are a 680 higher level abstraction synthesised by libpthread. What you can 681 be sure of from _ll_create/_ll_exit is the absolute limits of each 682 thread's lifetime, and hence be assured that all memory references 683 made by the thread fall inside the _ll_create/_ll_exit pair. This 684 is important for tools that need a 100% accurate account of which 685 thread is responsible for every memory reference in the process. 686 687 pthread_create/join/exit do not give this property. Calls/returns 688 to/from them happen arbitrarily far away from the relevant 689 low-level thread create/quit event. In general a few hundred 690 instructions; hence a few hundred(ish) memory references could get 691 misclassified each time. 692 693 pre_thread_first_insn: is called when the thread is all set up and 694 ready to go (stack in place, etc) but has not executed its first 695 instruction yet. Gives threading tools a chance to ask questions 696 about the thread (eg, what is its initial client stack pointer) 697 that are not easily answered at pre_thread_ll_create time. 698 699 For a given thread, the call sequence is: 700 ll_create (in the parent's context) 701 first_insn (in the child's context) 702 ll_exit (in the child's context) 703 */ 704 void VG_(track_pre_thread_ll_create) (void(*f)(ThreadId tid, ThreadId child)); 705 void VG_(track_pre_thread_first_insn)(void(*f)(ThreadId tid)); 706 void VG_(track_pre_thread_ll_exit) (void(*f)(ThreadId tid)); 707 708 709 /* Signal events (not exhaustive) 710 711 ... pre_send_signal, post_send_signal ... 712 713 Called before a signal is delivered; `alt_stack' indicates if it is 714 delivered on an alternative stack. */ 715 void VG_(track_pre_deliver_signal) (void(*f)(ThreadId tid, Int sigNo, 716 Bool alt_stack)); 717 /* Called after a signal is delivered. Nb: unfortunately, if the signal 718 handler longjmps, this won't be called. */ 719 void VG_(track_post_deliver_signal)(void(*f)(ThreadId tid, Int sigNo)); 720 721 #endif // __PUB_TOOL_TOOLIFACE_H 722 723 /*--------------------------------------------------------------------*/ 724 /*--- end ---*/ 725 /*--------------------------------------------------------------------*/ 726