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