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