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
17(** The JIT code model. See [llvm::CodeModel::Model]. *)
18module CodeModel : sig
19  type t =
20    | Default
21    | JIT_default
22    | Small
23    | Kernel
24    | Medium
25    | Large
26end
27
28module GenericValue: sig
29  (** [GenericValue.t] is a boxed union type used to portably pass arguments to
30      and receive values from the execution engine. It supports only a limited
31      selection of types; for more complex argument types, it is necessary to
32      generate a stub function by hand or to pass parameters by reference.
33      See the struct [llvm::GenericValue]. *)
34  type t
35
36  (** [of_float fpty n] boxes the float [n] in a float-valued generic value
37      according to the floating point type [fpty]. See the fields
38      [llvm::GenericValue::DoubleVal] and [llvm::GenericValue::FloatVal]. *)
39  val of_float : Llvm.lltype -> float -> t
40
41  (** [of_pointer v] boxes the pointer value [v] in a generic value. See the
42      field [llvm::GenericValue::PointerVal]. *)
43  val of_pointer : 'a -> t
44
45  (** [of_int32 n w] boxes the int32 [i] in a generic value with the bitwidth
46      [w]. See the field [llvm::GenericValue::IntVal]. *)
47  val of_int32 : Llvm.lltype -> int32 -> t
48
49  (** [of_int n w] boxes the int [i] in a generic value with the bitwidth
50      [w]. See the field [llvm::GenericValue::IntVal]. *)
51  val of_int : Llvm.lltype -> int -> t
52
53  (** [of_natint n w] boxes the native int [i] in a generic value with the
54      bitwidth [w]. See the field [llvm::GenericValue::IntVal]. *)
55  val of_nativeint : Llvm.lltype -> nativeint -> t
56
57  (** [of_int64 n w] boxes the int64 [i] in a generic value with the bitwidth
58      [w]. See the field [llvm::GenericValue::IntVal]. *)
59  val of_int64 : Llvm.lltype -> int64 -> t
60
61  (** [as_float fpty gv] unboxes the floating point-valued generic value [gv] of
62      floating point type [fpty]. See the fields [llvm::GenericValue::DoubleVal]
63      and [llvm::GenericValue::FloatVal]. *)
64  val as_float : Llvm.lltype -> t -> float
65
66  (** [as_pointer gv] unboxes the pointer-valued generic value [gv]. See the
67      field [llvm::GenericValue::PointerVal]. *)
68  val as_pointer : t -> 'a
69
70  (** [as_int32 gv] unboxes the integer-valued generic value [gv] as an [int32].
71      Is invalid if [gv] has a bitwidth greater than 32 bits. See the field
72      [llvm::GenericValue::IntVal]. *)
73  val as_int32 : t -> int32
74
75  (** [as_int gv] unboxes the integer-valued generic value [gv] as an [int].
76      Is invalid if [gv] has a bitwidth greater than the host bit width (but the
77      most significant bit may be lost). See the field
78      [llvm::GenericValue::IntVal]. *)
79  val as_int : t -> int
80
81  (** [as_natint gv] unboxes the integer-valued generic value [gv] as a
82      [nativeint]. Is invalid if [gv] has a bitwidth greater than
83      [nativeint]. See the field [llvm::GenericValue::IntVal]. *)
84  val as_nativeint : t -> nativeint
85
86  (** [as_int64 gv] returns the integer-valued generic value [gv] as an [int64].
87      Is invalid if [gv] has a bitwidth greater than [int64]. See the field
88      [llvm::GenericValue::IntVal]. *)
89  val as_int64 : t -> int64
90end
91
92
93module ExecutionEngine: sig
94  (** An execution engine is either a JIT compiler or an interpreter, capable of
95      directly loading an LLVM module and executing its functions without first
96      invoking a static compiler and generating a native executable. *)
97  type t
98
99  (** MCJIT compiler options. See [llvm::TargetOptions]. *)
100  type compileroptions = {
101    opt_level: int;
102    code_model: CodeModel.t;
103    no_framepointer_elim: bool;
104    enable_fast_isel: bool;
105  }
106
107  (** Default MCJIT compiler options:
108      [{ opt_level = 0; code_model = CodeModel.JIT_default;
109         no_framepointer_elim = false; enable_fast_isel = false }] *)
110  val default_compiler_options : compileroptions
111
112  (** [create m] creates a new execution engine, taking ownership of the
113      module [m] if successful. Creates a JIT if possible, else falls back to an
114      interpreter. Raises [Error msg] if an error occurrs. The execution engine
115      is not garbage collected and must be destroyed with [dispose ee].
116      See the function [llvm::EngineBuilder::create]. *)
117  val create : Llvm.llmodule -> t
118
119  (** [create_interpreter m] creates a new interpreter, taking ownership of the
120      module [m] if successful. Raises [Error msg] if an error occurrs. The
121      execution engine is not garbage collected and must be destroyed with
122      [dispose ee].
123      See the function [llvm::EngineBuilder::create]. *)
124  val create_interpreter : Llvm.llmodule -> t
125
126  (** [create_jit m optlevel] creates a new JIT (just-in-time compiler), taking
127      ownership of the module [m] if successful with the desired optimization
128      level [optlevel]. Raises [Error msg] if an error occurrs. The execution
129      engine is not garbage collected and must be destroyed with [dispose ee].
130      See the function [llvm::EngineBuilder::create].
131
132      Deprecated; use {!create_mcjit}. This function is a shim for {!create_mcjit}. *)
133  val create_jit : Llvm.llmodule -> int -> t
134
135  (** [create_jit m optlevel] creates a new JIT (just-in-time compiler), taking
136      ownership of the module [m] if successful with the desired optimization
137      level [optlevel]. Raises [Error msg] if an error occurrs. The execution
138      engine is not garbage collected and must be destroyed with [dispose ee].
139      See the function [llvm::EngineBuilder::create]. *)
140  val create_mcjit : Llvm.llmodule -> compileroptions -> t
141
142  (** [dispose ee] releases the memory used by the execution engine and must be
143      invoked to avoid memory leaks. *)
144  val dispose : t -> unit
145
146  (** [add_module m ee] adds the module [m] to the execution engine [ee]. *)
147  val add_module : Llvm.llmodule -> t -> unit
148
149  (** [remove_module m ee] removes the module [m] from the execution engine
150      [ee], disposing of [m] and the module referenced by [mp]. Raises
151      [Error msg] if an error occurs. *)
152  val remove_module : Llvm.llmodule -> t -> Llvm.llmodule
153
154  (** [find_function n ee] finds the function named [n] defined in any of the
155      modules owned by the execution engine [ee]. Returns [None] if the function
156      is not found and [Some f] otherwise. *)
157  val find_function : string -> t -> Llvm.llvalue option
158
159  (** [run_function f args ee] synchronously executes the function [f] with the
160      arguments [args], which must be compatible with the parameter types. *)
161  val run_function : Llvm.llvalue -> GenericValue.t array -> t ->
162                     GenericValue.t
163
164  (** [run_static_ctors ee] executes the static constructors of each module in
165      the execution engine [ee]. *)
166  val run_static_ctors : t -> unit
167
168  (** [run_static_dtors ee] executes the static destructors of each module in
169      the execution engine [ee]. *)
170  val run_static_dtors : t -> unit
171
172  (** [run_function_as_main f args env ee] executes the function [f] as a main
173      function, passing it [argv] and [argc] according to the string array
174      [args], and [envp] as specified by the array [env]. Returns the integer
175      return value of the function. *)
176  val run_function_as_main : Llvm.llvalue -> string array ->
177                                  (string * string) array -> t -> int
178
179  (** [free_machine_code f ee] releases the memory in the execution engine [ee]
180      used to store the machine code for the function [f]. *)
181  val free_machine_code : Llvm.llvalue -> t -> unit
182
183  (** [data_layout ee] is the data layout of the execution engine [ee]. *)
184  val data_layout : t -> Llvm_target.DataLayout.t
185end
186
187(** [initialize_native_target ()] initializes the native target corresponding
188    to the host. Returns [true] if initialization is {b not} done. *)
189val initialize_native_target : unit -> bool
190