l4/pkg/valgrind/src/valgrind-3.6.0-svn/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-2010 OpenWorks LLP
  11       info@open-works.net
  12
  13    This program is free software; you can redistribute it and/or
  14    modify it under the terms of the GNU General Public License as
  15    published by the Free Software Foundation; either version 2 of the
  16    License, or (at your option) any later version.
  17
  18    This program is distributed in the hope that it will be useful, but
  19    WITHOUT ANY WARRANTY; without even the implied warranty of
  20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21    General Public License for more details.
  22
  23    You should have received a copy of the GNU General Public License
  24    along with this program; if not, write to the Free Software
  25    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  26    02110-1301, USA.
  27
  28    The GNU General Public License is contained in the file COPYING.
  29
  30    Neither the names of the U.S. Department of Energy nor the
  31    University of California nor the names of its contributors may be
  32    used to endorse or promote products derived from this software
  33    without prior written permission.
  34 */
  35
  36 #ifndef __LIBVEX_H
  37 #define __LIBVEX_H
  38
  39
  40 #include "libvex_basictypes.h"
  41 #include "libvex_ir.h"
  42
  43
  44 /*---------------------------------------------------------------*/
  45 /*--- This file defines the top-level interface to LibVEX.    ---*/
  46 /*---------------------------------------------------------------*/
  47
  48 /*-------------------------------------------------------*/
  49 /*--- Architectures, variants, and other arch info    ---*/
  50 /*-------------------------------------------------------*/
  51
  52 typedef
  53    enum {
  54       VexArch_INVALID,
  55       VexArchX86,
  56       VexArchAMD64,
  57       VexArchARM,
  58       VexArchPPC32,
  59       VexArchPPC64,
  60       VexArchS390X
  61    }
  62    VexArch;
  63
  64
  65 /* For a given architecture, these specify extra capabilities beyond
  66    the minimum supported (baseline) capabilities.  They may be OR'd
  67    together, although some combinations don't make sense.  (eg, SSE2
  68    but not SSE1).  LibVEX_Translate will check for nonsensical
  69    combinations. */
  70
  71 /* x86: baseline capability is Pentium-1 (FPU, MMX, but no SSE), with
  72    cmpxchg8b. */
  73 #define VEX_HWCAPS_X86_SSE1    (1<<1)  /* SSE1 support (Pentium III) */
  74 #define VEX_HWCAPS_X86_SSE2    (1<<2)  /* SSE2 support (Pentium 4) */
  75 #define VEX_HWCAPS_X86_SSE3    (1<<3)  /* SSE3 support (>= Prescott) */
  76 #define VEX_HWCAPS_X86_LZCNT   (1<<4)  /* SSE4a LZCNT insn */
  77
  78 /* amd64: baseline capability is SSE2, with cmpxchg8b but not
  79    cmpxchg16b. */
  80 #define VEX_HWCAPS_AMD64_SSE3  (1<<5)  /* SSE3 support */
  81 #define VEX_HWCAPS_AMD64_CX16  (1<<6)  /* cmpxchg16b support */
  82 #define VEX_HWCAPS_AMD64_LZCNT (1<<7)  /* SSE4a LZCNT insn */
  83
  84 /* ppc32: baseline capability is integer only */
  85 #define VEX_HWCAPS_PPC32_F     (1<<8)  /* basic (non-optional) FP */
  86 #define VEX_HWCAPS_PPC32_V     (1<<9)  /* Altivec (VMX) */
  87 #define VEX_HWCAPS_PPC32_FX    (1<<10) /* FP extns (fsqrt, fsqrts) */
  88 #define VEX_HWCAPS_PPC32_GX    (1<<11) /* Graphics extns
  89                                           (fres,frsqrte,fsel,stfiwx) */
  90 #define VEX_HWCAPS_PPC32_VX    (1<<12) /* Vector-scalar floating-point (VSX); implies ISA 2.06 or higher  */
  91
  92 /* ppc64: baseline capability is integer and basic FP insns */
  93 #define VEX_HWCAPS_PPC64_V     (1<<13) /* Altivec (VMX) */
  94 #define VEX_HWCAPS_PPC64_FX    (1<<14) /* FP extns (fsqrt, fsqrts) */
  95 #define VEX_HWCAPS_PPC64_GX    (1<<15) /* Graphics extns
  96                                           (fres,frsqrte,fsel,stfiwx) */
  97 #define VEX_HWCAPS_PPC64_VX    (1<<16) /* Vector-scalar floating-point (VSX); implies ISA 2.06 or higher  */
  98
  99 /* s390x: Hardware capability encoding
 100
 101    Bits    Information
 102    [26:31] Machine model
 103    [25]    Long displacement facility
 104    [24]    Extended-immediate facility
 105    [23]    General-instruction-extension facility
 106    [22]    Decimal floating point facility
 107    [21]    FPR-GR transfer facility
 108    [0:20]  Currently unused; reserved for future use
 109 */
 110
 111 /* Model numbers must be assigned in chronological order.
 112    They are used as array index. */
 113 #define VEX_S390X_MODEL_Z900     0
 114 #define VEX_S390X_MODEL_Z800     1
 115 #define VEX_S390X_MODEL_Z990     2
 116 #define VEX_S390X_MODEL_Z890     3
 117 #define VEX_S390X_MODEL_Z9_EC    4
 118 #define VEX_S390X_MODEL_Z9_BC    5
 119 #define VEX_S390X_MODEL_Z10_EC   6
 120 #define VEX_S390X_MODEL_Z10_BC   7
 121 #define VEX_S390X_MODEL_Z196     8
 122 #define VEX_S390X_MODEL_INVALID  9
 123 #define VEX_S390X_MODEL_MASK     0x3F
 124
 125 #define VEX_HWCAPS_S390X_LDISP (1<<6)   /* Long-displacement facility */
 126 #define VEX_HWCAPS_S390X_EIMM  (1<<7)   /* Extended-immediate facility */
 127 #define VEX_HWCAPS_S390X_GIE   (1<<8)   /* General-instruction-extension facility */
 128 #define VEX_HWCAPS_S390X_DFP   (1<<9)   /* Decimal floating point facility */
 129 #define VEX_HWCAPS_S390X_FGX   (1<<10)  /* FPR-GR transfer facility */
 130
 131 /* Special value representing all available s390x hwcaps */
 132 #define VEX_HWCAPS_S390X_ALL   (VEX_HWCAPS_S390X_LDISP | \
 133                                 VEX_HWCAPS_S390X_EIMM  | \
 134                                 VEX_HWCAPS_S390X_GIE   | \
 135                                 VEX_HWCAPS_S390X_DFP   | \
 136                                 VEX_HWCAPS_S390X_FGX)
 137
 138 #define VEX_HWCAPS_S390X(x)  ((x) & ~VEX_S390X_MODEL_MASK)
 139 #define VEX_S390X_MODEL(x)   ((x) &  VEX_S390X_MODEL_MASK)
 140
 141 /* arm: baseline capability is ARMv4 */
 142 /* Bits 5:0 - architecture level (e.g. 5 for v5, 6 for v6 etc) */
 143 #define VEX_HWCAPS_ARM_VFP    (1<<6)  /* VFP extension */
 144 #define VEX_HWCAPS_ARM_VFP2   (1<<7)  /* VFPv2 */
 145 #define VEX_HWCAPS_ARM_VFP3   (1<<8)  /* VFPv3 */
 146 /* Bits 15:10 reserved for (possible) future VFP revisions */
 147 #define VEX_HWCAPS_ARM_NEON   (1<<16) /* Advanced SIMD also known as NEON */
 148
 149 /* Get an ARM architecure level from HWCAPS */
 150 #define VEX_ARM_ARCHLEVEL(x) ((x) & 0x3f)
 151
 152 /* These return statically allocated strings. */
 153
 154 extern const HChar* LibVEX_ppVexArch    ( VexArch );
 155 extern const HChar* LibVEX_ppVexHwCaps  ( VexArch, UInt );
 156
 157
 158 /* This struct is a bit of a hack, but is needed to carry misc
 159    important bits of info about an arch.  Fields which are meaningless
 160    or ignored for the platform in question should be set to zero. */
 161
 162 typedef
 163    struct {
 164       /* This is the only mandatory field. */
 165       UInt hwcaps;
 166       /* PPC32/PPC64 only: size of cache line */
 167       Int ppc_cache_line_szB;
 168       /* PPC32/PPC64 only: sizes zeroed by the dcbz/dcbzl instructions
 169        * (bug#135264) */
 170       UInt ppc_dcbz_szB;
 171       UInt ppc_dcbzl_szB; /* 0 means unsupported (SIGILL) */
 172    }
 173    VexArchInfo;
 174
 175 /* Write default settings info *vai. */
 176 extern
 177 void LibVEX_default_VexArchInfo ( /*OUT*/VexArchInfo* vai );
 178
 179
 180 /* This struct carries guest and host ABI variant information that may
 181    be needed.  Fields which are meaningless or ignored for the
 182    platform in question should be set to zero.
 183
 184    Settings which are believed to be correct are:
 185
 186    guest_stack_redzone_size
 187       guest is ppc32-linux                ==> 0
 188       guest is ppc64-linux                ==> 288
 189       guest is ppc32-aix5                 ==> 220
 190       guest is ppc64-aix5                 ==> unknown
 191       guest is amd64-linux                ==> 128
 192       guest is other                      ==> inapplicable
 193
 194    guest_amd64_assume_fs_is_zero
 195       guest is amd64-linux                ==> True
 196       guest is amd64-darwin               ==> False
 197       guest is other                      ==> inapplicable
 198
 199    guest_amd64_assume_gs_is_0x60
 200       guest is amd64-darwin               ==> True
 201       guest is amd64-linux                ==> False
 202       guest is other                      ==> inapplicable
 203
 204    guest_ppc_zap_RZ_at_blr
 205       guest is ppc64-linux                ==> True
 206       guest is ppc32-linux                ==> False
 207       guest is ppc64-aix5                 ==> unknown
 208       guest is ppc32-aix5                 ==> False
 209       guest is other                      ==> inapplicable
 210
 211    guest_ppc_zap_RZ_at_bl
 212       guest is ppc64-linux                ==> const True
 213       guest is ppc32-linux                ==> const False
 214       guest is ppc64-aix5                 ==> unknown
 215       guest is ppc32-aix5                 ==> True except for calls to
 216                                               millicode, $SAVEFn, $RESTFn
 217       guest is other                      ==> inapplicable
 218
 219    guest_ppc_sc_continues_at_LR:
 220       guest is ppc32-aix5  or ppc64-aix5  ==> True
 221       guest is ppc32-linux or ppc64-linux ==> False
 222       guest is other                      ==> inapplicable
 223
 224    host_ppc_calls_use_fndescrs:
 225       host is ppc32-linux                 ==> False
 226       host is ppc64-linux                 ==> True
 227       host is ppc32-aix5 or ppc64-aix5    ==> True
 228       host is other                       ==> inapplicable
 229
 230    host_ppc32_regalign_int64_args:
 231       host is ppc32-linux                 ==> True
 232       host is ppc32-aix5                  ==> False
 233       host is other                       ==> inapplicable
 234 */
 235
 236 typedef
 237    struct {
 238       /* PPC and AMD64 GUESTS only: how many bytes below the
 239          stack pointer are validly addressible? */
 240       Int guest_stack_redzone_size;
 241
 242       /* AMD64 GUESTS only: should we translate %fs-prefixed
 243          instructions using the assumption that %fs always contains
 244          zero? */
 245       Bool guest_amd64_assume_fs_is_zero;
 246
 247       /* AMD64 GUESTS only: should we translate %gs-prefixed
 248          instructions using the assumption that %gs always contains
 249          0x60? */
 250       Bool guest_amd64_assume_gs_is_0x60;
 251
 252       /* PPC GUESTS only: should we zap the stack red zone at a 'blr'
 253          (function return) ? */
 254       Bool guest_ppc_zap_RZ_at_blr;
 255
 256       /* PPC GUESTS only: should we zap the stack red zone at a 'bl'
 257          (function call) ?  Is supplied with the guest address of the
 258          target of the call since that may be significant.  If NULL,
 259          is assumed equivalent to a fn which always returns False. */
 260       Bool (*guest_ppc_zap_RZ_at_bl)(Addr64);
 261
 262       /* PPC32/PPC64 GUESTS only: where does the kernel resume after
 263          'sc'?  False => Linux style, at the next insn.  True => AIX
 264          style, at the address stated in the link register. */
 265       Bool guest_ppc_sc_continues_at_LR;
 266
 267       /* PPC32/PPC64 HOSTS only: does '&f' give us a pointer to a
 268          function descriptor on the host, or to the function code
 269          itself?  True => descriptor, False => code. */
 270       Bool host_ppc_calls_use_fndescrs;
 271
 272       /* PPC32 HOSTS only: when generating code to pass a 64-bit value
 273          (actual parameter) in a pair of regs, should we skip an arg
 274          reg if it is even-numbered?  True => yes, False => no. */
 275       Bool host_ppc32_regalign_int64_args;
 276    }
 277    VexAbiInfo;
 278
 279 /* Write default settings info *vbi. */
 280 extern
 281 void LibVEX_default_VexAbiInfo ( /*OUT*/VexAbiInfo* vbi );
 282
 283
 284 /*-------------------------------------------------------*/
 285 /*--- Control of Vex's optimiser (iropt).             ---*/
 286 /*-------------------------------------------------------*/
 287
 288 /* Control of Vex's optimiser. */
 289
 290 typedef
 291    struct {
 292       /* Controls verbosity of iropt.  0 = no output. */
 293       Int iropt_verbosity;
 294       /* Control aggressiveness of iropt.  0 = no opt, 1 = simple
 295          opts, 2 (default) = max optimisation. */
 296       Int iropt_level;
 297       /* Ensure all integer registers are up to date at potential
 298          memory exception points?  True(default)=yes, False=no, only
 299          the guest's stack pointer. */
 300       Bool iropt_precise_memory_exns;
 301       /* How aggressive should iropt be in unrolling loops?  Higher
 302          numbers make it more enthusiastic about loop unrolling.
 303          Default=120.  A setting of zero disables unrolling.  */
 304       Int iropt_unroll_thresh;
 305       /* What's the maximum basic block length the front end(s) allow?
 306          BBs longer than this are split up.  Default=50 (guest
 307          insns). */
 308       Int guest_max_insns;
 309       /* How aggressive should front ends be in following
 310          unconditional branches to known destinations?  Default=10,
 311          meaning that if a block contains less than 10 guest insns so
 312          far, the front end(s) will attempt to chase into its
 313          successor. A setting of zero disables chasing.  */
 314       Int guest_chase_thresh;
 315       /* EXPERIMENTAL: chase across conditional branches?  Not all
 316          front ends honour this.  Default: NO. */
 317       Bool guest_chase_cond;
 318    }
 319    VexControl;
 320
 321
 322 /* Write the default settings into *vcon. */
 323
 324 extern
 325 void LibVEX_default_VexControl ( /*OUT*/ VexControl* vcon );
 326
 327
 328 /*-------------------------------------------------------*/
 329 /*--- Storage management control                      ---*/
 330 /*-------------------------------------------------------*/
 331
 332 /* Allocate in Vex's temporary allocation area.  Be careful with this.
 333    You can only call it inside an instrumentation or optimisation
 334    callback that you have previously specified in a call to
 335    LibVEX_Translate.  The storage allocated will only stay alive until
 336    translation of the current basic block is complete.
 337  */
 338 extern HChar* private_LibVEX_alloc_first;
 339 extern HChar* private_LibVEX_alloc_curr;
 340 extern HChar* private_LibVEX_alloc_last;
 341 extern void   private_LibVEX_alloc_OOM(void) __attribute__((noreturn));
 342
 343 static inline void* LibVEX_Alloc ( Int nbytes )
 344 {
 345 #if 0
 346   /* Nasty debugging hack, do not use. */
 347   return malloc(nbytes);
 348 #else
 349    HChar* curr;
 350    HChar* next;
 351    Int    ALIGN;
 352    ALIGN  = sizeof(void*)-1;
 353    nbytes = (nbytes + ALIGN) & ~ALIGN;
 354    curr   = private_LibVEX_alloc_curr;
 355    next   = curr + nbytes;
 356    if (next >= private_LibVEX_alloc_last)
 357       private_LibVEX_alloc_OOM();
 358    private_LibVEX_alloc_curr = next;
 359    return curr;
 360 #endif
 361 }
 362
 363 /* Show Vex allocation statistics. */
 364 extern void LibVEX_ShowAllocStats ( void );
 365
 366
 367 /*-------------------------------------------------------*/
 368 /*--- Describing guest state layout                   ---*/
 369 /*-------------------------------------------------------*/
 370
 371 /* Describe the guest state enough that the instrumentation
 372    functions can work. */
 373
 374 /* The max number of guest state chunks which we can describe as
 375    always defined (for the benefit of Memcheck). */
 376 #define VEXGLO_N_ALWAYSDEFD  24
 377
 378 typedef
 379    struct {
 380       /* Total size of the guest state, in bytes.  Must be
 381          8-aligned. */
 382       Int total_sizeB;
 383       /* Whereabouts is the stack pointer? */
 384       Int offset_SP;
 385       Int sizeof_SP; /* 4 or 8 */
 386       /* Whereabouts is the frame pointer? */
 387       Int offset_FP;
 388       Int sizeof_FP; /* 4 or 8 */
 389       /* Whereabouts is the instruction pointer? */
 390       Int offset_IP;
 391       Int sizeof_IP; /* 4 or 8 */
 392       /* Describe parts of the guest state regarded as 'always
 393          defined'. */
 394       Int n_alwaysDefd;
 395       struct {
 396          Int offset;
 397          Int size;
 398       } alwaysDefd[VEXGLO_N_ALWAYSDEFD];
 399    }
 400    VexGuestLayout;
 401
 402 /* A note about guest state layout.
 403
 404    LibVEX defines the layout for the guest state, in the file
 405    pub/libvex_guest_<arch>.h.  The struct will have an 16-aligned
 406    size.  Each translated bb is assumed to be entered with a specified
 407    register pointing at such a struct.  Beyond that is two copies of
 408    the shadow state area with the same size as the struct.  Beyond
 409    that is a spill area that LibVEX may spill into.  It must have size
 410    LibVEX_N_SPILL_BYTES, and this must be a 16-aligned number.
 411
 412    On entry, the baseblock pointer register must be 16-aligned.
 413
 414    There must be no holes in between the primary guest state, its two
 415    copies, and the spill area.  In short, all 4 areas must have a
 416    16-aligned size and be 16-aligned, and placed back-to-back.
 417 */
 418
 419 #define LibVEX_N_SPILL_BYTES 4096
 420
 421
 422 /*-------------------------------------------------------*/
 423 /*--- Initialisation of the library                   ---*/
 424 /*-------------------------------------------------------*/
 425
 426 /* Initialise the library.  You must call this first. */
 427
 428 extern void LibVEX_Init (
 429
 430    /* failure exit function */
 431 #  if __cplusplus == 1 && __GNUC__ && __GNUC__ <= 3
 432    /* g++ 3.x doesn't understand attributes on function parameters.
 433       See #265762. */
 434 #  else
 435    __attribute__ ((noreturn))
 436 #  endif
 437    void (*failure_exit) ( void ),
 438
 439    /* logging output function */
 440    void (*log_bytes) ( HChar*, Int nbytes ),
 441
 442    /* debug paranoia level */
 443    Int debuglevel,
 444
 445    /* Are we supporting valgrind checking? */
 446    Bool valgrind_support,
 447
 448    /* Control ... */
 449    /*READONLY*/VexControl* vcon
 450 );
 451
 452
 453 /*-------------------------------------------------------*/
 454 /*--- Make a translation                              ---*/
 455 /*-------------------------------------------------------*/
 456
 457 /* Describes the outcome of a translation attempt. */
 458 typedef
 459    enum {
 460       VexTransOK,
 461       VexTransAccessFail,
 462       VexTransOutputFull
 463    }
 464    VexTranslateResult;
 465
 466
 467 /* Describes precisely the pieces of guest code that a translation
 468    covers.  Now that Vex can chase across BB boundaries, the old
 469    scheme of describing a chunk of guest code merely by its start
 470    address and length is inadequate.
 471
 472    Hopefully this struct is only 32 bytes long.  Space is important as
 473    clients will have to store one of these for each translation made.
 474 */
 475 typedef
 476    struct {
 477       Addr64 base[3];
 478       UShort len[3];
 479       UShort n_used;
 480    }
 481    VexGuestExtents;
 482
 483
 484 /* A structure to carry arguments for LibVEX_Translate.  There are so
 485    many of them, it seems better to have a structure. */
 486 typedef
 487    struct {
 488       /* IN: The instruction sets we are translating from and to.  And
 489          guest/host misc info. */
 490       VexArch      arch_guest;
 491       VexArchInfo  archinfo_guest;
 492       VexArch      arch_host;
 493       VexArchInfo  archinfo_host;
 494       VexAbiInfo   abiinfo_both;
 495
 496       /* IN: an opaque value which is passed as the first arg to all
 497          callback functions supplied in this struct.  Vex has no idea
 498          what's at the other end of this pointer. */
 499       void*   callback_opaque;
 500
 501       /* IN: the block to translate, and its guest address. */
 502       /* where are the actual bytes in the host's address space? */
 503       UChar*  guest_bytes;
 504       /* where do the bytes really come from in the guest's aspace?
 505          This is the post-redirection guest address.  Not that Vex
 506          understands anything about redirection; that is all done on
 507          the Valgrind side. */
 508       Addr64  guest_bytes_addr;
 509
 510       /* Is it OK to chase into this guest address?  May not be
 511          NULL. */
 512       Bool    (*chase_into_ok) ( /*callback_opaque*/void*, Addr64 );
 513
 514       /* OUT: which bits of guest code actually got translated */
 515       VexGuestExtents* guest_extents;
 516
 517       /* IN: a place to put the resulting code, and its size */
 518       UChar*  host_bytes;
 519       Int     host_bytes_size;
 520       /* OUT: how much of the output area is used. */
 521       Int*    host_bytes_used;
 522
 523       /* IN: optionally, two instrumentation functions.  May be
 524          NULL. */
 525       IRSB*   (*instrument1) ( /*callback_opaque*/void*,
 526                                IRSB*,
 527                                VexGuestLayout*,
 528                                VexGuestExtents*,
 529                                IRType gWordTy, IRType hWordTy );
 530       IRSB*   (*instrument2) ( /*callback_opaque*/void*,
 531                                IRSB*,
 532                                VexGuestLayout*,
 533                                VexGuestExtents*,
 534                                IRType gWordTy, IRType hWordTy );
 535
 536       IRSB* (*finaltidy) ( IRSB* );
 537
 538       /* IN: should this translation be self-checking?  default: False */
 539       Bool    do_self_check;
 540
 541       /* IN: optionally, a callback which allows the caller to add its
 542          own IR preamble following the self-check and any other
 543          VEX-generated preamble, if any.  May be NULL.  If non-NULL,
 544          the IRSB under construction is handed to this function, which
 545          presumably adds IR statements to it.  The callback may
 546          optionally complete the block and direct bb_to_IR not to
 547          disassemble any instructions into it; this is indicated by
 548          the callback returning True.
 549       */
 550       Bool    (*preamble_function)(/*callback_opaque*/void*, IRSB*);
 551
 552       /* IN: debug: trace vex activity at various points */
 553       Int     traceflags;
 554
 555       /* IN: address of the dispatcher entry point.  Describes the
 556          place where generated code should jump to at the end of each
 557          bb.
 558
 559          At the end of each translation, the next guest address is
 560          placed in the host's standard return register (x86: %eax,
 561          amd64: %rax, ppc32: %r3, ppc64: %r3).  Optionally, the guest
 562          state pointer register (on host x86: %ebp; amd64: %rbp;
 563          ppc32/64: r31) may be set to a VEX_TRC_ value to indicate any
 564          special action required before the next block is run.
 565
 566          Control is then passed back to the dispatcher (beyond Vex's
 567          control; caller supplies this) in the following way:
 568
 569          - On host archs which lack a link register (x86, amd64), by a
 570            jump to the host address specified in 'dispatcher', which
 571            must be non-NULL.
 572
 573          - On host archs which have a link register (ppc32, ppc64), by
 574            a branch to the link register (which is guaranteed to be
 575            unchanged from whatever it was at entry to the
 576            translation).  'dispatch' must be NULL.
 577
 578          The aim is to get back and forth between translations and the
 579          dispatcher without creating memory traffic to store return
 580          addresses.
 581       */
 582       void* dispatch;
 583    }
 584    VexTranslateArgs;
 585
 586
 587 extern
 588 VexTranslateResult LibVEX_Translate ( VexTranslateArgs* );
 589
 590 /* A subtlety re interaction between self-checking translations and
 591    bb-chasing.  The supplied chase_into_ok function should say NO
 592    (False) when presented with any address for which you might want to
 593    make a self-checking translation.
 594
 595    If it doesn't do that, you may end up with Vex chasing from BB #1
 596    to BB #2 (fine); but if you wanted checking for #2 and not #1, that
 597    would not be the result.  Therefore chase_into_ok should disallow
 598    following into #2.  That will force the caller to eventually
 599    request a new translation starting at #2, at which point Vex will
 600    correctly observe the make-a-self-check flag.  */
 601
 602
 603 /*-------------------------------------------------------*/
 604 /*--- Show accumulated statistics                     ---*/
 605 /*-------------------------------------------------------*/
 606
 607 extern void LibVEX_ShowStats ( void );
 608
 609
 610 /*-------------------------------------------------------*/
 611 /*--- Notes                                           ---*/
 612 /*-------------------------------------------------------*/
 613
 614 /* Code generation conventions that need to be recorded somewhere.
 615    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 616
 617    x86
 618    ~~~
 619    Generated code should be entered using a JMP instruction.  On
 620    entry, %ebp should point to the guest state, and %esp should be a
 621    valid stack pointer.  The generated code may change %eax, %ebx,
 622    %ecx, %edx, %esi, %edi, all the FP registers and control state, and
 623    all the XMM registers.
 624
 625    On entry, the FPU control word should be set to 0x027F, and the SSE
 626    control word (%mxcsr) should be set to 0x1F80.  On exit, they
 627    should still have those values (after masking off the lowest 6 bits
 628    of %mxcsr).  If they don't, there is a bug in VEX-generated code.
 629
 630    Generated code returns to the scheduler using a JMP instruction, to
 631    the address specified in the .dispatch field of VexTranslateArgs.
 632    %eax (or %eax:%edx, if simulating a 64-bit target) will contain the
 633    guest address of the next block to execute.  %ebp may be changed
 634    to a VEX_TRC_ value, otherwise it should be as it was at entry.
 635
 636    CRITICAL ISSUES in x86 code generation.  The only known critical
 637    issue is that the host FPU and SSE state is not properly saved
 638    across calls to helper functions.  If any helper references any
 639    such state, it is likely (1) to misbehave itself, since the FP
 640    stack tags will not be as expected, and (2) after returning to
 641    generated code, the generated code is likely to go wrong.  This
 642    really should be fixed.
 643
 644    amd64
 645    ~~~~~
 646    Analogous to x86.
 647
 648    ppc32
 649    ~~~~~
 650    On entry, guest state pointer is r31.  .dispatch must be NULL.
 651    Control is returned with a branch to the link register.  Generated
 652    code will not change lr.  At return, r3 holds the next guest addr
 653    (or r3:r4 ?).  r31 may be may be changed to a VEX_TRC_ value,
 654    otherwise it should be as it was at entry.
 655
 656    ppc64
 657    ~~~~~
 658    Same as ppc32.
 659
 660    ALL GUEST ARCHITECTURES
 661    ~~~~~~~~~~~~~~~~~~~~~~~
 662    The guest state must contain two pseudo-registers, guest_TISTART
 663    and guest_TILEN.  These are used to pass the address of areas of
 664    guest code, translations of which are to be invalidated, back to
 665    the despatcher.  Both pseudo-regs must have size equal to the guest
 666    word size.
 667
 668    The architecture must a third pseudo-register, guest_NRADDR, also
 669    guest-word-sized.  This is used to record the unredirected guest
 670    address at the start of a translation whose start has been
 671    redirected.  By reading this pseudo-register shortly afterwards,
 672    the translation can find out what the corresponding no-redirection
 673    address was.  Note, this is only set for wrap-style redirects, not
 674    for replace-style ones.
 675 */
 676 #endif /* ndef __LIBVEX_H */
 677
 678 /*---------------------------------------------------------------*/
 679 /*---                                                libvex.h ---*/
 680 /*---------------------------------------------------------------*/