Home | History | Annotate | Download | only in coregrind
      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 (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_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 /*--------------------------------------------------------------------*/
    264