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

source code of llvm/include/llvm/LTO/Config.h