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