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