[lld-macho][easy] Create group for LLD-specific CLI flags
[lldb.git] / llvm / include / llvm / LTO / Config.h
1 //===-Config.h - LLVM Link Time Optimizer Configuration ---------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file defines the lto::Config data structure, which allows clients to
10 // configure LTO.
11 //
12 //===----------------------------------------------------------------------===//
13
14 #ifndef LLVM_LTO_CONFIG_H
15 #define LLVM_LTO_CONFIG_H
16
17 #include "llvm/ADT/DenseSet.h"
18 #include "llvm/Config/llvm-config.h"
19 #include "llvm/IR/DiagnosticInfo.h"
20 #include "llvm/IR/GlobalValue.h"
21 #include "llvm/IR/LLVMContext.h"
22 #include "llvm/Passes/PassBuilder.h"
23 #include "llvm/Support/CodeGen.h"
24 #include "llvm/Target/TargetOptions.h"
25
26 #include <functional>
27
28 namespace llvm {
29
30 class Error;
31 class Module;
32 class ModuleSummaryIndex;
33 class raw_pwrite_stream;
34
35 namespace lto {
36
37 /// LTO configuration. A linker can configure LTO by setting fields in this data
38 /// structure and passing it to the lto::LTO constructor.
39 struct Config {
40   // Note: when adding fields here, consider whether they need to be added to
41   // computeCacheKey in LTO.cpp.
42   std::string CPU;
43   TargetOptions Options;
44   std::vector<std::string> MAttrs;
45   std::vector<std::string> PassPlugins;
46   Optional<Reloc::Model> RelocModel = Reloc::PIC_;
47   Optional<CodeModel::Model> CodeModel = None;
48   CodeGenOpt::Level CGOptLevel = CodeGenOpt::Default;
49   CodeGenFileType CGFileType = CGFT_ObjectFile;
50   unsigned OptLevel = 2;
51   bool DisableVerify = false;
52
53   /// Use the new pass manager
54   bool UseNewPM = LLVM_ENABLE_NEW_PASS_MANAGER;
55
56   /// Flag to indicate that the optimizer should not assume builtins are present
57   /// on the target.
58   bool Freestanding = false;
59
60   /// Disable entirely the optimizer, including importing for ThinLTO
61   bool CodeGenOnly = false;
62
63   /// Run PGO context sensitive IR instrumentation.
64   bool RunCSIRInstr = false;
65
66   /// Asserts whether we can assume whole program visibility during the LTO
67   /// link.
68   bool HasWholeProgramVisibility = false;
69
70   /// Always emit a Regular LTO object even when it is empty because no Regular
71   /// LTO modules were linked. This option is useful for some build system which
72   /// want to know a priori all possible output files.
73   bool AlwaysEmitRegularLTOObj = false;
74
75   /// If this field is set, the set of passes run in the middle-end optimizer
76   /// will be the one specified by the string. Only works with the new pass
77   /// manager as the old one doesn't have this ability.
78   std::string OptPipeline;
79
80   // If this field is set, it has the same effect of specifying an AA pipeline
81   // identified by the string. Only works with the new pass manager, in
82   // conjunction OptPipeline.
83   std::string AAPipeline;
84
85   /// Setting this field will replace target triples in input files with this
86   /// triple.
87   std::string OverrideTriple;
88
89   /// Setting this field will replace unspecified target triples in input files
90   /// with this triple.
91   std::string DefaultTriple;
92
93   /// Context Sensitive PGO profile path.
94   std::string CSIRProfile;
95
96   /// Sample PGO profile path.
97   std::string SampleProfile;
98
99   /// Name remapping file for profile data.
100   std::string ProfileRemapping;
101
102   /// The directory to store .dwo files.
103   std::string DwoDir;
104
105   /// The name for the split debug info file used for the DW_AT_[GNU_]dwo_name
106   /// attribute in the skeleton CU. This should generally only be used when
107   /// running an individual backend directly via thinBackend(), as otherwise
108   /// all objects would use the same .dwo file. Not used as output path.
109   std::string SplitDwarfFile;
110
111   /// The path to write a .dwo file to. This should generally only be used when
112   /// running an individual backend directly via thinBackend(), as otherwise
113   /// all .dwo files will be written to the same path. Not used in skeleton CU.
114   std::string SplitDwarfOutput;
115
116   /// Optimization remarks file path.
117   std::string RemarksFilename;
118
119   /// Optimization remarks pass filter.
120   std::string RemarksPasses;
121
122   /// Whether to emit optimization remarks with hotness informations.
123   bool RemarksWithHotness = false;
124
125   /// The minimum hotness value a diagnostic needs in order to be included in
126   /// optimization diagnostics.
127   ///
128   /// The threshold is an Optional value, which maps to one of the 3 states:
129   /// 1. 0            => threshold disabled. All emarks will be printed.
130   /// 2. positive int => manual threshold by user. Remarks with hotness exceed
131   ///                    threshold will be printed.
132   /// 3. None         => 'auto' threshold by user. The actual value is not
133   ///                    available at command line, but will be synced with
134   ///                    hotness threhold from profile summary during
135   ///                    compilation.
136   ///
137   /// If threshold option is not specified, it is disabled by default.
138   llvm::Optional<uint64_t> RemarksHotnessThreshold = 0;
139
140   /// The format used for serializing remarks (default: YAML).
141   std::string RemarksFormat;
142
143   /// Whether to emit the pass manager debuggging informations.
144   bool DebugPassManager = false;
145
146   /// Statistics output file path.
147   std::string StatsFile;
148
149   /// Specific thinLTO modules to compile.
150   std::vector<std::string> ThinLTOModulesToCompile;
151
152   /// Time trace enabled.
153   bool TimeTraceEnabled = false;
154
155   /// Time trace granularity.
156   unsigned TimeTraceGranularity = 500;
157
158   bool ShouldDiscardValueNames = true;
159   DiagnosticHandlerFunction DiagHandler;
160
161   /// If this field is set, LTO will write input file paths and symbol
162   /// resolutions here in llvm-lto2 command line flag format. This can be
163   /// used for testing and for running the LTO pipeline outside of the linker
164   /// with llvm-lto2.
165   std::unique_ptr<raw_ostream> ResolutionFile;
166
167   /// Tunable parameters for passes in the default pipelines.
168   PipelineTuningOptions PTO;
169
170   /// The following callbacks deal with tasks, which normally represent the
171   /// entire optimization and code generation pipeline for what will become a
172   /// single native object file. Each task has a unique identifier between 0 and
173   /// getMaxTasks()-1, which is supplied to the callback via the Task parameter.
174   /// A task represents the entire pipeline for ThinLTO and regular
175   /// (non-parallel) LTO, but a parallel code generation task will be split into
176   /// N tasks before code generation, where N is the parallelism level.
177   ///
178   /// LTO may decide to stop processing a task at any time, for example if the
179   /// module is empty or if a module hook (see below) returns false. For this
180   /// reason, the client should not expect to receive exactly getMaxTasks()
181   /// native object files.
182
183   /// A module hook may be used by a linker to perform actions during the LTO
184   /// pipeline. For example, a linker may use this function to implement
185   /// -save-temps. If this function returns false, any further processing for
186   /// that task is aborted.
187   ///
188   /// Module hooks must be thread safe with respect to the linker's internal
189   /// data structures. A module hook will never be called concurrently from
190   /// multiple threads with the same task ID, or the same module.
191   ///
192   /// Note that in out-of-process backend scenarios, none of the hooks will be
193   /// called for ThinLTO tasks.
194   using ModuleHookFn = std::function<bool(unsigned Task, const Module &)>;
195
196   /// This module hook is called after linking (regular LTO) or loading
197   /// (ThinLTO) the module, before modifying it.
198   ModuleHookFn PreOptModuleHook;
199
200   /// This hook is called after promoting any internal functions
201   /// (ThinLTO-specific).
202   ModuleHookFn PostPromoteModuleHook;
203
204   /// This hook is called after internalizing the module.
205   ModuleHookFn PostInternalizeModuleHook;
206
207   /// This hook is called after importing from other modules (ThinLTO-specific).
208   ModuleHookFn PostImportModuleHook;
209
210   /// This module hook is called after optimization is complete.
211   ModuleHookFn PostOptModuleHook;
212
213   /// This module hook is called before code generation. It is similar to the
214   /// PostOptModuleHook, but for parallel code generation it is called after
215   /// splitting the module.
216   ModuleHookFn PreCodeGenModuleHook;
217
218   /// A combined index hook is called after all per-module indexes have been
219   /// combined (ThinLTO-specific). It can be used to implement -save-temps for
220   /// the combined index.
221   ///
222   /// If this function returns false, any further processing for ThinLTO tasks
223   /// is aborted.
224   ///
225   /// It is called regardless of whether the backend is in-process, although it
226   /// is not called from individual backend processes.
227   using CombinedIndexHookFn = std::function<bool(
228       const ModuleSummaryIndex &Index,
229       const DenseSet<GlobalValue::GUID> &GUIDPreservedSymbols)>;
230   CombinedIndexHookFn CombinedIndexHook;
231
232   /// This is a convenience function that configures this Config object to write
233   /// temporary files named after the given OutputFileName for each of the LTO
234   /// phases to disk. A client can use this function to implement -save-temps.
235   ///
236   /// FIXME: Temporary files derived from ThinLTO backends are currently named
237   /// after the input file name, rather than the output file name, when
238   /// UseInputModulePath is set to true.
239   ///
240   /// Specifically, it (1) sets each of the above module hooks and the combined
241   /// index hook to a function that calls the hook function (if any) that was
242   /// present in the appropriate field when the addSaveTemps function was
243   /// called, and writes the module to a bitcode file with a name prefixed by
244   /// the given output file name, and (2) creates a resolution file whose name
245   /// is prefixed by the given output file name and sets ResolutionFile to its
246   /// file handle.
247   Error addSaveTemps(std::string OutputFileName,
248                      bool UseInputModulePath = false);
249 };
250
251 struct LTOLLVMDiagnosticHandler : public DiagnosticHandler {
252   DiagnosticHandlerFunction *Fn;
253   LTOLLVMDiagnosticHandler(DiagnosticHandlerFunction *DiagHandlerFn)
254       : Fn(DiagHandlerFn) {}
255   bool handleDiagnostics(const DiagnosticInfo &DI) override {
256     (*Fn)(DI);
257     return true;
258   }
259 };
260 /// A derived class of LLVMContext that initializes itself according to a given
261 /// Config object. The purpose of this class is to tie ownership of the
262 /// diagnostic handler to the context, as opposed to the Config object (which
263 /// may be ephemeral).
264 // FIXME: This should not be required as diagnostic handler is not callback.
265 struct LTOLLVMContext : LLVMContext {
266
267   LTOLLVMContext(const Config &C) : DiagHandler(C.DiagHandler) {
268     setDiscardValueNames(C.ShouldDiscardValueNames);
269     enableDebugTypeODRUniquing();
270     setDiagnosticHandler(
271         std::make_unique<LTOLLVMDiagnosticHandler>(&DiagHandler), true);
272   }
273   DiagnosticHandlerFunction DiagHandler;
274 };
275
276 }
277 }
278
279 #endif