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