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-2013 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   ( tl_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
64typedef
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
75extern VgDetails VG_(details);
76
77/* ---------------------------------------------------------------------
78   'Needs'
79   ------------------------------------------------------------------ */
80
81typedef
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
100extern VgNeeds VG_(needs);
101
102/* ---------------------------------------------------------------------
103   The dictionary of callable tool functions
104   ------------------------------------------------------------------ */
105
106typedef 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                               VexGuestLayout*, VexGuestExtents*,
114                               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, Error*, Error*);
122   void  (*tool_before_pp_Error)             (Error*);
123   void  (*tool_pp_Error)                    (Error*);
124   Bool  tool_show_ThreadIDs_for_errors;
125   UInt  (*tool_update_extra)                (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)   (Error*, Supp*);
130   const HChar* (*tool_get_error_name)       (Error*);
131   Bool  (*tool_get_extra_suppression_info)  (Error*,/*OUT*/HChar*,Int);
132   Bool  (*tool_print_extra_suppression_use) (Supp*,/*OUT*/HChar*,Int);
133   void  (*tool_update_extra_suppression_use) (Error*, Supp*);
134
135   // VG_(needs).superblock_discards
136   void (*tool_discard_superblock_info)(Addr64, 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_start_client_code)(ThreadId, ULong);
237   void (*track_stop_client_code) (ThreadId, ULong);
238
239   void (*track_pre_thread_ll_create)(ThreadId, ThreadId);
240   void (*track_pre_thread_first_insn)(ThreadId);
241   void (*track_pre_thread_ll_exit)  (ThreadId);
242
243   void (*track_pre_deliver_signal) (ThreadId, Int sigNo, Bool);
244   void (*track_post_deliver_signal)(ThreadId, Int sigNo);
245
246} VgToolInterface;
247
248extern VgToolInterface VG_(tdict);
249
250/* ---------------------------------------------------------------------
251   Miscellaneous functions
252   ------------------------------------------------------------------ */
253
254Bool VG_(sanity_check_needs) ( const HChar** failmsg );
255
256#endif   // __PUB_CORE_TOOLIFACE_H
257
258/*--------------------------------------------------------------------*/
259/*--- end                                                          ---*/
260/*--------------------------------------------------------------------*/
261