coregrind/pub_core_tooliface.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- The core/tool interface.                pub_core_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@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_CORE_TOOLIFACE_H
  32 #define __PUB_CORE_TOOLIFACE_H
  33
  34 #include "pub_tool_tooliface.h"
  35
  36 //--------------------------------------------------------------------
  37 // PURPOSE: This module encapsulates the key parts of the core/tool
  38 // interface: 'details', 'needs' and 'trackable events'.
  39 //--------------------------------------------------------------------
  40
  41 // Note the use of C's comma operator here -- it means that we execute both
  42 // statements, and the rvalue of the whole thing is the rvalue of the last
  43 // statement.  This lets us say "x = VG_TDICT_CALL(...)" in the required
  44 // places, while still checking the assertion.
  45 #define VG_TDICT_CALL(fn, args...) \
  46    ( vg_assert2(VG_(tdict).fn, \
  47                 "you forgot to set VgToolInterface function '" #fn "'"), \
  48      VG_(tdict).fn(args) )
  49
  50 #define VG_TRACK(fn, args...)                   \
  51    do {                                         \
  52       if (VG_(tdict).track_##fn)                \
  53          VG_(tdict).track_##fn(args);           \
  54    } while(0)
  55
  56 /* These structs are not exposed to tools to mitigate possibility of
  57    binary-incompatibilities when the core/tool interface changes.  Instead,
  58    set functions are provided (see include/pub_tool_tooliface.h). */
  59
  60 /* ---------------------------------------------------------------------
  61    'Details'
  62    ------------------------------------------------------------------ */
  63
  64 typedef
  65    struct {
  66       const HChar* name;
  67       const HChar* version;
  68       const HChar* description;
  69       const HChar* copyright_author;
  70       const HChar* bug_reports_to;
  71       UInt  avg_translation_sizeB;
  72    }
  73    VgDetails;
  74
  75 extern VgDetails VG_(details);
  76
  77 /* ---------------------------------------------------------------------
  78    'Needs'
  79    ------------------------------------------------------------------ */
  80
  81 typedef
  82    struct {
  83       Bool libc_freeres;
  84       Bool core_errors;
  85       Bool tool_errors;
  86       Bool superblock_discards;
  87       Bool command_line_options;
  88       Bool client_requests;
  89       Bool syscall_wrapper;
  90       Bool sanity_checks;
  91       Bool print_stats;
  92       Bool info_location;
  93       Bool var_info;
  94       Bool malloc_replacement;
  95       Bool xml_output;
  96       Bool final_IR_tidy_pass;
  97    }
  98    VgNeeds;
  99
 100 extern VgNeeds VG_(needs);
 101
 102 /* ---------------------------------------------------------------------
 103    The dictionary of callable tool functions
 104    ------------------------------------------------------------------ */
 105
 106 typedef struct {
 107    // -- 'Needs'-related functions ----------------------------------
 108    // Basic functions
 109    void  (*tool_pre_clo_init) (void);
 110    void  (*tool_post_clo_init)(void);
 111    IRSB* (*tool_instrument)   (VgCallbackClosure*,
 112                                IRSB*,
 113                                const VexGuestLayout*, const VexGuestExtents*,
 114                                const VexArchInfo*, IRType, IRType);
 115    void  (*tool_fini)         (Int);
 116
 117    // VG_(needs).core_errors
 118    // (none)
 119
 120    // VG_(needs).tool_errors
 121    Bool  (*tool_eq_Error)                  (VgRes, const Error*, const Error*);
 122    void  (*tool_before_pp_Error)           (const Error*);
 123    void  (*tool_pp_Error)                  (const Error*);
 124    Bool  tool_show_ThreadIDs_for_errors;
 125    UInt  (*tool_update_extra)                (const Error*);
 126    Bool  (*tool_recognised_suppression)      (const HChar*, Supp*);
 127    Bool  (*tool_read_extra_suppression_info) (Int, HChar**, SizeT*, Int*,
 128                                               Supp*);
 129    Bool  (*tool_error_matches_suppression)   (const Error*, const Supp*);
 130    const HChar* (*tool_get_error_name)       (const Error*);
 131    SizeT (*tool_get_extra_suppression_info)  (const Error*,/*OUT*/HChar*,Int);
 132    SizeT (*tool_print_extra_suppression_use) (const Supp*,/*OUT*/HChar*,Int);
 133    void  (*tool_update_extra_suppression_use) (const Error*, const Supp*);
 134
 135    // VG_(needs).superblock_discards
 136    void (*tool_discard_superblock_info)(Addr, VexGuestExtents);
 137
 138    // VG_(needs).command_line_options
 139    Bool (*tool_process_cmd_line_option)(const HChar*);
 140    void (*tool_print_usage)            (void);
 141    void (*tool_print_debug_usage)      (void);
 142
 143    // VG_(needs).client_requests
 144    Bool (*tool_handle_client_request)(ThreadId, UWord*, UWord*);
 145
 146    // VG_(needs).syscall_wrapper
 147    void (*tool_pre_syscall) (ThreadId, UInt, UWord*, UInt);
 148    void (*tool_post_syscall)(ThreadId, UInt, UWord*, UInt, SysRes);
 149
 150    // VG_(needs).sanity_checks
 151    Bool (*tool_cheap_sanity_check)(void);
 152    Bool (*tool_expensive_sanity_check)(void);
 153
 154    // VG_(needs).print_stats
 155    void (*tool_print_stats)(void);
 156
 157    // VG_(needs).info_location
 158    void (*tool_info_location)(Addr a);
 159
 160    // VG_(needs).malloc_replacement
 161    void* (*tool_malloc)              (ThreadId, SizeT);
 162    void* (*tool___builtin_new)       (ThreadId, SizeT);
 163    void* (*tool___builtin_vec_new)   (ThreadId, SizeT);
 164    void* (*tool_memalign)            (ThreadId, SizeT, SizeT);
 165    void* (*tool_calloc)              (ThreadId, SizeT, SizeT);
 166    void  (*tool_free)                (ThreadId, void*);
 167    void  (*tool___builtin_delete)    (ThreadId, void*);
 168    void  (*tool___builtin_vec_delete)(ThreadId, void*);
 169    void* (*tool_realloc)             (ThreadId, void*, SizeT);
 170    SizeT (*tool_malloc_usable_size)  (ThreadId, void*);
 171    SizeT tool_client_redzone_szB;
 172
 173    // VG_(needs).final_IR_tidy_pass
 174    IRSB* (*tool_final_IR_tidy_pass)  (IRSB*);
 175
 176    // VG_(needs).xml_output
 177    // (none)
 178
 179    // -- Event tracking functions ------------------------------------
 180    void (*track_new_mem_startup)     (Addr, SizeT, Bool, Bool, Bool, ULong);
 181    void (*track_new_mem_stack_signal)(Addr, SizeT, ThreadId);
 182    void (*track_new_mem_brk)         (Addr, SizeT, ThreadId);
 183    void (*track_new_mem_mmap)        (Addr, SizeT, Bool, Bool, Bool, ULong);
 184
 185    void (*track_copy_mem_remap)      (Addr src, Addr dst, SizeT);
 186    void (*track_change_mem_mprotect) (Addr, SizeT, Bool, Bool, Bool);
 187    void (*track_die_mem_stack_signal)(Addr, SizeT);
 188    void (*track_die_mem_brk)         (Addr, SizeT);
 189    void (*track_die_mem_munmap)      (Addr, SizeT);
 190
 191    void VG_REGPARM(2) (*track_new_mem_stack_4_w_ECU)  (Addr,UInt);
 192    void VG_REGPARM(2) (*track_new_mem_stack_8_w_ECU)  (Addr,UInt);
 193    void VG_REGPARM(2) (*track_new_mem_stack_12_w_ECU) (Addr,UInt);
 194    void VG_REGPARM(2) (*track_new_mem_stack_16_w_ECU) (Addr,UInt);
 195    void VG_REGPARM(2) (*track_new_mem_stack_32_w_ECU) (Addr,UInt);
 196    void VG_REGPARM(2) (*track_new_mem_stack_112_w_ECU)(Addr,UInt);
 197    void VG_REGPARM(2) (*track_new_mem_stack_128_w_ECU)(Addr,UInt);
 198    void VG_REGPARM(2) (*track_new_mem_stack_144_w_ECU)(Addr,UInt);
 199    void VG_REGPARM(2) (*track_new_mem_stack_160_w_ECU)(Addr,UInt);
 200    void (*track_new_mem_stack_w_ECU)(Addr,SizeT,UInt);
 201
 202    void VG_REGPARM(1) (*track_new_mem_stack_4)  (Addr);
 203    void VG_REGPARM(1) (*track_new_mem_stack_8)  (Addr);
 204    void VG_REGPARM(1) (*track_new_mem_stack_12) (Addr);
 205    void VG_REGPARM(1) (*track_new_mem_stack_16) (Addr);
 206    void VG_REGPARM(1) (*track_new_mem_stack_32) (Addr);
 207    void VG_REGPARM(1) (*track_new_mem_stack_112)(Addr);
 208    void VG_REGPARM(1) (*track_new_mem_stack_128)(Addr);
 209    void VG_REGPARM(1) (*track_new_mem_stack_144)(Addr);
 210    void VG_REGPARM(1) (*track_new_mem_stack_160)(Addr);
 211    void (*track_new_mem_stack)(Addr,SizeT);
 212
 213    void VG_REGPARM(1) (*track_die_mem_stack_4)  (Addr);
 214    void VG_REGPARM(1) (*track_die_mem_stack_8)  (Addr);
 215    void VG_REGPARM(1) (*track_die_mem_stack_12) (Addr);
 216    void VG_REGPARM(1) (*track_die_mem_stack_16) (Addr);
 217    void VG_REGPARM(1) (*track_die_mem_stack_32) (Addr);
 218    void VG_REGPARM(1) (*track_die_mem_stack_112)(Addr);
 219    void VG_REGPARM(1) (*track_die_mem_stack_128)(Addr);
 220    void VG_REGPARM(1) (*track_die_mem_stack_144)(Addr);
 221    void VG_REGPARM(1) (*track_die_mem_stack_160)(Addr);
 222    void (*track_die_mem_stack)(Addr, SizeT);
 223
 224    void (*track_ban_mem_stack)(Addr, SizeT);
 225
 226    void (*track_pre_mem_read)       (CorePart, ThreadId, const HChar*, Addr, SizeT);
 227    void (*track_pre_mem_read_asciiz)(CorePart, ThreadId, const HChar*, Addr);
 228    void (*track_pre_mem_write)      (CorePart, ThreadId, const HChar*, Addr, SizeT);
 229    void (*track_post_mem_write)     (CorePart, ThreadId, Addr, SizeT);
 230
 231    void (*track_pre_reg_read)  (CorePart, ThreadId, const HChar*, PtrdiffT, SizeT);
 232    void (*track_post_reg_write)(CorePart, ThreadId,               PtrdiffT, SizeT);
 233    void (*track_post_reg_write_clientcall_return)(ThreadId, PtrdiffT, SizeT,
 234                                                   Addr);
 235
 236    void (*track_copy_mem_to_reg)(CorePart, ThreadId, Addr, PtrdiffT, SizeT);
 237    void (*track_copy_reg_to_mem)(CorePart, ThreadId, PtrdiffT, Addr, SizeT);
 238
 239    void (*track_start_client_code)(ThreadId, ULong);
 240    void (*track_stop_client_code) (ThreadId, ULong);
 241
 242    void (*track_pre_thread_ll_create)(ThreadId, ThreadId);
 243    void (*track_pre_thread_first_insn)(ThreadId);
 244    void (*track_pre_thread_ll_exit)  (ThreadId);
 245
 246    void (*track_pre_deliver_signal) (ThreadId, Int sigNo, Bool);
 247    void (*track_post_deliver_signal)(ThreadId, Int sigNo);
 248
 249 } VgToolInterface;
 250
 251 extern VgToolInterface VG_(tdict);
 252
 253 /* ---------------------------------------------------------------------
 254    Miscellaneous functions
 255    ------------------------------------------------------------------ */
 256
 257 Bool VG_(sanity_check_needs) ( const HChar** failmsg );
 258
 259 #endif   // __PUB_CORE_TOOLIFACE_H
 260
 261 /*--------------------------------------------------------------------*/
 262 /*--- end                                                          ---*/
 263 /*--------------------------------------------------------------------*/