1/*===-- llvm-c/lto.h - LTO Public C Interface ---------------------*- C -*-===*\
2|* *|
3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4|* Exceptions. *|
5|* See https://llvm.org/LICENSE.txt for license information. *|
6|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
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 "llvm-c/ExternC.h"
20
21#ifdef __cplusplus
22#include <cstddef>
23#else
24#include <stddef.h>
25#endif
26#include <sys/types.h>
27
28#ifndef __cplusplus
29#if !defined(_MSC_VER)
30#include <stdbool.h>
31typedef bool lto_bool_t;
32#else
33/* MSVC in particular does not have anything like _Bool or bool in C, but we can
34 at least make sure the type is the same size. The implementation side will
35 use C++ bool. */
36typedef unsigned char lto_bool_t;
37#endif
38#else
39typedef bool lto_bool_t;
40#endif
41
42/**
43 * @defgroup LLVMCLTO LTO
44 * @ingroup LLVMC
45 *
46 * @{
47 */
48
49#define LTO_API_VERSION 30
50
51/**
52 * \since prior to LTO_API_VERSION=3
53 */
54typedef enum {
55 LTO_SYMBOL_ALIGNMENT_MASK = 0x0000001F, /* log2 of alignment */
56 LTO_SYMBOL_PERMISSIONS_MASK = 0x000000E0,
57 LTO_SYMBOL_PERMISSIONS_CODE = 0x000000A0,
58 LTO_SYMBOL_PERMISSIONS_DATA = 0x000000C0,
59 LTO_SYMBOL_PERMISSIONS_RODATA = 0x00000080,
60 LTO_SYMBOL_DEFINITION_MASK = 0x00000700,
61 LTO_SYMBOL_DEFINITION_REGULAR = 0x00000100,
62 LTO_SYMBOL_DEFINITION_TENTATIVE = 0x00000200,
63 LTO_SYMBOL_DEFINITION_WEAK = 0x00000300,
64 LTO_SYMBOL_DEFINITION_UNDEFINED = 0x00000400,
65 LTO_SYMBOL_DEFINITION_WEAKUNDEF = 0x00000500,
66 LTO_SYMBOL_SCOPE_MASK = 0x00003800,
67 LTO_SYMBOL_SCOPE_INTERNAL = 0x00000800,
68 LTO_SYMBOL_SCOPE_HIDDEN = 0x00001000,
69 LTO_SYMBOL_SCOPE_PROTECTED = 0x00002000,
70 LTO_SYMBOL_SCOPE_DEFAULT = 0x00001800,
71 LTO_SYMBOL_SCOPE_DEFAULT_CAN_BE_HIDDEN = 0x00002800,
72 LTO_SYMBOL_COMDAT = 0x00004000,
73 LTO_SYMBOL_ALIAS = 0x00008000
74} lto_symbol_attributes;
75
76/**
77 * \since prior to LTO_API_VERSION=3
78 */
79typedef enum {
80 LTO_DEBUG_MODEL_NONE = 0,
81 LTO_DEBUG_MODEL_DWARF = 1
82} lto_debug_model;
83
84/**
85 * \since prior to LTO_API_VERSION=3
86 */
87typedef enum {
88 LTO_CODEGEN_PIC_MODEL_STATIC = 0,
89 LTO_CODEGEN_PIC_MODEL_DYNAMIC = 1,
90 LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC = 2,
91 LTO_CODEGEN_PIC_MODEL_DEFAULT = 3
92} lto_codegen_model;
93
94/** opaque reference to a loaded object module */
95typedef struct LLVMOpaqueLTOModule *lto_module_t;
96
97/** opaque reference to a code generator */
98typedef struct LLVMOpaqueLTOCodeGenerator *lto_code_gen_t;
99
100/** opaque reference to a thin code generator */
101typedef struct LLVMOpaqueThinLTOCodeGenerator *thinlto_code_gen_t;
102
103LLVM_C_EXTERN_C_BEGIN
104
105/**
106 * Returns a printable string.
107 *
108 * \since prior to LTO_API_VERSION=3
109 */
110extern const char*
111lto_get_version(void);
112
113/**
114 * Returns the last error string or NULL if last operation was successful.
115 *
116 * \since prior to LTO_API_VERSION=3
117 */
118extern const char*
119lto_get_error_message(void);
120
121/**
122 * Checks if a file is a loadable object file.
123 *
124 * \since prior to LTO_API_VERSION=3
125 */
126extern lto_bool_t
127lto_module_is_object_file(const char* path);
128
129/**
130 * Checks if a file is a loadable object compiled for requested target.
131 *
132 * \since prior to LTO_API_VERSION=3
133 */
134extern lto_bool_t
135lto_module_is_object_file_for_target(const char* path,
136 const char* target_triple_prefix);
137
138/**
139 * Return true if \p Buffer contains a bitcode file with ObjC code (category
140 * or class) in it.
141 *
142 * \since LTO_API_VERSION=20
143 */
144extern lto_bool_t
145lto_module_has_objc_category(const void *mem, size_t length);
146
147/**
148 * Checks if a buffer is a loadable object file.
149 *
150 * \since prior to LTO_API_VERSION=3
151 */
152extern lto_bool_t lto_module_is_object_file_in_memory(const void *mem,
153 size_t length);
154
155/**
156 * Checks if a buffer is a loadable object compiled for requested target.
157 *
158 * \since prior to LTO_API_VERSION=3
159 */
160extern lto_bool_t
161lto_module_is_object_file_in_memory_for_target(const void* mem, size_t length,
162 const char* target_triple_prefix);
163
164/**
165 * Loads an object file from disk.
166 * Returns NULL on error (check lto_get_error_message() for details).
167 *
168 * \since prior to LTO_API_VERSION=3
169 */
170extern lto_module_t
171lto_module_create(const char* path);
172
173/**
174 * Loads an object file from memory.
175 * Returns NULL on error (check lto_get_error_message() for details).
176 *
177 * \since prior to LTO_API_VERSION=3
178 */
179extern lto_module_t
180lto_module_create_from_memory(const void* mem, size_t length);
181
182/**
183 * Loads an object file from memory with an extra path argument.
184 * Returns NULL on error (check lto_get_error_message() for details).
185 *
186 * \since LTO_API_VERSION=9
187 */
188extern lto_module_t
189lto_module_create_from_memory_with_path(const void* mem, size_t length,
190 const char *path);
191
192/**
193 * Loads an object file in its own context.
194 *
195 * Loads an object file in its own LLVMContext. This function call is
196 * thread-safe. However, modules created this way should not be merged into an
197 * lto_code_gen_t using \a lto_codegen_add_module().
198 *
199 * Returns NULL on error (check lto_get_error_message() for details).
200 *
201 * \since LTO_API_VERSION=11
202 */
203extern lto_module_t
204lto_module_create_in_local_context(const void *mem, size_t length,
205 const char *path);
206
207/**
208 * Loads an object file in the codegen context.
209 *
210 * Loads an object file into the same context as \c cg. The module is safe to
211 * add using \a lto_codegen_add_module().
212 *
213 * Returns NULL on error (check lto_get_error_message() for details).
214 *
215 * \since LTO_API_VERSION=11
216 */
217extern lto_module_t
218lto_module_create_in_codegen_context(const void *mem, size_t length,
219 const char *path, lto_code_gen_t cg);
220
221/**
222 * Loads an object file from disk. The seek point of fd is not preserved.
223 * Returns NULL on error (check lto_get_error_message() for details).
224 *
225 * \since LTO_API_VERSION=5
226 */
227extern lto_module_t
228lto_module_create_from_fd(int fd, const char *path, size_t file_size);
229
230/**
231 * Loads an object file from disk. The seek point of fd is not preserved.
232 * Returns NULL on error (check lto_get_error_message() for details).
233 *
234 * \since LTO_API_VERSION=5
235 */
236extern lto_module_t
237lto_module_create_from_fd_at_offset(int fd, const char *path, size_t file_size,
238 size_t map_size, off_t offset);
239
240/**
241 * Frees all memory internally allocated by the module.
242 * Upon return the lto_module_t is no longer valid.
243 *
244 * \since prior to LTO_API_VERSION=3
245 */
246extern void
247lto_module_dispose(lto_module_t mod);
248
249/**
250 * Returns triple string which the object module was compiled under.
251 *
252 * \since prior to LTO_API_VERSION=3
253 */
254extern const char*
255lto_module_get_target_triple(lto_module_t mod);
256
257/**
258 * Sets triple string with which the object will be codegened.
259 *
260 * \since LTO_API_VERSION=4
261 */
262extern void
263lto_module_set_target_triple(lto_module_t mod, const char *triple);
264
265/**
266 * Returns the number of symbols in the object module.
267 *
268 * \since prior to LTO_API_VERSION=3
269 */
270extern unsigned int
271lto_module_get_num_symbols(lto_module_t mod);
272
273/**
274 * Returns the name of the ith symbol in the object module.
275 *
276 * \since prior to LTO_API_VERSION=3
277 */
278extern const char*
279lto_module_get_symbol_name(lto_module_t mod, unsigned int index);
280
281/**
282 * Returns the attributes of the ith symbol in the object module.
283 *
284 * \since prior to LTO_API_VERSION=3
285 */
286extern lto_symbol_attributes
287lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index);
288
289/**
290 * Returns the number of asm undefined symbols in the object module.
291 *
292 * \since prior to LTO_API_VERSION=30
293 */
294extern unsigned int lto_module_get_num_asm_undef_symbols(lto_module_t mod);
295
296/**
297 * Returns the name of the ith asm undefined symbol in the object module.
298 *
299 * \since prior to LTO_API_VERSION=30
300 */
301extern const char *lto_module_get_asm_undef_symbol_name(lto_module_t mod,
302 unsigned int index);
303
304/**
305 * Returns the module's linker options.
306 *
307 * The linker options may consist of multiple flags. It is the linker's
308 * responsibility to split the flags using a platform-specific mechanism.
309 *
310 * \since LTO_API_VERSION=16
311 */
312extern const char*
313lto_module_get_linkeropts(lto_module_t mod);
314
315/**
316 * If targeting mach-o on darwin, this function gets the CPU type and subtype
317 * that will end up being encoded in the mach-o header. These are the values
318 * that can be found in mach/machine.h.
319 *
320 * \p out_cputype and \p out_cpusubtype must be non-NULL.
321 *
322 * Returns true on error (check lto_get_error_message() for details).
323 *
324 * \since LTO_API_VERSION=27
325 */
326extern lto_bool_t lto_module_get_macho_cputype(lto_module_t mod,
327 unsigned int *out_cputype,
328 unsigned int *out_cpusubtype);
329
330/**
331 * This function can be used by the linker to check if a given module has
332 * any constructor or destructor functions.
333 *
334 * Returns true if the module has either the @llvm.global_ctors or the
335 * @llvm.global_dtors symbol. Otherwise returns false.
336 *
337 * \since LTO_API_VERSION=29
338 */
339extern lto_bool_t lto_module_has_ctor_dtor(lto_module_t mod);
340/**
341 * Diagnostic severity.
342 *
343 * \since LTO_API_VERSION=7
344 */
345typedef enum {
346 LTO_DS_ERROR = 0,
347 LTO_DS_WARNING = 1,
348 LTO_DS_REMARK = 3, // Added in LTO_API_VERSION=10.
349 LTO_DS_NOTE = 2
350} lto_codegen_diagnostic_severity_t;
351
352/**
353 * Diagnostic handler type.
354 * \p severity defines the severity.
355 * \p diag is the actual diagnostic.
356 * The diagnostic is not prefixed by any of severity keyword, e.g., 'error: '.
357 * \p ctxt is used to pass the context set with the diagnostic handler.
358 *
359 * \since LTO_API_VERSION=7
360 */
361typedef void (*lto_diagnostic_handler_t)(
362 lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt);
363
364/**
365 * Set a diagnostic handler and the related context (void *).
366 * This is more general than lto_get_error_message, as the diagnostic handler
367 * can be called at anytime within lto.
368 *
369 * \since LTO_API_VERSION=7
370 */
371extern void lto_codegen_set_diagnostic_handler(lto_code_gen_t,
372 lto_diagnostic_handler_t,
373 void *);
374
375/**
376 * Instantiates a code generator.
377 * Returns NULL on error (check lto_get_error_message() for details).
378 *
379 * All modules added using \a lto_codegen_add_module() must have been created
380 * in the same context as the codegen.
381 *
382 * \since prior to LTO_API_VERSION=3
383 */
384extern lto_code_gen_t
385lto_codegen_create(void);
386
387/**
388 * Instantiate a code generator in its own context.
389 *
390 * Instantiates a code generator in its own context. Modules added via \a
391 * lto_codegen_add_module() must have all been created in the same context,
392 * using \a lto_module_create_in_codegen_context().
393 *
394 * \since LTO_API_VERSION=11
395 */
396extern lto_code_gen_t
397lto_codegen_create_in_local_context(void);
398
399/**
400 * Frees all code generator and all memory it internally allocated.
401 * Upon return the lto_code_gen_t is no longer valid.
402 *
403 * \since prior to LTO_API_VERSION=3
404 */
405extern void
406lto_codegen_dispose(lto_code_gen_t);
407
408/**
409 * Add an object module to the set of modules for which code will be generated.
410 * Returns true on error (check lto_get_error_message() for details).
411 *
412 * \c cg and \c mod must both be in the same context. See \a
413 * lto_codegen_create_in_local_context() and \a
414 * lto_module_create_in_codegen_context().
415 *
416 * \since prior to LTO_API_VERSION=3
417 */
418extern lto_bool_t
419lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod);
420
421/**
422 * Sets the object module for code generation. This will transfer the ownership
423 * of the module to the code generator.
424 *
425 * \c cg and \c mod must both be in the same context.
426 *
427 * \since LTO_API_VERSION=13
428 */
429extern void
430lto_codegen_set_module(lto_code_gen_t cg, lto_module_t mod);
431
432/**
433 * Sets if debug info should be generated.
434 * Returns true on error (check lto_get_error_message() for details).
435 *
436 * \since prior to LTO_API_VERSION=3
437 */
438extern lto_bool_t
439lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model);
440
441/**
442 * Sets which PIC code model to generated.
443 * Returns true on error (check lto_get_error_message() for details).
444 *
445 * \since prior to LTO_API_VERSION=3
446 */
447extern lto_bool_t
448lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model);
449
450/**
451 * Sets the cpu to generate code for.
452 *
453 * \since LTO_API_VERSION=4
454 */
455extern void
456lto_codegen_set_cpu(lto_code_gen_t cg, const char *cpu);
457
458/**
459 * Sets the location of the assembler tool to run. If not set, libLTO
460 * will use gcc to invoke the assembler.
461 *
462 * \since LTO_API_VERSION=3
463 */
464extern void
465lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path);
466
467/**
468 * Sets extra arguments that libLTO should pass to the assembler.
469 *
470 * \since LTO_API_VERSION=4
471 */
472extern void
473lto_codegen_set_assembler_args(lto_code_gen_t cg, const char **args,
474 int nargs);
475
476/**
477 * Adds to a list of all global symbols that must exist in the final generated
478 * code. If a function is not listed there, it might be inlined into every usage
479 * and optimized away.
480 *
481 * \since prior to LTO_API_VERSION=3
482 */
483extern void
484lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol);
485
486/**
487 * Writes a new object file at the specified path that contains the
488 * merged contents of all modules added so far.
489 * Returns true on error (check lto_get_error_message() for details).
490 *
491 * \since LTO_API_VERSION=5
492 */
493extern lto_bool_t
494lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path);
495
496/**
497 * Generates code for all added modules into one native object file.
498 * This calls lto_codegen_optimize then lto_codegen_compile_optimized.
499 *
500 * On success returns a pointer to a generated mach-o/ELF buffer and
501 * length set to the buffer size. The buffer is owned by the
502 * lto_code_gen_t and will be freed when lto_codegen_dispose()
503 * is called, or lto_codegen_compile() is called again.
504 * On failure, returns NULL (check lto_get_error_message() for details).
505 *
506 * \since prior to LTO_API_VERSION=3
507 */
508extern const void*
509lto_codegen_compile(lto_code_gen_t cg, size_t* length);
510
511/**
512 * Generates code for all added modules into one native object file.
513 * This calls lto_codegen_optimize then lto_codegen_compile_optimized (instead
514 * of returning a generated mach-o/ELF buffer, it writes to a file).
515 *
516 * The name of the file is written to name. Returns true on error.
517 *
518 * \since LTO_API_VERSION=5
519 */
520extern lto_bool_t
521lto_codegen_compile_to_file(lto_code_gen_t cg, const char** name);
522
523/**
524 * Runs optimization for the merged module. Returns true on error.
525 *
526 * \since LTO_API_VERSION=12
527 */
528extern lto_bool_t
529lto_codegen_optimize(lto_code_gen_t cg);
530
531/**
532 * Generates code for the optimized merged module into one native object file.
533 * It will not run any IR optimizations on the merged module.
534 *
535 * On success returns a pointer to a generated mach-o/ELF buffer and length set
536 * to the buffer size. The buffer is owned by the lto_code_gen_t and will be
537 * freed when lto_codegen_dispose() is called, or
538 * lto_codegen_compile_optimized() is called again. On failure, returns NULL
539 * (check lto_get_error_message() for details).
540 *
541 * \since LTO_API_VERSION=12
542 */
543extern const void*
544lto_codegen_compile_optimized(lto_code_gen_t cg, size_t* length);
545
546/**
547 * Returns the runtime API version.
548 *
549 * \since LTO_API_VERSION=12
550 */
551extern unsigned int
552lto_api_version(void);
553
554/**
555 * Parses options immediately, making them available as early as possible. For
556 * example during executing codegen::InitTargetOptionsFromCodeGenFlags. Since
557 * parsing shud only happen once, only one of lto_codegen_debug_options or
558 * lto_set_debug_options should be called.
559 *
560 * This function takes one or more options separated by spaces.
561 * Warning: passing file paths through this function may confuse the argument
562 * parser if the paths contain spaces.
563 *
564 * \since LTO_API_VERSION=28
565 */
566extern void lto_set_debug_options(const char *const *options, int number);
567
568/**
569 * Sets options to help debug codegen bugs. Since parsing shud only happen once,
570 * only one of lto_codegen_debug_options or lto_set_debug_options
571 * should be called.
572 *
573 * This function takes one or more options separated by spaces.
574 * Warning: passing file paths through this function may confuse the argument
575 * parser if the paths contain spaces.
576 *
577 * \since prior to LTO_API_VERSION=3
578 */
579extern void
580lto_codegen_debug_options(lto_code_gen_t cg, const char *);
581
582/**
583 * Same as the previous function, but takes every option separately through an
584 * array.
585 *
586 * \since prior to LTO_API_VERSION=26
587 */
588extern void lto_codegen_debug_options_array(lto_code_gen_t cg,
589 const char *const *, int number);
590
591/**
592 * Initializes LLVM disassemblers.
593 * FIXME: This doesn't really belong here.
594 *
595 * \since LTO_API_VERSION=5
596 */
597extern void
598lto_initialize_disassembler(void);
599
600/**
601 * Sets if we should run internalize pass during optimization and code
602 * generation.
603 *
604 * \since LTO_API_VERSION=14
605 */
606extern void
607lto_codegen_set_should_internalize(lto_code_gen_t cg,
608 lto_bool_t ShouldInternalize);
609
610/**
611 * Set whether to embed uselists in bitcode.
612 *
613 * Sets whether \a lto_codegen_write_merged_modules() should embed uselists in
614 * output bitcode. This should be turned on for all -save-temps output.
615 *
616 * \since LTO_API_VERSION=15
617 */
618extern void
619lto_codegen_set_should_embed_uselists(lto_code_gen_t cg,
620 lto_bool_t ShouldEmbedUselists);
621
622/** Opaque reference to an LTO input file */
623typedef struct LLVMOpaqueLTOInput *lto_input_t;
624
625/**
626 * Creates an LTO input file from a buffer. The path
627 * argument is used for diagnotics as this function
628 * otherwise does not know which file the given buffer
629 * is associated with.
630 *
631 * \since LTO_API_VERSION=24
632 */
633extern lto_input_t lto_input_create(const void *buffer,
634 size_t buffer_size,
635 const char *path);
636
637/**
638 * Frees all memory internally allocated by the LTO input file.
639 * Upon return the lto_module_t is no longer valid.
640 *
641 * \since LTO_API_VERSION=24
642 */
643extern void lto_input_dispose(lto_input_t input);
644
645/**
646 * Returns the number of dependent library specifiers
647 * for the given LTO input file.
648 *
649 * \since LTO_API_VERSION=24
650 */
651extern unsigned lto_input_get_num_dependent_libraries(lto_input_t input);
652
653/**
654 * Returns the ith dependent library specifier
655 * for the given LTO input file. The returned
656 * string is not null-terminated.
657 *
658 * \since LTO_API_VERSION=24
659 */
660extern const char * lto_input_get_dependent_library(lto_input_t input,
661 size_t index,
662 size_t *size);
663
664/**
665 * Returns the list of libcall symbols that can be generated by LTO
666 * that might not be visible from the symbol table of bitcode files.
667 *
668 * \since prior to LTO_API_VERSION=25
669 */
670extern const char *const *lto_runtime_lib_symbols_list(size_t *size);
671
672/**
673 * @} // endgoup LLVMCLTO
674 * @defgroup LLVMCTLTO ThinLTO
675 * @ingroup LLVMC
676 *
677 * @{
678 */
679
680/**
681 * Type to wrap a single object returned by ThinLTO.
682 *
683 * \since LTO_API_VERSION=18
684 */
685typedef struct {
686 const char *Buffer;
687 size_t Size;
688} LTOObjectBuffer;
689
690/**
691 * Instantiates a ThinLTO code generator.
692 * Returns NULL on error (check lto_get_error_message() for details).
693 *
694 *
695 * The ThinLTOCodeGenerator is not intended to be reuse for multiple
696 * compilation: the model is that the client adds modules to the generator and
697 * ask to perform the ThinLTO optimizations / codegen, and finally destroys the
698 * codegenerator.
699 *
700 * \since LTO_API_VERSION=18
701 */
702extern thinlto_code_gen_t thinlto_create_codegen(void);
703
704/**
705 * Frees the generator and all memory it internally allocated.
706 * Upon return the thinlto_code_gen_t is no longer valid.
707 *
708 * \since LTO_API_VERSION=18
709 */
710extern void thinlto_codegen_dispose(thinlto_code_gen_t cg);
711
712/**
713 * Add a module to a ThinLTO code generator. Identifier has to be unique among
714 * all the modules in a code generator. The data buffer stays owned by the
715 * client, and is expected to be available for the entire lifetime of the
716 * thinlto_code_gen_t it is added to.
717 *
718 * On failure, returns NULL (check lto_get_error_message() for details).
719 *
720 *
721 * \since LTO_API_VERSION=18
722 */
723extern void thinlto_codegen_add_module(thinlto_code_gen_t cg,
724 const char *identifier, const char *data,
725 int length);
726
727/**
728 * Optimize and codegen all the modules added to the codegenerator using
729 * ThinLTO. Resulting objects are accessible using thinlto_module_get_object().
730 *
731 * \since LTO_API_VERSION=18
732 */
733extern void thinlto_codegen_process(thinlto_code_gen_t cg);
734
735/**
736 * Returns the number of object files produced by the ThinLTO CodeGenerator.
737 *
738 * It usually matches the number of input files, but this is not a guarantee of
739 * the API and may change in future implementation, so the client should not
740 * assume it.
741 *
742 * \since LTO_API_VERSION=18
743 */
744extern unsigned int thinlto_module_get_num_objects(thinlto_code_gen_t cg);
745
746/**
747 * Returns a reference to the ith object file produced by the ThinLTO
748 * CodeGenerator.
749 *
750 * Client should use \p thinlto_module_get_num_objects() to get the number of
751 * available objects.
752 *
753 * \since LTO_API_VERSION=18
754 */
755extern LTOObjectBuffer thinlto_module_get_object(thinlto_code_gen_t cg,
756 unsigned int index);
757
758/**
759 * Returns the number of object files produced by the ThinLTO CodeGenerator.
760 *
761 * It usually matches the number of input files, but this is not a guarantee of
762 * the API and may change in future implementation, so the client should not
763 * assume it.
764 *
765 * \since LTO_API_VERSION=21
766 */
767unsigned int thinlto_module_get_num_object_files(thinlto_code_gen_t cg);
768
769/**
770 * Returns the path to the ith object file produced by the ThinLTO
771 * CodeGenerator.
772 *
773 * Client should use \p thinlto_module_get_num_object_files() to get the number
774 * of available objects.
775 *
776 * \since LTO_API_VERSION=21
777 */
778const char *thinlto_module_get_object_file(thinlto_code_gen_t cg,
779 unsigned int index);
780
781/**
782 * Sets which PIC code model to generate.
783 * Returns true on error (check lto_get_error_message() for details).
784 *
785 * \since LTO_API_VERSION=18
786 */
787extern lto_bool_t thinlto_codegen_set_pic_model(thinlto_code_gen_t cg,
788 lto_codegen_model);
789
790/**
791 * Sets the path to a directory to use as a storage for temporary bitcode files.
792 * The intention is to make the bitcode files available for debugging at various
793 * stage of the pipeline.
794 *
795 * \since LTO_API_VERSION=18
796 */
797extern void thinlto_codegen_set_savetemps_dir(thinlto_code_gen_t cg,
798 const char *save_temps_dir);
799
800/**
801 * Set the path to a directory where to save generated object files. This
802 * path can be used by a linker to request on-disk files instead of in-memory
803 * buffers. When set, results are available through
804 * thinlto_module_get_object_file() instead of thinlto_module_get_object().
805 *
806 * \since LTO_API_VERSION=21
807 */
808void thinlto_set_generated_objects_dir(thinlto_code_gen_t cg,
809 const char *save_temps_dir);
810
811/**
812 * Sets the cpu to generate code for.
813 *
814 * \since LTO_API_VERSION=18
815 */
816extern void thinlto_codegen_set_cpu(thinlto_code_gen_t cg, const char *cpu);
817
818/**
819 * Disable CodeGen, only run the stages till codegen and stop. The output will
820 * be bitcode.
821 *
822 * \since LTO_API_VERSION=19
823 */
824extern void thinlto_codegen_disable_codegen(thinlto_code_gen_t cg,
825 lto_bool_t disable);
826
827/**
828 * Perform CodeGen only: disable all other stages.
829 *
830 * \since LTO_API_VERSION=19
831 */
832extern void thinlto_codegen_set_codegen_only(thinlto_code_gen_t cg,
833 lto_bool_t codegen_only);
834
835/**
836 * Parse -mllvm style debug options.
837 *
838 * \since LTO_API_VERSION=18
839 */
840extern void thinlto_debug_options(const char *const *options, int number);
841
842/**
843 * Test if a module has support for ThinLTO linking.
844 *
845 * \since LTO_API_VERSION=18
846 */
847extern lto_bool_t lto_module_is_thinlto(lto_module_t mod);
848
849/**
850 * Adds a symbol to the list of global symbols that must exist in the final
851 * generated code. If a function is not listed there, it might be inlined into
852 * every usage and optimized away. For every single module, the functions
853 * referenced from code outside of the ThinLTO modules need to be added here.
854 *
855 * \since LTO_API_VERSION=18
856 */
857extern void thinlto_codegen_add_must_preserve_symbol(thinlto_code_gen_t cg,
858 const char *name,
859 int length);
860
861/**
862 * Adds a symbol to the list of global symbols that are cross-referenced between
863 * ThinLTO files. If the ThinLTO CodeGenerator can ensure that every
864 * references from a ThinLTO module to this symbol is optimized away, then
865 * the symbol can be discarded.
866 *
867 * \since LTO_API_VERSION=18
868 */
869extern void thinlto_codegen_add_cross_referenced_symbol(thinlto_code_gen_t cg,
870 const char *name,
871 int length);
872
873/**
874 * @} // endgoup LLVMCTLTO
875 * @defgroup LLVMCTLTO_CACHING ThinLTO Cache Control
876 * @ingroup LLVMCTLTO
877 *
878 * These entry points control the ThinLTO cache. The cache is intended to
879 * support incremental builds, and thus needs to be persistent across builds.
880 * The client enables the cache by supplying a path to an existing directory.
881 * The code generator will use this to store objects files that may be reused
882 * during a subsequent build.
883 * To avoid filling the disk space, a few knobs are provided:
884 * - The pruning interval limits the frequency at which the garbage collector
885 * will try to scan the cache directory to prune expired entries.
886 * Setting to a negative number disables the pruning.
887 * - The pruning expiration time indicates to the garbage collector how old an
888 * entry needs to be to be removed.
889 * - Finally, the garbage collector can be instructed to prune the cache until
890 * the occupied space goes below a threshold.
891 * @{
892 */
893
894/**
895 * Sets the path to a directory to use as a cache storage for incremental build.
896 * Setting this activates caching.
897 *
898 * \since LTO_API_VERSION=18
899 */
900extern void thinlto_codegen_set_cache_dir(thinlto_code_gen_t cg,
901 const char *cache_dir);
902
903/**
904 * Sets the cache pruning interval (in seconds). A negative value disables the
905 * pruning. An unspecified default value will be applied, and a value of 0 will
906 * force prunning to occur.
907 *
908 * \since LTO_API_VERSION=18
909 */
910extern void thinlto_codegen_set_cache_pruning_interval(thinlto_code_gen_t cg,
911 int interval);
912
913/**
914 * Sets the maximum cache size that can be persistent across build, in terms of
915 * percentage of the available space on the disk. Set to 100 to indicate
916 * no limit, 50 to indicate that the cache size will not be left over half the
917 * available space. A value over 100 will be reduced to 100, a value of 0 will
918 * be ignored. An unspecified default value will be applied.
919 *
920 * The formula looks like:
921 * AvailableSpace = FreeSpace + ExistingCacheSize
922 * NewCacheSize = AvailableSpace * P/100
923 *
924 * \since LTO_API_VERSION=18
925 */
926extern void thinlto_codegen_set_final_cache_size_relative_to_available_space(
927 thinlto_code_gen_t cg, unsigned percentage);
928
929/**
930 * Sets the expiration (in seconds) for an entry in the cache. An unspecified
931 * default value will be applied. A value of 0 will be ignored.
932 *
933 * \since LTO_API_VERSION=18
934 */
935extern void thinlto_codegen_set_cache_entry_expiration(thinlto_code_gen_t cg,
936 unsigned expiration);
937
938/**
939 * Sets the maximum size of the cache directory (in bytes). A value over the
940 * amount of available space on the disk will be reduced to the amount of
941 * available space. An unspecified default value will be applied. A value of 0
942 * will be ignored.
943 *
944 * \since LTO_API_VERSION=22
945 */
946extern void thinlto_codegen_set_cache_size_bytes(thinlto_code_gen_t cg,
947 unsigned max_size_bytes);
948
949/**
950 * Same as thinlto_codegen_set_cache_size_bytes, except the maximum size is in
951 * megabytes (2^20 bytes).
952 *
953 * \since LTO_API_VERSION=23
954 */
955extern void
956thinlto_codegen_set_cache_size_megabytes(thinlto_code_gen_t cg,
957 unsigned max_size_megabytes);
958
959/**
960 * Sets the maximum number of files in the cache directory. An unspecified
961 * default value will be applied. A value of 0 will be ignored.
962 *
963 * \since LTO_API_VERSION=22
964 */
965extern void thinlto_codegen_set_cache_size_files(thinlto_code_gen_t cg,
966 unsigned max_size_files);
967
968/**
969 * @} // endgroup LLVMCTLTO_CACHING
970 */
971
972LLVM_C_EXTERN_C_END
973
974#endif /* LLVM_C_LTO_H */
975