LTO

Collaboration diagram for LTO:

Macros
#define	LTO_API_VERSION   23

Typedefs
typedef struct LLVMOpaqueLTOModule *	lto_module_t
	opaque reference to a loaded object module More...
typedef struct LLVMOpaqueLTOCodeGenerator *	lto_code_gen_t
	opaque reference to a code generator More...
typedef struct LLVMOpaqueThinLTOCodeGenerator *	thinlto_code_gen_t
	opaque reference to a thin code generator More...
typedef void(*	lto_diagnostic_handler_t) (lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt)
	Diagnostic handler type. More...

Enumerations
enum	lto_symbol_attributes {   LTO_SYMBOL_ALIGNMENT_MASK = 0x0000001F, LTO_SYMBOL_PERMISSIONS_MASK = 0x000000E0, LTO_SYMBOL_PERMISSIONS_CODE = 0x000000A0, LTO_SYMBOL_PERMISSIONS_DATA = 0x000000C0,   LTO_SYMBOL_PERMISSIONS_RODATA = 0x00000080, LTO_SYMBOL_DEFINITION_MASK = 0x00000700, LTO_SYMBOL_DEFINITION_REGULAR = 0x00000100, LTO_SYMBOL_DEFINITION_TENTATIVE = 0x00000200,   LTO_SYMBOL_DEFINITION_WEAK = 0x00000300, LTO_SYMBOL_DEFINITION_UNDEFINED = 0x00000400, LTO_SYMBOL_DEFINITION_WEAKUNDEF = 0x00000500, LTO_SYMBOL_SCOPE_MASK = 0x00003800,   LTO_SYMBOL_SCOPE_INTERNAL = 0x00000800, LTO_SYMBOL_SCOPE_HIDDEN = 0x00001000, LTO_SYMBOL_SCOPE_PROTECTED = 0x00002000, LTO_SYMBOL_SCOPE_DEFAULT = 0x00001800,   LTO_SYMBOL_SCOPE_DEFAULT_CAN_BE_HIDDEN = 0x00002800, LTO_SYMBOL_COMDAT = 0x00004000, LTO_SYMBOL_ALIAS = 0x00008000 }
enum	lto_debug_model { LTO_DEBUG_MODEL_NONE = 0, LTO_DEBUG_MODEL_DWARF = 1 }
enum	lto_codegen_model { LTO_CODEGEN_PIC_MODEL_STATIC = 0, LTO_CODEGEN_PIC_MODEL_DYNAMIC = 1, LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC = 2, LTO_CODEGEN_PIC_MODEL_DEFAULT = 3 }
enum	lto_codegen_diagnostic_severity_t { LTO_DS_ERROR = 0, LTO_DS_WARNING = 1, LTO_DS_REMARK = 3, LTO_DS_NOTE = 2 }
	Diagnostic severity. More...

Functions
const char *	lto_get_version (void)
	Returns a printable string. More...
const char *	lto_get_error_message (void)
	Returns the last error string or NULL if last operation was successful. More...
lto_bool_t	lto_module_is_object_file (const char *path)
	Checks if a file is a loadable object file. More...
lto_bool_t	lto_module_is_object_file_for_target (const char *path, const char *target_triple_prefix)
	Checks if a file is a loadable object compiled for requested target. More...
lto_bool_t	lto_module_has_objc_category (const void *mem, size_t length)
	Return true if Buffer contains a bitcode file with ObjC code (category or class) in it. More...
lto_bool_t	lto_module_is_object_file_in_memory (const void *mem, size_t length)
	Checks if a buffer is a loadable object file. More...
lto_bool_t	lto_module_is_object_file_in_memory_for_target (const void *mem, size_t length, const char *target_triple_prefix)
	Checks if a buffer is a loadable object compiled for requested target. More...
lto_module_t	lto_module_create (const char *path)
	Loads an object file from disk. More...
lto_module_t	lto_module_create_from_memory (const void *mem, size_t length)
	Loads an object file from memory. More...
lto_module_t	lto_module_create_from_memory_with_path (const void *mem, size_t length, const char *path)
	Loads an object file from memory with an extra path argument. More...
