VEX/pub/libvex.h

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