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, 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 cxx_freeres;
  85       Bool core_errors;
  86       Bool tool_errors;
  87       Bool superblock_discards;
  88       Bool command_line_options;
  89       Bool client_requests;
  90       Bool syscall_wrapper;
  91       Bool sanity_checks;
  92       Bool print_stats;
  93       Bool info_location;
  94       Bool var_info;
  95       Bool malloc_replacement;
  96       Bool xml_output;
  97       Bool final_IR_tidy_pass;
  98    }
  99    VgNeeds;
 100
 101 extern VgNeeds VG_(needs);
 102
 103 /* ---------------------------------------------------------------------
 104    The dictionary of callable tool functions
 105    ------------------------------------------------------------------ */
 106
 107 typedef struct {
 108    // -- 'Needs'-related functions ----------------------------------
 109    // Basic functions
 110    void  (*tool_pre_clo_init) (void);
 111    void  (*tool_post_clo_init)(void);
 112    IRSB* (*tool_instrument)   (VgCallbackClosure*,
 113                                IRSB*,
 114                                const VexGuestLayout*, const VexGuestExtents*,
 115                                const VexArchInfo*, IRType, IRType);
 116    void  (*tool_fini)         (Int);
 117
 118    // VG_(needs).core_errors
 119    // (none)
 120
 121    // VG_(needs).tool_errors
 122    Bool  (*tool_eq_Error)                  (VgRes, const Error*, const Error*);
 123    void  (*tool_before_pp_Error)           (const Error*);
 124    void  (*tool_pp_Error)                  (const Error*);
 125    Bool  tool_show_ThreadIDs_for_errors;
 126    UInt  (*tool_update_extra)                (const Error*);
 127    Bool  (*tool_recognised_suppression)      (const HChar*, Supp*);
 128    Bool  (*tool_read_extra_suppression_info) (Int, HChar**, SizeT*, Int*,
 129                                               Supp*);
 130    Bool  (*tool_error_matches_suppression)   (const Error*, const Supp*);
 131    const HChar* (*tool_get_error_name)       (const Error*);
 132    SizeT (*tool_get_extra_suppression_info)  (const Error*,/*OUT*/HChar*,Int);
 133    SizeT (*tool_print_extra_suppression_use) (const Supp*,/*OUT*/HChar*,Int);
 134    void  (*tool_update_extra_suppression_use) (const Error*, const Supp*);
 135
 136    // VG_(needs).superblock_discards
 137    void (*tool_discard_superblock_info)(Addr, VexGuestExtents);
 138
 139    // VG_(needs).command_line_options
 140    Bool (*tool_process_cmd_line_option)(const HChar*);
 141    void (*tool_print_usage)            (void);
 142    void (*tool_print_debug_usage)      (void);
 143
 144    // VG_(needs).client_requests
 145    Bool (*tool_handle_client_request)(ThreadId, UWord*, UWord*);
 146
 147    // VG_(needs).syscall_wrapper
 148    void (*tool_pre_syscall) (ThreadId, UInt, UWord*, UInt);
 149    void (*tool_post_syscall)(ThreadId, UInt, UWord*, UInt, SysRes);
 150
 151    // VG_(needs).sanity_checks
 152    Bool (*tool_cheap_sanity_check)(void);
 153    Bool (*tool_expensive_sanity_check)(void);
 154
 155    // VG_(needs).print_stats
 156    void (*tool_print_stats)(void);
 157
 158    // VG_(needs).info_location
 159    void (*tool_info_location)(DiEpoch ep, Addr a);
 160
 161    // VG_(needs).malloc_replacement
 162    void* (*tool_malloc)              (ThreadId, SizeT);
 163    void* (*tool___builtin_new)       (ThreadId, SizeT);
 164    void* (*tool___builtin_vec_new)   (ThreadId, SizeT);
 165    void* (*tool_memalign)            (ThreadId, SizeT, SizeT);
 166    void* (*tool_calloc)              (ThreadId, SizeT, SizeT);
 167    void  (*tool_free)                (ThreadId, void*);
 168    void  (*tool___builtin_delete)    (ThreadId, void*);
 169    void  (*tool___builtin_vec_delete)(ThreadId, void*);
 170    void* (*tool_realloc)             (ThreadId, void*, SizeT);
 171    SizeT (*tool_malloc_usable_size)  (ThreadId, void*);
 172    SizeT tool_client_redzone_szB;
 173
 174    // VG_(needs).final_IR_tidy_pass
 175    IRSB* (*tool_final_IR_tidy_pass)  (IRSB*);
 176
 177    // VG_(needs).xml_output
 178    // (none)
 179
 180    // -- Event tracking functions ------------------------------------
 181    void (*track_new_mem_startup)     (Addr, SizeT, Bool, Bool, Bool, ULong);
 182    void (*track_new_mem_stack_signal)(Addr, SizeT, ThreadId);
 183    void (*track_new_mem_brk)         (Addr, SizeT, ThreadId);
 184    void (*track_new_mem_mmap)        (Addr, SizeT, Bool, Bool, Bool, ULong);
 185
 186    void (*track_copy_mem_remap)      (Addr src, Addr dst, SizeT);
 187    void (*track_change_mem_mprotect) (Addr, SizeT, Bool, Bool, Bool);
 188    void (*track_die_mem_stack_signal)(Addr, SizeT);
 189    void (*track_die_mem_brk)         (Addr, SizeT);
 190    void (*track_die_mem_munmap)      (Addr, SizeT);
 191
 192    void VG_REGPARM(2) (*track_new_mem_stack_4_w_ECU)  (Addr,UInt);
 193    void VG_REGPARM(2) (*track_new_mem_stack_8_w_ECU)  (Addr,UInt);
 194    void VG_REGPARM(2) (*track_new_mem_stack_12_w_ECU) (Addr,UInt);
 195    void VG_REGPARM(2) (*track_new_mem_stack_16_w_ECU) (Addr,UInt);
 196    void VG_REGPARM(2) (*track_new_mem_stack_32_w_ECU) (Addr,UInt);
 197    void VG_REGPARM(2) (*track_new_mem_stack_112_w_ECU)(Addr,UInt);
 198    void VG_REGPARM(2) (*track_new_mem_stack_128_w_ECU)(Addr,UInt);
 199    void VG_REGPARM(2) (*track_new_mem_stack_144_w_ECU)(Addr,UInt);
 200    void VG_REGPARM(2) (*track_new_mem_stack_160_w_ECU)(Addr,UInt);
 201    void (*track_new_mem_stack_w_ECU)(Addr,SizeT,UInt);
 202
 203    void VG_REGPARM(1) (*track_new_mem_stack_4)  (Addr);
 204    void VG_REGPARM(1) (*track_new_mem_stack_8)  (Addr);
 205    void VG_REGPARM(1) (*track_new_mem_stack_12) (Addr);
 206    void VG_REGPARM(1) (*track_new_mem_stack_16) (Addr);
 207    void VG_REGPARM(1) (*track_new_mem_stack_32) (Addr);
 208    void VG_REGPARM(1) (*track_new_mem_stack_112)(Addr);
 209    void VG_REGPARM(1) (*track_new_mem_stack_128)(Addr);
 210    void VG_REGPARM(1) (*track_new_mem_stack_144)(Addr);
 211    void VG_REGPARM(1) (*track_new_mem_stack_160)(Addr);
 212    void (*track_new_mem_stack)(Addr,SizeT);
 213
 214    Bool any_new_mem_stack; // True if one or more track_new_mem_stack is set
 215
 216    void VG_REGPARM(1) (*track_die_mem_stack_4)  (Addr);
 217    void VG_REGPARM(1) (*track_die_mem_stack_8)  (Addr);
 218    void VG_REGPARM(1) (*track_die_mem_stack_12) (Addr);
 219    void VG_REGPARM(1) (*track_die_mem_stack_16) (Addr);
 220    void VG_REGPARM(1) (*track_die_mem_stack_32) (Addr);
 221    void VG_REGPARM(1) (*track_die_mem_stack_112)(Addr);
 222    void VG_REGPARM(1) (*track_die_mem_stack_128)(Addr);
 223    void VG_REGPARM(1) (*track_die_mem_stack_144)(Addr);
 224    void VG_REGPARM(1) (*track_die_mem_stack_160)(Addr);
 225    void (*track_die_mem_stack)(Addr, SizeT);
 226
 227    Bool any_die_mem_stack; // True if one or more track_die_mem_stack is set
 228
 229    void (*track_ban_mem_stack)(Addr, SizeT);
 230
 231    void (*track_pre_mem_read)       (CorePart, ThreadId, const HChar*, Addr, SizeT);
 232    void (*track_pre_mem_read_asciiz)(CorePart, ThreadId, const HChar*, Addr);
 233    void (*track_pre_mem_write)      (CorePart, ThreadId, const HChar*, Addr, SizeT);
 234    void (*track_post_mem_write)     (CorePart, ThreadId, Addr, SizeT);
 235
 236    void (*track_pre_reg_read)  (CorePart, ThreadId, const HChar*, PtrdiffT, SizeT);
 237    void (*track_post_reg_write)(CorePart, ThreadId,               PtrdiffT, SizeT);
 238    void (*track_post_reg_write_clientcall_return)(ThreadId, PtrdiffT, SizeT,
 239                                                   Addr);
 240
 241    void (*track_copy_mem_to_reg)(CorePart, ThreadId, Addr, PtrdiffT, SizeT);
 242    void (*track_copy_reg_to_mem)(CorePart, ThreadId, PtrdiffT, Addr, SizeT);
 243
 244    void (*track_start_client_code)(ThreadId, ULong);
 245    void (*track_stop_client_code) (ThreadId, ULong);
 246
 247    void (*track_pre_thread_ll_create)(ThreadId, ThreadId);
 248    void (*track_pre_thread_first_insn)(ThreadId);
 249    void (*track_pre_thread_ll_exit)  (ThreadId);
 250
 251    void (*track_pre_deliver_signal) (ThreadId, Int sigNo, Bool);
 252    void (*track_post_deliver_signal)(ThreadId, Int sigNo);
 253
 254 } VgToolInterface;
 255
 256 extern VgToolInterface VG_(tdict);
 257
 258 /* ---------------------------------------------------------------------
 259    Miscellaneous functions
 260    ------------------------------------------------------------------ */
 261
 262 /* Sanity checks and finish the initialisation of the tool needs.
 263    Returns False and sets a failmsg if the needs are inconsistent. */
 264 Bool VG_(finish_needs_init) ( const HChar** failmsg );
 265
 266 #endif   // __PUB_CORE_TOOLIFACE_H
 267
 268 /*--------------------------------------------------------------------*/
 269 /*--- end                                                          ---*/
 270 /*--------------------------------------------------------------------*/