lto_module_t	lto_module_create_in_local_context (const void *mem, size_t length, const char *path)
	Loads an object file in its own context. More...
lto_module_t	lto_module_create_in_codegen_context (const void *mem, size_t length, const char *path, lto_code_gen_t cg)
	Loads an object file in the codegen context. More...
lto_module_t	lto_module_create_from_fd (int fd, const char *path, size_t file_size)
	Loads an object file from disk. More...
lto_module_t	lto_module_create_from_fd_at_offset (int fd, const char *path, size_t file_size, size_t map_size, off_t offset)
	Loads an object file from disk. More...
void	lto_module_dispose (lto_module_t mod)
	Frees all memory internally allocated by the module. More...
const char *	lto_module_get_target_triple (lto_module_t mod)
	Returns triple string which the object module was compiled under. More...
void	lto_module_set_target_triple (lto_module_t mod, const char *triple)
	Sets triple string with which the object will be codegened. More...
unsigned int	lto_module_get_num_symbols (lto_module_t mod)
	Returns the number of symbols in the object module. More...
const char *	lto_module_get_symbol_name (lto_module_t mod, unsigned int index)
	Returns the name of the ith symbol in the object module. More...
lto_symbol_attributes	lto_module_get_symbol_attribute (lto_module_t mod, unsigned int index)
	Returns the attributes of the ith symbol in the object module. More...
const char *	lto_module_get_linkeropts (lto_module_t mod)
	Returns the module's linker options. More...
void	lto_codegen_set_diagnostic_handler (lto_code_gen_t, lto_diagnostic_handler_t, void *)
	Set a diagnostic handler and the related context (void *). More...
lto_code_gen_t	lto_codegen_create (void)
	Instantiates a code generator. More...
lto_code_gen_t	lto_codegen_create_in_local_context (void)
	Instantiate a code generator in its own context. More...
void	lto_codegen_dispose (lto_code_gen_t)
	Frees all code generator and all memory it internally allocated. More...
lto_bool_t	lto_codegen_add_module (lto_code_gen_t cg, lto_module_t mod)
	Add an object module to the set of modules for which code will be generated. More...
void	lto_codegen_set_module (lto_code_gen_t cg, lto_module_t mod)
	Sets the object module for code generation. More...
lto_bool_t	lto_codegen_set_debug_model (lto_code_gen_t cg, lto_debug_model)
	Sets if debug info should be generated. More...
lto_bool_t	lto_codegen_set_pic_model (lto_code_gen_t cg, lto_codegen_model)
	Sets which PIC code model to generated. More...
void	lto_codegen_set_cpu (lto_code_gen_t cg, const char *cpu)
	Sets the cpu to generate code for. More...
void	lto_codegen_set_assembler_path (lto_code_gen_t cg, const char *path)
	Sets the location of the assembler tool to run. More...
void	lto_codegen_set_assembler_args (lto_code_gen_t cg, const char **args, int nargs)
	Sets extra arguments that libLTO should pass to the assembler. More...
void	lto_codegen_add_must_preserve_symbol (lto_code_gen_t cg, const char *symbol)
	Adds to a list of all global symbols that must exist in the final generated code. More...
lto_bool_t	lto_codegen_write_merged_modules (lto_code_gen_t cg, const char *path)
	Writes a new object file at the specified path that contains the merged contents of all modules added so far. More...
const void *	lto_codegen_compile (lto_code_gen_t cg, size_t *length)
	Generates code for all added modules into one native object file. More...
lto_bool_t	lto_codegen_compile_to_file (lto_code_gen_t cg, const char **name)
	Generates code for all added modules into one native object file. More...
lto_bool_t	lto_codegen_optimize (lto_code_gen_t cg)
	Runs optimization for the merged module. More...
const void *	lto_codegen_compile_optimized (lto_code_gen_t cg, size_t *length)
	Generates code for the optimized merged module into one native object file. More...
unsigned int	lto_api_version (void)
	Returns the runtime API version. More...
void	lto_codegen_debug_options (lto_code_gen_t cg, const char *)
	Sets options to help debug codegen bugs. More...
