1
2/*--------------------------------------------------------------------*/
3/*--- begin                               guest_generic_bb_to_IR.h ---*/
4/*--------------------------------------------------------------------*/
5
6/*
7   This file is part of Valgrind, a dynamic binary instrumentation
8   framework.
9
10   Copyright (C) 2004-2013 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 __VEX_GUEST_GENERIC_BB_TO_IR_H
37#define __VEX_GUEST_GENERIC_BB_TO_IR_H
38
39#include "libvex_basictypes.h"
40#include "libvex_ir.h"              // IRJumpKind
41#include "libvex.h"                 // VexArch
42
43/* This defines stuff needed by the guest insn disassemblers.
44   It's a bit circular; is imported by
45   - the guest-specific toIR.c files (guest-{x86,amd64,ppc,arm}/toIR.c)
46   - the generic disassembly driver (bb_to_IR.c)
47   - vex_main.c
48*/
49
50
51/* ---------------------------------------------------------------
52   Result of disassembling an instruction
53   --------------------------------------------------------------- */
54
55/* The results of disassembling an instruction.  There are three
56   possible outcomes.  For Dis_Resteer, the disassembler _must_
57   continue at the specified address.  For Dis_StopHere, the
58   disassembler _must_ terminate the BB.  For Dis_Continue, we may at
59   our option either disassemble the next insn, or terminate the BB;
60   but in the latter case we must set the bb's ->next field to point
61   to the next instruction.  */
62
63typedef
64
65   struct {
66
67      /* The disassembled insn has this length.  Must always be
68         set. */
69      Int len;
70
71      /* What happens next?
72         Dis_StopHere:  this insn terminates the BB; we must stop.
73         Dis_Continue:  we can optionally continue into the next insn
74         Dis_ResteerU:  followed an unconditional branch; continue at
75                        'continueAt'
76         Dis_ResteerC:  (speculatively, of course) followed a
77                        conditional branch; continue at 'continueAt'
78      */
79      enum { Dis_StopHere, Dis_Continue,
80             Dis_ResteerU, Dis_ResteerC } whatNext;
81
82      /* For Dis_StopHere, we need to end the block and create a
83         transfer to whatever the NIA is.  That will have presumably
84         been set by the IR generated for this insn.  So we need to
85         know the jump kind to use.  Should Ijk_INVALID in other Dis_
86         cases. */
87      IRJumpKind jk_StopHere;
88
89      /* For Dis_Resteer, this is the guest address we should continue
90         at.  Otherwise ignored (should be zero). */
91      Addr64 continueAt;
92
93   }
94
95   DisResult;
96
97
98/* ---------------------------------------------------------------
99   The type of a function which disassembles one instruction.
100   C's function-type syntax is really astonishing bizarre.
101   --------------------------------------------------------------- */
102
103/* A function of this type (DisOneInstrFn) disassembles an instruction
104   located at host address &guest_code[delta], whose guest IP is
105   guest_IP (this may be entirely unrelated to where the insn is
106   actually located in the host's address space.).  The returned
107   DisResult.len field carries its size.  If the returned
108   DisResult.whatNext field is Dis_Resteer then DisResult.continueAt
109   should hold the guest IP of the next insn to disassemble.
110
111   disInstr is not permitted to return Dis_Resteer if resteerOkFn,
112   when applied to the address which it wishes to resteer into,
113   returns False.
114
115   The resulting IR is added to the end of irbb.
116*/
117
118typedef
119
120   DisResult (*DisOneInstrFn) (
121
122      /* This is the IRSB to which the resulting IR is to be appended. */
123      /*OUT*/ IRSB*        irbb,
124
125      /* Return True iff resteering to the given addr is allowed (for
126         branches/calls to destinations that are known at JIT-time) */
127      /*IN*/  Bool         (*resteerOkFn) ( /*opaque*/void*, Addr64 ),
128
129      /* Should we speculatively resteer across conditional branches?
130         (Experimental and not enabled by default).  The strategy is
131         to assume that backward branches are taken and forward
132         branches are not taken. */
133      /*IN*/  Bool         resteerCisOk,
134
135      /* Vex-opaque data passed to all caller (valgrind) supplied
136         callbacks. */
137      /*IN*/  void*        callback_opaque,
138
139      /* Where is the guest code? */
140      /*IN*/  UChar*       guest_code,
141
142      /* Where is the actual insn?  Note: it's at &guest_code[delta] */
143      /*IN*/  Long         delta,
144
145      /* What is the guest IP of the insn? */
146      /*IN*/  Addr64       guest_IP,
147
148      /* Info about the guest architecture */
149      /*IN*/  VexArch      guest_arch,
150      /*IN*/  VexArchInfo* archinfo,
151
152      /* ABI info for both guest and host */
153      /*IN*/  VexAbiInfo*  abiinfo,
154
155      /* Is the host bigendian? */
156      /*IN*/  Bool         host_bigendian,
157
158      /* Should diagnostics be printed for illegal instructions? */
159      /*IN*/  Bool         sigill_diag
160
161   );
162
163
164/* ---------------------------------------------------------------
165   Top-level BB to IR conversion fn.
166   --------------------------------------------------------------- */
167
168/* See detailed comment in bb_to_IR.c. */
169extern
170IRSB* bb_to_IR (
171         /*OUT*/VexGuestExtents* vge,
172         /*OUT*/UInt*            n_sc_extents,
173         /*OUT*/UInt*            n_guest_instrs, /* stats only */
174         /*IN*/ void*            callback_opaque,
175         /*IN*/ DisOneInstrFn    dis_instr_fn,
176         /*IN*/ UChar*           guest_code,
177         /*IN*/ Addr64           guest_IP_bbstart,
178         /*IN*/ Bool             (*chase_into_ok)(void*,Addr64),
179         /*IN*/ Bool             host_bigendian,
180         /*IN*/ Bool             sigill_diag,
181         /*IN*/ VexArch          arch_guest,
182         /*IN*/ VexArchInfo*     archinfo_guest,
183         /*IN*/ VexAbiInfo*      abiinfo_both,
184         /*IN*/ IRType           guest_word_type,
185         /*IN*/ UInt             (*needs_self_check)(void*,VexGuestExtents*),
186         /*IN*/ Bool             (*preamble_function)(void*,IRSB*),
187         /*IN*/ Int              offB_GUEST_CMSTART,
188         /*IN*/ Int              offB_GUEST_CMLEN,
189         /*IN*/ Int              offB_GUEST_IP,
190         /*IN*/ Int              szB_GUEST_IP
191      );
192
193
194#endif /* ndef __VEX_GUEST_GENERIC_BB_TO_IR_H */
195
196/*--------------------------------------------------------------------*/
197/*--- end                                 guest_generic_bb_to_IR.h ---*/
198/*--------------------------------------------------------------------*/
199