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