void	lto_initialize_disassembler (void)
	Initializes LLVM disassemblers. More...
void	lto_codegen_set_should_internalize (lto_code_gen_t cg, lto_bool_t ShouldInternalize)
	Sets if we should run internalize pass during optimization and code generation. More...
void	lto_codegen_set_should_embed_uselists (lto_code_gen_t cg, lto_bool_t ShouldEmbedUselists)
	Set whether to embed uselists in bitcode. More...

Detailed Description

Macro Definition Documentation

LTO_API_VERSION

#define LTO_API_VERSION   23

Definition at line 47 of file lto.h.

Typedef Documentation

lto_code_gen_t

typedef struct LLVMOpaqueLTOCodeGenerator* lto_code_gen_t

opaque reference to a code generator

Definition at line 96 of file lto.h.

lto_diagnostic_handler_t

typedef void(* lto_diagnostic_handler_t) (lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt)

Diagnostic handler type.

severity defines the severity. diag is the actual diagnostic. The diagnostic is not prefixed by any of severity keyword, e.g., 'error: '. ctxt is used to pass the context set with the diagnostic handler.

Since

LTO_API_VERSION=7

Definition at line 321 of file lto.h.

lto_module_t

typedef struct LLVMOpaqueLTOModule* lto_module_t

opaque reference to a loaded object module

Definition at line 93 of file lto.h.

thinlto_code_gen_t

typedef struct LLVMOpaqueThinLTOCodeGenerator* thinlto_code_gen_t

opaque reference to a thin code generator

Definition at line 99 of file lto.h.

Enumeration Type Documentation

lto_codegen_diagnostic_severity_t

enum lto_codegen_diagnostic_severity_t

Diagnostic severity.

Since

LTO_API_VERSION=7

Enumerator
LTO_DS_ERROR
LTO_DS_WARNING
LTO_DS_REMARK
LTO_DS_NOTE

Definition at line 305 of file lto.h.

lto_codegen_model

enum lto_codegen_model

Since

prior to LTO_API_VERSION=3

Enumerator
LTO_CODEGEN_PIC_MODEL_STATIC
LTO_CODEGEN_PIC_MODEL_DYNAMIC
LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC
LTO_CODEGEN_PIC_MODEL_DEFAULT

Definition at line 85 of file lto.h.

lto_debug_model

enum lto_debug_model

Since

prior to LTO_API_VERSION=3

Enumerator
LTO_DEBUG_MODEL_NONE
LTO_DEBUG_MODEL_DWARF

Definition at line 77 of file lto.h.

lto_symbol_attributes

enum lto_symbol_attributes

Since

prior to LTO_API_VERSION=3

Enumerator
LTO_SYMBOL_ALIGNMENT_MASK
LTO_SYMBOL_PERMISSIONS_MASK
LTO_SYMBOL_PERMISSIONS_CODE
LTO_SYMBOL_PERMISSIONS_DATA
LTO_SYMBOL_PERMISSIONS_RODATA
LTO_SYMBOL_DEFINITION_MASK
LTO_SYMBOL_DEFINITION_REGULAR
LTO_SYMBOL_DEFINITION_TENTATIVE
LTO_SYMBOL_DEFINITION_WEAK
LTO_SYMBOL_DEFINITION_UNDEFINED
LTO_SYMBOL_DEFINITION_WEAKUNDEF
LTO_SYMBOL_SCOPE_MASK
LTO_SYMBOL_SCOPE_INTERNAL
LTO_SYMBOL_SCOPE_HIDDEN
LTO_SYMBOL_SCOPE_PROTECTED
LTO_SYMBOL_SCOPE_DEFAULT
LTO_SYMBOL_SCOPE_DEFAULT_CAN_BE_HIDDEN
LTO_SYMBOL_COMDAT
LTO_SYMBOL_ALIAS

Definition at line 52 of file lto.h.

Function Documentation

lto_api_version()

unsigned int lto_api_version

(

void

)

Returns the runtime API version.

Since

LTO_API_VERSION=12

lto_codegen_add_module()

