Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 1 | (*===-- llvm_executionengine.mli - LLVM Ocaml Interface ---------*- C++ -*-===* |
| 2 | * |
| 3 | * The LLVM Compiler Infrastructure |
| 4 | * |
Chris Lattner | 234d529 | 2007-12-29 22:59:10 +0000 | [diff] [blame] | 5 | * This file is distributed under the University of Illinois Open Source |
| 6 | * License. See LICENSE.TXT for details. |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 7 | * |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 8 | *===----------------------------------------------------------------------===*) |
| 9 | |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 10 | (** JIT Interpreter. |
| 11 | |
| 12 | This interface provides an ocaml API for LLVM execution engine (JIT/ |
| 13 | interpreter), the classes in the ExecutionEngine library. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 14 | |
| 15 | exception Error of string |
| 16 | |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 17 | module 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. |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 22 | See the struct [llvm::GenericValue]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 23 | type t |
| 24 | |
| 25 | (** [of_float fpty n] boxes the float [n] in a float-valued generic value |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 26 | according to the floating point type [fpty]. See the fields |
| 27 | [llvm::GenericValue::DoubleVal] and [llvm::GenericValue::FloatVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 28 | val of_float: Llvm.lltype -> float -> t |
| 29 | |
| 30 | (** [of_pointer v] boxes the pointer value [v] in a generic value. See the |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 31 | field [llvm::GenericValue::PointerVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 32 | val of_pointer: 'a -> t |
| 33 | |
| 34 | (** [of_int32 n w] boxes the int32 [i] in a generic value with the bitwidth |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 35 | [w]. See the field [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 39 | [w]. See the field [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 43 | bitwidth [w]. See the field [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 47 | [w]. See the field [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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] |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 52 | and [llvm::GenericValue::FloatVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 53 | val as_float: Llvm.lltype -> t -> float |
| 54 | |
| 55 | (** [as_pointer gv] unboxes the pointer-valued generic value [gv]. See the |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 56 | field [llvm::GenericValue::PointerVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 61 | [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 67 | [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 72 | [nativeint]. See the field [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 77 | [llvm::GenericValue::IntVal]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 78 | val as_int64: t -> int64 |
| 79 | end |
| 80 | |
| 81 | |
| 82 | module 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 85 | invoking a static compiler and generating a native executable. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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 |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 92 | [dispose ee]. See the function [llvm::ExecutionEngine::create]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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]. |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 99 | See the function [llvm::ExecutionEngine::create]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 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. Raises [Error msg] if |
| 104 | an error occurrs. The execution engine is not garbage collected and must |
| 105 | be destroyed with [dispose ee]. |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 106 | See the function [llvm::ExecutionEngine::create]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 107 | val create_jit: Llvm.llmoduleprovider -> t |
| 108 | |
| 109 | (** [dispose ee] releases the memory used by the execution engine and must be |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 110 | invoked to avoid memory leaks. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 111 | val dispose: t -> unit |
| 112 | |
| 113 | (** [add_module_provider mp ee] adds the module provider [mp] to the execution |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 114 | engine [ee]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 115 | val add_module_provider: Llvm.llmoduleprovider -> t -> unit |
| 116 | |
| 117 | (** [remove_module_provider mp ee] removes the module provider [mp] from the |
| 118 | execution engine [ee], disposing of [mp] and the module referenced by |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 119 | [mp]. Raises [Error msg] if an error occurs. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 120 | val remove_module_provider: Llvm.llmoduleprovider -> t -> Llvm.llmodule |
| 121 | |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 122 | (** [find_function n ee] finds the function named [n] defined in any of the |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 123 | modules owned by the execution engine [ee]. Returns [None] if the function |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 124 | is not found and [Some f] otherwise. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 125 | val find_function: string -> t -> Llvm.llvalue option |
| 126 | |
| 127 | (** [run_function f args ee] synchronously executes the function [f] with the |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 128 | arguments [args], which must be compatible with the parameter types. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 129 | val run_function: Llvm.llvalue -> GenericValue.t array -> t -> |
| 130 | GenericValue.t |
| 131 | |
| 132 | (** [run_static_ctors ee] executes the static constructors of each module in |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 133 | the execution engine [ee]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 134 | val run_static_ctors: t -> unit |
| 135 | |
| 136 | (** [run_static_dtors ee] executes the static destructors of each module in |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 137 | the execution engine [ee]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 138 | val run_static_dtors: t -> unit |
| 139 | |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 140 | (** [run_function_as_main f args env ee] executes the function [f] as a main |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 141 | function, passing it [argv] and [argc] according to the string array |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 142 | [args], and [envp] as specified by the array [env]. Returns the integer |
| 143 | return value of the function. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 144 | val run_function_as_main: Llvm.llvalue -> string array -> |
| 145 | (string * string) array -> t -> int |
| 146 | |
| 147 | (** [free_machine_code f ee] releases the memory in the execution engine [ee] |
Gordon Henriksen | 3b646de | 2008-03-09 07:17:38 +0000 | [diff] [blame] | 148 | used to store the machine code for the function [f]. *) |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 149 | val free_machine_code: Llvm.llvalue -> t -> unit |
Erick Tryzelaar | 7c1483b | 2008-03-27 00:27:14 +0000 | [diff] [blame^] | 150 | |
| 151 | (** [target_data ee] is the target data owned by the execution engine |
| 152 | [ee]. *) |
| 153 | val target_data: t -> Llvm_target.TargetData.t |
Gordon Henriksen | 2e855e6 | 2007-12-23 16:59:28 +0000 | [diff] [blame] | 154 | end |