llvm_executionengine.mli revision c13c4d6a1bbc91a9e3bb9f964f32f3a999071070 
1(*===-- llvm_executionengine.mli - LLVM Ocaml Interface ---------*- C++ -*-===*
2 *
3 *                     The LLVM Compiler Infrastructure
4 *
5 * This file is distributed under the University of Illinois Open Source
6 * License. See LICENSE.TXT for details.
7 *
8 *===----------------------------------------------------------------------===*)
9
10(** JIT Interpreter.
11
12    This interface provides an ocaml API for LLVM execution engine (JIT/
13    interpreter), the classes in the ExecutionEngine library. *)
14
15exception Error of string
16
17module GenericValue: sig
18  (** [GenericValue.t] is a boxed union type used to portably pass arguments to
19      and receive values from the execution engine. It supports only a limited
20      selection of types; for more complex argument types, it is necessary to
21      generate a stub function by hand or to pass parameters by reference.
22      See the struct [llvm::GenericValue]. *)
23  type t
24  
25  (** [of_float fpty n] boxes the float [n] in a float-valued generic value
26      according to the floating point type [fpty]. See the fields
27      [llvm::GenericValue::DoubleVal] and [llvm::GenericValue::FloatVal]. *)
28  val of_float: Llvm.lltype -> float -> t
29  
30  (** [of_pointer v] boxes the pointer value [v] in a generic value. See the
31      field [llvm::GenericValue::PointerVal]. *)
32  val of_pointer: 'a -> t
33  
34  (** [of_int32 n w] boxes the int32 [i] in a generic value with the bitwidth
35      [w]. See the field [llvm::GenericValue::IntVal]. *)
36  val of_int32: Llvm.lltype -> int32 -> t
37  
38  (** [of_int n w] boxes the int [i] in a generic value with the bitwidth
39      [w]. See the field [llvm::GenericValue::IntVal]. *)
40  val of_int: Llvm.lltype -> int -> t
41  
42  (** [of_natint n w] boxes the native int [i] in a generic value with the
43      bitwidth [w]. See the field [llvm::GenericValue::IntVal]. *)
44  val of_nativeint: Llvm.lltype -> nativeint -> t
45  
46  (** [of_int64 n w] boxes the int64 [i] in a generic value with the bitwidth
47      [w]. See the field [llvm::GenericValue::IntVal]. *)
48  val of_int64: Llvm.lltype -> int64 -> t
49  
50  (** [as_float fpty gv] unboxes the floating point-valued generic value [gv] of
51      floating point type [fpty]. See the fields [llvm::GenericValue::DoubleVal]
52      and [llvm::GenericValue::FloatVal]. *)
53  val as_float: Llvm.lltype -> t -> float
54  
55  (** [as_pointer gv] unboxes the pointer-valued generic value [gv]. See the
56      field [llvm::GenericValue::PointerVal]. *)
57  val as_pointer: t -> 'a
58  
59  (** [as_int32 gv] unboxes the integer-valued generic value [gv] as an [int32].
60      Is invalid if [gv] has a bitwidth greater than 32 bits. See the field
61      [llvm::GenericValue::IntVal]. *)
62  val as_int32: t -> int32
63  
64  (** [as_int gv] unboxes the integer-valued generic value [gv] as an [int].
65      Is invalid if [gv] has a bitwidth greater than the host bit width (but the
66      most significant bit may be lost). See the field
67      [llvm::GenericValue::IntVal]. *)
68  val as_int: t -> int
69  
70  (** [as_natint gv] unboxes the integer-valued generic value [gv] as a
71      [nativeint]. Is invalid if [gv] has a bitwidth greater than
72      [nativeint]. See the field [llvm::GenericValue::IntVal]. *)
73  val as_nativeint: t -> nativeint
74  
75  (** [as_int64 gv] returns the integer-valued generic value [gv] as an [int64].
76      Is invalid if [gv] has a bitwidth greater than [int64]. See the field
77      [llvm::GenericValue::IntVal]. *)
78  val as_int64: t -> int64
79end
80
81
82module ExecutionEngine: sig
83  (** An execution engine is either a JIT compiler or an interpreter, capable of
84      directly loading an LLVM module and executing its functions without first
85      invoking a static compiler and generating a native executable. *)
86  type t
87  
88  (** [create mp] creates a new execution engine, taking ownership of the
89      module provider [mp] if successful. Creates a JIT if possible, else falls
90      back to an interpreter. Raises [Error msg] if an error occurrs. The
91      execution engine is not garbage collected and must be destroyed with
92      [dispose ee]. See the function [llvm::ExecutionEngine::create]. *)
93  val create: Llvm.llmoduleprovider -> t
94  
95  (** [create_interpreter mp] creates a new interpreter, taking ownership of the
96      module provider [mp] if successful. Raises [Error msg] if an error
97      occurrs. The execution engine is not garbage collected and must be
98      destroyed with [dispose ee].
99      See the function [llvm::ExecutionEngine::create]. *)
100  val create_interpreter: Llvm.llmoduleprovider -> t
101  
102  (** [create_jit mp] creates a new JIT (just-in-time compiler), taking
103      ownership of the module provider [mp] if successful. This function creates
104      a JIT which favors code quality over compilation speed. Raises [Error msg]
105      if an error occurrs. The execution engine is not garbage collected and
106      must be destroyed with [dispose ee].
107      See the function [llvm::ExecutionEngine::create]. *)
108  val create_jit: Llvm.llmoduleprovider -> t
109  
110  (** [create_fast_jit mp] creates a new JIT (just-in-time compiler) which
111      favors compilation speed over code quality. It takes ownership of the
112      module provider [mp] if successful. Raises [Error msg] if an error
113      occurrs. The execution engine is not garbage collected and must be
114      destroyed with [dispose ee].
115      See the function [llvm::ExecutionEngine::create]. *)
116  val create_fast_jit: Llvm.llmoduleprovider -> t
117  
118  (** [dispose ee] releases the memory used by the execution engine and must be
119      invoked to avoid memory leaks. *)
120  val dispose: t -> unit
121  
122  (** [add_module_provider mp ee] adds the module provider [mp] to the execution
123      engine [ee]. *)
124  val add_module_provider: Llvm.llmoduleprovider -> t -> unit
125  
126  (** [remove_module_provider mp ee] removes the module provider [mp] from the
127      execution engine [ee], disposing of [mp] and the module referenced by
128      [mp]. Raises [Error msg] if an error occurs. *)
129  val remove_module_provider: Llvm.llmoduleprovider -> t -> Llvm.llmodule
130  
131  (** [find_function n ee] finds the function named [n] defined in any of the
132      modules owned by the execution engine [ee]. Returns [None] if the function
133      is not found and [Some f] otherwise. *)
134  val find_function: string -> t -> Llvm.llvalue option
135  
136  (** [run_function f args ee] synchronously executes the function [f] with the
137      arguments [args], which must be compatible with the parameter types. *)
138  val run_function: Llvm.llvalue -> GenericValue.t array -> t ->
139                    GenericValue.t
140  
141  (** [run_static_ctors ee] executes the static constructors of each module in
142      the execution engine [ee]. *)
143  val run_static_ctors: t -> unit
144  
145  (** [run_static_dtors ee] executes the static destructors of each module in
146      the execution engine [ee]. *)
147  val run_static_dtors: t -> unit
148  
149  (** [run_function_as_main f args env ee] executes the function [f] as a main
150      function, passing it [argv] and [argc] according to the string array
151      [args], and [envp] as specified by the array [env]. Returns the integer
152      return value of the function. *)
153  val run_function_as_main: Llvm.llvalue -> string array ->
154                            (string * string) array -> t -> int
155  
156  (** [free_machine_code f ee] releases the memory in the execution engine [ee]
157      used to store the machine code for the function [f]. *)
158  val free_machine_code: Llvm.llvalue -> t -> unit
159
160  (** [target_data ee] is the target data owned by the execution engine
161      [ee]. *)
162  val target_data: t -> Llvm_target.TargetData.t
163end
164