LLVM API Documentation

lto.h

Go to the documentation of this file.
00001 /*===-- llvm-c/lto.h - LTO Public C Interface ---------------------*- C -*-===*\
00002 |*                                                                            *|
00003 |*                     The LLVM Compiler Infrastructure                       *|
00004 |*                                                                            *|
00005 |* This file is distributed under the University of Illinois Open Source      *|
00006 |* License. See LICENSE.TXT for details.                                      *|
00007 |*                                                                            *|
00008 |*===----------------------------------------------------------------------===*|
00009 |*                                                                            *|
00010 |* This header provides public interface to an abstract link time optimization*|
00011 |* library.  LLVM provides an implementation of this interface for use with   *|
00012 |* llvm bitcode files.                                                        *|
00013 |*                                                                            *|
00014 \*===----------------------------------------------------------------------===*/
00015 
00016 #ifndef LTO_H
00017 #define LTO_H  1
00018 
00019 #include <stdbool.h>
00020 #include <stddef.h>
00021 
00022 #define LTO_API_VERSION 3
00023 
00024 typedef enum {
00025     LTO_SYMBOL_ALIGNMENT_MASK         = 0x0000001F,    /* log2 of alignment */
00026     LTO_SYMBOL_PERMISSIONS_MASK       = 0x000000E0,    
00027     LTO_SYMBOL_PERMISSIONS_CODE       = 0x000000A0,    
00028     LTO_SYMBOL_PERMISSIONS_DATA       = 0x000000C0,    
00029     LTO_SYMBOL_PERMISSIONS_RODATA     = 0x00000080,    
00030     LTO_SYMBOL_DEFINITION_MASK        = 0x00000700,    
00031     LTO_SYMBOL_DEFINITION_REGULAR     = 0x00000100,    
00032     LTO_SYMBOL_DEFINITION_TENTATIVE   = 0x00000200,    
00033     LTO_SYMBOL_DEFINITION_WEAK        = 0x00000300,    
00034     LTO_SYMBOL_DEFINITION_UNDEFINED   = 0x00000400,    
00035     LTO_SYMBOL_DEFINITION_WEAKUNDEF   = 0x00000500,
00036     LTO_SYMBOL_SCOPE_MASK             = 0x00003800,    
00037     LTO_SYMBOL_SCOPE_INTERNAL         = 0x00000800,    
00038     LTO_SYMBOL_SCOPE_HIDDEN           = 0x00001000,    
00039     LTO_SYMBOL_SCOPE_PROTECTED        = 0x00002000,    
00040     LTO_SYMBOL_SCOPE_DEFAULT          = 0x00001800    
00041 } lto_symbol_attributes;
00042 
00043 typedef enum {
00044     LTO_DEBUG_MODEL_NONE         = 0,
00045     LTO_DEBUG_MODEL_DWARF        = 1
00046 } lto_debug_model;
00047 
00048 typedef enum {
00049     LTO_CODEGEN_PIC_MODEL_STATIC         = 0,
00050     LTO_CODEGEN_PIC_MODEL_DYNAMIC        = 1,
00051     LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC = 2
00052 } lto_codegen_model;
00053 
00054 
00055 /** opaque reference to a loaded object module */
00056 typedef struct LTOModule*         lto_module_t;
00057 
00058 /** opaque reference to a code generator */
00059 typedef struct LTOCodeGenerator*  lto_code_gen_t;
00060 
00061 #ifdef __cplusplus
00062 extern "C" {
00063 #endif
00064 
00065 /**
00066  * Returns a printable string.
00067  */
00068 extern const char*
00069 lto_get_version(void);
00070 
00071 
00072 /**
00073  * Returns the last error string or NULL if last operation was sucessful.
00074  */
00075 extern const char*
00076 lto_get_error_message(void);
00077 
00078 /**
00079  * Checks if a file is a loadable object file.
00080  */
00081 extern bool
00082 lto_module_is_object_file(const char* path);
00083 
00084 
00085 /**
00086  * Checks if a file is a loadable object compiled for requested target.
00087  */
00088 extern bool
00089 lto_module_is_object_file_for_target(const char* path, 
00090                                      const char* target_triple_prefix);
00091 
00092 
00093 /**
00094  * Checks if a buffer is a loadable object file.
00095  */
00096 extern bool
00097 lto_module_is_object_file_in_memory(const void* mem, size_t length);
00098 
00099 
00100 /**
00101  * Checks if a buffer is a loadable object compiled for requested target.
00102  */
00103 extern bool
00104 lto_module_is_object_file_in_memory_for_target(const void* mem, size_t length, 
00105                                                const char* target_triple_prefix);
00106 
00107 
00108 /**
00109  * Loads an object file from disk.
00110  * Returns NULL on error (check lto_get_error_message() for details).
00111  */
00112 extern lto_module_t
00113 lto_module_create(const char* path);
00114 
00115 
00116 /**
00117  * Loads an object file from memory.
00118  * Returns NULL on error (check lto_get_error_message() for details).
00119  */
00120 extern lto_module_t
00121 lto_module_create_from_memory(const void* mem, size_t length);
00122 
00123 
00124 /**
00125  * Frees all memory internally allocated by the module.
00126  * Upon return the lto_module_t is no longer valid.
00127  */
00128 extern void
00129 lto_module_dispose(lto_module_t mod);
00130 
00131 
00132 /**
00133  * Returns triple string which the object module was compiled under.
00134  */
00135 extern const char*
00136 lto_module_get_target_triple(lto_module_t mod);
00137 
00138 
00139 /**
00140  * Returns the number of symbols in the object module.
00141  */
00142 extern unsigned int
00143 lto_module_get_num_symbols(lto_module_t mod);
00144 
00145 
00146 /**
00147  * Returns the name of the ith symbol in the object module.
00148  */
00149 extern const char*
00150 lto_module_get_symbol_name(lto_module_t mod, unsigned int index);
00151 
00152 
00153 /**
00154  * Returns the attributes of the ith symbol in the object module.
00155  */
00156 extern lto_symbol_attributes
00157 lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index);
00158 
00159 
00160 /**
00161  * Instantiates a code generator.
00162  * Returns NULL on error (check lto_get_error_message() for details).
00163  */
00164 extern lto_code_gen_t
00165 lto_codegen_create(void);
00166 
00167 
00168 /**
00169  * Frees all code generator and all memory it internally allocated.
00170  * Upon return the lto_code_gen_t is no longer valid.
00171  */
00172 extern void
00173 lto_codegen_dispose(lto_code_gen_t);
00174 
00175 
00176 
00177 /**
00178  * Add an object module to the set of modules for which code will be generated.
00179  * Returns true on error (check lto_get_error_message() for details).
00180  */
00181 extern bool
00182 lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod);
00183 
00184 
00185 
00186 /**
00187  * Sets if debug info should be generated.
00188  * Returns true on error (check lto_get_error_message() for details).
00189  */
00190 extern bool
00191 lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model);
00192 
00193 
00194 /**
00195  * Sets which PIC code model to generated.
00196  * Returns true on error (check lto_get_error_message() for details).
00197  */
00198 extern bool
00199 lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model);
00200 
00201 
00202 /**
00203  * Sets the location of the "gcc" to run. If not set, libLTO will search for
00204  * "gcc" on the path.
00205  */
00206 extern void
00207 lto_codegen_set_gcc_path(lto_code_gen_t cg, const char* path);
00208 
00209 
00210 /**
00211  * Sets the location of the assembler tool to run. If not set, libLTO
00212  * will use gcc to invoke the assembler.
00213  */
00214 extern void
00215 lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path);
00216 
00217 
00218 /**
00219  * Adds to a list of all global symbols that must exist in the final
00220  * generated code.  If a function is not listed, it might be
00221  * inlined into every usage and optimized away.
00222  */
00223 extern void
00224 lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol);
00225 
00226 
00227 /**
00228  * Writes a new object file at the specified path that contains the
00229  * merged contents of all modules added so far.
00230  * Returns true on error (check lto_get_error_message() for details).
00231  */
00232 extern bool
00233 lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path);
00234 
00235 
00236 /**
00237  * Generates code for all added modules into one native object file.
00238  * On sucess returns a pointer to a generated mach-o/ELF buffer and
00239  * length set to the buffer size.  The buffer is owned by the 
00240  * lto_code_gen_t and will be freed when lto_codegen_dispose()
00241  * is called, or lto_codegen_compile() is called again.
00242  * On failure, returns NULL (check lto_get_error_message() for details).
00243  */
00244 extern const void*
00245 lto_codegen_compile(lto_code_gen_t cg, size_t* length);
00246 
00247 
00248 /**
00249  * Sets options to help debug codegen bugs.
00250  */
00251 extern void
00252 lto_codegen_debug_options(lto_code_gen_t cg, const char *);
00253 #ifdef __cplusplus
00254 }
00255 #endif
00256 
00257 
00258 #endif