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