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