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 (at) 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 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
