]>
Commit | Line | Data |
---|---|---|
223e47cc LB |
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 | ||
970d7e83 LB |
16 | #ifndef LLVM_C_LTO_H |
17 | #define LLVM_C_LTO_H | |
223e47cc | 18 | |
223e47cc | 19 | #include <stddef.h> |
1a4d82fc JJ |
20 | #include <sys/types.h> |
21 | ||
22 | #ifndef __cplusplus | |
23 | #if !defined(_MSC_VER) | |
24 | #include <stdbool.h> | |
25 | typedef bool lto_bool_t; | |
26 | #else | |
27 | /* MSVC in particular does not have anything like _Bool or bool in C, but we can | |
28 | at least make sure the type is the same size. The implementation side will | |
29 | use C++ bool. */ | |
30 | typedef unsigned char lto_bool_t; | |
31 | #endif | |
32 | #else | |
33 | typedef bool lto_bool_t; | |
34 | #endif | |
223e47cc LB |
35 | |
36 | /** | |
37 | * @defgroup LLVMCLTO LTO | |
38 | * @ingroup LLVMC | |
39 | * | |
40 | * @{ | |
41 | */ | |
42 | ||
85aaf69f | 43 | #define LTO_API_VERSION 11 |
223e47cc | 44 | |
1a4d82fc JJ |
45 | /** |
46 | * \since prior to LTO_API_VERSION=3 | |
47 | */ | |
223e47cc LB |
48 | typedef enum { |
49 | LTO_SYMBOL_ALIGNMENT_MASK = 0x0000001F, /* log2 of alignment */ | |
50 | LTO_SYMBOL_PERMISSIONS_MASK = 0x000000E0, | |
51 | LTO_SYMBOL_PERMISSIONS_CODE = 0x000000A0, | |
52 | LTO_SYMBOL_PERMISSIONS_DATA = 0x000000C0, | |
53 | LTO_SYMBOL_PERMISSIONS_RODATA = 0x00000080, | |
54 | LTO_SYMBOL_DEFINITION_MASK = 0x00000700, | |
55 | LTO_SYMBOL_DEFINITION_REGULAR = 0x00000100, | |
56 | LTO_SYMBOL_DEFINITION_TENTATIVE = 0x00000200, | |
57 | LTO_SYMBOL_DEFINITION_WEAK = 0x00000300, | |
58 | LTO_SYMBOL_DEFINITION_UNDEFINED = 0x00000400, | |
59 | LTO_SYMBOL_DEFINITION_WEAKUNDEF = 0x00000500, | |
60 | LTO_SYMBOL_SCOPE_MASK = 0x00003800, | |
61 | LTO_SYMBOL_SCOPE_INTERNAL = 0x00000800, | |
62 | LTO_SYMBOL_SCOPE_HIDDEN = 0x00001000, | |
63 | LTO_SYMBOL_SCOPE_PROTECTED = 0x00002000, | |
64 | LTO_SYMBOL_SCOPE_DEFAULT = 0x00001800, | |
65 | LTO_SYMBOL_SCOPE_DEFAULT_CAN_BE_HIDDEN = 0x00002800 | |
66 | } lto_symbol_attributes; | |
67 | ||
1a4d82fc JJ |
68 | /** |
69 | * \since prior to LTO_API_VERSION=3 | |
70 | */ | |
223e47cc LB |
71 | typedef enum { |
72 | LTO_DEBUG_MODEL_NONE = 0, | |
73 | LTO_DEBUG_MODEL_DWARF = 1 | |
74 | } lto_debug_model; | |
75 | ||
1a4d82fc JJ |
76 | /** |
77 | * \since prior to LTO_API_VERSION=3 | |
78 | */ | |
223e47cc LB |
79 | typedef enum { |
80 | LTO_CODEGEN_PIC_MODEL_STATIC = 0, | |
81 | LTO_CODEGEN_PIC_MODEL_DYNAMIC = 1, | |
1a4d82fc JJ |
82 | LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC = 2, |
83 | LTO_CODEGEN_PIC_MODEL_DEFAULT = 3 | |
223e47cc LB |
84 | } lto_codegen_model; |
85 | ||
223e47cc | 86 | /** opaque reference to a loaded object module */ |
1a4d82fc | 87 | typedef struct LLVMOpaqueLTOModule *lto_module_t; |
223e47cc LB |
88 | |
89 | /** opaque reference to a code generator */ | |
1a4d82fc | 90 | typedef struct LLVMOpaqueLTOCodeGenerator *lto_code_gen_t; |
223e47cc LB |
91 | |
92 | #ifdef __cplusplus | |
93 | extern "C" { | |
94 | #endif | |
95 | ||
96 | /** | |
97 | * Returns a printable string. | |
1a4d82fc JJ |
98 | * |
99 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
100 | */ |
101 | extern const char* | |
102 | lto_get_version(void); | |
103 | ||
104 | ||
105 | /** | |
106 | * Returns the last error string or NULL if last operation was successful. | |
1a4d82fc JJ |
107 | * |
108 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
109 | */ |
110 | extern const char* | |
111 | lto_get_error_message(void); | |
112 | ||
113 | /** | |
114 | * Checks if a file is a loadable object file. | |
1a4d82fc JJ |
115 | * |
116 | * \since prior to LTO_API_VERSION=3 | |
223e47cc | 117 | */ |
1a4d82fc | 118 | extern lto_bool_t |
223e47cc LB |
119 | lto_module_is_object_file(const char* path); |
120 | ||
121 | ||
122 | /** | |
123 | * Checks if a file is a loadable object compiled for requested target. | |
1a4d82fc JJ |
124 | * |
125 | * \since prior to LTO_API_VERSION=3 | |
223e47cc | 126 | */ |
1a4d82fc | 127 | extern lto_bool_t |
223e47cc LB |
128 | lto_module_is_object_file_for_target(const char* path, |
129 | const char* target_triple_prefix); | |
130 | ||
131 | ||
132 | /** | |
133 | * Checks if a buffer is a loadable object file. | |
1a4d82fc JJ |
134 | * |
135 | * \since prior to LTO_API_VERSION=3 | |
223e47cc | 136 | */ |
1a4d82fc | 137 | extern lto_bool_t |
223e47cc LB |
138 | lto_module_is_object_file_in_memory(const void* mem, size_t length); |
139 | ||
140 | ||
141 | /** | |
142 | * Checks if a buffer is a loadable object compiled for requested target. | |
1a4d82fc JJ |
143 | * |
144 | * \since prior to LTO_API_VERSION=3 | |
223e47cc | 145 | */ |
1a4d82fc | 146 | extern lto_bool_t |
223e47cc LB |
147 | lto_module_is_object_file_in_memory_for_target(const void* mem, size_t length, |
148 | const char* target_triple_prefix); | |
149 | ||
150 | ||
151 | /** | |
152 | * Loads an object file from disk. | |
153 | * Returns NULL on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
154 | * |
155 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
156 | */ |
157 | extern lto_module_t | |
158 | lto_module_create(const char* path); | |
159 | ||
160 | ||
161 | /** | |
162 | * Loads an object file from memory. | |
163 | * Returns NULL on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
164 | * |
165 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
166 | */ |
167 | extern lto_module_t | |
168 | lto_module_create_from_memory(const void* mem, size_t length); | |
169 | ||
1a4d82fc JJ |
170 | /** |
171 | * Loads an object file from memory with an extra path argument. | |
172 | * Returns NULL on error (check lto_get_error_message() for details). | |
173 | * | |
174 | * \since prior to LTO_API_VERSION=9 | |
175 | */ | |
176 | extern lto_module_t | |
177 | lto_module_create_from_memory_with_path(const void* mem, size_t length, | |
178 | const char *path); | |
179 | ||
85aaf69f SL |
180 | /** |
181 | * \brief Loads an object file in its own context. | |
182 | * | |
183 | * Loads an object file in its own LLVMContext. This function call is | |
184 | * thread-safe. However, modules created this way should not be merged into an | |
185 | * lto_code_gen_t using \a lto_codegen_add_module(). | |
186 | * | |
187 | * Returns NULL on error (check lto_get_error_message() for details). | |
188 | * | |
189 | * \since LTO_API_VERSION=11 | |
190 | */ | |
191 | extern lto_module_t | |
192 | lto_module_create_in_local_context(const void *mem, size_t length, | |
193 | const char *path); | |
194 | ||
195 | /** | |
196 | * \brief Loads an object file in the codegen context. | |
197 | * | |
198 | * Loads an object file into the same context as \c cg. The module is safe to | |
199 | * add using \a lto_codegen_add_module(). | |
200 | * | |
201 | * Returns NULL on error (check lto_get_error_message() for details). | |
202 | * | |
203 | * \since LTO_API_VERSION=11 | |
204 | */ | |
205 | extern lto_module_t | |
206 | lto_module_create_in_codegen_context(const void *mem, size_t length, | |
207 | const char *path, lto_code_gen_t cg); | |
208 | ||
223e47cc LB |
209 | /** |
210 | * Loads an object file from disk. The seek point of fd is not preserved. | |
211 | * Returns NULL on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
212 | * |
213 | * \since LTO_API_VERSION=5 | |
223e47cc LB |
214 | */ |
215 | extern lto_module_t | |
216 | lto_module_create_from_fd(int fd, const char *path, size_t file_size); | |
217 | ||
218 | /** | |
219 | * Loads an object file from disk. The seek point of fd is not preserved. | |
220 | * Returns NULL on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
221 | * |
222 | * \since LTO_API_VERSION=5 | |
223e47cc LB |
223 | */ |
224 | extern lto_module_t | |
225 | lto_module_create_from_fd_at_offset(int fd, const char *path, size_t file_size, | |
226 | size_t map_size, off_t offset); | |
227 | ||
223e47cc LB |
228 | /** |
229 | * Frees all memory internally allocated by the module. | |
230 | * Upon return the lto_module_t is no longer valid. | |
1a4d82fc JJ |
231 | * |
232 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
233 | */ |
234 | extern void | |
235 | lto_module_dispose(lto_module_t mod); | |
236 | ||
223e47cc LB |
237 | /** |
238 | * Returns triple string which the object module was compiled under. | |
1a4d82fc JJ |
239 | * |
240 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
241 | */ |
242 | extern const char* | |
243 | lto_module_get_target_triple(lto_module_t mod); | |
244 | ||
245 | /** | |
246 | * Sets triple string with which the object will be codegened. | |
1a4d82fc JJ |
247 | * |
248 | * \since LTO_API_VERSION=4 | |
223e47cc LB |
249 | */ |
250 | extern void | |
251 | lto_module_set_target_triple(lto_module_t mod, const char *triple); | |
252 | ||
253 | ||
254 | /** | |
255 | * Returns the number of symbols in the object module. | |
1a4d82fc JJ |
256 | * |
257 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
258 | */ |
259 | extern unsigned int | |
260 | lto_module_get_num_symbols(lto_module_t mod); | |
261 | ||
262 | ||
263 | /** | |
264 | * Returns the name of the ith symbol in the object module. | |
1a4d82fc JJ |
265 | * |
266 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
267 | */ |
268 | extern const char* | |
269 | lto_module_get_symbol_name(lto_module_t mod, unsigned int index); | |
270 | ||
271 | ||
272 | /** | |
273 | * Returns the attributes of the ith symbol in the object module. | |
1a4d82fc JJ |
274 | * |
275 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
276 | */ |
277 | extern lto_symbol_attributes | |
278 | lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index); | |
279 | ||
280 | ||
1a4d82fc JJ |
281 | /** |
282 | * Returns the number of dependent libraries in the object module. | |
283 | * | |
284 | * \since LTO_API_VERSION=8 | |
285 | */ | |
286 | extern unsigned int | |
287 | lto_module_get_num_deplibs(lto_module_t mod); | |
288 | ||
289 | ||
290 | /** | |
291 | * Returns the ith dependent library in the module. | |
292 | * | |
293 | * \since LTO_API_VERSION=8 | |
294 | */ | |
295 | extern const char* | |
296 | lto_module_get_deplib(lto_module_t mod, unsigned int index); | |
297 | ||
298 | ||
299 | /** | |
300 | * Returns the number of linker options in the object module. | |
301 | * | |
302 | * \since LTO_API_VERSION=8 | |
303 | */ | |
304 | extern unsigned int | |
305 | lto_module_get_num_linkeropts(lto_module_t mod); | |
306 | ||
307 | ||
308 | /** | |
309 | * Returns the ith linker option in the module. | |
310 | * | |
311 | * \since LTO_API_VERSION=8 | |
312 | */ | |
313 | extern const char* | |
314 | lto_module_get_linkeropt(lto_module_t mod, unsigned int index); | |
315 | ||
316 | ||
317 | /** | |
318 | * Diagnostic severity. | |
319 | * | |
320 | * \since LTO_API_VERSION=7 | |
321 | */ | |
322 | typedef enum { | |
323 | LTO_DS_ERROR = 0, | |
324 | LTO_DS_WARNING = 1, | |
325 | LTO_DS_REMARK = 3, // Added in LTO_API_VERSION=10. | |
326 | LTO_DS_NOTE = 2 | |
327 | } lto_codegen_diagnostic_severity_t; | |
328 | ||
329 | /** | |
330 | * Diagnostic handler type. | |
331 | * \p severity defines the severity. | |
332 | * \p diag is the actual diagnostic. | |
333 | * The diagnostic is not prefixed by any of severity keyword, e.g., 'error: '. | |
334 | * \p ctxt is used to pass the context set with the diagnostic handler. | |
335 | * | |
336 | * \since LTO_API_VERSION=7 | |
337 | */ | |
338 | typedef void (*lto_diagnostic_handler_t)( | |
339 | lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt); | |
340 | ||
341 | /** | |
342 | * Set a diagnostic handler and the related context (void *). | |
343 | * This is more general than lto_get_error_message, as the diagnostic handler | |
344 | * can be called at anytime within lto. | |
345 | * | |
346 | * \since LTO_API_VERSION=7 | |
347 | */ | |
348 | extern void lto_codegen_set_diagnostic_handler(lto_code_gen_t, | |
349 | lto_diagnostic_handler_t, | |
350 | void *); | |
351 | ||
223e47cc LB |
352 | /** |
353 | * Instantiates a code generator. | |
354 | * Returns NULL on error (check lto_get_error_message() for details). | |
1a4d82fc | 355 | * |
85aaf69f SL |
356 | * All modules added using \a lto_codegen_add_module() must have been created |
357 | * in the same context as the codegen. | |
358 | * | |
1a4d82fc | 359 | * \since prior to LTO_API_VERSION=3 |
223e47cc LB |
360 | */ |
361 | extern lto_code_gen_t | |
362 | lto_codegen_create(void); | |
363 | ||
85aaf69f SL |
364 | /** |
365 | * \brief Instantiate a code generator in its own context. | |
366 | * | |
367 | * Instantiates a code generator in its own context. Modules added via \a | |
368 | * lto_codegen_add_module() must have all been created in the same context, | |
369 | * using \a lto_module_create_in_codegen_context(). | |
370 | * | |
371 | * \since LTO_API_VERSION=11 | |
372 | */ | |
373 | extern lto_code_gen_t | |
374 | lto_codegen_create_in_local_context(void); | |
375 | ||
223e47cc LB |
376 | /** |
377 | * Frees all code generator and all memory it internally allocated. | |
378 | * Upon return the lto_code_gen_t is no longer valid. | |
1a4d82fc JJ |
379 | * |
380 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
381 | */ |
382 | extern void | |
383 | lto_codegen_dispose(lto_code_gen_t); | |
384 | ||
223e47cc LB |
385 | /** |
386 | * Add an object module to the set of modules for which code will be generated. | |
387 | * Returns true on error (check lto_get_error_message() for details). | |
1a4d82fc | 388 | * |
85aaf69f SL |
389 | * \c cg and \c mod must both be in the same context. See \a |
390 | * lto_codegen_create_in_local_context() and \a | |
391 | * lto_module_create_in_codegen_context(). | |
392 | * | |
1a4d82fc | 393 | * \since prior to LTO_API_VERSION=3 |
223e47cc | 394 | */ |
1a4d82fc | 395 | extern lto_bool_t |
223e47cc LB |
396 | lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod); |
397 | ||
223e47cc LB |
398 | /** |
399 | * Sets if debug info should be generated. | |
400 | * Returns true on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
401 | * |
402 | * \since prior to LTO_API_VERSION=3 | |
223e47cc | 403 | */ |
1a4d82fc | 404 | extern lto_bool_t |
223e47cc LB |
405 | lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model); |
406 | ||
407 | ||
408 | /** | |
409 | * Sets which PIC code model to generated. | |
410 | * Returns true on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
411 | * |
412 | * \since prior to LTO_API_VERSION=3 | |
223e47cc | 413 | */ |
1a4d82fc | 414 | extern lto_bool_t |
223e47cc LB |
415 | lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model); |
416 | ||
417 | ||
418 | /** | |
419 | * Sets the cpu to generate code for. | |
1a4d82fc JJ |
420 | * |
421 | * \since LTO_API_VERSION=4 | |
223e47cc LB |
422 | */ |
423 | extern void | |
424 | lto_codegen_set_cpu(lto_code_gen_t cg, const char *cpu); | |
425 | ||
426 | ||
427 | /** | |
428 | * Sets the location of the assembler tool to run. If not set, libLTO | |
429 | * will use gcc to invoke the assembler. | |
1a4d82fc JJ |
430 | * |
431 | * \since LTO_API_VERSION=3 | |
223e47cc LB |
432 | */ |
433 | extern void | |
434 | lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path); | |
435 | ||
436 | /** | |
437 | * Sets extra arguments that libLTO should pass to the assembler. | |
1a4d82fc JJ |
438 | * |
439 | * \since LTO_API_VERSION=4 | |
223e47cc LB |
440 | */ |
441 | extern void | |
442 | lto_codegen_set_assembler_args(lto_code_gen_t cg, const char **args, | |
443 | int nargs); | |
444 | ||
445 | /** | |
1a4d82fc JJ |
446 | * Adds to a list of all global symbols that must exist in the final generated |
447 | * code. If a function is not listed there, it might be inlined into every usage | |
448 | * and optimized away. | |
449 | * | |
450 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
451 | */ |
452 | extern void | |
453 | lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol); | |
454 | ||
455 | /** | |
456 | * Writes a new object file at the specified path that contains the | |
457 | * merged contents of all modules added so far. | |
458 | * Returns true on error (check lto_get_error_message() for details). | |
1a4d82fc JJ |
459 | * |
460 | * \since LTO_API_VERSION=5 | |
223e47cc | 461 | */ |
1a4d82fc | 462 | extern lto_bool_t |
223e47cc LB |
463 | lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path); |
464 | ||
465 | /** | |
466 | * Generates code for all added modules into one native object file. | |
467 | * On success returns a pointer to a generated mach-o/ELF buffer and | |
468 | * length set to the buffer size. The buffer is owned by the | |
469 | * lto_code_gen_t and will be freed when lto_codegen_dispose() | |
470 | * is called, or lto_codegen_compile() is called again. | |
471 | * On failure, returns NULL (check lto_get_error_message() for details). | |
1a4d82fc JJ |
472 | * |
473 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
474 | */ |
475 | extern const void* | |
476 | lto_codegen_compile(lto_code_gen_t cg, size_t* length); | |
477 | ||
478 | /** | |
479 | * Generates code for all added modules into one native object file. | |
480 | * The name of the file is written to name. Returns true on error. | |
1a4d82fc JJ |
481 | * |
482 | * \since LTO_API_VERSION=5 | |
223e47cc | 483 | */ |
1a4d82fc | 484 | extern lto_bool_t |
223e47cc LB |
485 | lto_codegen_compile_to_file(lto_code_gen_t cg, const char** name); |
486 | ||
487 | ||
488 | /** | |
489 | * Sets options to help debug codegen bugs. | |
1a4d82fc JJ |
490 | * |
491 | * \since prior to LTO_API_VERSION=3 | |
223e47cc LB |
492 | */ |
493 | extern void | |
494 | lto_codegen_debug_options(lto_code_gen_t cg, const char *); | |
495 | ||
970d7e83 LB |
496 | /** |
497 | * Initializes LLVM disassemblers. | |
498 | * FIXME: This doesn't really belong here. | |
1a4d82fc JJ |
499 | * |
500 | * \since LTO_API_VERSION=5 | |
970d7e83 LB |
501 | */ |
502 | extern void | |
503 | lto_initialize_disassembler(void); | |
504 | ||
223e47cc LB |
505 | #ifdef __cplusplus |
506 | } | |
507 | #endif | |
508 | ||
509 | /** | |
510 | * @} | |
511 | */ | |
512 | ||
513 | #endif |