lto.h revision 98197e55c10176c3ef9100f7d852abbd2347225f 
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 location of the "gcc" to run. If not set, libLTO will search for
210 * "gcc" on the path.
211 */
212extern void
213lto_codegen_set_gcc_path(lto_code_gen_t cg, const char* path);
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