blob: 97cb8aa9dcafb74660381a1801265b53dfc1b441 [file] [log] [blame]
sewardjac9af022004-07-05 01:15:34 +00001
2/*---------------------------------------------------------------*/
3/*--- ---*/
sewardj887a11a2004-07-05 17:26:47 +00004/*--- This file (libvex.h) is ---*/
sewardjdbcfae72005-08-02 11:14:04 +00005/*--- Copyright (C) OpenWorks LLP. All rights reserved. ---*/
sewardjac9af022004-07-05 01:15:34 +00006/*--- ---*/
7/*---------------------------------------------------------------*/
8
sewardjf8ed9d82004-11-12 17:40:23 +00009/*
10 This file is part of LibVEX, a library for dynamic binary
11 instrumentation and translation.
12
sewardj7bd6ffe2005-08-03 16:07:36 +000013 Copyright (C) 2004-2005 OpenWorks LLP. All rights reserved.
sewardjf8ed9d82004-11-12 17:40:23 +000014
sewardj7bd6ffe2005-08-03 16:07:36 +000015 This library is made available under a dual licensing scheme.
sewardjf8ed9d82004-11-12 17:40:23 +000016
sewardj7bd6ffe2005-08-03 16:07:36 +000017 If you link LibVEX against other code all of which is itself
18 licensed under the GNU General Public License, version 2 dated June
19 1991 ("GPL v2"), then you may use LibVEX under the terms of the GPL
20 v2, as appearing in the file LICENSE.GPL. If the file LICENSE.GPL
21 is missing, you can obtain a copy of the GPL v2 from the Free
22 Software Foundation Inc., 51 Franklin St, Fifth Floor, Boston, MA
23 02110-1301, USA.
24
25 For any other uses of LibVEX, you must first obtain a commercial
26 license from OpenWorks LLP. Please contact info@open-works.co.uk
27 for information about commercial licensing.
28
29 This software is provided by OpenWorks LLP "as is" and any express
30 or implied warranties, including, but not limited to, the implied
31 warranties of merchantability and fitness for a particular purpose
32 are disclaimed. In no event shall OpenWorks LLP be liable for any
33 direct, indirect, incidental, special, exemplary, or consequential
34 damages (including, but not limited to, procurement of substitute
35 goods or services; loss of use, data, or profits; or business
36 interruption) however caused and on any theory of liability,
37 whether in contract, strict liability, or tort (including
38 negligence or otherwise) arising in any way out of the use of this
39 software, even if advised of the possibility of such damage.
sewardjf8ed9d82004-11-12 17:40:23 +000040
41 Neither the names of the U.S. Department of Energy nor the
42 University of California nor the names of its contributors may be
43 used to endorse or promote products derived from this software
44 without prior written permission.
sewardjf8ed9d82004-11-12 17:40:23 +000045*/
46
sewardj887a11a2004-07-05 17:26:47 +000047#ifndef __LIBVEX_H
48#define __LIBVEX_H
sewardjac9af022004-07-05 01:15:34 +000049
50
sewardj887a11a2004-07-05 17:26:47 +000051#include "libvex_basictypes.h"
52#include "libvex_ir.h"
sewardjac9af022004-07-05 01:15:34 +000053
54
55/*---------------------------------------------------------------*/
sewardjd887b862005-01-17 18:34:34 +000056/*--- This file defines the top-level interface to LibVEX. ---*/
sewardjac9af022004-07-05 01:15:34 +000057/*---------------------------------------------------------------*/
58
sewardjd887b862005-01-17 18:34:34 +000059/*-------------------------------------------------------*/
sewardj27e1dd62005-06-30 11:49:14 +000060/*--- Architectures, variants, and other arch info ---*/
sewardjd887b862005-01-17 18:34:34 +000061/*-------------------------------------------------------*/
sewardjbef170b2004-12-21 01:23:00 +000062
63typedef
64 enum {
65 VexArch_INVALID,
66 VexArchX86,
67 VexArchAMD64,
cerion896a1372005-01-25 12:24:25 +000068 VexArchARM,
cerionaabdfbf2005-01-29 12:56:15 +000069 VexArchPPC32
sewardjbef170b2004-12-21 01:23:00 +000070 }
71 VexArch;
72
73typedef
74 enum {
75 VexSubArch_INVALID,
sewardj0ec57c52005-02-01 15:24:10 +000076 VexSubArch_NONE, /* Arch has no variants */
77 VexSubArchX86_sse0, /* has SSE state but no insns (Pentium II) */
78 VexSubArchX86_sse1, /* SSE1 support (Pentium III) */
79 VexSubArchX86_sse2, /* SSE2 support (Pentium 4) */
80 VexSubArchARM_v4, /* ARM version 4 */
81 VexSubArchPPC32_noAV, /* 32-bit PowerPC, no Altivec */
82 VexSubArchPPC32_AV /* 32-bit PowerPC with Altivec */
sewardjbef170b2004-12-21 01:23:00 +000083 }
84 VexSubArch;
85
86/* These return statically allocated strings. */
87
88extern const HChar* LibVEX_ppVexArch ( VexArch );
89extern const HChar* LibVEX_ppVexSubArch ( VexSubArch );
90
sewardjac9af022004-07-05 01:15:34 +000091
sewardj27e1dd62005-06-30 11:49:14 +000092/* This struct is a bit of a hack, but is needed to carry misc
93 important bits of info about an arch. Fields which are optional or
94 ignored on some arch should be set to zero. */
95
96typedef
97 struct {
98 /* This is the only mandatory field. */
99 VexSubArch subarch;
100 /* PPC32 only: size of cache line */
101 Int ppc32_cache_line_szB;
102 }
103 VexArchInfo;
104
105/* Write default settings info *vai. */
106extern
107void LibVEX_default_VexArchInfo ( /*OUT*/VexArchInfo* vai );
108
109
sewardjd887b862005-01-17 18:34:34 +0000110/*-------------------------------------------------------*/
111/*--- Control of Vex's optimiser (iropt). ---*/
112/*-------------------------------------------------------*/
113
sewardj08613742004-10-25 13:01:45 +0000114/* Control of Vex's optimiser. */
115
116typedef
117 struct {
118 /* Controls verbosity of iropt. 0 = no output. */
119 Int iropt_verbosity;
120 /* Control aggressiveness of iropt. 0 = no opt, 1 = simple
121 opts, 2 (default) = max optimisation. */
122 Int iropt_level;
123 /* Ensure all integer registers are up to date at potential
124 memory exception points? True(default)=yes, False=no, only
125 the guest's stack pointer. */
126 Bool iropt_precise_memory_exns;
127 /* How aggressive should iropt be in unrolling loops? Higher
128 numbers make it more enthusiastic about loop unrolling.
129 Default=120. A setting of zero disables unrolling. */
130 Int iropt_unroll_thresh;
131 /* What's the maximum basic block length the front end(s) allow?
132 BBs longer than this are split up. Default=50 (guest
133 insns). */
134 Int guest_max_insns;
135 /* How aggressive should front ends be in following
136 unconditional branches to known destinations? Default=10,
137 meaning that if a block contains less than 10 guest insns so
138 far, the front end(s) will attempt to chase into its
139 successor. A setting of zero disables chasing. */
140 Int guest_chase_thresh;
141 }
142 VexControl;
143
144
145/* Write the default settings into *vcon. */
sewardjbef170b2004-12-21 01:23:00 +0000146
sewardjd887b862005-01-17 18:34:34 +0000147extern
148void LibVEX_default_VexControl ( /*OUT*/ VexControl* vcon );
sewardj08613742004-10-25 13:01:45 +0000149
150
sewardjd887b862005-01-17 18:34:34 +0000151/*-------------------------------------------------------*/
152/*--- Version information ---*/
153/*-------------------------------------------------------*/
sewardj80f5fce2004-12-20 04:37:50 +0000154
sewardjd887b862005-01-17 18:34:34 +0000155/* Returns the Vex SVN version, as a statically allocated string. */
156
157extern const HChar* LibVEX_Version ( void );
sewardj80f5fce2004-12-20 04:37:50 +0000158
159
sewardjd887b862005-01-17 18:34:34 +0000160/*-------------------------------------------------------*/
161/*--- Storage management control ---*/
162/*-------------------------------------------------------*/
sewardjac9af022004-07-05 01:15:34 +0000163
sewardjd887b862005-01-17 18:34:34 +0000164/* Allocate in Vex's temporary allocation area. Be careful with this.
165 You can only call it inside an instrumentation or optimisation
166 callback that you have previously specified in a call to
167 LibVEX_Translate. The storage allocated will only stay alive until
168 translation of the current basic block is complete.
169 */
sewardj35421a32004-07-05 13:12:34 +0000170extern void* LibVEX_Alloc ( Int nbytes );
sewardjac9af022004-07-05 01:15:34 +0000171
sewardjd887b862005-01-17 18:34:34 +0000172/* Show Vex allocation statistics. */
173extern void LibVEX_ShowAllocStats ( void );
174
175
176/*-------------------------------------------------------*/
177/*--- Describing guest state layout ---*/
178/*-------------------------------------------------------*/
sewardjac9af022004-07-05 01:15:34 +0000179
sewardj49651f42004-10-28 22:11:04 +0000180/* Describe the guest state enough that the instrumentation
181 functions can work. */
182
sewardjeeac8412004-11-02 00:26:55 +0000183/* The max number of guest state chunks which we can describe as
184 always defined (for the benefit of Memcheck). */
sewardj6d269842005-08-06 11:45:02 +0000185#define VEXGLO_N_ALWAYSDEFD 22
sewardjeeac8412004-11-02 00:26:55 +0000186
sewardj49651f42004-10-28 22:11:04 +0000187typedef
188 struct {
sewardjcf787902004-11-03 09:08:33 +0000189 /* Total size of the guest state, in bytes. Must be
190 8-aligned. */
sewardjeeac8412004-11-02 00:26:55 +0000191 Int total_sizeB;
sewardj49651f42004-10-28 22:11:04 +0000192 /* Whereabouts is the stack pointer? */
193 Int offset_SP;
194 Int sizeof_SP; /* 4 or 8 */
sewardjcf787902004-11-03 09:08:33 +0000195 /* Whereabouts is the instruction pointer? */
196 Int offset_IP;
197 Int sizeof_IP; /* 4 or 8 */
sewardjeeac8412004-11-02 00:26:55 +0000198 /* Describe parts of the guest state regarded as 'always
199 defined'. */
200 Int n_alwaysDefd;
201 struct {
202 Int offset;
203 Int size;
204 } alwaysDefd[VEXGLO_N_ALWAYSDEFD];
sewardj49651f42004-10-28 22:11:04 +0000205 }
sewardjeeac8412004-11-02 00:26:55 +0000206 VexGuestLayout;
sewardj49651f42004-10-28 22:11:04 +0000207
sewardjd887b862005-01-17 18:34:34 +0000208/* A note about guest state layout.
sewardj49651f42004-10-28 22:11:04 +0000209
sewardjd887b862005-01-17 18:34:34 +0000210 LibVEX defines the layout for the guest state, in the file
211 pub/libvex_guest_<arch>.h. The struct will have an 8-aligned size.
212 Each translated bb is assumed to be entered with a specified
213 register pointing at such a struct. Beyond that is a shadow
214 state area with the same size as the struct. Beyond that is
215 a spill area that LibVEX may spill into. It must have size
216 LibVEX_N_SPILL_BYTES, and this must be a 16-aligned number.
217
218 On entry, the baseblock pointer register must be 8-aligned.
219*/
220
sewardj84a2c382005-05-03 09:08:23 +0000221#define LibVEX_N_SPILL_BYTES 1024
sewardjd887b862005-01-17 18:34:34 +0000222
223
224/*-------------------------------------------------------*/
225/*--- Initialisation of the library ---*/
226/*-------------------------------------------------------*/
227
228/* Initialise the library. You must call this first. */
229
230extern void LibVEX_Init (
231 /* failure exit function */
232 __attribute__ ((noreturn))
233 void (*failure_exit) ( void ),
234 /* logging output function */
sewardj58277842005-02-07 03:11:17 +0000235 void (*log_bytes) ( HChar*, Int nbytes ),
sewardjd887b862005-01-17 18:34:34 +0000236 /* debug paranoia level */
237 Int debuglevel,
238 /* Are we supporting valgrind checking? */
239 Bool valgrind_support,
240 /* Control ... */
241 /*READONLY*/VexControl* vcon
242);
243
244
245/*-------------------------------------------------------*/
246/*--- Make a translation ---*/
247/*-------------------------------------------------------*/
sewardjac9af022004-07-05 01:15:34 +0000248
sewardj72c72812005-01-19 11:49:45 +0000249/* Describes the outcome of a translation attempt. */
sewardjac9af022004-07-05 01:15:34 +0000250typedef
sewardjd887b862005-01-17 18:34:34 +0000251 enum {
252 VexTransOK,
253 VexTransAccessFail,
254 VexTransOutputFull
255 }
256 VexTranslateResult;
sewardjac9af022004-07-05 01:15:34 +0000257
sewardj72c72812005-01-19 11:49:45 +0000258
259/* Describes precisely the pieces of guest code that a translation
260 covers. Now that Vex can chase across BB boundaries, the old
261 scheme of describing a chunk of guest code merely by its start
262 address and length is inadequate.
263
264 Hopefully this struct is only 32 bytes long. Space is important as
265 clients will have to store one of these for each translation made.
266*/
267typedef
268 struct {
269 Addr64 base[3];
270 UShort len[3];
271 UShort n_used;
272 }
273 VexGuestExtents;
274
275
sewardjac9af022004-07-05 01:15:34 +0000276extern
sewardjd887b862005-01-17 18:34:34 +0000277VexTranslateResult LibVEX_Translate (
sewardjac9af022004-07-05 01:15:34 +0000278 /* The instruction sets we are translating from and to. */
sewardj27e1dd62005-06-30 11:49:14 +0000279 VexArch arch_guest,
280 VexArchInfo* archinfo_guest,
281 VexArch arch_host,
282 VexArchInfo* archinfo_host,
sewardjac9af022004-07-05 01:15:34 +0000283 /* IN: the block to translate, and its guest address. */
sewardjbef170b2004-12-21 01:23:00 +0000284 UChar* guest_bytes,
285 Addr64 guest_bytes_addr,
286 Bool (*chase_into_ok) ( Addr64 ),
sewardj72c72812005-01-19 11:49:45 +0000287 /* OUT: which bits of guest code actually got translated */
288 VexGuestExtents* guest_extents,
sewardjac9af022004-07-05 01:15:34 +0000289 /* IN: a place to put the resulting code, and its size */
sewardjbef170b2004-12-21 01:23:00 +0000290 UChar* host_bytes,
291 Int host_bytes_size,
sewardjac9af022004-07-05 01:15:34 +0000292 /* OUT: how much of the output area is used. */
sewardjbef170b2004-12-21 01:23:00 +0000293 Int* host_bytes_used,
sewardj49651f42004-10-28 22:11:04 +0000294 /* IN: optionally, two instrumentation functions. */
sewardj918c8f32005-03-21 00:54:33 +0000295 IRBB* (*instrument1) ( IRBB*, VexGuestLayout*,
296 IRType gWordTy, IRType hWordTy ),
297 IRBB* (*instrument2) ( IRBB*, VexGuestLayout*,
298 IRType gWordTy, IRType hWordTy ),
sewardjbef170b2004-12-21 01:23:00 +0000299 Bool cleanup_after_instrumentation,
sewardjec3c8852005-07-07 09:56:24 +0000300 /* IN: should this translation be self-checking? */
301 Bool do_self_check,
sewardjac9af022004-07-05 01:15:34 +0000302 /* IN: optionally, an access check function for guest code. */
sewardjbef170b2004-12-21 01:23:00 +0000303 Bool (*byte_accessible) ( Addr64 ),
sewardjf48ac192004-10-29 00:41:29 +0000304 /* IN: debug: trace vex activity at various points */
sewardjbef170b2004-12-21 01:23:00 +0000305 Int traceflags
sewardjac9af022004-07-05 01:15:34 +0000306);
307
sewardjc24824a2005-07-07 13:52:03 +0000308/* A subtlety re interaction between self-checking translations and
309 bb-chasing. The supplied chase_into_ok function should say NO
310 (False) when presented with any address for which you might want to
311 make a self-checking translation.
312
313 If it doesn't do that, you may end up with Vex chasing from BB #1
314 to BB #2 (fine); but if you wanted checking for #2 and not #1, that
315 would not be the result. Therefore chase_into_ok should disallow
316 following into #2. That will force the caller to eventually
317 request a new translation starting at #2, at which point Vex will
318 correctly observe the make-a-self-check flag. */
319
sewardjac9af022004-07-05 01:15:34 +0000320
sewardjd887b862005-01-17 18:34:34 +0000321/*-------------------------------------------------------*/
322/*--- Show accumulated statistics ---*/
323/*-------------------------------------------------------*/
sewardjac9af022004-07-05 01:15:34 +0000324
sewardj887a11a2004-07-05 17:26:47 +0000325extern void LibVEX_ShowStats ( void );
sewardjac9af022004-07-05 01:15:34 +0000326
327
sewardjd887b862005-01-17 18:34:34 +0000328/*-------------------------------------------------------*/
329/*--- Notes ---*/
330/*-------------------------------------------------------*/
sewardj812a8582005-01-13 16:33:19 +0000331
332/* Code generation conventions that need to be recorded somewhere.
333 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
334
335 x86
336 ~~~
337 Generated code should be entered using a CALL instruction. On
338 entry, %ebp should point to the guest state, and %esp should be a
339 valid stack pointer. The generated code may change %eax, %ebx,
340 %ecx, %edx, %esi, %edi, all the FP registers and control state, and
341 all the XMM registers.
342
sewardj6915b972005-01-13 16:36:42 +0000343 On entry, the FPU control word should be set to 0x027F, and the SSE
sewardj812a8582005-01-13 16:33:19 +0000344 control word (%mxcsr) should be set to 0x1F80. On exit, they
345 should still have those values (after masking off the lowest 6 bits
346 of %mxcsr). If they don't, there is a bug in VEX-generated code.
347
348 Generated code returns to the scheduler using a RET instruction.
349 %eax (or %eax:%edx, if simulating a 64-bit target) will contain the
350 guest address of the next block to execute.
351
352 CRITICAL ISSUES in x86 code generation. The only known critical
353 issue is that the host FPU and SSE state is not properly saved
354 across calls to helper functions. If any helper references any
355 such state, it is likely (1) to misbehave itself, since the FP
356 stack tags will not be as expected, and (2) after returning to
357 generated code, the generated code is likely to go wrong. This
358 really should be fixed.
sewardjdb4738a2005-07-07 01:32:16 +0000359
360 ALL GUEST ARCHITECTURES
361 ~~~~~~~~~~~~~~~~~~~~~~~
362 The architecture must contain two pseudo-registers, guest_TISTART
363 and guest_TILEN. These are used to pass the address of areas of
364 guest code, translations of which are to be invalidated, back to
365 the despatcher. Both pseudo-regs must have size equal to the guest
366 word size.
sewardj812a8582005-01-13 16:33:19 +0000367*/
sewardj887a11a2004-07-05 17:26:47 +0000368#endif /* ndef __LIBVEX_H */
sewardjac9af022004-07-05 01:15:34 +0000369
370/*---------------------------------------------------------------*/
sewardj887a11a2004-07-05 17:26:47 +0000371/*--- libvex.h ---*/
sewardjac9af022004-07-05 01:15:34 +0000372/*---------------------------------------------------------------*/