1(*===-- llvm_executionengine.mli - LLVM OCaml Interface -------*- OCaml -*-===*
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(** [initialize ()] initializes the backend corresponding to the host.
18    Returns [true] if initialization is successful; [false] indicates
19    that there is no such backend or it is unable to emit object code
20    via MCJIT. *)
21val initialize : unit -> bool
22
23(** An execution engine is either a JIT compiler or an interpreter, capable of
24    directly loading an LLVM module and executing its functions without first
25    invoking a static compiler and generating a native executable. *)
26type llexecutionengine
27
28(** MCJIT compiler options. See [llvm::TargetOptions]. *)
29type llcompileroptions = {
30  opt_level: int;
31  code_model: Llvm_target.CodeModel.t;
32  no_framepointer_elim: bool;
33  enable_fast_isel: bool;
34}
35
36(** Default MCJIT compiler options:
37    [{ opt_level = 0; code_model = CodeModel.JIT_default;
38       no_framepointer_elim = false; enable_fast_isel = false }] *)
39val default_compiler_options : llcompileroptions
40
41(** [create m optlevel] creates a new MCJIT just-in-time compiler, taking
42    ownership of the module [m] if successful with the desired optimization
43    level [optlevel]. Raises [Error msg] if an error occurrs. The execution
44    engine is not garbage collected and must be destroyed with [dispose ee].
45
46    Run {!initialize} before using this function.
47
48    See the function [llvm::EngineBuilder::create]. *)
49val create : ?options:llcompileroptions -> Llvm.llmodule -> llexecutionengine
50
51(** [dispose ee] releases the memory used by the execution engine and must be
52    invoked to avoid memory leaks. *)
53val dispose : llexecutionengine -> unit
54
55(** [add_module m ee] adds the module [m] to the execution engine [ee]. *)
56val add_module : Llvm.llmodule -> llexecutionengine -> unit
57
58(** [remove_module m ee] removes the module [m] from the execution engine
59    [ee]. Raises [Error msg] if an error occurs. *)
60val remove_module : Llvm.llmodule -> llexecutionengine -> unit
61
62(** [run_static_ctors ee] executes the static constructors of each module in
63    the execution engine [ee]. *)
64val run_static_ctors : llexecutionengine -> unit
65
66(** [run_static_dtors ee] executes the static destructors of each module in
67    the execution engine [ee]. *)
68val run_static_dtors : llexecutionengine -> unit
69
70(** [data_layout ee] is the data layout of the execution engine [ee]. *)
71val data_layout : llexecutionengine -> Llvm_target.DataLayout.t
72
73(** [add_global_mapping gv ptr ee] tells the execution engine [ee] that
74    the global [gv] is at the specified location [ptr], which must outlive
75    [gv] and [ee].
76    All uses of [gv] in the compiled code will refer to [ptr]. *)
77val add_global_mapping : Llvm.llvalue -> 'a Ctypes.ptr -> llexecutionengine -> unit
78
79(** [get_pointer_to_global gv typ ee] returns the value of the global
80    variable [gv] in the execution engine [ee] as type [typ], which may
81    be a pointer type (e.g. [int ptr typ]) for global variables or
82    a function (e.g. [(int -> int) typ]) type for functions, and which
83    will be live as long as [gv] and [ee] are. *)
84val get_pointer_to_global : Llvm.llvalue -> 'a Ctypes.typ -> llexecutionengine -> 'a
85