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