LLVM  14.0.0git
lto.h
Go to the documentation of this file.
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 */
66  LTO_SYMBOL_SCOPE_MASK = 0x00003800,
72  LTO_SYMBOL_COMDAT = 0x00004000,
73  LTO_SYMBOL_ALIAS = 0x00008000
75 
76 /**
77  * \since prior to LTO_API_VERSION=3
78  */
79 typedef enum {
83 
84 /**
85  * \since prior to LTO_API_VERSION=3
86  */
87 typedef enum {
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 
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*
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
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*
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
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*
280 
281 /**
282  * Returns the attributes of the ith symbol in the object module.
283  *
284  * \since prior to LTO_API_VERSION=3
285  */
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*
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  */
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  */
325 /**
326  * Diagnostic severity.
327  *
328  * \since LTO_API_VERSION=7
329  */
330 typedef enum {
333  LTO_DS_REMARK = 3, // Added in LTO_API_VERSION=10.
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  */
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
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
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
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
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
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
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
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
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
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
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*
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  */
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
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
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
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  */
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  */
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;
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
810  lto_bool_t disable);
811 
812 /**
813  * Perform CodeGen only: disable all other stages.
814  *
815  * \since LTO_API_VERSION=19
816  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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
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  */
951  unsigned max_size_files);
952 
953 /**
954  * @} // endgroup LLVMCTLTO_CACHING
955  */
956 
958 
959 #endif /* LLVM_C_LTO_H */
lto_module_t
struct LLVMOpaqueLTOModule * lto_module_t
opaque reference to a loaded object module
Definition: lto.h:95
lto_codegen_create
lto_code_gen_t lto_codegen_create(void)
Instantiates a code generator.
LTO_SYMBOL_SCOPE_DEFAULT
@ LTO_SYMBOL_SCOPE_DEFAULT
Definition: lto.h:70
lto_codegen_diagnostic_severity_t
lto_codegen_diagnostic_severity_t
Diagnostic severity.
Definition: lto.h:330
LTO_SYMBOL_SCOPE_PROTECTED
@ LTO_SYMBOL_SCOPE_PROTECTED
Definition: lto.h:69
lto_runtime_lib_symbols_list
const char *const * lto_runtime_lib_symbols_list(size_t *size)
Returns the list of libcall symbols that can be generated by LTO that might not be visible from the s...
lto_module_get_symbol_name
const char * lto_module_get_symbol_name(lto_module_t mod, unsigned int index)
Returns the name of the ith symbol in the object module.
lto_bool_t
bool lto_bool_t
Definition: lto.h:31
LTO_SYMBOL_DEFINITION_TENTATIVE
@ LTO_SYMBOL_DEFINITION_TENTATIVE
Definition: lto.h:62
LTO_DEBUG_MODEL_NONE
@ LTO_DEBUG_MODEL_NONE
Definition: lto.h:80
lto_codegen_compile_optimized
const void * lto_codegen_compile_optimized(lto_code_gen_t cg, size_t *length)
Generates code for the optimized merged module into one native object file.
lto_codegen_set_diagnostic_handler
void lto_codegen_set_diagnostic_handler(lto_code_gen_t, lto_diagnostic_handler_t, void *)
Set a diagnostic handler and the related context (void *).
LTO_DS_NOTE
@ LTO_DS_NOTE
Definition: lto.h:334
LTO_DS_REMARK
@ LTO_DS_REMARK
Definition: lto.h:333
lto_codegen_set_should_internalize
void lto_codegen_set_should_internalize(lto_code_gen_t cg, lto_bool_t ShouldInternalize)
Sets if we should run internalize pass during optimization and code generation.
thinlto_module_get_num_objects
unsigned int thinlto_module_get_num_objects(thinlto_code_gen_t cg)
Returns the number of object files produced by the ThinLTO CodeGenerator.
lto_codegen_debug_options_array
void lto_codegen_debug_options_array(lto_code_gen_t cg, const char *const *, int number)
Same as the previous function, but takes every option separately through an array.
lto_module_create_in_local_context
lto_module_t lto_module_create_in_local_context(const void *mem, size_t length, const char *path)
Loads an object file in its own context.
thinlto_debug_options
void thinlto_debug_options(const char *const *options, int number)
Parse -mllvm style debug options.
lto_module_is_object_file_in_memory
lto_bool_t lto_module_is_object_file_in_memory(const void *mem, size_t length)
Checks if a buffer is a loadable object file.
LTOObjectBuffer::Buffer
const char * Buffer
Definition: lto.h:671
lto_module_create
lto_module_t lto_module_create(const char *path)
Loads an object file from disk.
lto_module_get_symbol_attribute
lto_symbol_attributes lto_module_get_symbol_attribute(lto_module_t mod, unsigned int index)
Returns the attributes of the ith symbol in the object module.
lto_module_is_thinlto
lto_bool_t lto_module_is_thinlto(lto_module_t mod)
Test if a module has support for ThinLTO linking.
LTO_DS_WARNING
@ LTO_DS_WARNING
Definition: lto.h:332
lto_module_is_object_file_in_memory_for_target
lto_bool_t lto_module_is_object_file_in_memory_for_target(const void *mem, size_t length, const char *target_triple_prefix)
Checks if a buffer is a loadable object compiled for requested target.
thinlto_module_get_object_file
const char * thinlto_module_get_object_file(thinlto_code_gen_t cg, unsigned int index)
Returns the path to the ith object file produced by the ThinLTO CodeGenerator.
LTO_SYMBOL_PERMISSIONS_MASK
@ LTO_SYMBOL_PERMISSIONS_MASK
Definition: lto.h:56
LTO_SYMBOL_ALIAS
@ LTO_SYMBOL_ALIAS
Definition: lto.h:73
thinlto_codegen_dispose
void thinlto_codegen_dispose(thinlto_code_gen_t cg)
Frees the generator and all memory it internally allocated.
lto_input_dispose
void lto_input_dispose(lto_input_t input)
Frees all memory internally allocated by the LTO input file.
lto_codegen_set_module
void lto_codegen_set_module(lto_code_gen_t cg, lto_module_t mod)
Sets the object module for code generation.
lto_module_create_from_fd_at_offset
lto_module_t lto_module_create_from_fd_at_offset(int fd, const char *path, size_t file_size, size_t map_size, off_t offset)
Loads an object file from disk.
lto_codegen_set_assembler_args
void lto_codegen_set_assembler_args(lto_code_gen_t cg, const char **args, int nargs)
Sets extra arguments that libLTO should pass to the assembler.
lto_codegen_set_assembler_path
void lto_codegen_set_assembler_path(lto_code_gen_t cg, const char *path)
Sets the location of the assembler tool to run.
lto_module_create_in_codegen_context
lto_module_t lto_module_create_in_codegen_context(const void *mem, size_t length, const char *path, lto_code_gen_t cg)
Loads an object file in the codegen context.
LTO_SYMBOL_DEFINITION_WEAKUNDEF
@ LTO_SYMBOL_DEFINITION_WEAKUNDEF
Definition: lto.h:65
LTO_SYMBOL_PERMISSIONS_RODATA
@ LTO_SYMBOL_PERMISSIONS_RODATA
Definition: lto.h:59
thinlto_create_codegen
thinlto_code_gen_t thinlto_create_codegen(void)
Instantiates a ThinLTO code generator.
lto_codegen_compile
const void * lto_codegen_compile(lto_code_gen_t cg, size_t *length)
Generates code for all added modules into one native object file.
thinlto_codegen_set_cache_size_megabytes
void thinlto_codegen_set_cache_size_megabytes(thinlto_code_gen_t cg, unsigned max_size_megabytes)
Same as thinlto_codegen_set_cache_size_bytes, except the maximum size is in megabytes (2^20 bytes).
lto_module_get_num_symbols
unsigned int lto_module_get_num_symbols(lto_module_t mod)
Returns the number of symbols in the object module.
lto_module_is_object_file_for_target
lto_bool_t lto_module_is_object_file_for_target(const char *path, const char *target_triple_prefix)
Checks if a file is a loadable object compiled for requested target.
thinlto_codegen_add_module
void thinlto_codegen_add_module(thinlto_code_gen_t cg, const char *identifier, const char *data, int length)
Add a module to a ThinLTO code generator.
lto_codegen_set_pic_model
lto_bool_t lto_codegen_set_pic_model(lto_code_gen_t cg, lto_codegen_model)
Sets which PIC code model to generated.
thinlto_code_gen_t
struct LLVMOpaqueThinLTOCodeGenerator * thinlto_code_gen_t
opaque reference to a thin code generator
Definition: lto.h:101
lto_input_create
lto_input_t lto_input_create(const void *buffer, size_t buffer_size, const char *path)
Creates an LTO input file from a buffer.
LTO_SYMBOL_DEFINITION_UNDEFINED
@ LTO_SYMBOL_DEFINITION_UNDEFINED
Definition: lto.h:64
input
The initial backend is deliberately restricted to z10 We should add support for later architectures at some point If an asm ties an i32 r result to an i64 input
Definition: README.txt:10
lto_codegen_set_should_embed_uselists
void lto_codegen_set_should_embed_uselists(lto_code_gen_t cg, lto_bool_t ShouldEmbedUselists)
Set whether to embed uselists in bitcode.
LTO_SYMBOL_SCOPE_DEFAULT_CAN_BE_HIDDEN
@ LTO_SYMBOL_SCOPE_DEFAULT_CAN_BE_HIDDEN
Definition: lto.h:71
LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC
@ LTO_CODEGEN_PIC_MODEL_DYNAMIC_NO_PIC
Definition: lto.h:90
lto_debug_model
lto_debug_model
Definition: lto.h:79
lto_codegen_compile_to_file
lto_bool_t lto_codegen_compile_to_file(lto_code_gen_t cg, const char **name)
Generates code for all added modules into one native object file.
LTO_SYMBOL_COMDAT
@ LTO_SYMBOL_COMDAT
Definition: lto.h:72
thinlto_module_get_num_object_files
unsigned int thinlto_module_get_num_object_files(thinlto_code_gen_t cg)
Returns the number of object files produced by the ThinLTO CodeGenerator.
lto_module_set_target_triple
void lto_module_set_target_triple(lto_module_t mod, const char *triple)
Sets triple string with which the object will be codegened.
thinlto_set_generated_objects_dir
void thinlto_set_generated_objects_dir(thinlto_code_gen_t cg, const char *save_temps_dir)
Set the path to a directory where to save generated object files.
thinlto_codegen_process
void thinlto_codegen_process(thinlto_code_gen_t cg)
Optimize and codegen all the modules added to the codegenerator using ThinLTO.
thinlto_codegen_set_cache_entry_expiration
void thinlto_codegen_set_cache_entry_expiration(thinlto_code_gen_t cg, unsigned expiration)
Sets the expiration (in seconds) for an entry in the cache.
index
splat index
Definition: README_ALTIVEC.txt:181
lto_input_t
struct LLVMOpaqueLTOInput * lto_input_t
Opaque reference to an LTO input file.
Definition: lto.h:608
lto_api_version
unsigned int lto_api_version(void)
Returns the runtime API version.
thinlto_codegen_set_savetemps_dir
void thinlto_codegen_set_savetemps_dir(thinlto_code_gen_t cg, const char *save_temps_dir)
Sets the path to a directory to use as a storage for temporary bitcode files.
lto_module_create_from_memory_with_path
lto_module_t lto_module_create_from_memory_with_path(const void *mem, size_t length, const char *path)
Loads an object file from memory with an extra path argument.
LTO_SYMBOL_SCOPE_MASK
@ LTO_SYMBOL_SCOPE_MASK
Definition: lto.h:66
lto_code_gen_t
struct LLVMOpaqueLTOCodeGenerator * lto_code_gen_t
opaque reference to a code generator
Definition: lto.h:98
lto_module_create_from_memory
lto_module_t lto_module_create_from_memory(const void *mem, size_t length)
Loads an object file from memory.
size
i< reg-> size
Definition: README.txt:166
thinlto_codegen_set_pic_model
lto_bool_t thinlto_codegen_set_pic_model(thinlto_code_gen_t cg, lto_codegen_model)
Sets which PIC code model to generate.
LTO_DS_ERROR
@ LTO_DS_ERROR
Definition: lto.h:331
LTOObjectBuffer::Size
size_t Size
Definition: lto.h:672
LTO_SYMBOL_DEFINITION_MASK
@ LTO_SYMBOL_DEFINITION_MASK
Definition: lto.h:60
lto_get_version
const LLVM_C_EXTERN_C_BEGIN char * lto_get_version(void)
Returns a printable string.
lto_input_get_dependent_library
const char * lto_input_get_dependent_library(lto_input_t input, size_t index, size_t *size)
Returns the ith dependent library specifier for the given LTO input file.
LTO_SYMBOL_DEFINITION_WEAK
@ LTO_SYMBOL_DEFINITION_WEAK
Definition: lto.h:63
lto_diagnostic_handler_t
void(* lto_diagnostic_handler_t)(lto_codegen_diagnostic_severity_t severity, const char *diag, void *ctxt)
Diagnostic handler type.
Definition: lto.h:346
LTO_SYMBOL_DEFINITION_REGULAR
@ LTO_SYMBOL_DEFINITION_REGULAR
Definition: lto.h:61
thinlto_codegen_set_codegen_only
void thinlto_codegen_set_codegen_only(thinlto_code_gen_t cg, lto_bool_t codegen_only)
Perform CodeGen only: disable all other stages.
lto_codegen_model
lto_codegen_model
Definition: lto.h:87
lto_codegen_debug_options
void lto_codegen_debug_options(lto_code_gen_t cg, const char *)
Sets options to help debug codegen bugs.
lto_module_has_ctor_dtor
lto_bool_t lto_module_has_ctor_dtor(lto_module_t mod)
This function can be used by the linker to check if a given module has any constructor or destructor ...
lto_codegen_create_in_local_context
lto_code_gen_t lto_codegen_create_in_local_context(void)
Instantiate a code generator in its own context.
lto_get_error_message
const char * lto_get_error_message(void)
Returns the last error string or NULL if last operation was successful.
lto_set_debug_options
void lto_set_debug_options(const char *const *options, int number)
Parses options immediately, making them available as early as possible.
thinlto_module_get_object
LTOObjectBuffer thinlto_module_get_object(thinlto_code_gen_t cg, unsigned int index)
Returns a reference to the ith object file produced by the ThinLTO CodeGenerator.
lto_module_is_object_file
lto_bool_t lto_module_is_object_file(const char *path)
Checks if a file is a loadable object file.
lto_codegen_optimize
lto_bool_t lto_codegen_optimize(lto_code_gen_t cg)
Runs optimization for the merged module.
lto_module_has_objc_category
lto_bool_t lto_module_has_objc_category(const void *mem, size_t length)
Return true if Buffer contains a bitcode file with ObjC code (category or class) in it.
thinlto_codegen_disable_codegen
void thinlto_codegen_disable_codegen(thinlto_code_gen_t cg, lto_bool_t disable)
Disable CodeGen, only run the stages till codegen and stop.
LLVM_C_EXTERN_C_END
#define LLVM_C_EXTERN_C_END
Definition: ExternC.h:36
LTO_SYMBOL_SCOPE_INTERNAL
@ LTO_SYMBOL_SCOPE_INTERNAL
Definition: lto.h:67
name
static const char * name
Definition: SVEIntrinsicOpts.cpp:75
lto_module_create_from_fd
lto_module_t lto_module_create_from_fd(int fd, const char *path, size_t file_size)
Loads an object file from disk.
LTO_CODEGEN_PIC_MODEL_STATIC
@ LTO_CODEGEN_PIC_MODEL_STATIC
Definition: lto.h:88
lto_codegen_set_cpu
void lto_codegen_set_cpu(lto_code_gen_t cg, const char *cpu)
Sets the cpu to generate code for.
lto_module_get_linkeropts
const char * lto_module_get_linkeropts(lto_module_t mod)
Returns the module's linker options.
lto_initialize_disassembler
void lto_initialize_disassembler(void)
Initializes LLVM disassemblers.
LTOObjectBuffer
Type to wrap a single object returned by ThinLTO.
Definition: lto.h:670
LTO_SYMBOL_SCOPE_HIDDEN
@ LTO_SYMBOL_SCOPE_HIDDEN
Definition: lto.h:68
lto_codegen_set_debug_model
lto_bool_t lto_codegen_set_debug_model(lto_code_gen_t cg, lto_debug_model)
Sets if debug info should be generated.
options
The object format emitted by the WebAssembly backed is documented see the home and packaging for producing WebAssembly applications that can run in browsers and other environments wasi sdk provides a more minimal C C SDK based on llvm and a libc based on for producing WebAssemmbly applictions that use the WASI ABI Rust provides WebAssembly support integrated into Cargo There are two main options
Definition: README.txt:24
lto_codegen_add_module
lto_bool_t lto_codegen_add_module(lto_code_gen_t cg, lto_module_t mod)
Add an object module to the set of modules for which code will be generated.
LTO_CODEGEN_PIC_MODEL_DYNAMIC
@ LTO_CODEGEN_PIC_MODEL_DYNAMIC
Definition: lto.h:89
thinlto_codegen_set_cache_pruning_interval
void thinlto_codegen_set_cache_pruning_interval(thinlto_code_gen_t cg, int interval)
Sets the cache pruning interval (in seconds).
lto_codegen_add_must_preserve_symbol
void lto_codegen_add_must_preserve_symbol(lto_code_gen_t cg, const char *symbol)
Adds to a list of all global symbols that must exist in the final generated code.
LTO_SYMBOL_ALIGNMENT_MASK
@ LTO_SYMBOL_ALIGNMENT_MASK
Definition: lto.h:55
LLVM_C_EXTERN_C_BEGIN
#define LLVM_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
lto_module_get_macho_cputype
lto_bool_t lto_module_get_macho_cputype(lto_module_t mod, unsigned int *out_cputype, unsigned int *out_cpusubtype)
If targeting mach-o on darwin, this function gets the CPU type and subtype that will end up being enc...
LTO_DEBUG_MODEL_DWARF
@ LTO_DEBUG_MODEL_DWARF
Definition: lto.h:81
LTO_CODEGEN_PIC_MODEL_DEFAULT
@ LTO_CODEGEN_PIC_MODEL_DEFAULT
Definition: lto.h:91
lto_symbol_attributes
lto_symbol_attributes
Definition: lto.h:54
thinlto_codegen_set_final_cache_size_relative_to_available_space
void thinlto_codegen_set_final_cache_size_relative_to_available_space(thinlto_code_gen_t cg, unsigned percentage)
Sets the maximum cache size that can be persistent across build, in terms of percentage of the availa...
thinlto_codegen_set_cache_size_files
void thinlto_codegen_set_cache_size_files(thinlto_code_gen_t cg, unsigned max_size_files)
Sets the maximum number of files in the cache directory.
LTO_SYMBOL_PERMISSIONS_DATA
@ LTO_SYMBOL_PERMISSIONS_DATA
Definition: lto.h:58
thinlto_codegen_add_cross_referenced_symbol
void thinlto_codegen_add_cross_referenced_symbol(thinlto_code_gen_t cg, const char *name, int length)
Adds a symbol to the list of global symbols that are cross-referenced between ThinLTO files.
lto_codegen_write_merged_modules
lto_bool_t lto_codegen_write_merged_modules(lto_code_gen_t cg, const char *path)
Writes a new object file at the specified path that contains the merged contents of all modules added...
llvm::sys::fs::file_size
std::error_code file_size(const Twine &Path, uint64_t &Result)
Get file size.
Definition: FileSystem.h:691
lto_input_get_num_dependent_libraries
unsigned lto_input_get_num_dependent_libraries(lto_input_t input)
Returns the number of dependent library specifiers for the given LTO input file.
thinlto_codegen_set_cache_dir
void thinlto_codegen_set_cache_dir(thinlto_code_gen_t cg, const char *cache_dir)
Sets the path to a directory to use as a cache storage for incremental build.
lto_codegen_dispose
void lto_codegen_dispose(lto_code_gen_t)
Frees all code generator and all memory it internally allocated.
thinlto_codegen_set_cache_size_bytes
void thinlto_codegen_set_cache_size_bytes(thinlto_code_gen_t cg, unsigned max_size_bytes)
Sets the maximum size of the cache directory (in bytes).
thinlto_codegen_set_cpu
void thinlto_codegen_set_cpu(thinlto_code_gen_t cg, const char *cpu)
Sets the cpu to generate code for.
lto_module_dispose
void lto_module_dispose(lto_module_t mod)
Frees all memory internally allocated by the module.
thinlto_codegen_add_must_preserve_symbol
void thinlto_codegen_add_must_preserve_symbol(thinlto_code_gen_t cg, const char *name, int length)
Adds a symbol to the list of global symbols that must exist in the final generated code.
LTO_SYMBOL_PERMISSIONS_CODE
@ LTO_SYMBOL_PERMISSIONS_CODE
Definition: lto.h:57
ExternC.h
lto_module_get_target_triple
const char * lto_module_get_target_triple(lto_module_t mod)
Returns triple string which the object module was compiled under.