975 lines · c
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_H17#define LLVM_C_LTO_H18 19#include "llvm-c/ExternC.h"20 21#ifdef __cplusplus22#include <cstddef>23#else24#include <stddef.h>25#endif26#include <sys/types.h>27 28#ifndef __cplusplus29#if !defined(_MSC_VER)30#include <stdbool.h>31typedef bool lto_bool_t;32#else33/* MSVC in particular does not have anything like _Bool or bool in C, but we can34 at least make sure the type is the same size. The implementation side will35 use C++ bool. */36typedef unsigned char lto_bool_t;37#endif38#else39typedef bool lto_bool_t;40#endif41 42/**43 * @defgroup LLVMCLTO LTO44 * @ingroup LLVMC45 *46 * @{47 */48 49#define LTO_API_VERSION 3050 51/**52 * \since prior to LTO_API_VERSION=353 */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 = 0x0000800074} lto_symbol_attributes;75 76/**77 * \since prior to LTO_API_VERSION=378 */79typedef enum {80 LTO_DEBUG_MODEL_NONE = 0,81 LTO_DEBUG_MODEL_DWARF = 182} lto_debug_model;83 84/**85 * \since prior to LTO_API_VERSION=386 */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 = 392} 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_BEGIN104 105/**106 * Returns a printable string.107 *108 * \since prior to LTO_API_VERSION=3109 */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=3117 */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=3125 */126extern lto_bool_t127lto_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=3133 */134extern lto_bool_t135lto_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 (category140 * or class) in it.141 *142 * \since LTO_API_VERSION=20143 */144extern lto_bool_t145lto_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=3151 */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=3159 */160extern lto_bool_t161lto_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=3169 */170extern lto_module_t171lto_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=3178 */179extern lto_module_t180lto_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=9187 */188extern lto_module_t189lto_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 is196 * thread-safe. However, modules created this way should not be merged into an197 * 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=11202 */203extern lto_module_t204lto_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 to211 * 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=11216 */217extern lto_module_t218lto_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=5226 */227extern lto_module_t228lto_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=5235 */236extern lto_module_t237lto_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=3245 */246extern void247lto_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=3253 */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=4261 */262extern void263lto_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=3269 */270extern unsigned int271lto_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=3277 */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=3285 */286extern lto_symbol_attributes287lto_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=30293 */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=30300 */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's308 * responsibility to split the flags using a platform-specific mechanism.309 *310 * \since LTO_API_VERSION=16311 */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 subtype317 * that will end up being encoded in the mach-o header. These are the values318 * 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=27325 */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 has332 * any constructor or destructor functions.333 *334 * Returns true if the module has either the @llvm.global_ctors or the335 * @llvm.global_dtors symbol. Otherwise returns false.336 *337 * \since LTO_API_VERSION=29338 */339extern lto_bool_t lto_module_has_ctor_dtor(lto_module_t mod);340/**341 * Diagnostic severity.342 *343 * \since LTO_API_VERSION=7344 */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 = 2350} 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=7360 */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 handler367 * can be called at anytime within lto.368 *369 * \since LTO_API_VERSION=7370 */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 created380 * in the same context as the codegen.381 *382 * \since prior to LTO_API_VERSION=3383 */384extern lto_code_gen_t385lto_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 \a391 * 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=11395 */396extern lto_code_gen_t397lto_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=3404 */405extern void406lto_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 \a413 * lto_codegen_create_in_local_context() and \a414 * lto_module_create_in_codegen_context().415 *416 * \since prior to LTO_API_VERSION=3417 */418extern lto_bool_t419lto_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 ownership423 * 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=13428 */429extern void430lto_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=3437 */438extern lto_bool_t439lto_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=3446 */447extern lto_bool_t448lto_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=4454 */455extern void456lto_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, libLTO460 * will use gcc to invoke the assembler.461 *462 * \since LTO_API_VERSION=3463 */464extern void465lto_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=4471 */472extern void473lto_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 generated478 * code. If a function is not listed there, it might be inlined into every usage479 * and optimized away.480 *481 * \since prior to LTO_API_VERSION=3482 */483extern void484lto_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 the488 * 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=5492 */493extern lto_bool_t494lto_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 and501 * length set to the buffer size. The buffer is owned by the502 * 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=3507 */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 (instead514 * 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=5519 */520extern lto_bool_t521lto_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=12527 */528extern lto_bool_t529lto_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 set536 * to the buffer size. The buffer is owned by the lto_code_gen_t and will be537 * freed when lto_codegen_dispose() is called, or538 * lto_codegen_compile_optimized() is called again. On failure, returns NULL539 * (check lto_get_error_message() for details).540 *541 * \since LTO_API_VERSION=12542 */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=12550 */551extern unsigned int552lto_api_version(void);553 554/**555 * Parses options immediately, making them available as early as possible. For556 * example during executing codegen::InitTargetOptionsFromCodeGenFlags. Since557 * parsing shud only happen once, only one of lto_codegen_debug_options or558 * 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 argument562 * parser if the paths contain spaces.563 *564 * \since LTO_API_VERSION=28565 */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_options571 * 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 argument575 * parser if the paths contain spaces.576 *577 * \since prior to LTO_API_VERSION=3578 */579extern void580lto_codegen_debug_options(lto_code_gen_t cg, const char *);581 582/**583 * Same as the previous function, but takes every option separately through an584 * array.585 *586 * \since prior to LTO_API_VERSION=26587 */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=5596 */597extern void598lto_initialize_disassembler(void);599 600/**601 * Sets if we should run internalize pass during optimization and code602 * generation.603 *604 * \since LTO_API_VERSION=14605 */606extern void607lto_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 in614 * output bitcode. This should be turned on for all -save-temps output.615 *616 * \since LTO_API_VERSION=15617 */618extern void619lto_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 path627 * argument is used for diagnotics as this function628 * otherwise does not know which file the given buffer629 * is associated with.630 *631 * \since LTO_API_VERSION=24632 */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=24642 */643extern void lto_input_dispose(lto_input_t input);644 645/**646 * Returns the number of dependent library specifiers647 * for the given LTO input file.648 *649 * \since LTO_API_VERSION=24650 */651extern unsigned lto_input_get_num_dependent_libraries(lto_input_t input);652 653/**654 * Returns the ith dependent library specifier655 * for the given LTO input file. The returned656 * string is not null-terminated.657 *658 * \since LTO_API_VERSION=24659 */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 LTO666 * that might not be visible from the symbol table of bitcode files.667 *668 * \since prior to LTO_API_VERSION=25669 */670extern const char *const *lto_runtime_lib_symbols_list(size_t *size);671 672/**673 * @} // endgoup LLVMCLTO674 * @defgroup LLVMCTLTO ThinLTO675 * @ingroup LLVMC676 *677 * @{678 */679 680/**681 * Type to wrap a single object returned by ThinLTO.682 *683 * \since LTO_API_VERSION=18684 */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 multiple696 * compilation: the model is that the client adds modules to the generator and697 * ask to perform the ThinLTO optimizations / codegen, and finally destroys the698 * codegenerator.699 *700 * \since LTO_API_VERSION=18701 */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=18709 */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 among714 * all the modules in a code generator. The data buffer stays owned by the715 * client, and is expected to be available for the entire lifetime of the716 * 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=18722 */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 using729 * ThinLTO. Resulting objects are accessible using thinlto_module_get_object().730 *731 * \since LTO_API_VERSION=18732 */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 of739 * the API and may change in future implementation, so the client should not740 * assume it.741 *742 * \since LTO_API_VERSION=18743 */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 ThinLTO748 * CodeGenerator.749 *750 * Client should use \p thinlto_module_get_num_objects() to get the number of751 * available objects.752 *753 * \since LTO_API_VERSION=18754 */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 of762 * the API and may change in future implementation, so the client should not763 * assume it.764 *765 * \since LTO_API_VERSION=21766 */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 ThinLTO771 * CodeGenerator.772 *773 * Client should use \p thinlto_module_get_num_object_files() to get the number774 * of available objects.775 *776 * \since LTO_API_VERSION=21777 */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=18786 */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 various793 * stage of the pipeline.794 *795 * \since LTO_API_VERSION=18796 */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. This802 * path can be used by a linker to request on-disk files instead of in-memory803 * buffers. When set, results are available through804 * thinlto_module_get_object_file() instead of thinlto_module_get_object().805 *806 * \since LTO_API_VERSION=21807 */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=18815 */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 will820 * be bitcode.821 *822 * \since LTO_API_VERSION=19823 */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=19831 */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=18839 */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=18846 */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 final851 * generated code. If a function is not listed there, it might be inlined into852 * every usage and optimized away. For every single module, the functions853 * referenced from code outside of the ThinLTO modules need to be added here.854 *855 * \since LTO_API_VERSION=18856 */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 between863 * ThinLTO files. If the ThinLTO CodeGenerator can ensure that every864 * references from a ThinLTO module to this symbol is optimized away, then865 * the symbol can be discarded.866 *867 * \since LTO_API_VERSION=18868 */869extern void thinlto_codegen_add_cross_referenced_symbol(thinlto_code_gen_t cg,870 const char *name,871 int length);872 873/**874 * @} // endgoup LLVMCTLTO875 * @defgroup LLVMCTLTO_CACHING ThinLTO Cache Control876 * @ingroup LLVMCTLTO877 *878 * These entry points control the ThinLTO cache. The cache is intended to879 * 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 reused882 * 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 collector885 * 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 an888 * entry needs to be to be removed.889 * - Finally, the garbage collector can be instructed to prune the cache until890 * 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=18899 */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 the905 * pruning. An unspecified default value will be applied, and a value of 0 will906 * force prunning to occur.907 *908 * \since LTO_API_VERSION=18909 */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 of915 * percentage of the available space on the disk. Set to 100 to indicate916 * no limit, 50 to indicate that the cache size will not be left over half the917 * available space. A value over 100 will be reduced to 100, a value of 0 will918 * be ignored. An unspecified default value will be applied.919 *920 * The formula looks like:921 * AvailableSpace = FreeSpace + ExistingCacheSize922 * NewCacheSize = AvailableSpace * P/100923 *924 * \since LTO_API_VERSION=18925 */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 unspecified931 * default value will be applied. A value of 0 will be ignored.932 *933 * \since LTO_API_VERSION=18934 */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 the940 * amount of available space on the disk will be reduced to the amount of941 * available space. An unspecified default value will be applied. A value of 0942 * will be ignored.943 *944 * \since LTO_API_VERSION=22945 */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 in951 * megabytes (2^20 bytes).952 *953 * \since LTO_API_VERSION=23954 */955extern void956thinlto_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 unspecified961 * default value will be applied. A value of 0 will be ignored.962 *963 * \since LTO_API_VERSION=22964 */965extern void thinlto_codegen_set_cache_size_files(thinlto_code_gen_t cg,966 unsigned max_size_files);967 968/**969 * @} // endgroup LLVMCTLTO_CACHING970 */971 972LLVM_C_EXTERN_C_END973 974#endif /* LLVM_C_LTO_H */975