lto_bool_t lto_codegen_add_module	(	lto_code_gen_t	cg,
		lto_module_t	mod
	)

Add an object module to the set of modules for which code will be generated.

Returns true on error (check lto_get_error_message() for details).

cg and mod must both be in the same context. See lto_codegen_create_in_local_context() and lto_module_create_in_codegen_context().

Since

prior to LTO_API_VERSION=3

lto_codegen_add_must_preserve_symbol()

void lto_codegen_add_must_preserve_symbol	(	lto_code_gen_t	cg,
		const char *	symbol
	)

Adds to a list of all global symbols that must exist in the final generated code.

If a function is not listed there, it might be inlined into every usage and optimized away.

Since

prior to LTO_API_VERSION=3

lto_codegen_compile()

const void* lto_codegen_compile	(	lto_code_gen_t	cg,
		size_t *	length
	)

Generates code for all added modules into one native object file.

This calls lto_codegen_optimize then lto_codegen_compile_optimized.

On success returns a pointer to a generated mach-o/ELF buffer and length set to the buffer size. The buffer is owned by the lto_code_gen_t and will be freed when lto_codegen_dispose() is called, or lto_codegen_compile() is called again. On failure, returns NULL (check lto_get_error_message() for details).

Since

prior to LTO_API_VERSION=3

lto_codegen_compile_optimized()

const void* lto_codegen_compile_optimized	(	lto_code_gen_t	cg,
		size_t *	length
	)

Generates code for the optimized merged module into one native object file.

It will not run any IR optimizations on the merged module.

On success returns a pointer to a generated mach-o/ELF buffer and length set to the buffer size. The buffer is owned by the lto_code_gen_t and will be freed when lto_codegen_dispose() is called, or lto_codegen_compile_optimized() is called again. On failure, returns NULL (check lto_get_error_message() for details).

Since

LTO_API_VERSION=12

lto_codegen_compile_to_file()

lto_bool_t lto_codegen_compile_to_file	(	lto_code_gen_t	cg,
		const char **	name
	)

Generates code for all added modules into one native object file.

This calls lto_codegen_optimize then lto_codegen_compile_optimized (instead of returning a generated mach-o/ELF buffer, it writes to a file).

The name of the file is written to name. Returns true on error.

Since

LTO_API_VERSION=5

lto_codegen_create()

lto_code_gen_t lto_codegen_create

(

void

)

Instantiates a code generator.

Returns NULL on error (check lto_get_error_message() for details).

All modules added using lto_codegen_add_module() must have been created in the same context as the codegen.

Since

prior to LTO_API_VERSION=3

lto_codegen_create_in_local_context()

lto_code_gen_t lto_codegen_create_in_local_context

(

void

)

Instantiate a code generator in its own context.

Instantiates a code generator in its own context. Modules added via lto_codegen_add_module() must have all been created in the same context, using lto_module_create_in_codegen_context().

Since

LTO_API_VERSION=11

lto_codegen_debug_options()

void lto_codegen_debug_options	(	lto_code_gen_t	cg,
		const char *
	)

Sets options to help debug codegen bugs.

Since

prior to LTO_API_VERSION=3

lto_codegen_dispose()

void lto_codegen_dispose

(

lto_code_gen_t

)

Frees all code generator and all memory it internally allocated.

Upon return the lto_code_gen_t is no longer valid.

Since

prior to LTO_API_VERSION=3

lto_codegen_optimize()

lto_bool_t lto_codegen_optimize

(

lto_code_gen_t

cg

)

Runs optimization for the merged module.

Returns true on error.

Since

LTO_API_VERSION=12

lto_codegen_set_assembler_args()

void lto_codegen_set_assembler_args	(	lto_code_gen_t	cg,
		const char **	args,
		int	nargs
	)

Sets extra arguments that libLTO should pass to the assembler.

Since

LTO_API_VERSION=4

lto_codegen_set_assembler_path()

void lto_codegen_set_assembler_path	(	lto_code_gen_t	cg,
		const char *	path
	)

Sets the location of the assembler tool to run.

If not set, libLTO will use gcc to invoke the assembler.

Since

