lto.h revision 2d643ef32891859ec73b6eea2959748f5ebc3af7 
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#ifdef __cplusplus
62extern "C" {
63#endif
64
65/**
66 * Returns a printable string.
67 */
68extern const char*
69lto_get_version(void);
70
71
72/**
73 * Returns the last error string or NULL if last operation was sucessful.
74 */
75extern const char*
76lto_get_error_message(void);
77
78/**
79 * Checks if a file is a loadable object file.
80 */
81extern bool
82lto_module_is_object_file(const char* path);
83
84
85/**
86 * Checks if a file is a loadable object compiled for requested target.
87 */
88extern bool
89lto_module_is_object_file_for_target(const char* path,
90                                     const char* target_triple_prefix);
91
92
93/**
94 * Checks if a buffer is a loadable object file.
95 */
96extern bool
97lto_module_is_object_file_in_memory(const void* mem, size_t length);
98
99
100/**
101 * Checks if a buffer is a loadable object compiled for requested target.
102 */
103extern bool
104lto_module_is_object_file_in_memory_for_target(const void* mem, size_t length,
105                                              const char* target_triple_prefix);
106
107
108/**
109 * Loads an object file from disk.
110 * Returns NULL on error (check lto_get_error_message() for details).
111 */
112extern lto_module_t
113lto_module_create(const char* path);
114
115
116/**
117 * Loads an object file from memory.
118 * Returns NULL on error (check lto_get_error_message() for details).
119 */
120extern lto_module_t
121lto_module_create_from_memory(const void* mem, size_t length);
122
123
124/**
125 * Frees all memory internally allocated by the module.
126 * Upon return the lto_module_t is no longer valid.
127 */
128extern void
129lto_module_dispose(lto_module_t mod);
130
131
132/**
133 * Returns triple string which the object module was compiled under.
134 */
135extern const char*
136lto_module_get_target_triple(lto_module_t mod);
137
138/**
139 * Sets triple string with which the object will be codegened.
140 */
141extern void
142lto_module_set_target_triple(lto_module_t mod, const char *triple);
143
144
145/**
146 * Returns the number of symbols in the object module.
147 */
148extern unsigned int
149lto_module_get_num_symbols(lto_module_t mod);
150
151
152/**
153 * Returns the name of the ith symbol in the object module.
154 */
155extern const char*
156lto_module_get_symbol_name(lto_module_t mod, unsigned int index);
157
158
159/**
160 * Returns the attributes of the ith symbol in the object module.
161 */
162extern lto_symbol_attributes
163lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index);
164
165
166/**
167 * Instantiates a code generator.
168 * Returns NULL on error (check lto_get_error_message() for details).
169 */
170extern lto_code_gen_t
171lto_codegen_create(void);
172
173
174/**
175 * Frees all code generator and all memory it internally allocated.
176 * Upon return the lto_code_gen_t is no longer valid.
177 */
178extern void
179lto_codegen_dispose(lto_code_gen_t);
180
181
182
183/**
184 * Add an object module to the set of modules for which code will be generated.
185 * Returns true on error (check lto_get_error_message() for details).
186 */
187extern bool
188lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod);
189
190
191
192/**
193 * Sets if debug info should be generated.
194 * Returns true on error (check lto_get_error_message() for details).
195 */
196extern bool
197lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model);
198
199
200/**
201 * Sets which PIC code model to generated.
202 * Returns true on error (check lto_get_error_message() for details).
203 */
204extern bool
205lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model);
206
207
208/**
209 * Sets the cpu to generate code for.
210 */
211extern void
212lto_codegen_set_cpu(lto_code_gen_t cg, const char *cpu);
213
214
215/**
216 * Sets the location of the "gcc" to run. If not set, libLTO will search for
217 * "gcc" on the path.
218 */
219extern void
220lto_codegen_set_gcc_path(lto_code_gen_t cg, const char* path);
221
222
223/**
224 * Sets the location of the assembler tool to run. If not set, libLTO
225 * will use gcc to invoke the assembler.
226 */
227extern void
228lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path);
229
230/**
231 * Sets extra arguments that libLTO should pass to the assembler.
232 */
233extern void
234lto_codegen_set_assembler_args(lto_code_gen_t cg, const char **args,
235                               int nargs);
236
237/**
238 * Adds to a list of all global symbols that must exist in the final
239 * generated code.  If a function is not listed, it might be
240 * inlined into every usage and optimized away.
241 */
242extern void
243lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol);
244
245
246/**
247 * Writes a new object file at the specified path that contains the
248 * merged contents of all modules added so far.
249 * Returns true on error (check lto_get_error_message() for details).
250 */
251extern bool
252lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path);
253
254
255/**
256 * Generates code for all added modules into one native object file.
257 * On sucess returns a pointer to a generated mach-o/ELF buffer and
258 * length set to the buffer size.  The buffer is owned by the
259 * lto_code_gen_t and will be freed when lto_codegen_dispose()
260 * is called, or lto_codegen_compile() is called again.
261 * On failure, returns NULL (check lto_get_error_message() for details).
262 */
263extern const void*
264lto_codegen_compile(lto_code_gen_t cg, size_t* length);
265
266
267/**
268 * Sets options to help debug codegen bugs.
269 */
270extern void
271lto_codegen_debug_options(lto_code_gen_t cg, const char *);
272#ifdef __cplusplus
273}
274#endif
275
276
277#endif
278