blob: 757ae9f3aaa66ddc225a5bcb56151ba2d53dd7f6 [file] [log] [blame]
sewardjac9af022004-07-05 01:15:34 +00001
2/*---------------------------------------------------------------*/
3/*--- ---*/
sewardj887a11a2004-07-05 17:26:47 +00004/*--- This file (libvex.h) is ---*/
sewardjac9af022004-07-05 01:15:34 +00005/*--- Copyright (c) 2004 OpenWorks LLP. All rights reserved. ---*/
6/*--- ---*/
7/*---------------------------------------------------------------*/
8
sewardj887a11a2004-07-05 17:26:47 +00009#ifndef __LIBVEX_H
10#define __LIBVEX_H
sewardjac9af022004-07-05 01:15:34 +000011
12
sewardj887a11a2004-07-05 17:26:47 +000013#include "libvex_basictypes.h"
14#include "libvex_ir.h"
sewardjac9af022004-07-05 01:15:34 +000015
16
17/*---------------------------------------------------------------*/
18/*--- Top-level interface to the library. ---*/
19/*---------------------------------------------------------------*/
20
21
sewardj08613742004-10-25 13:01:45 +000022/* Control of Vex's optimiser. */
23
24typedef
25 struct {
26 /* Controls verbosity of iropt. 0 = no output. */
27 Int iropt_verbosity;
28 /* Control aggressiveness of iropt. 0 = no opt, 1 = simple
29 opts, 2 (default) = max optimisation. */
30 Int iropt_level;
31 /* Ensure all integer registers are up to date at potential
32 memory exception points? True(default)=yes, False=no, only
33 the guest's stack pointer. */
34 Bool iropt_precise_memory_exns;
35 /* How aggressive should iropt be in unrolling loops? Higher
36 numbers make it more enthusiastic about loop unrolling.
37 Default=120. A setting of zero disables unrolling. */
38 Int iropt_unroll_thresh;
39 /* What's the maximum basic block length the front end(s) allow?
40 BBs longer than this are split up. Default=50 (guest
41 insns). */
42 Int guest_max_insns;
43 /* How aggressive should front ends be in following
44 unconditional branches to known destinations? Default=10,
45 meaning that if a block contains less than 10 guest insns so
46 far, the front end(s) will attempt to chase into its
47 successor. A setting of zero disables chasing. */
48 Int guest_chase_thresh;
49 }
50 VexControl;
51
52
53/* Write the default settings into *vcon. */
54extern void LibVEX_default_VexControl ( /*OUT*/ VexControl* vcon );
55
56
sewardjac9af022004-07-05 01:15:34 +000057/* Initialise the translator. */
58
sewardj887a11a2004-07-05 17:26:47 +000059extern void LibVEX_Init (
sewardjac9af022004-07-05 01:15:34 +000060 /* failure exit function */
sewardj2b515872004-07-05 20:50:45 +000061 __attribute__ ((noreturn))
sewardjac9af022004-07-05 01:15:34 +000062 void (*failure_exit) ( void ),
63 /* logging output function */
64 void (*log_bytes) ( Char*, Int nbytes ),
65 /* debug paranoia level */
66 Int debuglevel,
sewardjac9af022004-07-05 01:15:34 +000067 /* Are we supporting valgrind checking? */
68 Bool valgrind_support,
sewardj08613742004-10-25 13:01:45 +000069 /* Control ... */
70 /*READONLY*/VexControl* vcon
sewardjac9af022004-07-05 01:15:34 +000071);
72
73
74/* Storage management: clear the area, and allocate from it. */
75
sewardj443cd9d2004-07-18 23:06:45 +000076/* By default allocation occurs in the temporary area. However, it is
77 possible to switch to permanent area allocation if that's what you
78 want. Permanent area allocation is very limited, tho. */
79
80typedef
81 enum { AllocModeTEMPORARY, AllocModePERMANENT }
82 AllocMode;
83
84extern void LibVEX_SetAllocMode ( AllocMode );
85extern AllocMode LibVEX_GetAllocMode ( void );
86
87extern void LibVEX_ClearTemporary ( Bool show_stats );
sewardjac9af022004-07-05 01:15:34 +000088
sewardj35421a32004-07-05 13:12:34 +000089extern void* LibVEX_Alloc ( Int nbytes );
sewardjac9af022004-07-05 01:15:34 +000090
91
sewardj49651f42004-10-28 22:11:04 +000092/* Describe the guest state enough that the instrumentation
93 functions can work. */
94
sewardjeeac8412004-11-02 00:26:55 +000095/* The max number of indexable guest state sections we can describe.
96 2 is enough for x86. */
97#define VEXGLO_N_DESCRS 2
98
99/* The max number of guest state chunks which we can describe as
100 always defined (for the benefit of Memcheck). */
101#define VEXGLO_N_ALWAYSDEFD 14
102
sewardj49651f42004-10-28 22:11:04 +0000103typedef
104 struct {
sewardjcf787902004-11-03 09:08:33 +0000105 /* Total size of the guest state, in bytes. Must be
106 8-aligned. */
sewardjeeac8412004-11-02 00:26:55 +0000107 Int total_sizeB;
sewardj49651f42004-10-28 22:11:04 +0000108 /* Whereabouts is the stack pointer? */
109 Int offset_SP;
110 Int sizeof_SP; /* 4 or 8 */
sewardjcf787902004-11-03 09:08:33 +0000111 /* Whereabouts is the instruction pointer? */
112 Int offset_IP;
113 Int sizeof_IP; /* 4 or 8 */
sewardjeeac8412004-11-02 00:26:55 +0000114 /* Describe parts of the guest state regarded as 'always
115 defined'. */
116 Int n_alwaysDefd;
117 struct {
118 Int offset;
119 Int size;
120 } alwaysDefd[VEXGLO_N_ALWAYSDEFD];
sewardj49651f42004-10-28 22:11:04 +0000121 }
sewardjeeac8412004-11-02 00:26:55 +0000122 VexGuestLayout;
sewardj49651f42004-10-28 22:11:04 +0000123
124
sewardjac9af022004-07-05 01:15:34 +0000125/* Translate a basic block. */
126
127typedef
128 enum { InsnSetX86, InsnSetARM }
129 InsnSet;
130
131typedef
132 enum { TransOK, TransAccessFail, TransOutputFull }
133 TranslateResult;
134
135extern
sewardj887a11a2004-07-05 17:26:47 +0000136TranslateResult LibVEX_Translate (
sewardjac9af022004-07-05 01:15:34 +0000137 /* The instruction sets we are translating from and to. */
138 InsnSet iset_guest,
139 InsnSet iset_host,
140 /* IN: the block to translate, and its guest address. */
sewardj81bd5502004-07-21 18:49:27 +0000141 UChar* guest_bytes,
sewardjac9af022004-07-05 01:15:34 +0000142 Addr64 guest_bytes_addr,
143 /* OUT: the number of bytes actually read */
144 Int* guest_bytes_read,
145 /* IN: a place to put the resulting code, and its size */
sewardj81bd5502004-07-21 18:49:27 +0000146 UChar* host_bytes,
147 Int host_bytes_size,
sewardjac9af022004-07-05 01:15:34 +0000148 /* OUT: how much of the output area is used. */
149 Int* host_bytes_used,
sewardj49651f42004-10-28 22:11:04 +0000150 /* IN: optionally, two instrumentation functions. */
sewardjcf787902004-11-03 09:08:33 +0000151 IRBB* (*instrument1) ( IRBB*, VexGuestLayout*, IRType hWordTy ),
152 IRBB* (*instrument2) ( IRBB*, VexGuestLayout*, IRType hWordTy ),
sewardjac9af022004-07-05 01:15:34 +0000153 /* IN: optionally, an access check function for guest code. */
sewardj58800ff2004-07-28 01:51:10 +0000154 Bool (*byte_accessible) ( Addr64 ),
sewardjf48ac192004-10-29 00:41:29 +0000155 /* IN: debug: trace vex activity at various points */
156 Int traceflags
sewardjac9af022004-07-05 01:15:34 +0000157);
158
159
160/* Show accumulated statistics. */
161
sewardj887a11a2004-07-05 17:26:47 +0000162extern void LibVEX_ShowStats ( void );
sewardjac9af022004-07-05 01:15:34 +0000163
164
sewardj81ec4182004-10-25 23:15:52 +0000165
166/* A note about baseblock layout.
167
168 LibVEX defines the layout for the guest state, in the file
169 pub/libvex_guest_<arch>.h. The struct will have an 8-aligned size.
170 Each translated bb is assumed to be entered with a specified
171 register pointing at such a struct. Beyond that is a shadow
172 state area with the same size as the struct. Beyond that is
173 a spill area that LibVEX may spill into. It must have size
174 LibVEX_N_SPILL_BYTES, and this will be a 16-aligned number.
175
176 On entry, the baseblock pointer register must be 8-aligned.
177*/
178
179#define LibVEX_N_SPILL_BYTES 256
180
181
sewardj887a11a2004-07-05 17:26:47 +0000182#endif /* ndef __LIBVEX_H */
sewardjac9af022004-07-05 01:15:34 +0000183
184/*---------------------------------------------------------------*/
sewardj887a11a2004-07-05 17:26:47 +0000185/*--- libvex.h ---*/
sewardjac9af022004-07-05 01:15:34 +0000186/*---------------------------------------------------------------*/