1dfc58e3bcfcb8f37796b2ca1c289dd202f26d03cSylvestre Ledru(*===-- llvm_executionengine.mli - LLVM OCaml Interface ---------*- C++ -*-===* 22e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen * 32e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen * The LLVM Compiler Infrastructure 42e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen * 5234d529e582963ad4b5d83b911cd057fe99d1435Chris Lattner * This file is distributed under the University of Illinois Open Source 6234d529e582963ad4b5d83b911cd057fe99d1435Chris Lattner * License. See LICENSE.TXT for details. 72e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen * 82e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen *===----------------------------------------------------------------------===*) 92e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 103b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen(** JIT Interpreter. 112e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 12dfc58e3bcfcb8f37796b2ca1c289dd202f26d03cSylvestre Ledru This interface provides an OCaml API for LLVM execution engine (JIT/ 133b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen interpreter), the classes in the ExecutionEngine library. *) 142e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 153b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksenexception Error of string 162e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 172e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksenmodule GenericValue: sig 182e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [GenericValue.t] is a boxed union type used to portably pass arguments to 192e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen and receive values from the execution engine. It supports only a limited 202e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen selection of types; for more complex argument types, it is necessary to 212e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen generate a stub function by hand or to pass parameters by reference. 223b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen See the struct [llvm::GenericValue]. *) 232e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen type t 242e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 252e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [of_float fpty n] boxes the float [n] in a float-valued generic value 263b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen according to the floating point type [fpty]. See the fields 273b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [llvm::GenericValue::DoubleVal] and [llvm::GenericValue::FloatVal]. *) 28a156efdf71bc668093e31593713694cf076db895Torok Edwin val of_float : Llvm.lltype -> float -> t 292e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 302e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [of_pointer v] boxes the pointer value [v] in a generic value. See the 313b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen field [llvm::GenericValue::PointerVal]. *) 32a156efdf71bc668093e31593713694cf076db895Torok Edwin val of_pointer : 'a -> t 332e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 342e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [of_int32 n w] boxes the int32 [i] in a generic value with the bitwidth 353b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [w]. See the field [llvm::GenericValue::IntVal]. *) 36a156efdf71bc668093e31593713694cf076db895Torok Edwin val of_int32 : Llvm.lltype -> int32 -> t 372e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 382e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [of_int n w] boxes the int [i] in a generic value with the bitwidth 393b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [w]. See the field [llvm::GenericValue::IntVal]. *) 40a156efdf71bc668093e31593713694cf076db895Torok Edwin val of_int : Llvm.lltype -> int -> t 412e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 422e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [of_natint n w] boxes the native int [i] in a generic value with the 433b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen bitwidth [w]. See the field [llvm::GenericValue::IntVal]. *) 44a156efdf71bc668093e31593713694cf076db895Torok Edwin val of_nativeint : Llvm.lltype -> nativeint -> t 45a156efdf71bc668093e31593713694cf076db895Torok Edwin 462e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [of_int64 n w] boxes the int64 [i] in a generic value with the bitwidth 473b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [w]. See the field [llvm::GenericValue::IntVal]. *) 48a156efdf71bc668093e31593713694cf076db895Torok Edwin val of_int64 : Llvm.lltype -> int64 -> t 497b3afb4547c943565e9c5740dd60de3bce5a2793Erick Tryzelaar 502e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [as_float fpty gv] unboxes the floating point-valued generic value [gv] of 512e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen floating point type [fpty]. See the fields [llvm::GenericValue::DoubleVal] 523b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen and [llvm::GenericValue::FloatVal]. *) 53a156efdf71bc668093e31593713694cf076db895Torok Edwin val as_float : Llvm.lltype -> t -> float 542e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 552e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [as_pointer gv] unboxes the pointer-valued generic value [gv]. See the 563b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen field [llvm::GenericValue::PointerVal]. *) 57a156efdf71bc668093e31593713694cf076db895Torok Edwin val as_pointer : t -> 'a 582e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 592e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [as_int32 gv] unboxes the integer-valued generic value [gv] as an [int32]. 602e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen Is invalid if [gv] has a bitwidth greater than 32 bits. See the field 613b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [llvm::GenericValue::IntVal]. *) 62a156efdf71bc668093e31593713694cf076db895Torok Edwin val as_int32 : t -> int32 632e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 642e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [as_int gv] unboxes the integer-valued generic value [gv] as an [int]. 652e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen Is invalid if [gv] has a bitwidth greater than the host bit width (but the 662e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen most significant bit may be lost). See the field 673b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [llvm::GenericValue::IntVal]. *) 68a156efdf71bc668093e31593713694cf076db895Torok Edwin val as_int : t -> int 692e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 702e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [as_natint gv] unboxes the integer-valued generic value [gv] as a 712e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen [nativeint]. Is invalid if [gv] has a bitwidth greater than 723b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [nativeint]. See the field [llvm::GenericValue::IntVal]. *) 73a156efdf71bc668093e31593713694cf076db895Torok Edwin val as_nativeint : t -> nativeint 742e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 752e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [as_int64 gv] returns the integer-valued generic value [gv] as an [int64]. 762e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen Is invalid if [gv] has a bitwidth greater than [int64]. See the field 773b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [llvm::GenericValue::IntVal]. *) 78a156efdf71bc668093e31593713694cf076db895Torok Edwin val as_int64 : t -> int64 792e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksenend 802e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 812e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 822e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksenmodule ExecutionEngine: sig 832e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** An execution engine is either a JIT compiler or an interpreter, capable of 842e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen directly loading an LLVM module and executing its functions without first 853b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen invoking a static compiler and generating a native executable. *) 862e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen type t 872e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 8816609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar (** [create m] creates a new execution engine, taking ownership of the 8916609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar module [m] if successful. Creates a JIT if possible, else falls back to an 9016609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar interpreter. Raises [Error msg] if an error occurrs. The execution engine 9116609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar is not garbage collected and must be destroyed with [dispose ee]. 9216609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar See the function [llvm::EngineBuilder::create]. *) 93a156efdf71bc668093e31593713694cf076db895Torok Edwin val create : Llvm.llmodule -> t 942e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 9516609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar (** [create_interpreter m] creates a new interpreter, taking ownership of the 9616609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar module [m] if successful. Raises [Error msg] if an error occurrs. The 9716609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar execution engine is not garbage collected and must be destroyed with 9816609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar [dispose ee]. 994b1511b027ce0b648b3379f2891816c25b46f515Reid Kleckner See the function [llvm::EngineBuilder::create]. *) 100a156efdf71bc668093e31593713694cf076db895Torok Edwin val create_interpreter : Llvm.llmodule -> t 1012e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 1020dd27da1841ca50d00aad3465f4f9b6a646fd64eErick Tryzelaar (** [create_jit m optlevel] creates a new JIT (just-in-time compiler), taking 1030dd27da1841ca50d00aad3465f4f9b6a646fd64eErick Tryzelaar ownership of the module [m] if successful with the desired optimization 1040dd27da1841ca50d00aad3465f4f9b6a646fd64eErick Tryzelaar level [optlevel]. Raises [Error msg] if an error occurrs. The execution 1050dd27da1841ca50d00aad3465f4f9b6a646fd64eErick Tryzelaar engine is not garbage collected and must be destroyed with [dispose ee]. 1064b1511b027ce0b648b3379f2891816c25b46f515Reid Kleckner See the function [llvm::EngineBuilder::create]. *) 107a156efdf71bc668093e31593713694cf076db895Torok Edwin val create_jit : Llvm.llmodule -> int -> t 1080dd27da1841ca50d00aad3465f4f9b6a646fd64eErick Tryzelaar 1092e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [dispose ee] releases the memory used by the execution engine and must be 1103b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen invoked to avoid memory leaks. *) 111a156efdf71bc668093e31593713694cf076db895Torok Edwin val dispose : t -> unit 112e5de63c7de04c81d7d8484e5b64f47941143c739Peter Zotov 11316609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar (** [add_module m ee] adds the module [m] to the execution engine [ee]. *) 114a156efdf71bc668093e31593713694cf076db895Torok Edwin val add_module : Llvm.llmodule -> t -> unit 1152e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 11616609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar (** [remove_module m ee] removes the module [m] from the execution engine 11716609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar [ee], disposing of [m] and the module referenced by [mp]. Raises 11816609f3c5c26ba34603ae0d7ebab86fb11a72722Erick Tryzelaar [Error msg] if an error occurs. *) 119a156efdf71bc668093e31593713694cf076db895Torok Edwin val remove_module : Llvm.llmodule -> t -> Llvm.llmodule 120a156efdf71bc668093e31593713694cf076db895Torok Edwin 1213b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen (** [find_function n ee] finds the function named [n] defined in any of the 1222e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen modules owned by the execution engine [ee]. Returns [None] if the function 1233b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen is not found and [Some f] otherwise. *) 124a156efdf71bc668093e31593713694cf076db895Torok Edwin val find_function : string -> t -> Llvm.llvalue option 1252e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 1262e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [run_function f args ee] synchronously executes the function [f] with the 1273b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen arguments [args], which must be compatible with the parameter types. *) 128a156efdf71bc668093e31593713694cf076db895Torok Edwin val run_function : Llvm.llvalue -> GenericValue.t array -> t -> 1297b3afb4547c943565e9c5740dd60de3bce5a2793Erick Tryzelaar GenericValue.t 130a156efdf71bc668093e31593713694cf076db895Torok Edwin 1312e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [run_static_ctors ee] executes the static constructors of each module in 1323b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen the execution engine [ee]. *) 133a156efdf71bc668093e31593713694cf076db895Torok Edwin val run_static_ctors : t -> unit 1342e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 1352e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [run_static_dtors ee] executes the static destructors of each module in 1363b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen the execution engine [ee]. *) 137a156efdf71bc668093e31593713694cf076db895Torok Edwin val run_static_dtors : t -> unit 1382e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen 1393b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen (** [run_function_as_main f args env ee] executes the function [f] as a main 1402e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen function, passing it [argv] and [argc] according to the string array 1413b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen [args], and [envp] as specified by the array [env]. Returns the integer 1423b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen return value of the function. *) 143a156efdf71bc668093e31593713694cf076db895Torok Edwin val run_function_as_main : Llvm.llvalue -> string array -> 1447b3afb4547c943565e9c5740dd60de3bce5a2793Erick Tryzelaar (string * string) array -> t -> int 145a156efdf71bc668093e31593713694cf076db895Torok Edwin 1462e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksen (** [free_machine_code f ee] releases the memory in the execution engine [ee] 1473b646de03668fed630f4e3fa9df56a7332a905e4Gordon Henriksen used to store the machine code for the function [f]. *) 148a156efdf71bc668093e31593713694cf076db895Torok Edwin val free_machine_code : Llvm.llvalue -> t -> unit 149a156efdf71bc668093e31593713694cf076db895Torok Edwin 15004deb4957ab253c02bce9d982d69396954744a41Peter Zotov (** [data_layout ee] is the data layout of the execution engine [ee]. *) 15104deb4957ab253c02bce9d982d69396954744a41Peter Zotov val data_layout : t -> Llvm_target.DataLayout.t 1522e855e68d861224c9b61e2bc9cecad1536b1534bGordon Henriksenend 15346262684285cd7baf74425610228ac8b4547dab1Erick Tryzelaar 154cd81d94322a39503e4a3e87b6ee03d4fcb3465fbStephen Hines(** [initialize_native_target ()] initializes the native target corresponding 155cd81d94322a39503e4a3e87b6ee03d4fcb3465fbStephen Hines to the host. Returns [true] if initialization is {b not} done. *) 156a156efdf71bc668093e31593713694cf076db895Torok Edwinval initialize_native_target : unit -> bool 157