lto.h revision 193574 
1/*===-- llvm-c/lto.h - LTO Public C Interface ---------------------*- C -*-===*\
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|* This header provides public interface to an abstract link time optimization*|
11|* library.  LLVM provides an implementation of this interface for use with   *|
12|* llvm bitcode files.                                                        *|
13|*                                                                            *|
14\*===----------------------------------------------------------------------===*/
15
16#ifndef LTO_H
17#define LTO_H  1
18
19#include <stdbool.h>
20#include <stddef.h>
21
22#define LTO_API_VERSION 3
23
24typedef enum {
25    LTO_SYMBOL_ALIGNMENT_MASK         = 0x0000001F,    /* log2 of alignment */
26    LTO_SYMBOL_PERMISSIONS_MASK       = 0x000000E0,
27    LTO_SYMBOL_PERMISSIONS_CODE       = 0x000000A0,
28    LTO_SYMBOL_PERMISSIONS_DATA       = 0x000000C0,
29    LTO_SYMBOL_PERMISSIONS_RODATA     = 0x00000080,
30    LTO_SYMBOL_DEFINITION_MASK        = 0x00000700,
31    LTO_SYMBOL_DEFINITION_REGULAR     = 0x00000100,
32    LTO_SYMBOL_DEFINITION_TENTATIVE   = 0x00000200,
33    LTO_SYMBOL_DEFINITION_WEAK        = 0x00000300,
34    LTO_SYMBOL_DEFINITION_UNDEFINED   = 0x00000400,
35    LTO_SYMBOL_DEFINITION_WEAKUNDEF   = 0x00000500,
36    LTO_SYMBOL_SCOPE_MASK             = 0x00003800,
37    LTO_SYMBOL_SCOPE_INTERNAL         = 0x00000800,
38    LTO_SYMBOL_SCOPE_HIDDEN           = 0x00001000,
39    LTO_SYMBOL_SCOPE_PROTECTED        = 0x00002000,
40    LTO_SYMBOL_SCOPE_DEFAULT          = 0x00001800
41} lto_symbol_attributes;
42
43typedef enum {
44    LTO_DEBUG_MODEL_NONE         = 0,
45    LTO_DEBUG_MODEL_DWARF        = 1
46} lto_debug_model;
47
48typedef enum {
49    LTO_CODEGEN_PIC_MODEL_STATIC         = 0,
50    LTO_CODEGEN_PIC_MODEL_DYNAMIC        = 1,
51    LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC = 2
52} lto_codegen_model;
53
54
55/** opaque reference to a loaded object module */
56typedef struct LTOModule*         lto_module_t;
57
58/** opaque reference to a code generator */
59typedef struct LTOCodeGenerator*  lto_code_gen_t;
60
61
62#ifdef __cplusplus
63extern "C" {
64#endif
65
66/**
67 * Returns a printable string.
68 */
69extern const char*
70lto_get_version(void);
71
72
73/**
74 * Returns the last error string or NULL if last operation was sucessful.
75 */
76extern const char*
77lto_get_error_message(void);
78
79
80/**
81 * Checks if a file is a loadable object file.
82 */
83extern bool
84lto_module_is_object_file(const char* path);
85
86
87/**
88 * Checks if a file is a loadable object compiled for requested target.
89 */
90extern bool
91lto_module_is_object_file_for_target(const char* path,
92                                     const char* target_triple_prefix);
93
94
95/**
96 * Checks if a buffer is a loadable object file.
97 */
98extern bool
99lto_module_is_object_file_in_memory(const void* mem, size_t length);
100
101
102/**
103 * Checks if a buffer is a loadable object compiled for requested target.
104 */
105extern bool
106lto_module_is_object_file_in_memory_for_target(const void* mem, size_t length,
107                                               const char* target_triple_prefix);
108
109
110/**
111 * Loads an object file from disk.
112 * Returns NULL on error (check lto_get_error_message() for details).
113 */
114extern lto_module_t
115lto_module_create(const char* path);
116
117
118/**
119 * Loads an object file from memory.
120 * Returns NULL on error (check lto_get_error_message() for details).
121 */
122extern lto_module_t
123lto_module_create_from_memory(const void* mem, size_t length);
124
125
126/**
127 * Frees all memory internally allocated by the module.
128 * Upon return the lto_module_t is no longer valid.
129 */
130extern void
131lto_module_dispose(lto_module_t mod);
132
133
134/**
135 * Returns triple string which the object module was compiled under.
136 */
137extern const char*
138lto_module_get_target_triple(lto_module_t mod);
139
140
141/**
142 * Returns the number of symbols in the object module.
143 */
144extern unsigned int
145lto_module_get_num_symbols(lto_module_t mod);
146
147
148/**
149 * Returns the name of the ith symbol in the object module.
150 */
151extern const char*
152lto_module_get_symbol_name(lto_module_t mod, unsigned int index);
153
154
155/**
156 * Returns the attributes of the ith symbol in the object module.
157 */
158extern lto_symbol_attributes
159lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index);
160
161
162/**
163 * Instantiates a code generator.
164 * Returns NULL on error (check lto_get_error_message() for details).
165 */
166extern lto_code_gen_t
167lto_codegen_create(void);
168
169
170/**
171 * Frees all code generator and all memory it internally allocated.
172 * Upon return the lto_code_gen_t is no longer valid.
173 */
174extern void
175lto_codegen_dispose(lto_code_gen_t);
176
177
178
179/**
180 * Add an object module to the set of modules for which code will be generated.
181 * Returns true on error (check lto_get_error_message() for details).
182 */
183extern bool
184lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod);
185
186
187
188/**
189 * Sets if debug info should be generated.
190 * Returns true on error (check lto_get_error_message() for details).
191 */
192extern bool
193lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model);
194
195
196/**
197 * Sets which PIC code model to generated.
198 * Returns true on error (check lto_get_error_message() for details).
199 */
200extern bool
201lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model);
202
203
204/**
205 * Sets the location of the "gcc" to run. If not set, libLTO will search for
206 * "gcc" on the path.
207 */
208extern void
209lto_codegen_set_gcc_path(lto_code_gen_t cg, const char* path);
210
211
212/**
213 * Sets the location of the assembler tool to run. If not set, libLTO
214 * will use gcc to invoke the assembler.
215 */
216extern void
217lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path);
218
219
220/**
221 * Adds to a list of all global symbols that must exist in the final
222 * generated code.  If a function is not listed, it might be
223 * inlined into every usage and optimized away.
224 */
225extern void
226lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol);
227
228
229/**
230 * Writes a new object file at the specified path that contains the
231 * merged contents of all modules added so far.
232 * Returns true on error (check lto_get_error_message() for details).
233 */
234extern bool
235lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path);
236
237
238/**
239 * Generates code for all added modules into one native object file.
240 * On sucess returns a pointer to a generated mach-o/ELF buffer and
241 * length set to the buffer size.  The buffer is owned by the
242 * lto_code_gen_t and will be freed when lto_codegen_dispose()
243 * is called, or lto_codegen_compile() is called again.
244 * On failure, returns NULL (check lto_get_error_message() for details).
245 */
246extern const void*
247lto_codegen_compile(lto_code_gen_t cg, size_t* length);
248
249
250/**
251 * Sets options to help debug codegen bugs.
252 */
253extern void
254lto_codegen_debug_options(lto_code_gen_t cg, const char *);
255#ifdef __cplusplus
256}
257#endif
258
259
260#endif
261