Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

Rev

Blame | Last modification | View Log | Download | RSS feed

  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>
  31. typedef 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. */
  36. typedef unsigned char lto_bool_t;
  37. #endif
  38. #else
  39. typedef bool lto_bool_t;
  40. #endif
  41.  
  42. /**
  43.  * @defgroup LLVMCLTO LTO
  44.  * @ingroup LLVMC
  45.  *
  46.  * @{
  47.  */
  48.  
  49. #define LTO_API_VERSION 29
  50.  
  51. /**
  52.  * \since prior to LTO_API_VERSION=3
  53.  */
  54. typedef 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.  */
  79. typedef 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.  */
  87. typedef 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 */
  95. typedef struct LLVMOpaqueLTOModule *lto_module_t;
  96.  
  97. /** opaque reference to a code generator */
  98. typedef struct LLVMOpaqueLTOCodeGenerator *lto_code_gen_t;
  99.  
  100. /** opaque reference to a thin code generator */
  101. typedef struct LLVMOpaqueThinLTOCodeGenerator *thinlto_code_gen_t;
  102.  
  103. LLVM_C_EXTERN_C_BEGIN
  104.  
  105. /**
  106.  * Returns a printable string.
  107.  *
  108.  * \since prior to LTO_API_VERSION=3
  109.  */
  110. extern const char*
  111. lto_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.  */
  118. extern const char*
  119. lto_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.  */
  126. extern lto_bool_t
  127. lto_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.  */
  134. extern lto_bool_t
  135. lto_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.  */
  144. extern lto_bool_t
  145. lto_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.  */
  152. extern 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.  */
  160. extern lto_bool_t
  161. lto_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.  */
  170. extern lto_module_t
  171. lto_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.  */
  179. extern lto_module_t
  180. lto_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.  */
  188. extern lto_module_t
  189. lto_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.  */
  203. extern lto_module_t
  204. lto_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.  */
  217. extern lto_module_t
  218. lto_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.  */
  227. extern lto_module_t
  228. lto_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.  */
  236. extern lto_module_t
  237. lto_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.  */
  246. extern void
  247. lto_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.  */
  254. extern const char*
  255. lto_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.  */
  262. extern void
  263. lto_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.  */
  270. extern unsigned int
  271. lto_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.  */
  278. extern const char*
  279. lto_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.  */
  286. extern lto_symbol_attributes
  287. lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index);
  288.  
  289. /**
  290.  * Returns the module's linker options.
  291.  *
  292.  * The linker options may consist of multiple flags. It is the linker's
  293.  * responsibility to split the flags using a platform-specific mechanism.
  294.  *
  295.  * \since LTO_API_VERSION=16
  296.  */
  297. extern const char*
  298. lto_module_get_linkeropts(lto_module_t mod);
  299.  
  300. /**
  301.  * If targeting mach-o on darwin, this function gets the CPU type and subtype
  302.  * that will end up being encoded in the mach-o header. These are the values
  303.  * that can be found in mach/machine.h.
  304.  *
  305.  * \p out_cputype and \p out_cpusubtype must be non-NULL.
  306.  *
  307.  * Returns true on error (check lto_get_error_message() for details).
  308.  *
  309.  * \since LTO_API_VERSION=27
  310.  */
  311. extern lto_bool_t lto_module_get_macho_cputype(lto_module_t mod,
  312.                                                unsigned int *out_cputype,
  313.                                                unsigned int *out_cpusubtype);
  314.  
  315. /**
  316.  * This function can be used by the linker to check if a given module has
  317.  * any constructor or destructor functions.
  318.  *
  319.  * Returns true if the module has either the @llvm.global_ctors or the
  320.  * @llvm.global_dtors symbol. Otherwise returns false.
  321.  *
  322.  * \since LTO_API_VERSION=29
  323.  */
  324. extern lto_bool_t lto_module_has_ctor_dtor(lto_module_t mod);
  325. /**
  326.  * Diagnostic severity.
  327.  *
  328.  * \since LTO_API_VERSION=7
  329.  */
  330. typedef enum {
  331.   LTO_DS_ERROR = 0,
  332.   LTO_DS_WARNING = 1,
  333.   LTO_DS_REMARK = 3, // Added in LTO_API_VERSION=10.
  334.   LTO_DS_NOTE = 2
  335. } lto_codegen_diagnostic_severity_t;
  336.  
  337. /**
  338.  * Diagnostic handler type.
  339.  * \p severity defines the severity.
  340.  * \p diag is the actual diagnostic.
  341.  * The diagnostic is not prefixed by any of severity keyword, e.g., 'error: '.
  342.  * \p ctxt is used to pass the context set with the diagnostic handler.
  343.  *
  344.  * \since LTO_API_VERSION=7
  345.  */
  346. typedef void (*lto_diagnostic_handler_t)(
  347.     lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt);
  348.  
  349. /**
  350.  * Set a diagnostic handler and the related context (void *).
  351.  * This is more general than lto_get_error_message, as the diagnostic handler
  352.  * can be called at anytime within lto.
  353.  *
  354.  * \since LTO_API_VERSION=7
  355.  */
  356. extern void lto_codegen_set_diagnostic_handler(lto_code_gen_t,
  357.                                                lto_diagnostic_handler_t,
  358.                                                void *);
  359.  
  360. /**
  361.  * Instantiates a code generator.
  362.  * Returns NULL on error (check lto_get_error_message() for details).
  363.  *
  364.  * All modules added using \a lto_codegen_add_module() must have been created
  365.  * in the same context as the codegen.
  366.  *
  367.  * \since prior to LTO_API_VERSION=3
  368.  */
  369. extern lto_code_gen_t
  370. lto_codegen_create(void);
  371.  
  372. /**
  373.  * Instantiate a code generator in its own context.
  374.  *
  375.  * Instantiates a code generator in its own context.  Modules added via \a
  376.  * lto_codegen_add_module() must have all been created in the same context,
  377.  * using \a lto_module_create_in_codegen_context().
  378.  *
  379.  * \since LTO_API_VERSION=11
  380.  */
  381. extern lto_code_gen_t
  382. lto_codegen_create_in_local_context(void);
  383.  
  384. /**
  385.  * Frees all code generator and all memory it internally allocated.
  386.  * Upon return the lto_code_gen_t is no longer valid.
  387.  *
  388.  * \since prior to LTO_API_VERSION=3
  389.  */
  390. extern void
  391. lto_codegen_dispose(lto_code_gen_t);
  392.  
  393. /**
  394.  * Add an object module to the set of modules for which code will be generated.
  395.  * Returns true on error (check lto_get_error_message() for details).
  396.  *
  397.  * \c cg and \c mod must both be in the same context.  See \a
  398.  * lto_codegen_create_in_local_context() and \a
  399.  * lto_module_create_in_codegen_context().
  400.  *
  401.  * \since prior to LTO_API_VERSION=3
  402.  */
  403. extern lto_bool_t
  404. lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod);
  405.  
  406. /**
  407.  * Sets the object module for code generation. This will transfer the ownership
  408.  * of the module to the code generator.
  409.  *
  410.  * \c cg and \c mod must both be in the same context.
  411.  *
  412.  * \since LTO_API_VERSION=13
  413.  */
  414. extern void
  415. lto_codegen_set_module(lto_code_gen_t cg, lto_module_t mod);
  416.  
  417. /**
  418.  * Sets if debug info should be generated.
  419.  * Returns true on error (check lto_get_error_message() for details).
  420.  *
  421.  * \since prior to LTO_API_VERSION=3
  422.  */
  423. extern lto_bool_t
  424. lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model);
  425.  
  426. /**
  427.  * Sets which PIC code model to generated.
  428.  * Returns true on error (check lto_get_error_message() for details).
  429.  *
  430.  * \since prior to LTO_API_VERSION=3
  431.  */
  432. extern lto_bool_t
  433. lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model);
  434.  
  435. /**
  436.  * Sets the cpu to generate code for.
  437.  *
  438.  * \since LTO_API_VERSION=4
  439.  */
  440. extern void
  441. lto_codegen_set_cpu(lto_code_gen_t cg, const char *cpu);
  442.  
  443. /**
  444.  * Sets the location of the assembler tool to run. If not set, libLTO
  445.  * will use gcc to invoke the assembler.
  446.  *
  447.  * \since LTO_API_VERSION=3
  448.  */
  449. extern void
  450. lto_codegen_set_assembler_path(lto_code_gen_t cg, const char* path);
  451.  
  452. /**
  453.  * Sets extra arguments that libLTO should pass to the assembler.
  454.  *
  455.  * \since LTO_API_VERSION=4
  456.  */
  457. extern void
  458. lto_codegen_set_assembler_args(lto_code_gen_t cg, const char **args,
  459.                                int nargs);
  460.  
  461. /**
  462.  * Adds to a list of all global symbols that must exist in the final generated
  463.  * code. If a function is not listed there, it might be inlined into every usage
  464.  * and optimized away.
  465.  *
  466.  * \since prior to LTO_API_VERSION=3
  467.  */
  468. extern void
  469. lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char* symbol);
  470.  
  471. /**
  472.  * Writes a new object file at the specified path that contains the
  473.  * merged contents of all modules added so far.
  474.  * Returns true on error (check lto_get_error_message() for details).
  475.  *
  476.  * \since LTO_API_VERSION=5
  477.  */
  478. extern lto_bool_t
  479. lto_codegen_write_merged_modules(lto_code_gen_t cg, const char* path);
  480.  
  481. /**
  482.  * Generates code for all added modules into one native object file.
  483.  * This calls lto_codegen_optimize then lto_codegen_compile_optimized.
  484.  *
  485.  * On success returns a pointer to a generated mach-o/ELF buffer and
  486.  * length set to the buffer size.  The buffer is owned by the
  487.  * lto_code_gen_t and will be freed when lto_codegen_dispose()
  488.  * is called, or lto_codegen_compile() is called again.
  489.  * On failure, returns NULL (check lto_get_error_message() for details).
  490.  *
  491.  * \since prior to LTO_API_VERSION=3
  492.  */
  493. extern const void*
  494. lto_codegen_compile(lto_code_gen_t cg, size_t* length);
  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 (instead
  499.  * of returning a generated mach-o/ELF buffer, it writes to a file).
  500.  *
  501.  * The name of the file is written to name. Returns true on error.
  502.  *
  503.  * \since LTO_API_VERSION=5
  504.  */
  505. extern lto_bool_t
  506. lto_codegen_compile_to_file(lto_code_gen_t cg, const char** name);
  507.  
  508. /**
  509.  * Runs optimization for the merged module. Returns true on error.
  510.  *
  511.  * \since LTO_API_VERSION=12
  512.  */
  513. extern lto_bool_t
  514. lto_codegen_optimize(lto_code_gen_t cg);
  515.  
  516. /**
  517.  * Generates code for the optimized merged module into one native object file.
  518.  * It will not run any IR optimizations on the merged module.
  519.  *
  520.  * On success returns a pointer to a generated mach-o/ELF buffer and length set
  521.  * to the buffer size.  The buffer is owned by the lto_code_gen_t and will be
  522.  * freed when lto_codegen_dispose() is called, or
  523.  * lto_codegen_compile_optimized() is called again. On failure, returns NULL
  524.  * (check lto_get_error_message() for details).
  525.  *
  526.  * \since LTO_API_VERSION=12
  527.  */
  528. extern const void*
  529. lto_codegen_compile_optimized(lto_code_gen_t cg, size_t* length);
  530.  
  531. /**
  532.  * Returns the runtime API version.
  533.  *
  534.  * \since LTO_API_VERSION=12
  535.  */
  536. extern unsigned int
  537. lto_api_version(void);
  538.  
  539. /**
  540.  * Parses options immediately, making them available as early as possible. For
  541.  * example during executing codegen::InitTargetOptionsFromCodeGenFlags. Since
  542.  * parsing shud only happen once, only one of lto_codegen_debug_options or
  543.  * lto_set_debug_options should be called.
  544.  *
  545.  * This function takes one or more options separated by spaces.
  546.  * Warning: passing file paths through this function may confuse the argument
  547.  * parser if the paths contain spaces.
  548.  *
  549.  * \since LTO_API_VERSION=28
  550.  */
  551. extern void lto_set_debug_options(const char *const *options, int number);
  552.  
  553. /**
  554.  * Sets options to help debug codegen bugs. Since parsing shud only happen once,
  555.  * only one of lto_codegen_debug_options or lto_set_debug_options
  556.  * should be called.
  557.  *
  558.  * This function takes one or more options separated by spaces.
  559.  * Warning: passing file paths through this function may confuse the argument
  560.  * parser if the paths contain spaces.
  561.  *
  562.  * \since prior to LTO_API_VERSION=3
  563.  */
  564. extern void
  565. lto_codegen_debug_options(lto_code_gen_t cg, const char *);
  566.  
  567. /**
  568.  * Same as the previous function, but takes every option separately through an
  569.  * array.
  570.  *
  571.  * \since prior to LTO_API_VERSION=26
  572.  */
  573. extern void lto_codegen_debug_options_array(lto_code_gen_t cg,
  574.                                             const char *const *, int number);
  575.  
  576. /**
  577.  * Initializes LLVM disassemblers.
  578.  * FIXME: This doesn't really belong here.
  579.  *
  580.  * \since LTO_API_VERSION=5
  581.  */
  582. extern void
  583. lto_initialize_disassembler(void);
  584.  
  585. /**
  586.  * Sets if we should run internalize pass during optimization and code
  587.  * generation.
  588.  *
  589.  * \since LTO_API_VERSION=14
  590.  */
  591. extern void
  592. lto_codegen_set_should_internalize(lto_code_gen_t cg,
  593.                                    lto_bool_t ShouldInternalize);
  594.  
  595. /**
  596.  * Set whether to embed uselists in bitcode.
  597.  *
  598.  * Sets whether \a lto_codegen_write_merged_modules() should embed uselists in
  599.  * output bitcode.  This should be turned on for all -save-temps output.
  600.  *
  601.  * \since LTO_API_VERSION=15
  602.  */
  603. extern void
  604. lto_codegen_set_should_embed_uselists(lto_code_gen_t cg,
  605.                                       lto_bool_t ShouldEmbedUselists);
  606.  
  607. /** Opaque reference to an LTO input file */
  608. typedef struct LLVMOpaqueLTOInput *lto_input_t;
  609.  
  610. /**
  611.   * Creates an LTO input file from a buffer. The path
  612.   * argument is used for diagnotics as this function
  613.   * otherwise does not know which file the given buffer
  614.   * is associated with.
  615.   *
  616.   * \since LTO_API_VERSION=24
  617.   */
  618. extern lto_input_t lto_input_create(const void *buffer,
  619.                                     size_t buffer_size,
  620.                                     const char *path);
  621.  
  622. /**
  623.   * Frees all memory internally allocated by the LTO input file.
  624.   * Upon return the lto_module_t is no longer valid.
  625.   *
  626.   * \since LTO_API_VERSION=24
  627.   */
  628. extern void lto_input_dispose(lto_input_t input);
  629.  
  630. /**
  631.   * Returns the number of dependent library specifiers
  632.   * for the given LTO input file.
  633.   *
  634.   * \since LTO_API_VERSION=24
  635.   */
  636. extern unsigned lto_input_get_num_dependent_libraries(lto_input_t input);
  637.  
  638. /**
  639.   * Returns the ith dependent library specifier
  640.   * for the given LTO input file. The returned
  641.   * string is not null-terminated.
  642.   *
  643.   * \since LTO_API_VERSION=24
  644.   */
  645. extern const char * lto_input_get_dependent_library(lto_input_t input,
  646.                                                     size_t index,
  647.                                                     size_t *size);
  648.  
  649. /**
  650.  * Returns the list of libcall symbols that can be generated by LTO
  651.  * that might not be visible from the symbol table of bitcode files.
  652.  *
  653.  * \since prior to LTO_API_VERSION=25
  654.  */
  655. extern const char *const *lto_runtime_lib_symbols_list(size_t *size);
  656.  
  657. /**
  658.  * @} // endgoup LLVMCLTO
  659.  * @defgroup LLVMCTLTO ThinLTO
  660.  * @ingroup LLVMC
  661.  *
  662.  * @{
  663.  */
  664.  
  665. /**
  666.  * Type to wrap a single object returned by ThinLTO.
  667.  *
  668.  * \since LTO_API_VERSION=18
  669.  */
  670. typedef struct {
  671.   const char *Buffer;
  672.   size_t Size;
  673. } LTOObjectBuffer;
  674.  
  675. /**
  676.  * Instantiates a ThinLTO code generator.
  677.  * Returns NULL on error (check lto_get_error_message() for details).
  678.  *
  679.  *
  680.  * The ThinLTOCodeGenerator is not intended to be reuse for multiple
  681.  * compilation: the model is that the client adds modules to the generator and
  682.  * ask to perform the ThinLTO optimizations / codegen, and finally destroys the
  683.  * codegenerator.
  684.  *
  685.  * \since LTO_API_VERSION=18
  686.  */
  687. extern thinlto_code_gen_t thinlto_create_codegen(void);
  688.  
  689. /**
  690.  * Frees the generator and all memory it internally allocated.
  691.  * Upon return the thinlto_code_gen_t is no longer valid.
  692.  *
  693.  * \since LTO_API_VERSION=18
  694.  */
  695. extern void thinlto_codegen_dispose(thinlto_code_gen_t cg);
  696.  
  697. /**
  698.  * Add a module to a ThinLTO code generator. Identifier has to be unique among
  699.  * all the modules in a code generator. The data buffer stays owned by the
  700.  * client, and is expected to be available for the entire lifetime of the
  701.  * thinlto_code_gen_t it is added to.
  702.  *
  703.  * On failure, returns NULL (check lto_get_error_message() for details).
  704.  *
  705.  *
  706.  * \since LTO_API_VERSION=18
  707.  */
  708. extern void thinlto_codegen_add_module(thinlto_code_gen_t cg,
  709.                                        const char *identifier, const char *data,
  710.                                        int length);
  711.  
  712. /**
  713.  * Optimize and codegen all the modules added to the codegenerator using
  714.  * ThinLTO. Resulting objects are accessible using thinlto_module_get_object().
  715.  *
  716.  * \since LTO_API_VERSION=18
  717.  */
  718. extern void thinlto_codegen_process(thinlto_code_gen_t cg);
  719.  
  720. /**
  721.  * Returns the number of object files produced by the ThinLTO CodeGenerator.
  722.  *
  723.  * It usually matches the number of input files, but this is not a guarantee of
  724.  * the API and may change in future implementation, so the client should not
  725.  * assume it.
  726.  *
  727.  * \since LTO_API_VERSION=18
  728.  */
  729. extern unsigned int thinlto_module_get_num_objects(thinlto_code_gen_t cg);
  730.  
  731. /**
  732.  * Returns a reference to the ith object file produced by the ThinLTO
  733.  * CodeGenerator.
  734.  *
  735.  * Client should use \p thinlto_module_get_num_objects() to get the number of
  736.  * available objects.
  737.  *
  738.  * \since LTO_API_VERSION=18
  739.  */
  740. extern LTOObjectBuffer thinlto_module_get_object(thinlto_code_gen_t cg,
  741.                                                  unsigned int index);
  742.  
  743. /**
  744.  * Returns the number of object files produced by the ThinLTO CodeGenerator.
  745.  *
  746.  * It usually matches the number of input files, but this is not a guarantee of
  747.  * the API and may change in future implementation, so the client should not
  748.  * assume it.
  749.  *
  750.  * \since LTO_API_VERSION=21
  751.  */
  752. unsigned int thinlto_module_get_num_object_files(thinlto_code_gen_t cg);
  753.  
  754. /**
  755.  * Returns the path to the ith object file produced by the ThinLTO
  756.  * CodeGenerator.
  757.  *
  758.  * Client should use \p thinlto_module_get_num_object_files() to get the number
  759.  * of available objects.
  760.  *
  761.  * \since LTO_API_VERSION=21
  762.  */
  763. const char *thinlto_module_get_object_file(thinlto_code_gen_t cg,
  764.                                            unsigned int index);
  765.  
  766. /**
  767.  * Sets which PIC code model to generate.
  768.  * Returns true on error (check lto_get_error_message() for details).
  769.  *
  770.  * \since LTO_API_VERSION=18
  771.  */
  772. extern lto_bool_t thinlto_codegen_set_pic_model(thinlto_code_gen_t cg,
  773.                                                 lto_codegen_model);
  774.  
  775. /**
  776.  * Sets the path to a directory to use as a storage for temporary bitcode files.
  777.  * The intention is to make the bitcode files available for debugging at various
  778.  * stage of the pipeline.
  779.  *
  780.  * \since LTO_API_VERSION=18
  781.  */
  782. extern void thinlto_codegen_set_savetemps_dir(thinlto_code_gen_t cg,
  783.                                               const char *save_temps_dir);
  784.  
  785. /**
  786.  * Set the path to a directory where to save generated object files. This
  787.  * path can be used by a linker to request on-disk files instead of in-memory
  788.  * buffers. When set, results are available through
  789.  * thinlto_module_get_object_file() instead of thinlto_module_get_object().
  790.  *
  791.  * \since LTO_API_VERSION=21
  792.  */
  793. void thinlto_set_generated_objects_dir(thinlto_code_gen_t cg,
  794.                                        const char *save_temps_dir);
  795.  
  796. /**
  797.  * Sets the cpu to generate code for.
  798.  *
  799.  * \since LTO_API_VERSION=18
  800.  */
  801. extern void thinlto_codegen_set_cpu(thinlto_code_gen_t cg, const char *cpu);
  802.  
  803. /**
  804.  * Disable CodeGen, only run the stages till codegen and stop. The output will
  805.  * be bitcode.
  806.  *
  807.  * \since LTO_API_VERSION=19
  808.  */
  809. extern void thinlto_codegen_disable_codegen(thinlto_code_gen_t cg,
  810.                                             lto_bool_t disable);
  811.  
  812. /**
  813.  * Perform CodeGen only: disable all other stages.
  814.  *
  815.  * \since LTO_API_VERSION=19
  816.  */
  817. extern void thinlto_codegen_set_codegen_only(thinlto_code_gen_t cg,
  818.                                              lto_bool_t codegen_only);
  819.  
  820. /**
  821.  * Parse -mllvm style debug options.
  822.  *
  823.  * \since LTO_API_VERSION=18
  824.  */
  825. extern void thinlto_debug_options(const char *const *options, int number);
  826.  
  827. /**
  828.  * Test if a module has support for ThinLTO linking.
  829.  *
  830.  * \since LTO_API_VERSION=18
  831.  */
  832. extern lto_bool_t lto_module_is_thinlto(lto_module_t mod);
  833.  
  834. /**
  835.  * Adds a symbol to the list of global symbols that must exist in the final
  836.  * generated code. If a function is not listed there, it might be inlined into
  837.  * every usage and optimized away. For every single module, the functions
  838.  * referenced from code outside of the ThinLTO modules need to be added here.
  839.  *
  840.  * \since LTO_API_VERSION=18
  841.  */
  842. extern void thinlto_codegen_add_must_preserve_symbol(thinlto_code_gen_t cg,
  843.                                                      const char *name,
  844.                                                      int length);
  845.  
  846. /**
  847.  * Adds a symbol to the list of global symbols that are cross-referenced between
  848.  * ThinLTO files. If the ThinLTO CodeGenerator can ensure that every
  849.  * references from a ThinLTO module to this symbol is optimized away, then
  850.  * the symbol can be discarded.
  851.  *
  852.  * \since LTO_API_VERSION=18
  853.  */
  854. extern void thinlto_codegen_add_cross_referenced_symbol(thinlto_code_gen_t cg,
  855.                                                         const char *name,
  856.                                                         int length);
  857.  
  858. /**
  859.  * @} // endgoup LLVMCTLTO
  860.  * @defgroup LLVMCTLTO_CACHING ThinLTO Cache Control
  861.  * @ingroup LLVMCTLTO
  862.  *
  863.  * These entry points control the ThinLTO cache. The cache is intended to
  864.  * support incremental builds, and thus needs to be persistent across builds.
  865.  * The client enables the cache by supplying a path to an existing directory.
  866.  * The code generator will use this to store objects files that may be reused
  867.  * during a subsequent build.
  868.  * To avoid filling the disk space, a few knobs are provided:
  869.  *  - The pruning interval limits the frequency at which the garbage collector
  870.  *    will try to scan the cache directory to prune expired entries.
  871.  *    Setting to a negative number disables the pruning.
  872.  *  - The pruning expiration time indicates to the garbage collector how old an
  873.  *    entry needs to be to be removed.
  874.  *  - Finally, the garbage collector can be instructed to prune the cache until
  875.  *    the occupied space goes below a threshold.
  876.  * @{
  877.  */
  878.  
  879. /**
  880.  * Sets the path to a directory to use as a cache storage for incremental build.
  881.  * Setting this activates caching.
  882.  *
  883.  * \since LTO_API_VERSION=18
  884.  */
  885. extern void thinlto_codegen_set_cache_dir(thinlto_code_gen_t cg,
  886.                                           const char *cache_dir);
  887.  
  888. /**
  889.  * Sets the cache pruning interval (in seconds). A negative value disables the
  890.  * pruning. An unspecified default value will be applied, and a value of 0 will
  891.  * force prunning to occur.
  892.  *
  893.  * \since LTO_API_VERSION=18
  894.  */
  895. extern void thinlto_codegen_set_cache_pruning_interval(thinlto_code_gen_t cg,
  896.                                                        int interval);
  897.  
  898. /**
  899.  * Sets the maximum cache size that can be persistent across build, in terms of
  900.  * percentage of the available space on the disk. Set to 100 to indicate
  901.  * no limit, 50 to indicate that the cache size will not be left over half the
  902.  * available space. A value over 100 will be reduced to 100, a value of 0 will
  903.  * be ignored. An unspecified default value will be applied.
  904.  *
  905.  * The formula looks like:
  906.  *  AvailableSpace = FreeSpace + ExistingCacheSize
  907.  *  NewCacheSize = AvailableSpace * P/100
  908.  *
  909.  * \since LTO_API_VERSION=18
  910.  */
  911. extern void thinlto_codegen_set_final_cache_size_relative_to_available_space(
  912.     thinlto_code_gen_t cg, unsigned percentage);
  913.  
  914. /**
  915.  * Sets the expiration (in seconds) for an entry in the cache. An unspecified
  916.  * default value will be applied. A value of 0 will be ignored.
  917.  *
  918.  * \since LTO_API_VERSION=18
  919.  */
  920. extern void thinlto_codegen_set_cache_entry_expiration(thinlto_code_gen_t cg,
  921.                                                        unsigned expiration);
  922.  
  923. /**
  924.  * Sets the maximum size of the cache directory (in bytes). A value over the
  925.  * amount of available space on the disk will be reduced to the amount of
  926.  * available space. An unspecified default value will be applied. A value of 0
  927.  * will be ignored.
  928.  *
  929.  * \since LTO_API_VERSION=22
  930.  */
  931. extern void thinlto_codegen_set_cache_size_bytes(thinlto_code_gen_t cg,
  932.                                                  unsigned max_size_bytes);
  933.  
  934. /**
  935.  * Same as thinlto_codegen_set_cache_size_bytes, except the maximum size is in
  936.  * megabytes (2^20 bytes).
  937.  *
  938.  * \since LTO_API_VERSION=23
  939.  */
  940. extern void
  941. thinlto_codegen_set_cache_size_megabytes(thinlto_code_gen_t cg,
  942.                                          unsigned max_size_megabytes);
  943.  
  944. /**
  945.  * Sets the maximum number of files in the cache directory. An unspecified
  946.  * default value will be applied. A value of 0 will be ignored.
  947.  *
  948.  * \since LTO_API_VERSION=22
  949.  */
  950. extern void thinlto_codegen_set_cache_size_files(thinlto_code_gen_t cg,
  951.                                                  unsigned max_size_files);
  952.  
  953. /**
  954.  * @} // endgroup LLVMCTLTO_CACHING
  955.  */
  956.  
  957. LLVM_C_EXTERN_C_END
  958.  
  959. #endif /* LLVM_C_LTO_H */
  960.