LTO_API_VERSION=3

lto_codegen_set_cpu()

void lto_codegen_set_cpu	(	lto_code_gen_t	cg,
		const char *	cpu
	)

Sets the cpu to generate code for.

Since

LTO_API_VERSION=4

lto_codegen_set_debug_model()

lto_bool_t lto_codegen_set_debug_model	(	lto_code_gen_t	cg,
		lto_debug_model
	)

Sets if debug info should be generated.

Returns true on error (check lto_get_error_message() for details).

Since

prior to LTO_API_VERSION=3

lto_codegen_set_diagnostic_handler()

void lto_codegen_set_diagnostic_handler	(	lto_code_gen_t	,
		lto_diagnostic_handler_t	,
		void *
	)

Set a diagnostic handler and the related context (void *).

This is more general than lto_get_error_message, as the diagnostic handler can be called at anytime within lto.

Since

LTO_API_VERSION=7

lto_codegen_set_module()

void lto_codegen_set_module	(	lto_code_gen_t	cg,
		lto_module_t	mod
	)

Sets the object module for code generation.

This will transfer the ownership of the module to the code generator.

cg and mod must both be in the same context.

Since

LTO_API_VERSION=13

lto_codegen_set_pic_model()

lto_bool_t lto_codegen_set_pic_model	(	lto_code_gen_t	cg,
		lto_codegen_model
	)

Sets which PIC code model to generated.

Returns true on error (check lto_get_error_message() for details).

Since

prior to LTO_API_VERSION=3

lto_codegen_set_should_embed_uselists()

void lto_codegen_set_should_embed_uselists	(	lto_code_gen_t	cg,
		lto_bool_t	ShouldEmbedUselists
	)

Set whether to embed uselists in bitcode.

Sets whether lto_codegen_write_merged_modules() should embed uselists in output bitcode. This should be turned on for all -save-temps output.

Since

LTO_API_VERSION=15

lto_codegen_set_should_internalize()

void lto_codegen_set_should_internalize	(	lto_code_gen_t	cg,
		lto_bool_t	ShouldInternalize
	)

Sets if we should run internalize pass during optimization and code generation.

Since

LTO_API_VERSION=14

lto_codegen_write_merged_modules()

lto_bool_t lto_codegen_write_merged_modules	(	lto_code_gen_t	cg,
		const char *	path
	)

Writes a new object file at the specified path that contains the merged contents of all modules added so far.

Returns true on error (check lto_get_error_message() for details).

Since

LTO_API_VERSION=5

lto_get_error_message()

const char* lto_get_error_message

(

void

)

Returns the last error string or NULL if last operation was successful.

Since

prior to LTO_API_VERSION=3

lto_get_version()

const char* lto_get_version

(

void

)

Returns a printable string.

Since

prior to LTO_API_VERSION=3

lto_initialize_disassembler()

void lto_initialize_disassembler

(

void

)

Initializes LLVM disassemblers.

FIXME: This doesn't really belong here.

Since

LTO_API_VERSION=5

lto_module_create()

lto_module_t lto_module_create

(

const char *

path

)

Loads an object file from disk.

Returns NULL on error (check lto_get_error_message() for details).

Since

prior to LTO_API_VERSION=3

lto_module_create_from_fd()

lto_module_t lto_module_create_from_fd	(	int	fd,
		const char *	path,
		size_t	file_size
	)

Loads an object file from disk.

The seek point of fd is not preserved. Returns NULL on error (check lto_get_error_message() for details).

Since

LTO_API_VERSION=5

lto_module_create_from_fd_at_offset()

lto_module_t lto_module_create_from_fd_at_offset	(	int	fd,
		const char *	path,
		size_t	file_size,
		size_t	map_size,
		off_t	offset
	)

Loads an object file from disk.

The seek point of fd is not preserved. Returns NULL on error (check lto_get_error_message() for details).

Since

LTO_API_VERSION=5

lto_module_create_from_memory()

lto_module_t lto_module_create_from_memory	(	const void *	mem,
		size_t	length
	)

Loads an object file from memory.

Returns NULL on error (check lto_get_error_message() for details).

