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 (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 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 amd64-solaris ==> True 328 guest is other ==> inapplicable 329 330 guest_amd64_assume_gs_is_const 331 guest is amd64-darwin ==> True 332 guest is amd64-linux ==> True 333 guest is amd64-solaris ==> False 334 guest is other ==> inapplicable 335 336 guest_ppc_zap_RZ_at_blr 337 guest is ppc64-linux ==> True 338 guest is ppc32-linux ==> False 339 guest is other ==> inapplicable 340 341 guest_ppc_zap_RZ_at_bl 342 guest is ppc64-linux ==> const True 343 guest is ppc32-linux ==> const False 344 guest is other ==> inapplicable 345 346 host_ppc_calls_use_fndescrs: 347 host is ppc32-linux ==> False 348 host is ppc64-linux ==> True 349 host is other ==> inapplicable 350 */ 351 352 typedef 353 struct { 354 /* PPC and AMD64 GUESTS only: how many bytes below the 355 stack pointer are validly addressible? */ 356 Int guest_stack_redzone_size; 357 358 /* AMD64 GUESTS only: should we translate %fs-prefixed 359 instructions using the assumption that %fs always contains 360 the same value? (typically zero on linux and solaris) */ 361 Bool guest_amd64_assume_fs_is_const; 362 363 /* AMD64 GUESTS only: should we translate %gs-prefixed 364 instructions using the assumption that %gs always contains 365 the same value? (typically 0x60 on darwin)? */ 366 Bool guest_amd64_assume_gs_is_const; 367 368 /* PPC GUESTS only: should we zap the stack red zone at a 'blr' 369 (function return) ? */ 370 Bool guest_ppc_zap_RZ_at_blr; 371 372 /* PPC GUESTS only: should we zap the stack red zone at a 'bl' 373 (function call) ? Is supplied with the guest address of the 374 target of the call since that may be significant. If NULL, 375 is assumed equivalent to a fn which always returns False. */ 376 Bool (*guest_ppc_zap_RZ_at_bl)(Addr); 377 378 /* PPC32/PPC64 HOSTS only: does '&f' give us a pointer to a 379 function descriptor on the host, or to the function code 380 itself? True => descriptor, False => code. */ 381 Bool host_ppc_calls_use_fndescrs; 382 } 383 VexAbiInfo; 384 385 /* Write default settings info *vbi. */ 386 extern 387 void LibVEX_default_VexAbiInfo ( /*OUT*/VexAbiInfo* vbi ); 388 389 390 /*-------------------------------------------------------*/ 391 /*--- Control of Vex's optimiser (iropt). ---*/ 392 /*-------------------------------------------------------*/ 393 394 395 /* VexRegisterUpdates specifies when to ensure that the guest state is 396 up to date, in order of increasing accuracy but increasing expense. 397 398 VexRegUpdSpAtMemAccess: all registers are updated at superblock 399 exits, and SP is also up to date at memory exception points. The 400 SP is described by the arch specific functions 401 guest_<arch>_state_requires_precise_mem_exns. 402 403 VexRegUpdUnwindregsAtMemAccess: registers needed to make a stack 404 trace are up to date at memory exception points. Typically, 405 these are PC/SP/FP. The minimal registers are described by the 406 arch specific functions guest_<arch>_state_requires_precise_mem_exns. 407 This is what Valgrind sets as the default. 408 409 VexRegUpdAllregsAtMemAccess: all registers up to date at memory 410 exception points. This is what normally might be considered as 411 providing "precise exceptions for memory", but does not 412 necessarily provide precise register values at any other kind of 413 exception. 414 415 VexRegUpdAllregsAtEachInsn: all registers up to date at each 416 instruction. 417 */ 418 typedef 419 enum { 420 VexRegUpd_INVALID=0x700, 421 VexRegUpdSpAtMemAccess, 422 VexRegUpdUnwindregsAtMemAccess, 423 VexRegUpdAllregsAtMemAccess, 424 VexRegUpdAllregsAtEachInsn 425 } 426 VexRegisterUpdates; 427 428 /* Control of Vex's optimiser. */ 429 430 typedef 431 struct { 432 /* Controls verbosity of iropt. 0 = no output. */ 433 Int iropt_verbosity; 434 /* Control aggressiveness of iropt. 0 = no opt, 1 = simple 435 opts, 2 (default) = max optimisation. */ 436 Int iropt_level; 437 /* Controls when registers are updated in guest state. Note 438 that this is the default value. The VEX client can override 439 this on a per-IRSB basis if it wants. bb_to_IR() will query 440 the client to ask if it wants a different setting for the 441 block under construction, and that new setting is transported 442 back to LibVEX_Translate, which feeds it to iropt via the 443 various do_iropt_BB calls. */ 444 VexRegisterUpdates iropt_register_updates_default; 445 /* How aggressive should iropt be in unrolling loops? Higher 446 numbers make it more enthusiastic about loop unrolling. 447 Default=120. A setting of zero disables unrolling. */ 448 Int iropt_unroll_thresh; 449 /* What's the maximum basic block length the front end(s) allow? 450 BBs longer than this are split up. Default=50 (guest 451 insns). */ 452 Int guest_max_insns; 453 /* How aggressive should front ends be in following 454 unconditional branches to known destinations? Default=10, 455 meaning that if a block contains less than 10 guest insns so 456 far, the front end(s) will attempt to chase into its 457 successor. A setting of zero disables chasing. */ 458 Int guest_chase_thresh; 459 /* EXPERIMENTAL: chase across conditional branches? Not all 460 front ends honour this. Default: NO. */ 461 Bool guest_chase_cond; 462 } 463 VexControl; 464 465 466 /* Write the default settings into *vcon. */ 467 468 extern 469 void LibVEX_default_VexControl ( /*OUT*/ VexControl* vcon ); 470 471 472 /*-------------------------------------------------------*/ 473 /*--- Storage management control ---*/ 474 /*-------------------------------------------------------*/ 475 476 /* Allocate in Vex's temporary allocation area. Be careful with this. 477 You can only call it inside an instrumentation or optimisation 478 callback that you have previously specified in a call to 479 LibVEX_Translate. The storage allocated will only stay alive until 480 translation of the current basic block is complete. */ 481 extern void* LibVEX_Alloc ( SizeT nbytes ); 482 483 /* Show Vex allocation statistics. */ 484 extern void LibVEX_ShowAllocStats ( void ); 485 486 487 /*-------------------------------------------------------*/ 488 /*--- Describing guest state layout ---*/ 489 /*-------------------------------------------------------*/ 490 491 /* Describe the guest state enough that the instrumentation 492 functions can work. */ 493 494 /* The max number of guest state chunks which we can describe as 495 always defined (for the benefit of Memcheck). */ 496 #define VEXGLO_N_ALWAYSDEFD 24 497 498 typedef 499 struct { 500 /* Total size of the guest state, in bytes. Must be 501 16-aligned. */ 502 Int total_sizeB; 503 /* Whereabouts is the stack pointer? */ 504 Int offset_SP; 505 Int sizeof_SP; /* 4 or 8 */ 506 /* Whereabouts is the frame pointer? */ 507 Int offset_FP; 508 Int sizeof_FP; /* 4 or 8 */ 509 /* Whereabouts is the instruction pointer? */ 510 Int offset_IP; 511 Int sizeof_IP; /* 4 or 8 */ 512 /* Describe parts of the guest state regarded as 'always 513 defined'. */ 514 Int n_alwaysDefd; 515 struct { 516 Int offset; 517 Int size; 518 } alwaysDefd[VEXGLO_N_ALWAYSDEFD]; 519 } 520 VexGuestLayout; 521 522 /* A note about guest state layout. 523 524 LibVEX defines the layout for the guest state, in the file 525 pub/libvex_guest_<arch>.h. The struct will have an 16-aligned 526 size. Each translated bb is assumed to be entered with a specified 527 register pointing at such a struct. Beyond that is two copies of 528 the shadow state area with the same size as the struct. Beyond 529 that is a spill area that LibVEX may spill into. It must have size 530 LibVEX_N_SPILL_BYTES, and this must be a 16-aligned number. 531 532 On entry, the baseblock pointer register must be 16-aligned. 533 534 There must be no holes in between the primary guest state, its two 535 copies, and the spill area. In short, all 4 areas must have a 536 16-aligned size and be 16-aligned, and placed back-to-back. 537 */ 538 539 #define LibVEX_N_SPILL_BYTES 4096 540 541 /* The size of the guest state must be a multiple of this number. */ 542 #define LibVEX_GUEST_STATE_ALIGN 16 543 544 /*-------------------------------------------------------*/ 545 /*--- Initialisation of the library ---*/ 546 /*-------------------------------------------------------*/ 547 548 /* Initialise the library. You must call this first. */ 549 550 extern void LibVEX_Init ( 551 552 /* failure exit function */ 553 # if __cplusplus == 1 && __GNUC__ && __GNUC__ <= 3 554 /* g++ 3.x doesn't understand attributes on function parameters. 555 See #265762. */ 556 # else 557 __attribute__ ((noreturn)) 558 # endif 559 void (*failure_exit) ( void ), 560 561 /* logging output function */ 562 void (*log_bytes) ( const HChar*, SizeT nbytes ), 563 564 /* debug paranoia level */ 565 Int debuglevel, 566 567 /* Control ... */ 568 const VexControl* vcon 569 ); 570 571 572 /*-------------------------------------------------------*/ 573 /*--- Make a translation ---*/ 574 /*-------------------------------------------------------*/ 575 576 /* Describes the outcome of a translation attempt. */ 577 typedef 578 struct { 579 /* overall status */ 580 enum { VexTransOK=0x800, 581 VexTransAccessFail, VexTransOutputFull } status; 582 /* The number of extents that have a self-check (0 to 3) */ 583 UInt n_sc_extents; 584 /* Offset in generated code of the profile inc, or -1 if 585 none. Needed for later patching. */ 586 Int offs_profInc; 587 /* Stats only: the number of guest insns included in the 588 translation. It may be zero (!). */ 589 UInt n_guest_instrs; 590 } 591 VexTranslateResult; 592 593 594 /* Describes precisely the pieces of guest code that a translation 595 covers. Now that Vex can chase across BB boundaries, the old 596 scheme of describing a chunk of guest code merely by its start 597 address and length is inadequate. 598 599 This struct uses 20 bytes on a 32-bit archtecture and 32 bytes on a 600 64-bit architecture. Space is important as clients will have to store 601 one of these for each translation made. 602 */ 603 typedef 604 struct { 605 Addr base[3]; 606 UShort len[3]; 607 UShort n_used; 608 } 609 VexGuestExtents; 610 611 612 /* A structure to carry arguments for LibVEX_Translate. There are so 613 many of them, it seems better to have a structure. */ 614 typedef 615 struct { 616 /* IN: The instruction sets we are translating from and to. And 617 guest/host misc info. */ 618 VexArch arch_guest; 619 VexArchInfo archinfo_guest; 620 VexArch arch_host; 621 VexArchInfo archinfo_host; 622 VexAbiInfo abiinfo_both; 623 624 /* IN: an opaque value which is passed as the first arg to all 625 callback functions supplied in this struct. Vex has no idea 626 what's at the other end of this pointer. */ 627 void* callback_opaque; 628 629 /* IN: the block to translate, and its guest address. */ 630 /* where are the actual bytes in the host's address space? */ 631 const UChar* guest_bytes; 632 /* where do the bytes really come from in the guest's aspace? 633 This is the post-redirection guest address. Not that Vex 634 understands anything about redirection; that is all done on 635 the Valgrind side. */ 636 Addr guest_bytes_addr; 637 638 /* Is it OK to chase into this guest address? May not be 639 NULL. */ 640 Bool (*chase_into_ok) ( /*callback_opaque*/void*, Addr ); 641 642 /* OUT: which bits of guest code actually got translated */ 643 VexGuestExtents* guest_extents; 644 645 /* IN: a place to put the resulting code, and its size */ 646 UChar* host_bytes; 647 Int host_bytes_size; 648 /* OUT: how much of the output area is used. */ 649 Int* host_bytes_used; 650 651 /* IN: optionally, two instrumentation functions. May be 652 NULL. */ 653 IRSB* (*instrument1) ( /*callback_opaque*/void*, 654 IRSB*, 655 const VexGuestLayout*, 656 const VexGuestExtents*, 657 const VexArchInfo*, 658 IRType gWordTy, IRType hWordTy ); 659 IRSB* (*instrument2) ( /*callback_opaque*/void*, 660 IRSB*, 661 const VexGuestLayout*, 662 const VexGuestExtents*, 663 const VexArchInfo*, 664 IRType gWordTy, IRType hWordTy ); 665 666 IRSB* (*finaltidy) ( IRSB* ); 667 668 /* IN: a callback used to ask the caller which of the extents, 669 if any, a self check is required for. Must not be NULL. 670 The returned value is a bitmask with a 1 in position i indicating 671 that the i'th extent needs a check. Since there can be at most 672 3 extents, the returned values must be between 0 and 7. 673 674 This call also gives the VEX client the opportunity to change 675 the precision of register update preservation as performed by 676 the IR optimiser. Before the call, VEX will set *pxControl 677 to hold the default register-update status value as specified 678 by VexControl::iropt_register_updates_default as passed to 679 LibVEX_Init at library initialisation time. The client (in 680 this callback) can if it wants, inspect the value and change 681 it to something different, and that value will be used for 682 subsequent IR optimisation of the block. */ 683 UInt (*needs_self_check)( /*callback_opaque*/void*, 684 /*MAYBE_MOD*/VexRegisterUpdates* pxControl, 685 const VexGuestExtents* ); 686 687 /* IN: optionally, a callback which allows the caller to add its 688 own IR preamble following the self-check and any other 689 VEX-generated preamble, if any. May be NULL. If non-NULL, 690 the IRSB under construction is handed to this function, which 691 presumably adds IR statements to it. The callback may 692 optionally complete the block and direct bb_to_IR not to 693 disassemble any instructions into it; this is indicated by 694 the callback returning True. 695 */ 696 Bool (*preamble_function)(/*callback_opaque*/void*, IRSB*); 697 698 /* IN: debug: trace vex activity at various points */ 699 Int traceflags; 700 701 /* IN: debug: print diagnostics when an illegal instr is detected */ 702 Bool sigill_diag; 703 704 /* IN: profiling: add a 64 bit profiler counter increment to the 705 translation? */ 706 Bool addProfInc; 707 708 /* IN: address of the dispatcher entry points. Describes the 709 places where generated code should jump to at the end of each 710 bb. 711 712 At the end of each translation, the next guest address is 713 placed in the host's standard return register (x86: %eax, 714 amd64: %rax, ppc32: %r3, ppc64: %r3). Optionally, the guest 715 state pointer register (on host x86: %ebp; amd64: %rbp; 716 ppc32/64: r31) may be set to a VEX_TRC_ value to indicate any 717 special action required before the next block is run. 718 719 Control is then passed back to the dispatcher (beyond Vex's 720 control; caller supplies this) in the following way: 721 722 - On host archs which lack a link register (x86, amd64), by a 723 jump to the host address specified in 724 'dispatcher_assisted', if the guest state pointer has been 725 changed so as to request some action before the next block 726 is run, or 'dispatcher_unassisted' (the fast path), in 727 which it is assumed that the guest state pointer is 728 unchanged and we wish to continue directly with the next 729 translation. Both of these must be non-NULL. 730 731 - On host archs which have a link register (ppc32, ppc64), by 732 a branch to the link register (which is guaranteed to be 733 unchanged from whatever it was at entry to the 734 translation). 'dispatch_assisted' and 735 'dispatch_unassisted' must be NULL. 736 737 The aim is to get back and forth between translations and the 738 dispatcher without creating memory traffic to store return 739 addresses. 740 741 FIXME: update this comment 742 */ 743 const void* disp_cp_chain_me_to_slowEP; 744 const void* disp_cp_chain_me_to_fastEP; 745 const void* disp_cp_xindir; 746 const void* disp_cp_xassisted; 747 } 748 VexTranslateArgs; 749 750 751 extern 752 VexTranslateResult LibVEX_Translate ( VexTranslateArgs* ); 753 754 /* A subtlety re interaction between self-checking translations and 755 bb-chasing. The supplied chase_into_ok function should say NO 756 (False) when presented with any address for which you might want to 757 make a self-checking translation. 758 759 If it doesn't do that, you may end up with Vex chasing from BB #1 760 to BB #2 (fine); but if you wanted checking for #2 and not #1, that 761 would not be the result. Therefore chase_into_ok should disallow 762 following into #2. That will force the caller to eventually 763 request a new translation starting at #2, at which point Vex will 764 correctly observe the make-a-self-check flag. 765 766 FIXME: is this still up to date? */ 767 768 769 /*-------------------------------------------------------*/ 770 /*--- Patch existing translations ---*/ 771 /*-------------------------------------------------------*/ 772 773 /* A host address range that was modified by the functions below. 774 Callers must request I-cache syncing after the call as appropriate. */ 775 typedef 776 struct { 777 HWord start; 778 HWord len; /* always > 0 */ 779 } 780 VexInvalRange; 781 782 /* Chain an XDirect jump located at place_to_chain so it jumps to 783 place_to_jump_to. It is expected (and checked) that this site 784 currently contains a call to the dispatcher specified by 785 disp_cp_chain_me_EXPECTED. */ 786 extern 787 VexInvalRange LibVEX_Chain ( VexArch arch_host, 788 VexEndness endhess_host, 789 void* place_to_chain, 790 const void* disp_cp_chain_me_EXPECTED, 791 const void* place_to_jump_to ); 792 793 /* Undo an XDirect jump located at place_to_unchain, so it is 794 converted back into a call to disp_cp_chain_me. It is expected 795 (and checked) that this site currently contains a jump directly to 796 the address specified by place_to_jump_to_EXPECTED. */ 797 extern 798 VexInvalRange LibVEX_UnChain ( VexArch arch_host, 799 VexEndness endness_host, 800 void* place_to_unchain, 801 const void* place_to_jump_to_EXPECTED, 802 const void* disp_cp_chain_me ); 803 804 /* Returns a constant -- the size of the event check that is put at 805 the start of every translation. This makes it possible to 806 calculate the fast entry point address if the slow entry point 807 address is known (the usual case), or vice versa. */ 808 extern 809 Int LibVEX_evCheckSzB ( VexArch arch_host ); 810 811 812 /* Patch the counter location into an existing ProfInc point. The 813 specified point is checked to make sure it is plausible. */ 814 extern 815 VexInvalRange LibVEX_PatchProfInc ( VexArch arch_host, 816 VexEndness endness_host, 817 void* place_to_patch, 818 const ULong* location_of_counter ); 819 820 821 /*-------------------------------------------------------*/ 822 /*--- Show accumulated statistics ---*/ 823 /*-------------------------------------------------------*/ 824 825 extern void LibVEX_ShowStats ( void ); 826 827 /*-------------------------------------------------------*/ 828 /*-- IR injection --*/ 829 /*-------------------------------------------------------*/ 830 831 /* IR Injection Control Block */ 832 833 #define NO_ROUNDING_MODE (~0u) 834 835 typedef 836 struct { 837 IROp op; // the operation to perform 838 HWord result; // address of the result 839 HWord opnd1; // address of 1st operand 840 HWord opnd2; // address of 2nd operand 841 HWord opnd3; // address of 3rd operand 842 HWord opnd4; // address of 4th operand 843 IRType t_result; // type of result 844 IRType t_opnd1; // type of 1st operand 845 IRType t_opnd2; // type of 2nd operand 846 IRType t_opnd3; // type of 3rd operand 847 IRType t_opnd4; // type of 4th operand 848 UInt rounding_mode; 849 UInt num_operands; // excluding rounding mode, if any 850 Bool shift_amount_is_immediate; 851 } 852 IRICB; 853 854 extern void LibVEX_InitIRI ( const IRICB * ); 855 856 /*-------------------------------------------------------*/ 857 /*--- Notes ---*/ 858 /*-------------------------------------------------------*/ 859 860 /* Code generation conventions that need to be recorded somewhere. 861 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 862 863 x86 864 ~~~ 865 Generated code should be entered using a JMP instruction. On 866 entry, %ebp should point to the guest state, and %esp should be a 867 valid stack pointer. The generated code may change %eax, %ebx, 868 %ecx, %edx, %esi, %edi, all the FP registers and control state, and 869 all the XMM registers. 870 871 On entry, the FPU control word should be set to 0x027F, and the SSE 872 control word (%mxcsr) should be set to 0x1F80. On exit, they 873 should still have those values (after masking off the lowest 6 bits 874 of %mxcsr). If they don't, there is a bug in VEX-generated code. 875 876 Generated code returns to the scheduler using a JMP instruction, to 877 the address specified in the .dispatch field of VexTranslateArgs. 878 %eax (or %eax:%edx, if simulating a 64-bit target) will contain the 879 guest address of the next block to execute. %ebp may be changed 880 to a VEX_TRC_ value, otherwise it should be as it was at entry. 881 882 CRITICAL ISSUES in x86 code generation. The only known critical 883 issue is that the host FPU and SSE state is not properly saved 884 across calls to helper functions. If any helper references any 885 such state, it is likely (1) to misbehave itself, since the FP 886 stack tags will not be as expected, and (2) after returning to 887 generated code, the generated code is likely to go wrong. This 888 really should be fixed. 889 890 amd64 891 ~~~~~ 892 Analogous to x86. 893 894 ppc32 895 ~~~~~ 896 On entry, guest state pointer is r31. .dispatch must be NULL. 897 Control is returned with a branch to the link register. Generated 898 code will not change lr. At return, r3 holds the next guest addr 899 (or r3:r4 ?). r31 may be may be changed to a VEX_TRC_ value, 900 otherwise it should be as it was at entry. 901 902 ppc64 903 ~~~~~ 904 Same as ppc32. 905 906 arm32 907 ~~~~~ 908 r8 is GSP. 909 910 arm64 911 ~~~~~ 912 r21 is GSP. 913 914 ALL GUEST ARCHITECTURES 915 ~~~~~~~~~~~~~~~~~~~~~~~ 916 The guest state must contain two pseudo-registers, guest_CMSTART 917 and guest_CMLEN. These are used to specify guest address ranges, 918 either of code to be invalidated, when used in conjunction with 919 Ijk_InvalICache, or of d-cache ranges to be flushed, when used in 920 conjunction with Ijk_FlushDCache. In such cases, the two _CM 921 pseudo-regs should be filled in by the IR, and then an exit with 922 one of the two abovementioned Ijk_ kinds should happen, so that the 923 dispatcher can action them. Both pseudo-regs must have size equal 924 to the guest word size. 925 926 The architecture must a third pseudo-register, guest_NRADDR, also 927 guest-word-sized. This is used to record the unredirected guest 928 address at the start of a translation whose start has been 929 redirected. By reading this pseudo-register shortly afterwards, 930 the translation can find out what the corresponding no-redirection 931 address was. Note, this is only set for wrap-style redirects, not 932 for replace-style ones. 933 */ 934 #endif /* ndef __LIBVEX_H */ 935 936 /*---------------------------------------------------------------*/ 937 /*--- libvex.h ---*/ 938 /*---------------------------------------------------------------*/ 939
