• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 LLVM_C_LTO_H
17  #define LLVM_C_LTO_H
18  
19  #include <stddef.h>
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
35  
36  /**
37   * @defgroup LLVMCLTO LTO
38   * @ingroup LLVMC
39   *
40   * @{
41   */
42  
43  #define LTO_API_VERSION 11
44  
45  /**
46   * \since prior to LTO_API_VERSION=3
47   */
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  
68  /**
69   * \since prior to LTO_API_VERSION=3
70   */
71  typedef enum {
72      LTO_DEBUG_MODEL_NONE         = 0,
73      LTO_DEBUG_MODEL_DWARF        = 1
74  } lto_debug_model;
75  
76  /**
77   * \since prior to LTO_API_VERSION=3
78   */
79  typedef enum {
80      LTO_CODEGEN_PIC_MODEL_STATIC         = 0,
81      LTO_CODEGEN_PIC_MODEL_DYNAMIC        = 1,
82      LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC = 2,
83      LTO_CODEGEN_PIC_MODEL_DEFAULT        = 3
84  } lto_codegen_model;
85  
86  /** opaque reference to a loaded object module */
87  typedef struct LLVMOpaqueLTOModule *lto_module_t;
88  
89  /** opaque reference to a code generator */
90  typedef struct LLVMOpaqueLTOCodeGenerator *lto_code_gen_t;
91  
92  #ifdef __cplusplus
93  extern "C" {
94  #endif
95  
96  /**
97   * Returns a printable string.
98   *
99   * \since prior to LTO_API_VERSION=3
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.
107   *
108   * \since prior to LTO_API_VERSION=3
109   */
110  extern const char*
111  lto_get_error_message(void);
112  
113  /**
114   * Checks if a file is a loadable object file.
115   *
116   * \since prior to LTO_API_VERSION=3
117   */
118  extern lto_bool_t
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.
124   *
125   * \since prior to LTO_API_VERSION=3
126   */
127  extern lto_bool_t
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.
134   *
135   * \since prior to LTO_API_VERSION=3
136   */
137  extern lto_bool_t
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.
143   *
144   * \since prior to LTO_API_VERSION=3
145   */
146  extern lto_bool_t
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).
154   *
155   * \since prior to LTO_API_VERSION=3
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).
164   *
165   * \since prior to LTO_API_VERSION=3
166   */
167  extern lto_module_t
168  lto_module_create_from_memory(const void* mem, size_t length);
169  
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  
180  /**
181   * Loads an object file from disk. The seek point of fd is not preserved.
182   * Returns NULL on error (check lto_get_error_message() for details).
183   *
184   * \since LTO_API_VERSION=5
185   */
186  extern lto_module_t
187  lto_module_create_from_fd(int fd, const char *path, size_t file_size);
188  
189  /**
190   * Loads an object file from disk. The seek point of fd is not preserved.
191   * Returns NULL on error (check lto_get_error_message() for details).
192   *
193   * \since LTO_API_VERSION=5
194   */
195  extern lto_module_t
196  lto_module_create_from_fd_at_offset(int fd, const char *path, size_t file_size,
197                                      size_t map_size, off_t offset);
198  
199  /**
200   * Frees all memory internally allocated by the module.
201   * Upon return the lto_module_t is no longer valid.
202   *
203   * \since prior to LTO_API_VERSION=3
204   */
205  extern void
206  lto_module_dispose(lto_module_t mod);
207  
208  /**
209   * Returns triple string which the object module was compiled under.
210   *
211   * \since prior to LTO_API_VERSION=3
212   */
213  extern const char*
214  lto_module_get_target_triple(lto_module_t mod);
215  
216  /**
217   * Sets triple string with which the object will be codegened.
218   *
219   * \since LTO_API_VERSION=4
220   */
221  extern void
222  lto_module_set_target_triple(lto_module_t mod, const char *triple);
223  
224  
225  /**
226   * Returns the number of symbols in the object module.
227   *
228   * \since prior to LTO_API_VERSION=3
229   */
230  extern unsigned int
231  lto_module_get_num_symbols(lto_module_t mod);
232  
233  
234  /**
235   * Returns the name of the ith symbol in the object module.
236   *
237   * \since prior to LTO_API_VERSION=3
238   */
239  extern const char*
240  lto_module_get_symbol_name(lto_module_t mod, unsigned int index);
241  
242  
243  /**
244   * Returns the attributes of the ith symbol in the object module.
245   *
246   * \since prior to LTO_API_VERSION=3
247   */
248  extern lto_symbol_attributes
249  lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index);
250  
251  
252  /**
253   * Returns the number of dependent libraries in the object module.
254   *
255   * \since LTO_API_VERSION=8
256   */
257  extern unsigned int
258  lto_module_get_num_deplibs(lto_module_t mod);
259  
260  
261  /**
262   * Returns the ith dependent library in the module.
263   *
264   * \since LTO_API_VERSION=8
265   */
266  extern const char*
267  lto_module_get_deplib(lto_module_t mod, unsigned int index);
268  
269  
270  /**
271   * Returns the number of linker options in the object module.
272   *
273   * \since LTO_API_VERSION=8
274   */
275  extern unsigned int
276  lto_module_get_num_linkeropts(lto_module_t mod);
277  
278  
279  /**
280   * Returns the ith linker option in the module.
281   *
282   * \since LTO_API_VERSION=8
283   */
284  extern const char*
285  lto_module_get_linkeropt(lto_module_t mod, unsigned int index);
286  
287  
288  /**
289   * Diagnostic severity.
290   *
291   * \since LTO_API_VERSION=7
292   */
293  typedef enum {
294    LTO_DS_ERROR = 0,
295    LTO_DS_WARNING = 1,
296    LTO_DS_REMARK = 3, // Added in LTO_API_VERSION=10.
297    LTO_DS_NOTE = 2
298  } lto_codegen_diagnostic_severity_t;
299  
300  /**
301   * Diagnostic handler type.
302   * \p severity defines the severity.
303   * \p diag is the actual diagnostic.
304   * The diagnostic is not prefixed by any of severity keyword, e.g., 'error: '.
305   * \p ctxt is used to pass the context set with the diagnostic handler.
306   *
307   * \since LTO_API_VERSION=7
308   */
309  typedef void (*lto_diagnostic_handler_t)(
310      lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt);
311  
312  /**
313   * Set a diagnostic handler and the related context (void *).
314   * This is more general than lto_get_error_message, as the diagnostic handler
315   * can be called at anytime within lto.
316   *
317   * \since LTO_API_VERSION=7
318   */
319  extern void lto_codegen_set_diagnostic_handler(lto_code_gen_t,
320                                                 lto_diagnostic_handler_t,
321                                                 void *);
322  
323  /**
324   * Instantiates a code generator.
325   * Returns NULL on error (check lto_get_error_message() for details).
326   *
327   * \since prior to LTO_API_VERSION=3
328   */
329  extern lto_code_gen_t
330  lto_codegen_create(void);
331  
332  /**
333   * Frees all code generator and all memory it internally allocated.
334   * Upon return the lto_code_gen_t is no longer valid.
335   *
336   * \since prior to LTO_API_VERSION=3
337   */
338  extern void
339  lto_codegen_dispose(lto_code_gen_t);
340  
341  /**
342   * Add an object module to the set of modules for which code will be generated.
343   * Returns true on error (check lto_get_error_message() for details).
344   *
345   * \since prior to LTO_API_VERSION=3
346   */
347  extern lto_bool_t
348  lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod);
349  
350  /**
351   * Sets if debug info should be generated.
352   * Returns true on error (check lto_get_error_message() for details).
353   *
354   * \since prior to LTO_API_VERSION=3
355   */
356  extern lto_bool_t
357  lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model);
358  
359  
360  /**
361   * Sets which PIC code model to generated.
362   * Returns true on error (check lto_get_error_message() for details).
363   *
364   * \since prior to LTO_API_VERSION=3
365   */
366  extern lto_bool_t
367  lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model);
368  
369  
370  /**
371   * Sets the cpu to generate code for.
372   *
373   * \since LTO_API_VERSION=4
374   */
375  extern void
376  lto_codegen_set_cpu(lto_code_gen_t cg, const char *cpu);
377  
378  /**
379   * Sets attributes for the cpu to generate code for.
380   *
381   * \since LTO_API_VERSION=11
382   */
383  extern void
384  lto_codegen_set_attr(lto_code_gen_t cg, const char *attr);
385  
386  
387  /**
388   * Sets the location of the assembler tool to run. If not set, libLTO
389   * will use gcc to invoke the assembler.
390   *
391   * \since LTO_API_VERSION=3
392   */
393  extern void
394  lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path);
395  
396  /**
397   * Sets extra arguments that libLTO should pass to the assembler.
398   *
399   * \since LTO_API_VERSION=4
400   */
401  extern void
402  lto_codegen_set_assembler_args(lto_code_gen_t cg, const char **args,
403                                 int nargs);
404  
405  /**
406   * Adds to a list of all global symbols that must exist in the final generated
407   * code. If a function is not listed there, it might be inlined into every usage
408   * and optimized away.
409   *
410   * \since prior to LTO_API_VERSION=3
411   */
412  extern void
413  lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol);
414  
415  /**
416   * Writes a new object file at the specified path that contains the
417   * merged contents of all modules added so far.
418   * Returns true on error (check lto_get_error_message() for details).
419   *
420   * \since LTO_API_VERSION=5
421   */
422  extern lto_bool_t
423  lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path);
424  
425  /**
426   * Generates code for all added modules into one native object file.
427   * On success returns a pointer to a generated mach-o/ELF buffer and
428   * length set to the buffer size.  The buffer is owned by the
429   * lto_code_gen_t and will be freed when lto_codegen_dispose()
430   * is called, or lto_codegen_compile() is called again.
431   * On failure, returns NULL (check lto_get_error_message() for details).
432   *
433   * \since prior to LTO_API_VERSION=3
434   */
435  extern const void*
436  lto_codegen_compile(lto_code_gen_t cg, size_t* length);
437  
438  /**
439   * Generates code for all added modules into one native object file.
440   * The name of the file is written to name. Returns true on error.
441   *
442   * \since LTO_API_VERSION=5
443   */
444  extern lto_bool_t
445  lto_codegen_compile_to_file(lto_code_gen_t cg, const char** name);
446  
447  
448  /**
449   * Sets options to help debug codegen bugs.
450   *
451   * \since prior to LTO_API_VERSION=3
452   */
453  extern void
454  lto_codegen_debug_options(lto_code_gen_t cg, const char *);
455  
456  /**
457   * Initializes LLVM disassemblers.
458   * FIXME: This doesn't really belong here.
459   *
460   * \since LTO_API_VERSION=5
461   */
462  extern void
463  lto_initialize_disassembler(void);
464  
465  #ifdef __cplusplus
466  }
467  #endif
468  
469  /**
470   * @}
471   */
472  
473  #endif
474