Since

prior to LTO_API_VERSION=3

lto_module_create_from_memory_with_path()

lto_module_t lto_module_create_from_memory_with_path	(	const void *	mem,
		size_t	length,
		const char *	path
	)

Loads an object file from memory with an extra path argument.

Returns NULL on error (check lto_get_error_message() for details).

Since

LTO_API_VERSION=9

lto_module_create_in_codegen_context()

lto_module_t lto_module_create_in_codegen_context	(	const void *	mem,
		size_t	length,
		const char *	path,
		lto_code_gen_t	cg
	)

Loads an object file in the codegen context.

Loads an object file into the same context as cg. The module is safe to add using lto_codegen_add_module().

Returns NULL on error (check lto_get_error_message() for details).

Since

LTO_API_VERSION=11

lto_module_create_in_local_context()

lto_module_t lto_module_create_in_local_context	(	const void *	mem,
		size_t	length,
		const char *	path
	)

Loads an object file in its own context.

Loads an object file in its own LLVMContext. This function call is thread-safe. However, modules created this way should not be merged into an lto_code_gen_t using lto_codegen_add_module().

Returns NULL on error (check lto_get_error_message() for details).

Since

LTO_API_VERSION=11

lto_module_dispose()

void lto_module_dispose

(

lto_module_t

mod

)

Frees all memory internally allocated by the module.

Upon return the lto_module_t is no longer valid.

Since

prior to LTO_API_VERSION=3

lto_module_get_linkeropts()

const char* lto_module_get_linkeropts

(

lto_module_t

mod

)

Returns the module's linker options.

The linker options may consist of multiple flags. It is the linker's responsibility to split the flags using a platform-specific mechanism.

Since

LTO_API_VERSION=16

lto_module_get_num_symbols()

unsigned int lto_module_get_num_symbols

(

lto_module_t

mod

)

Returns the number of symbols in the object module.

Since

prior to LTO_API_VERSION=3

lto_module_get_symbol_attribute()

lto_symbol_attributes lto_module_get_symbol_attribute	(	lto_module_t	mod,
		unsigned int	index
	)

Returns the attributes of the ith symbol in the object module.

Since

prior to LTO_API_VERSION=3

lto_module_get_symbol_name()

const char* lto_module_get_symbol_name	(	lto_module_t	mod,
		unsigned int	index
	)

Returns the name of the ith symbol in the object module.

Since

prior to LTO_API_VERSION=3

lto_module_get_target_triple()

const char* lto_module_get_target_triple

(

lto_module_t

mod

)

Returns triple string which the object module was compiled under.

Since

prior to LTO_API_VERSION=3

lto_module_has_objc_category()

lto_bool_t lto_module_has_objc_category	(	const void *	mem,
		size_t	length
	)

Return true if Buffer contains a bitcode file with ObjC code (category or class) in it.

Since

LTO_API_VERSION=20

lto_module_is_object_file()

lto_bool_t lto_module_is_object_file

(

const char *

path

)

Checks if a file is a loadable object file.

Since

prior to LTO_API_VERSION=3

lto_module_is_object_file_for_target()

lto_bool_t lto_module_is_object_file_for_target	(	const char *	path,
		const char *	target_triple_prefix
	)

Checks if a file is a loadable object compiled for requested target.

Since

prior to LTO_API_VERSION=3

lto_module_is_object_file_in_memory()

lto_bool_t lto_module_is_object_file_in_memory	(	const void *	mem,
		size_t	length
	)

Checks if a buffer is a loadable object file.

Since

prior to LTO_API_VERSION=3

lto_module_is_object_file_in_memory_for_target()

lto_bool_t lto_module_is_object_file_in_memory_for_target	(	const void *	mem,
		size_t	length,
		const char *	target_triple_prefix
	)

Checks if a buffer is a loadable object compiled for requested target.

Since

prior to LTO_API_VERSION=3

lto_module_set_target_triple()

void lto_module_set_target_triple	(	lto_module_t	mod,
		const char *	triple
	)

Sets triple string with which the object will be codegened.

Since

LTO_API_VERSION=4