1
2 /*---------------------------------------------------------------*/
3 /*--- begin libvex.h ---*/
4 /*---------------------------------------------------------------*/
5
6 /*
7 This file is part of Valgrind, a dynamic binary instrumentation
8 framework.
9
10 Copyright (C) 2004-2012 OpenWorks LLP
11 info@open-works.net
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., 51 Franklin Street, Fifth Floor, Boston, MA
26 02110-1301, USA.
27
28 The GNU General Public License is contained in the file COPYING.
29
30 Neither the names of the U.S. Department of Energy nor the
31 University of California nor the names of its contributors may be
32 used to endorse or promote products derived from this software
33 without prior written permission.
34 */
35
36 #ifndef __LIBVEX_H
37 #define __LIBVEX_H
38
39
40 #include "libvex_basictypes.h"
41 #include "libvex_ir.h"
42
43
44 /*---------------------------------------------------------------*/
45 /*--- This file defines the top-level interface to LibVEX. ---*/
46 /*---------------------------------------------------------------*/
47
48 /*-------------------------------------------------------*/
49 /*--- Architectures, variants, and other arch info ---*/
50 /*-------------------------------------------------------*/
51
52 typedef
53 enum {
54 VexArch_INVALID,
55 VexArchX86,
56 VexArchAMD64,
57 VexArchARM,
58 VexArchPPC32,
59 VexArchPPC64,
60 VexArchS390X,
61 VexArchMIPS32
62 }
63 VexArch;
64
65
66 /* For a given architecture, these specify extra capabilities beyond
67 the minimum supported (baseline) capabilities. They may be OR'd
68 together, although some combinations don't make sense. (eg, SSE2
69 but not SSE1). LibVEX_Translate will check for nonsensical
70 combinations. */
71
72 /* x86: baseline capability is Pentium-1 (FPU, MMX, but no SSE), with
73 cmpxchg8b. */
74 #define VEX_HWCAPS_X86_SSE1 (1<<1) /* SSE1 support (Pentium III) */
75 #define VEX_HWCAPS_X86_SSE2 (1<<2) /* SSE2 support (Pentium 4) */
76 #define VEX_HWCAPS_X86_SSE3 (1<<3) /* SSE3 support (>= Prescott) */
77 #define VEX_HWCAPS_X86_LZCNT (1<<4) /* SSE4a LZCNT insn */
78
79 /* amd64: baseline capability is SSE2, with cmpxchg8b but not
80 cmpxchg16b. */
81 #define VEX_HWCAPS_AMD64_SSE3 (1<<5) /* SSE3 support */
82 #define VEX_HWCAPS_AMD64_CX16 (1<<6) /* cmpxchg16b support */
83 #define VEX_HWCAPS_AMD64_LZCNT (1<<7) /* SSE4a LZCNT insn */
84 #define VEX_HWCAPS_AMD64_AVX (1<<8) /* AVX instructions */
85
86 /* ppc32: baseline capability is integer only */
87 #define VEX_HWCAPS_PPC32_F (1<<8) /* basic (non-optional) FP */
88 #define VEX_HWCAPS_PPC32_V (1<<9) /* Altivec (VMX) */
89 #define VEX_HWCAPS_PPC32_FX (1<<10) /* FP extns (fsqrt, fsqrts) */
90 #define VEX_HWCAPS_PPC32_GX (1<<11) /* Graphics extns
91 (fres,frsqrte,fsel,stfiwx) */
92 #define VEX_HWCAPS_PPC32_VX (1<<12) /* Vector-scalar floating-point (VSX); implies ISA 2.06 or higher */
93 #define VEX_HWCAPS_PPC32_DFP (1<<17) /* Decimal Floating Point (DFP) -- e.g., dadd */
94
95 /* ppc64: baseline capability is integer and basic FP insns */
96 #define VEX_HWCAPS_PPC64_V (1<<13) /* Altivec (VMX) */
97 #define VEX_HWCAPS_PPC64_FX (1<<14) /* FP extns (fsqrt, fsqrts) */
98 #define VEX_HWCAPS_PPC64_GX (1<<15) /* Graphics extns
99 (fres,frsqrte,fsel,stfiwx) */
100 #define VEX_HWCAPS_PPC64_VX (1<<16) /* Vector-scalar floating-point (VSX); implies ISA 2.06 or higher */
101 #define VEX_HWCAPS_PPC64_DFP (1<<18) /* Decimal Floating Point (DFP) -- e.g., dadd */
102
103 /* s390x: Hardware capability encoding
104
105 Bits [26:31] encode the machine model (see VEX_S390X_MODEL... below)
106 Bits [0:20] encode specific hardware capabilities
107 (see VEX_HWAPS_S390X_... below)
108 */
109
110 /* Model numbers must be assigned in chronological order.
111 They are used as array index. */
112 #define VEX_S390X_MODEL_Z900 0
113 #define VEX_S390X_MODEL_Z800 1
114 #define VEX_S390X_MODEL_Z990 2
115 #define VEX_S390X_MODEL_Z890 3
116 #define VEX_S390X_MODEL_Z9_EC 4
117 #define VEX_S390X_MODEL_Z9_BC 5
118 #define VEX_S390X_MODEL_Z10_EC 6
119 #define VEX_S390X_MODEL_Z10_BC 7
120 #define VEX_S390X_MODEL_Z196 8
121 #define VEX_S390X_MODEL_Z114 9
122 #define VEX_S390X_MODEL_UNKNOWN 10 /* always last in list */
123 #define VEX_S390X_MODEL_MASK 0x3F
124
125 #define VEX_HWCAPS_S390X_LDISP (1<<6) /* Long-displacement facility */
126 #define VEX_HWCAPS_S390X_EIMM (1<<7) /* Extended-immediate facility */
127 #define VEX_HWCAPS_S390X_GIE (1<<8) /* General-instruction-extension facility */
128 #define VEX_HWCAPS_S390X_DFP (1<<9) /* Decimal floating point facility */
129 #define VEX_HWCAPS_S390X_FGX (1<<10) /* FPR-GR transfer facility */
130 #define VEX_HWCAPS_S390X_ETF2 (1<<11) /* ETF2-enhancement facility */
131 #define VEX_HWCAPS_S390X_STFLE (1<<12) /* STFLE facility */
132 #define VEX_HWCAPS_S390X_ETF3 (1<<13) /* ETF3-enhancement facility */
133
134 /* Special value representing all available s390x hwcaps */
135 #define VEX_HWCAPS_S390X_ALL (VEX_HWCAPS_S390X_LDISP | \
136 VEX_HWCAPS_S390X_EIMM | \
137 VEX_HWCAPS_S390X_GIE | \
138 VEX_HWCAPS_S390X_DFP | \
139 VEX_HWCAPS_S390X_FGX | \
140 VEX_HWCAPS_S390X_STFLE | \
141 VEX_HWCAPS_S390X_ETF3 | \
142 VEX_HWCAPS_S390X_ETF2)
143
144 #define VEX_HWCAPS_S390X(x) ((x) & ~VEX_S390X_MODEL_MASK)
145 #define VEX_S390X_MODEL(x) ((x) & VEX_S390X_MODEL_MASK)
146
147 /* arm: baseline capability is ARMv4 */
148 /* Bits 5:0 - architecture level (e.g. 5 for v5, 6 for v6 etc) */
149 #define VEX_HWCAPS_ARM_VFP (1<<6) /* VFP extension */
150 #define VEX_HWCAPS_ARM_VFP2 (1<<7) /* VFPv2 */
151 #define VEX_HWCAPS_ARM_VFP3 (1<<8) /* VFPv3 */
152 /* Bits 15:10 reserved for (possible) future VFP revisions */
153 #define VEX_HWCAPS_ARM_NEON (1<<16) /* Advanced SIMD also known as NEON */
154
155 /* Get an ARM architecure level from HWCAPS */
156 #define VEX_ARM_ARCHLEVEL(x) ((x) & 0x3f)
157
158 /* MIPS baseline capability */
159 /* Assigned Company values for bits 23:16 of the PRId Register
160 (CP0 register 15, select 0). As of the MIPS32 and MIPS64 specs from
161 MTI, the PRId register is defined in this (backwards compatible)
162 way:
163
164 +----------------+----------------+----------------+----------------+
165 | Company Options| Company ID | Processor ID | Revision |
166 +----------------+----------------+----------------+----------------+
167 31 24 23 16 15 8 7
168
169 */
170
171 #define VEX_PRID_COMP_MIPS 0x00010000
172 #define VEX_PRID_COMP_BROADCOM 0x00020000
173
174 /* These return statically allocated strings. */
175
176 extern const HChar* LibVEX_ppVexArch ( VexArch );
177 extern const HChar* LibVEX_ppVexHwCaps ( VexArch, UInt );
178
179
180 /* This struct is a bit of a hack, but is needed to carry misc
181 important bits of info about an arch. Fields which are meaningless
182 or ignored for the platform in question should be set to zero. */
183
184 typedef
185 struct {
186 /* This is the only mandatory field. */
187 UInt hwcaps;
188 /* PPC32/PPC64 only: size of cache line */
189 Int ppc_cache_line_szB;
190 /* PPC32/PPC64 only: sizes zeroed by the dcbz/dcbzl instructions
191 * (bug#135264) */
192 UInt ppc_dcbz_szB;
193 UInt ppc_dcbzl_szB; /* 0 means unsupported (SIGILL) */
194 }
195 VexArchInfo;
196
197 /* Write default settings info *vai. */
198 extern
199 void LibVEX_default_VexArchInfo ( /*OUT*/VexArchInfo* vai );
200
201
202 /* This struct carries guest and host ABI variant information that may
203 be needed. Fields which are meaningless or ignored for the
204 platform in question should be set to zero.
205
206 Settings which are believed to be correct are:
207
208 guest_stack_redzone_size
209 guest is ppc32-linux ==> 0
210 guest is ppc64-linux ==> 288
211 guest is ppc32-aix5 ==> 220
212 guest is ppc64-aix5 ==> unknown
213 guest is amd64-linux ==> 128
214 guest is other ==> inapplicable
215
216 guest_amd64_assume_fs_is_zero
217 guest is amd64-linux ==> True
218 guest is amd64-darwin ==> False
219 guest is other ==> inapplicable
220
221 guest_amd64_assume_gs_is_0x60
222 guest is amd64-darwin ==> True
223 guest is amd64-linux ==> False
224 guest is other ==> inapplicable
225
226 guest_ppc_zap_RZ_at_blr
227 guest is ppc64-linux ==> True
228 guest is ppc32-linux ==> False
229 guest is ppc64-aix5 ==> unknown
230 guest is ppc32-aix5 ==> False
231 guest is other ==> inapplicable
232
233 guest_ppc_zap_RZ_at_bl
234 guest is ppc64-linux ==> const True
235 guest is ppc32-linux ==> const False
236 guest is ppc64-aix5 ==> unknown
237 guest is ppc32-aix5 ==> True except for calls to
238 millicode, $SAVEFn, $RESTFn
239 guest is other ==> inapplicable
240
241 guest_ppc_sc_continues_at_LR:
242 guest is ppc32-aix5 or ppc64-aix5 ==> True
243 guest is ppc32-linux or ppc64-linux ==> False
244 guest is other ==> inapplicable
245
246 host_ppc_calls_use_fndescrs:
247 host is ppc32-linux ==> False
248 host is ppc64-linux ==> True
249 host is ppc32-aix5 or ppc64-aix5 ==> True
250 host is other ==> inapplicable
251
252 host_ppc32_regalign_int64_args:
253 host is ppc32-linux ==> True
254 host is ppc32-aix5 ==> False
255 host is other ==> inapplicable
256 */
257
258 typedef
259 struct {
260 /* PPC and AMD64 GUESTS only: how many bytes below the
261 stack pointer are validly addressible? */
262 Int guest_stack_redzone_size;
263
264 /* AMD64 GUESTS only: should we translate %fs-prefixed
265 instructions using the assumption that %fs always contains
266 zero? */
267 Bool guest_amd64_assume_fs_is_zero;
268
269 /* AMD64 GUESTS only: should we translate %gs-prefixed
270 instructions using the assumption that %gs always contains
271 0x60? */
272 Bool guest_amd64_assume_gs_is_0x60;
273
274 /* PPC GUESTS only: should we zap the stack red zone at a 'blr'
275 (function return) ? */
276 Bool guest_ppc_zap_RZ_at_blr;
277
278 /* PPC GUESTS only: should we zap the stack red zone at a 'bl'
279 (function call) ? Is supplied with the guest address of the
280 target of the call since that may be significant. If NULL,
281 is assumed equivalent to a fn which always returns False. */
282 Bool (*guest_ppc_zap_RZ_at_bl)(Addr64);
283
284 /* PPC32/PPC64 GUESTS only: where does the kernel resume after
285 'sc'? False => Linux style, at the next insn. True => AIX
286 style, at the address stated in the link register. */
287 Bool guest_ppc_sc_continues_at_LR;
288
289 /* PPC32/PPC64 HOSTS only: does '&f' give us a pointer to a
290 function descriptor on the host, or to the function code
291 itself? True => descriptor, False => code. */
292 Bool host_ppc_calls_use_fndescrs;
293
294 /* PPC32 HOSTS only: when generating code to pass a 64-bit value
295 (actual parameter) in a pair of regs, should we skip an arg
296 reg if it is even-numbered? True => yes, False => no. */
297 Bool host_ppc32_regalign_int64_args;
298 }
299 VexAbiInfo;
300
301 /* Write default settings info *vbi. */
302 extern
303 void LibVEX_default_VexAbiInfo ( /*OUT*/VexAbiInfo* vbi );
304
305
306 /*-------------------------------------------------------*/
307 /*--- Control of Vex's optimiser (iropt). ---*/
308 /*-------------------------------------------------------*/
309
310
311 /* VexRegisterUpdates specifies when to ensure that the guest state is
312 up to date.
313
314 VexRegUpdUnwindregsAtMemAccess : registers needed to make a stack trace are
315 up to date at memory exception points. Typically, these are PC/SP/FP. The
316 minimal registers are described by the arch specific functions
317 guest_<arch>_state_requires_precise_mem_exns.
318
319 VexRegUpdAllregsAtMemAccess : all registers up to date at memory exception
320 points.
321
322 VexRegUpdAllregsAtEachInsn : all registers up to date at each instruction. */
323 typedef enum { VexRegUpdUnwindregsAtMemAccess,
324 VexRegUpdAllregsAtMemAccess,
325 VexRegUpdAllregsAtEachInsn } VexRegisterUpdates;
326
327 /* Control of Vex's optimiser. */
328
329 typedef
330 struct {
331 /* Controls verbosity of iropt. 0 = no output. */
332 Int iropt_verbosity;
333 /* Control aggressiveness of iropt. 0 = no opt, 1 = simple
334 opts, 2 (default) = max optimisation. */
335 Int iropt_level;
336 /* Controls when registers are updated in guest state. */
337 VexRegisterUpdates iropt_register_updates;
338 /* How aggressive should iropt be in unrolling loops? Higher
339 numbers make it more enthusiastic about loop unrolling.
340 Default=120. A setting of zero disables unrolling. */
341 Int iropt_unroll_thresh;
342 /* What's the maximum basic block length the front end(s) allow?
343 BBs longer than this are split up. Default=50 (guest
344 insns). */
345 Int guest_max_insns;
346 /* How aggressive should front ends be in following
347 unconditional branches to known destinations? Default=10,
348 meaning that if a block contains less than 10 guest insns so
349 far, the front end(s) will attempt to chase into its
350 successor. A setting of zero disables chasing. */
351 Int guest_chase_thresh;
352 /* EXPERIMENTAL: chase across conditional branches? Not all
353 front ends honour this. Default: NO. */
354 Bool guest_chase_cond;
355 }
356 VexControl;
357
358
359 /* Write the default settings into *vcon. */
360
361 extern
362 void LibVEX_default_VexControl ( /*OUT*/ VexControl* vcon );
363
364
365 /*-------------------------------------------------------*/
366 /*--- Storage management control ---*/
367 /*-------------------------------------------------------*/
368
369 /* Allocate in Vex's temporary allocation area. Be careful with this.
370 You can only call it inside an instrumentation or optimisation
371 callback that you have previously specified in a call to
372 LibVEX_Translate. The storage allocated will only stay alive until
373 translation of the current basic block is complete.
374 */
375 extern HChar* private_LibVEX_alloc_first;
376 extern HChar* private_LibVEX_alloc_curr;
377 extern HChar* private_LibVEX_alloc_last;
378 extern void private_LibVEX_alloc_OOM(void) __attribute__((noreturn));
379
LibVEX_Alloc(Int nbytes)380 static inline void* LibVEX_Alloc ( Int nbytes )
381 {
382 struct align {
383 char c;
384 union {
385 char c;
386 short s;
387 int i;
388 long l;
389 long long ll;
390 float f;
391 double d;
392 /* long double is currently not used and would increase alignment
393 unnecessarily. */
394 /* long double ld; */
395 void *pto;
396 void (*ptf)(void);
397 } x;
398 };
399
400 #if 0
401 /* Nasty debugging hack, do not use. */
402 return malloc(nbytes);
403 #else
404 HChar* curr;
405 HChar* next;
406 Int ALIGN;
407 ALIGN = offsetof(struct align,x) - 1;
408 nbytes = (nbytes + ALIGN) & ~ALIGN;
409 curr = private_LibVEX_alloc_curr;
410 next = curr + nbytes;
411 if (next >= private_LibVEX_alloc_last)
412 private_LibVEX_alloc_OOM();
413 private_LibVEX_alloc_curr = next;
414 return curr;
415 #endif
416 }
417
418 /* Show Vex allocation statistics. */
419 extern void LibVEX_ShowAllocStats ( void );
420
421
422 /*-------------------------------------------------------*/
423 /*--- Describing guest state layout ---*/
424 /*-------------------------------------------------------*/
425
426 /* Describe the guest state enough that the instrumentation
427 functions can work. */
428
429 /* The max number of guest state chunks which we can describe as
430 always defined (for the benefit of Memcheck). */
431 #define VEXGLO_N_ALWAYSDEFD 24
432
433 typedef
434 struct {
435 /* Total size of the guest state, in bytes. Must be
436 8-aligned. */
437 Int total_sizeB;
438 /* Whereabouts is the stack pointer? */
439 Int offset_SP;
440 Int sizeof_SP; /* 4 or 8 */
441 /* Whereabouts is the frame pointer? */
442 Int offset_FP;
443 Int sizeof_FP; /* 4 or 8 */
444 /* Whereabouts is the instruction pointer? */
445 Int offset_IP;
446 Int sizeof_IP; /* 4 or 8 */
447 /* Describe parts of the guest state regarded as 'always
448 defined'. */
449 Int n_alwaysDefd;
450 struct {
451 Int offset;
452 Int size;
453 } alwaysDefd[VEXGLO_N_ALWAYSDEFD];
454 }
455 VexGuestLayout;
456
457 /* A note about guest state layout.
458
459 LibVEX defines the layout for the guest state, in the file
460 pub/libvex_guest_<arch>.h. The struct will have an 16-aligned
461 size. Each translated bb is assumed to be entered with a specified
462 register pointing at such a struct. Beyond that is two copies of
463 the shadow state area with the same size as the struct. Beyond
464 that is a spill area that LibVEX may spill into. It must have size
465 LibVEX_N_SPILL_BYTES, and this must be a 16-aligned number.
466
467 On entry, the baseblock pointer register must be 16-aligned.
468
469 There must be no holes in between the primary guest state, its two
470 copies, and the spill area. In short, all 4 areas must have a
471 16-aligned size and be 16-aligned, and placed back-to-back.
472 */
473
474 #define LibVEX_N_SPILL_BYTES 4096
475
476
477 /*-------------------------------------------------------*/
478 /*--- Initialisation of the library ---*/
479 /*-------------------------------------------------------*/
480
481 /* Initialise the library. You must call this first. */
482
483 extern void LibVEX_Init (
484
485 /* failure exit function */
486 # if __cplusplus == 1 && __GNUC__ && __GNUC__ <= 3
487 /* g++ 3.x doesn't understand attributes on function parameters.
488 See #265762. */
489 # else
490 __attribute__ ((noreturn))
491 # endif
492 void (*failure_exit) ( void ),
493
494 /* logging output function */
495 void (*log_bytes) ( HChar*, Int nbytes ),
496
497 /* debug paranoia level */
498 Int debuglevel,
499
500 /* Are we supporting valgrind checking? */
501 Bool valgrind_support,
502
503 /* Control ... */
504 /*READONLY*/VexControl* vcon
505 );
506
507
508 /*-------------------------------------------------------*/
509 /*--- Make a translation ---*/
510 /*-------------------------------------------------------*/
511
512 /* Describes the outcome of a translation attempt. */
513 typedef
514 struct {
515 /* overall status */
516 enum { VexTransOK,
517 VexTransAccessFail, VexTransOutputFull } status;
518 /* The number of extents that have a self-check (0 to 3) */
519 UInt n_sc_extents;
520 /* Offset in generated code of the profile inc, or -1 if
521 none. Needed for later patching. */
522 Int offs_profInc;
523 /* Stats only: the number of guest insns included in the
524 translation. It may be zero (!). */
525 UInt n_guest_instrs;
526 }
527 VexTranslateResult;
528
529
530 /* Describes precisely the pieces of guest code that a translation
531 covers. Now that Vex can chase across BB boundaries, the old
532 scheme of describing a chunk of guest code merely by its start
533 address and length is inadequate.
534
535 Hopefully this struct is only 32 bytes long. Space is important as
536 clients will have to store one of these for each translation made.
537 */
538 typedef
539 struct {
540 Addr64 base[3];
541 UShort len[3];
542 UShort n_used;
543 }
544 VexGuestExtents;
545
546
547 /* A structure to carry arguments for LibVEX_Translate. There are so
548 many of them, it seems better to have a structure. */
549 typedef
550 struct {
551 /* IN: The instruction sets we are translating from and to. And
552 guest/host misc info. */
553 VexArch arch_guest;
554 VexArchInfo archinfo_guest;
555 VexArch arch_host;
556 VexArchInfo archinfo_host;
557 VexAbiInfo abiinfo_both;
558
559 /* IN: an opaque value which is passed as the first arg to all
560 callback functions supplied in this struct. Vex has no idea
561 what's at the other end of this pointer. */
562 void* callback_opaque;
563
564 /* IN: the block to translate, and its guest address. */
565 /* where are the actual bytes in the host's address space? */
566 UChar* guest_bytes;
567 /* where do the bytes really come from in the guest's aspace?
568 This is the post-redirection guest address. Not that Vex
569 understands anything about redirection; that is all done on
570 the Valgrind side. */
571 Addr64 guest_bytes_addr;
572
573 /* Is it OK to chase into this guest address? May not be
574 NULL. */
575 Bool (*chase_into_ok) ( /*callback_opaque*/void*, Addr64 );
576
577 /* OUT: which bits of guest code actually got translated */
578 VexGuestExtents* guest_extents;
579
580 /* IN: a place to put the resulting code, and its size */
581 UChar* host_bytes;
582 Int host_bytes_size;
583 /* OUT: how much of the output area is used. */
584 Int* host_bytes_used;
585
586 /* IN: optionally, two instrumentation functions. May be
587 NULL. */
588 IRSB* (*instrument1) ( /*callback_opaque*/void*,
589 IRSB*,
590 VexGuestLayout*,
591 VexGuestExtents*,
592 IRType gWordTy, IRType hWordTy );
593 IRSB* (*instrument2) ( /*callback_opaque*/void*,
594 IRSB*,
595 VexGuestLayout*,
596 VexGuestExtents*,
597 IRType gWordTy, IRType hWordTy );
598
599 IRSB* (*finaltidy) ( IRSB* );
600
601 /* IN: a callback used to ask the caller which of the extents,
602 if any, a self check is required for. Must not be NULL.
603 The returned value is a bitmask with a 1 in position i indicating
604 that the i'th extent needs a check. Since there can be at most
605 3 extents, the returned values must be between 0 and 7. */
606 UInt (*needs_self_check)( /*callback_opaque*/void*,
607 VexGuestExtents* );
608
609 /* IN: optionally, a callback which allows the caller to add its
610 own IR preamble following the self-check and any other
611 VEX-generated preamble, if any. May be NULL. If non-NULL,
612 the IRSB under construction is handed to this function, which
613 presumably adds IR statements to it. The callback may
614 optionally complete the block and direct bb_to_IR not to
615 disassemble any instructions into it; this is indicated by
616 the callback returning True.
617 */
618 Bool (*preamble_function)(/*callback_opaque*/void*, IRSB*);
619
620 /* IN: debug: trace vex activity at various points */
621 Int traceflags;
622
623 /* IN: profiling: add a 64 bit profiler counter increment to the
624 translation? */
625 Bool addProfInc;
626
627 /* IN: address of the dispatcher entry points. Describes the
628 places where generated code should jump to at the end of each
629 bb.
630
631 At the end of each translation, the next guest address is
632 placed in the host's standard return register (x86: %eax,
633 amd64: %rax, ppc32: %r3, ppc64: %r3). Optionally, the guest
634 state pointer register (on host x86: %ebp; amd64: %rbp;
635 ppc32/64: r31) may be set to a VEX_TRC_ value to indicate any
636 special action required before the next block is run.
637
638 Control is then passed back to the dispatcher (beyond Vex's
639 control; caller supplies this) in the following way:
640
641 - On host archs which lack a link register (x86, amd64), by a
642 jump to the host address specified in
643 'dispatcher_assisted', if the guest state pointer has been
644 changed so as to request some action before the next block
645 is run, or 'dispatcher_unassisted' (the fast path), in
646 which it is assumed that the guest state pointer is
647 unchanged and we wish to continue directly with the next
648 translation. Both of these must be non-NULL.
649
650 - On host archs which have a link register (ppc32, ppc64), by
651 a branch to the link register (which is guaranteed to be
652 unchanged from whatever it was at entry to the
653 translation). 'dispatch_assisted' and
654 'dispatch_unassisted' must be NULL.
655
656 The aim is to get back and forth between translations and the
657 dispatcher without creating memory traffic to store return
658 addresses.
659
660 FIXME: update this comment
661 */
662 void* disp_cp_chain_me_to_slowEP;
663 void* disp_cp_chain_me_to_fastEP;
664 void* disp_cp_xindir;
665 void* disp_cp_xassisted;
666 }
667 VexTranslateArgs;
668
669
670 extern
671 VexTranslateResult LibVEX_Translate ( VexTranslateArgs* );
672
673 /* A subtlety re interaction between self-checking translations and
674 bb-chasing. The supplied chase_into_ok function should say NO
675 (False) when presented with any address for which you might want to
676 make a self-checking translation.
677
678 If it doesn't do that, you may end up with Vex chasing from BB #1
679 to BB #2 (fine); but if you wanted checking for #2 and not #1, that
680 would not be the result. Therefore chase_into_ok should disallow
681 following into #2. That will force the caller to eventually
682 request a new translation starting at #2, at which point Vex will
683 correctly observe the make-a-self-check flag.
684
685 FIXME: is this still up to date? */
686
687
688 /*-------------------------------------------------------*/
689 /*--- Patch existing translations ---*/
690 /*-------------------------------------------------------*/
691
692 /* Indicates a host address range for which callers to the functions
693 below must request I-D cache syncing after the call. ::len == 0 is
694 ambiguous -- it could mean either zero bytes or the entire address
695 space, so we mean the former. */
696 typedef
697 struct {
698 HWord start;
699 HWord len;
700 }
701 VexInvalRange;
702
703 /* Chain an XDirect jump located at place_to_chain so it jumps to
704 place_to_jump_to. It is expected (and checked) that this site
705 currently contains a call to the dispatcher specified by
706 disp_cp_chain_me_EXPECTED. */
707 extern
708 VexInvalRange LibVEX_Chain ( VexArch arch_host,
709 void* place_to_chain,
710 void* disp_cp_chain_me_EXPECTED,
711 void* place_to_jump_to );
712
713 /* Undo an XDirect jump located at place_to_unchain, so it is
714 converted back into a call to disp_cp_chain_me. It is expected
715 (and checked) that this site currently contains a jump directly to
716 the address specified by place_to_jump_to_EXPECTED. */
717 extern
718 VexInvalRange LibVEX_UnChain ( VexArch arch_host,
719 void* place_to_unchain,
720 void* place_to_jump_to_EXPECTED,
721 void* disp_cp_chain_me );
722
723 /* Returns a constant -- the size of the event check that is put at
724 the start of every translation. This makes it possible to
725 calculate the fast entry point address if the slow entry point
726 address is known (the usual case), or vice versa. */
727 extern
728 Int LibVEX_evCheckSzB ( VexArch arch_host );
729
730
731 /* Patch the counter location into an existing ProfInc point. The
732 specified point is checked to make sure it is plausible. */
733 extern
734 VexInvalRange LibVEX_PatchProfInc ( VexArch arch_host,
735 void* place_to_patch,
736 ULong* location_of_counter );
737
738
739 /*-------------------------------------------------------*/
740 /*--- Show accumulated statistics ---*/
741 /*-------------------------------------------------------*/
742
743 extern void LibVEX_ShowStats ( void );
744
745
746 /*-------------------------------------------------------*/
747 /*--- Notes ---*/
748 /*-------------------------------------------------------*/
749
750 /* Code generation conventions that need to be recorded somewhere.
751 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
752
753 x86
754 ~~~
755 Generated code should be entered using a JMP instruction. On
756 entry, %ebp should point to the guest state, and %esp should be a
757 valid stack pointer. The generated code may change %eax, %ebx,
758 %ecx, %edx, %esi, %edi, all the FP registers and control state, and
759 all the XMM registers.
760
761 On entry, the FPU control word should be set to 0x027F, and the SSE
762 control word (%mxcsr) should be set to 0x1F80. On exit, they
763 should still have those values (after masking off the lowest 6 bits
764 of %mxcsr). If they don't, there is a bug in VEX-generated code.
765
766 Generated code returns to the scheduler using a JMP instruction, to
767 the address specified in the .dispatch field of VexTranslateArgs.
768 %eax (or %eax:%edx, if simulating a 64-bit target) will contain the
769 guest address of the next block to execute. %ebp may be changed
770 to a VEX_TRC_ value, otherwise it should be as it was at entry.
771
772 CRITICAL ISSUES in x86 code generation. The only known critical
773 issue is that the host FPU and SSE state is not properly saved
774 across calls to helper functions. If any helper references any
775 such state, it is likely (1) to misbehave itself, since the FP
776 stack tags will not be as expected, and (2) after returning to
777 generated code, the generated code is likely to go wrong. This
778 really should be fixed.
779
780 amd64
781 ~~~~~
782 Analogous to x86.
783
784 ppc32
785 ~~~~~
786 On entry, guest state pointer is r31. .dispatch must be NULL.
787 Control is returned with a branch to the link register. Generated
788 code will not change lr. At return, r3 holds the next guest addr
789 (or r3:r4 ?). r31 may be may be changed to a VEX_TRC_ value,
790 otherwise it should be as it was at entry.
791
792 ppc64
793 ~~~~~
794 Same as ppc32.
795
796 ALL GUEST ARCHITECTURES
797 ~~~~~~~~~~~~~~~~~~~~~~~
798 The guest state must contain two pseudo-registers, guest_TISTART
799 and guest_TILEN. These are used to pass the address of areas of
800 guest code, translations of which are to be invalidated, back to
801 the despatcher. Both pseudo-regs must have size equal to the guest
802 word size.
803
804 The architecture must a third pseudo-register, guest_NRADDR, also
805 guest-word-sized. This is used to record the unredirected guest
806 address at the start of a translation whose start has been
807 redirected. By reading this pseudo-register shortly afterwards,
808 the translation can find out what the corresponding no-redirection
809 address was. Note, this is only set for wrap-style redirects, not
810 for replace-style ones.
811 */
812 #endif /* ndef __LIBVEX_H */
813
814 /*---------------------------------------------------------------*/
815 /*--- libvex.h ---*/
816 /*---------------------------------------------------------------*/
817