xref: /openbsd/gnu/llvm/llvm/include/llvm/IR/Module.h (revision d415bd75)
1 //===- llvm/Module.h - C++ class to represent a VM module -------*- 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 /// @file
10 /// Module.h This file contains the declarations for the Module class.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_IR_MODULE_H
15 #define LLVM_IR_MODULE_H
16 
17 #include "llvm-c/Types.h"
18 #include "llvm/ADT/STLExtras.h"
19 #include "llvm/ADT/StringMap.h"
20 #include "llvm/ADT/StringRef.h"
21 #include "llvm/ADT/iterator_range.h"
22 #include "llvm/IR/Attributes.h"
23 #include "llvm/IR/Comdat.h"
24 #include "llvm/IR/DataLayout.h"
25 #include "llvm/IR/Function.h"
26 #include "llvm/IR/GlobalAlias.h"
27 #include "llvm/IR/GlobalIFunc.h"
28 #include "llvm/IR/GlobalVariable.h"
29 #include "llvm/IR/Metadata.h"
30 #include "llvm/IR/ProfileSummary.h"
31 #include "llvm/IR/SymbolTableListTraits.h"
32 #include "llvm/Support/CBindingWrapping.h"
33 #include "llvm/Support/CodeGen.h"
34 #include <cstddef>
35 #include <cstdint>
36 #include <iterator>
37 #include <memory>
38 #include <optional>
39 #include <string>
40 #include <vector>
41 
42 namespace llvm {
43 
44 class Error;
45 class FunctionType;
46 class GVMaterializer;
47 class LLVMContext;
48 class MemoryBuffer;
49 class ModuleSummaryIndex;
50 class RandomNumberGenerator;
51 class StructType;
52 class VersionTuple;
53 
54 /// A Module instance is used to store all the information related to an
55 /// LLVM module. Modules are the top level container of all other LLVM
56 /// Intermediate Representation (IR) objects. Each module directly contains a
57 /// list of globals variables, a list of functions, a list of libraries (or
58 /// other modules) this module depends on, a symbol table, and various data
59 /// about the target's characteristics.
60 ///
61 /// A module maintains a GlobalList object that is used to hold all
62 /// constant references to global variables in the module.  When a global
63 /// variable is destroyed, it should have no entries in the GlobalList.
64 /// The main container class for the LLVM Intermediate Representation.
65 class LLVM_EXTERNAL_VISIBILITY Module {
66   /// @name Types And Enumerations
67   /// @{
68 public:
69   /// The type for the list of global variables.
70   using GlobalListType = SymbolTableList<GlobalVariable>;
71   /// The type for the list of functions.
72   using FunctionListType = SymbolTableList<Function>;
73   /// The type for the list of aliases.
74   using AliasListType = SymbolTableList<GlobalAlias>;
75   /// The type for the list of ifuncs.
76   using IFuncListType = SymbolTableList<GlobalIFunc>;
77   /// The type for the list of named metadata.
78   using NamedMDListType = ilist<NamedMDNode>;
79   /// The type of the comdat "symbol" table.
80   using ComdatSymTabType = StringMap<Comdat>;
81   /// The type for mapping names to named metadata.
82   using NamedMDSymTabType = StringMap<NamedMDNode *>;
83 
84   /// The Global Variable iterator.
85   using global_iterator = GlobalListType::iterator;
86   /// The Global Variable constant iterator.
87   using const_global_iterator = GlobalListType::const_iterator;
88 
89   /// The Function iterators.
90   using iterator = FunctionListType::iterator;
91   /// The Function constant iterator
92   using const_iterator = FunctionListType::const_iterator;
93 
94   /// The Function reverse iterator.
95   using reverse_iterator = FunctionListType::reverse_iterator;
96   /// The Function constant reverse iterator.
97   using const_reverse_iterator = FunctionListType::const_reverse_iterator;
98 
99   /// The Global Alias iterators.
100   using alias_iterator = AliasListType::iterator;
101   /// The Global Alias constant iterator
102   using const_alias_iterator = AliasListType::const_iterator;
103 
104   /// The Global IFunc iterators.
105   using ifunc_iterator = IFuncListType::iterator;
106   /// The Global IFunc constant iterator
107   using const_ifunc_iterator = IFuncListType::const_iterator;
108 
109   /// The named metadata iterators.
110   using named_metadata_iterator = NamedMDListType::iterator;
111   /// The named metadata constant iterators.
112   using const_named_metadata_iterator = NamedMDListType::const_iterator;
113 
114   /// This enumeration defines the supported behaviors of module flags.
115   enum ModFlagBehavior {
116     /// Emits an error if two values disagree, otherwise the resulting value is
117     /// that of the operands.
118     Error = 1,
119 
120     /// Emits a warning if two values disagree. The result value will be the
121     /// operand for the flag from the first module being linked.
122     Warning = 2,
123 
124     /// Adds a requirement that another module flag be present and have a
125     /// specified value after linking is performed. The value must be a metadata
126     /// pair, where the first element of the pair is the ID of the module flag
127     /// to be restricted, and the second element of the pair is the value the
128     /// module flag should be restricted to. This behavior can be used to
129     /// restrict the allowable results (via triggering of an error) of linking
130     /// IDs with the **Override** behavior.
131     Require = 3,
132 
133     /// Uses the specified value, regardless of the behavior or value of the
134     /// other module. If both modules specify **Override**, but the values
135     /// differ, an error will be emitted.
136     Override = 4,
137 
138     /// Appends the two values, which are required to be metadata nodes.
139     Append = 5,
140 
141     /// Appends the two values, which are required to be metadata
142     /// nodes. However, duplicate entries in the second list are dropped
143     /// during the append operation.
144     AppendUnique = 6,
145 
146     /// Takes the max of the two values, which are required to be integers.
147     Max = 7,
148 
149     /// Takes the min of the two values, which are required to be integers.
150     Min = 8,
151 
152     // Markers:
153     ModFlagBehaviorFirstVal = Error,
154     ModFlagBehaviorLastVal = Min
155   };
156 
157   /// Checks if Metadata represents a valid ModFlagBehavior, and stores the
158   /// converted result in MFB.
159   static bool isValidModFlagBehavior(Metadata *MD, ModFlagBehavior &MFB);
160 
161   /// Check if the given module flag metadata represents a valid module flag,
162   /// and store the flag behavior, the key string and the value metadata.
163   static bool isValidModuleFlag(const MDNode &ModFlag, ModFlagBehavior &MFB,
164                                 MDString *&Key, Metadata *&Val);
165 
166   struct ModuleFlagEntry {
167     ModFlagBehavior Behavior;
168     MDString *Key;
169     Metadata *Val;
170 
ModuleFlagEntryModuleFlagEntry171     ModuleFlagEntry(ModFlagBehavior B, MDString *K, Metadata *V)
172         : Behavior(B), Key(K), Val(V) {}
173   };
174 
175 /// @}
176 /// @name Member Variables
177 /// @{
178 private:
179   LLVMContext &Context;           ///< The LLVMContext from which types and
180                                   ///< constants are allocated.
181   GlobalListType GlobalList;      ///< The Global Variables in the module
182   FunctionListType FunctionList;  ///< The Functions in the module
183   AliasListType AliasList;        ///< The Aliases in the module
184   IFuncListType IFuncList;        ///< The IFuncs in the module
185   NamedMDListType NamedMDList;    ///< The named metadata in the module
186   std::string GlobalScopeAsm;     ///< Inline Asm at global scope.
187   std::unique_ptr<ValueSymbolTable> ValSymTab; ///< Symbol table for values
188   ComdatSymTabType ComdatSymTab;  ///< Symbol table for COMDATs
189   std::unique_ptr<MemoryBuffer>
190   OwnedMemoryBuffer;              ///< Memory buffer directly owned by this
191                                   ///< module, for legacy clients only.
192   std::unique_ptr<GVMaterializer>
193   Materializer;                   ///< Used to materialize GlobalValues
194   std::string ModuleID;           ///< Human readable identifier for the module
195   std::string SourceFileName;     ///< Original source file name for module,
196                                   ///< recorded in bitcode.
197   std::string TargetTriple;       ///< Platform target triple Module compiled on
198                                   ///< Format: (arch)(sub)-(vendor)-(sys0-(abi)
199   NamedMDSymTabType NamedMDSymTab;  ///< NamedMDNode names.
200   DataLayout DL;                  ///< DataLayout associated with the module
201   StringMap<unsigned>
202       CurrentIntrinsicIds; ///< Keep track of the current unique id count for
203                            ///< the specified intrinsic basename.
204   DenseMap<std::pair<Intrinsic::ID, const FunctionType *>, unsigned>
205       UniquedIntrinsicNames; ///< Keep track of uniqued names of intrinsics
206                              ///< based on unnamed types. The combination of
207                              ///< ID and FunctionType maps to the extension that
208                              ///< is used to make the intrinsic name unique.
209 
210   friend class Constant;
211 
212 /// @}
213 /// @name Constructors
214 /// @{
215 public:
216   /// The Module constructor. Note that there is no default constructor. You
217   /// must provide a name for the module upon construction.
218   explicit Module(StringRef ModuleID, LLVMContext& C);
219   /// The module destructor. This will dropAllReferences.
220   ~Module();
221 
222 /// @}
223 /// @name Module Level Accessors
224 /// @{
225 
226   /// Get the module identifier which is, essentially, the name of the module.
227   /// @returns the module identifier as a string
getModuleIdentifier()228   const std::string &getModuleIdentifier() const { return ModuleID; }
229 
230   /// Returns the number of non-debug IR instructions in the module.
231   /// This is equivalent to the sum of the IR instruction counts of each
232   /// function contained in the module.
233   unsigned getInstructionCount() const;
234 
235   /// Get the module's original source file name. When compiling from
236   /// bitcode, this is taken from a bitcode record where it was recorded.
237   /// For other compiles it is the same as the ModuleID, which would
238   /// contain the source file name.
getSourceFileName()239   const std::string &getSourceFileName() const { return SourceFileName; }
240 
241   /// Get a short "name" for the module.
242   ///
243   /// This is useful for debugging or logging. It is essentially a convenience
244   /// wrapper around getModuleIdentifier().
getName()245   StringRef getName() const { return ModuleID; }
246 
247   /// Get the data layout string for the module's target platform. This is
248   /// equivalent to getDataLayout()->getStringRepresentation().
getDataLayoutStr()249   const std::string &getDataLayoutStr() const {
250     return DL.getStringRepresentation();
251   }
252 
253   /// Get the data layout for the module's target platform.
254   const DataLayout &getDataLayout() const;
255 
256   /// Get the target triple which is a string describing the target host.
257   /// @returns a string containing the target triple.
getTargetTriple()258   const std::string &getTargetTriple() const { return TargetTriple; }
259 
260   /// Get the global data context.
261   /// @returns LLVMContext - a container for LLVM's global information
getContext()262   LLVMContext &getContext() const { return Context; }
263 
264   /// Get any module-scope inline assembly blocks.
265   /// @returns a string containing the module-scope inline assembly blocks.
getModuleInlineAsm()266   const std::string &getModuleInlineAsm() const { return GlobalScopeAsm; }
267 
268   /// Get a RandomNumberGenerator salted for use with this module. The
269   /// RNG can be seeded via -rng-seed=<uint64> and is salted with the
270   /// ModuleID and the provided pass salt. The returned RNG should not
271   /// be shared across threads or passes.
272   ///
273   /// A unique RNG per pass ensures a reproducible random stream even
274   /// when other randomness consuming passes are added or removed. In
275   /// addition, the random stream will be reproducible across LLVM
276   /// versions when the pass does not change.
277   std::unique_ptr<RandomNumberGenerator> createRNG(const StringRef Name) const;
278 
279   /// Return true if size-info optimization remark is enabled, false
280   /// otherwise.
shouldEmitInstrCountChangedRemark()281   bool shouldEmitInstrCountChangedRemark() {
282     return getContext().getDiagHandlerPtr()->isAnalysisRemarkEnabled(
283         "size-info");
284   }
285 
286   /// @}
287   /// @name Module Level Mutators
288   /// @{
289 
290   /// Set the module identifier.
setModuleIdentifier(StringRef ID)291   void setModuleIdentifier(StringRef ID) { ModuleID = std::string(ID); }
292 
293   /// Set the module's original source file name.
setSourceFileName(StringRef Name)294   void setSourceFileName(StringRef Name) { SourceFileName = std::string(Name); }
295 
296   /// Set the data layout
297   void setDataLayout(StringRef Desc);
298   void setDataLayout(const DataLayout &Other);
299 
300   /// Set the target triple.
setTargetTriple(StringRef T)301   void setTargetTriple(StringRef T) { TargetTriple = std::string(T); }
302 
303   /// Set the module-scope inline assembly blocks.
304   /// A trailing newline is added if the input doesn't have one.
setModuleInlineAsm(StringRef Asm)305   void setModuleInlineAsm(StringRef Asm) {
306     GlobalScopeAsm = std::string(Asm);
307     if (!GlobalScopeAsm.empty() && GlobalScopeAsm.back() != '\n')
308       GlobalScopeAsm += '\n';
309   }
310 
311   /// Append to the module-scope inline assembly blocks.
312   /// A trailing newline is added if the input doesn't have one.
appendModuleInlineAsm(StringRef Asm)313   void appendModuleInlineAsm(StringRef Asm) {
314     GlobalScopeAsm += Asm;
315     if (!GlobalScopeAsm.empty() && GlobalScopeAsm.back() != '\n')
316       GlobalScopeAsm += '\n';
317   }
318 
319 /// @}
320 /// @name Generic Value Accessors
321 /// @{
322 
323   /// Return the global value in the module with the specified name, of
324   /// arbitrary type. This method returns null if a global with the specified
325   /// name is not found.
326   GlobalValue *getNamedValue(StringRef Name) const;
327 
328   /// Return the number of global values in the module.
329   unsigned getNumNamedValues() const;
330 
331   /// Return a unique non-zero ID for the specified metadata kind. This ID is
332   /// uniqued across modules in the current LLVMContext.
333   unsigned getMDKindID(StringRef Name) const;
334 
335   /// Populate client supplied SmallVector with the name for custom metadata IDs
336   /// registered in this LLVMContext.
337   void getMDKindNames(SmallVectorImpl<StringRef> &Result) const;
338 
339   /// Populate client supplied SmallVector with the bundle tags registered in
340   /// this LLVMContext.  The bundle tags are ordered by increasing bundle IDs.
341   /// \see LLVMContext::getOperandBundleTagID
342   void getOperandBundleTags(SmallVectorImpl<StringRef> &Result) const;
343 
344   std::vector<StructType *> getIdentifiedStructTypes() const;
345 
346   /// Return a unique name for an intrinsic whose mangling is based on an
347   /// unnamed type. The Proto represents the function prototype.
348   std::string getUniqueIntrinsicName(StringRef BaseName, Intrinsic::ID Id,
349                                      const FunctionType *Proto);
350 
351 /// @}
352 /// @name Function Accessors
353 /// @{
354 
355   /// Look up the specified function in the module symbol table. Four
356   /// possibilities:
357   ///   1. If it does not exist, add a prototype for the function and return it.
358   ///   2. Otherwise, if the existing function has the correct prototype, return
359   ///      the existing function.
360   ///   3. Finally, the function exists but has the wrong prototype: return the
361   ///      function with a constantexpr cast to the right prototype.
362   ///
363   /// In all cases, the returned value is a FunctionCallee wrapper around the
364   /// 'FunctionType *T' passed in, as well as a 'Value*' either of the Function or
365   /// the bitcast to the function.
366   ///
367   /// Note: For library calls getOrInsertLibFunc() should be used instead.
368   FunctionCallee getOrInsertFunction(StringRef Name, FunctionType *T,
369                                      AttributeList AttributeList);
370 
371   FunctionCallee getOrInsertFunction(StringRef Name, FunctionType *T);
372 
373   /// Look up the specified function in the module symbol table. If it does not
374   /// exist, add a prototype for the function and return it. This function
375   /// guarantees to return a constant of pointer to the specified function type
376   /// or a ConstantExpr BitCast of that type if the named function has a
377   /// different type. This version of the method takes a list of
378   /// function arguments, which makes it easier for clients to use.
379   template <typename... ArgsTy>
getOrInsertFunction(StringRef Name,AttributeList AttributeList,Type * RetTy,ArgsTy...Args)380   FunctionCallee getOrInsertFunction(StringRef Name,
381                                      AttributeList AttributeList, Type *RetTy,
382                                      ArgsTy... Args) {
383     SmallVector<Type*, sizeof...(ArgsTy)> ArgTys{Args...};
384     return getOrInsertFunction(Name,
385                                FunctionType::get(RetTy, ArgTys, false),
386                                AttributeList);
387   }
388 
389   /// Same as above, but without the attributes.
390   template <typename... ArgsTy>
getOrInsertFunction(StringRef Name,Type * RetTy,ArgsTy...Args)391   FunctionCallee getOrInsertFunction(StringRef Name, Type *RetTy,
392                                      ArgsTy... Args) {
393     return getOrInsertFunction(Name, AttributeList{}, RetTy, Args...);
394   }
395 
396   // Avoid an incorrect ordering that'd otherwise compile incorrectly.
397   template <typename... ArgsTy>
398   FunctionCallee
399   getOrInsertFunction(StringRef Name, AttributeList AttributeList,
400                       FunctionType *Invalid, ArgsTy... Args) = delete;
401 
402   /// Look up the specified function in the module symbol table. If it does not
403   /// exist, return null.
404   Function *getFunction(StringRef Name) const;
405 
406 /// @}
407 /// @name Global Variable Accessors
408 /// @{
409 
410   /// Look up the specified global variable in the module symbol table. If it
411   /// does not exist, return null. If AllowInternal is set to true, this
412   /// function will return types that have InternalLinkage. By default, these
413   /// types are not returned.
getGlobalVariable(StringRef Name)414   GlobalVariable *getGlobalVariable(StringRef Name) const {
415     return getGlobalVariable(Name, false);
416   }
417 
418   GlobalVariable *getGlobalVariable(StringRef Name, bool AllowInternal) const;
419 
420   GlobalVariable *getGlobalVariable(StringRef Name,
421                                     bool AllowInternal = false) {
422     return static_cast<const Module *>(this)->getGlobalVariable(Name,
423                                                                 AllowInternal);
424   }
425 
426   /// Return the global variable in the module with the specified name, of
427   /// arbitrary type. This method returns null if a global with the specified
428   /// name is not found.
getNamedGlobal(StringRef Name)429   const GlobalVariable *getNamedGlobal(StringRef Name) const {
430     return getGlobalVariable(Name, true);
431   }
getNamedGlobal(StringRef Name)432   GlobalVariable *getNamedGlobal(StringRef Name) {
433     return const_cast<GlobalVariable *>(
434                        static_cast<const Module *>(this)->getNamedGlobal(Name));
435   }
436 
437   /// Look up the specified global in the module symbol table.
438   /// If it does not exist, invoke a callback to create a declaration of the
439   /// global and return it. The global is constantexpr casted to the expected
440   /// type if necessary.
441   Constant *
442   getOrInsertGlobal(StringRef Name, Type *Ty,
443                     function_ref<GlobalVariable *()> CreateGlobalCallback);
444 
445   /// Look up the specified global in the module symbol table. If required, this
446   /// overload constructs the global variable using its constructor's defaults.
447   Constant *getOrInsertGlobal(StringRef Name, Type *Ty);
448 
449 /// @}
450 /// @name Global Alias Accessors
451 /// @{
452 
453   /// Return the global alias in the module with the specified name, of
454   /// arbitrary type. This method returns null if a global with the specified
455   /// name is not found.
456   GlobalAlias *getNamedAlias(StringRef Name) const;
457 
458 /// @}
459 /// @name Global IFunc Accessors
460 /// @{
461 
462   /// Return the global ifunc in the module with the specified name, of
463   /// arbitrary type. This method returns null if a global with the specified
464   /// name is not found.
465   GlobalIFunc *getNamedIFunc(StringRef Name) const;
466 
467 /// @}
468 /// @name Named Metadata Accessors
469 /// @{
470 
471   /// Return the first NamedMDNode in the module with the specified name. This
472   /// method returns null if a NamedMDNode with the specified name is not found.
473   NamedMDNode *getNamedMetadata(const Twine &Name) const;
474 
475   /// Return the named MDNode in the module with the specified name. This method
476   /// returns a new NamedMDNode if a NamedMDNode with the specified name is not
477   /// found.
478   NamedMDNode *getOrInsertNamedMetadata(StringRef Name);
479 
480   /// Remove the given NamedMDNode from this module and delete it.
481   void eraseNamedMetadata(NamedMDNode *NMD);
482 
483 /// @}
484 /// @name Comdat Accessors
485 /// @{
486 
487   /// Return the Comdat in the module with the specified name. It is created
488   /// if it didn't already exist.
489   Comdat *getOrInsertComdat(StringRef Name);
490 
491 /// @}
492 /// @name Module Flags Accessors
493 /// @{
494 
495   /// Returns the module flags in the provided vector.
496   void getModuleFlagsMetadata(SmallVectorImpl<ModuleFlagEntry> &Flags) const;
497 
498   /// Return the corresponding value if Key appears in module flags, otherwise
499   /// return null.
500   Metadata *getModuleFlag(StringRef Key) const;
501 
502   /// Returns the NamedMDNode in the module that represents module-level flags.
503   /// This method returns null if there are no module-level flags.
504   NamedMDNode *getModuleFlagsMetadata() const;
505 
506   /// Returns the NamedMDNode in the module that represents module-level flags.
507   /// If module-level flags aren't found, it creates the named metadata that
508   /// contains them.
509   NamedMDNode *getOrInsertModuleFlagsMetadata();
510 
511   /// Add a module-level flag to the module-level flags metadata. It will create
512   /// the module-level flags named metadata if it doesn't already exist.
513   void addModuleFlag(ModFlagBehavior Behavior, StringRef Key, Metadata *Val);
514   void addModuleFlag(ModFlagBehavior Behavior, StringRef Key, Constant *Val);
515   void addModuleFlag(ModFlagBehavior Behavior, StringRef Key, uint32_t Val);
516   void addModuleFlag(MDNode *Node);
517   /// Like addModuleFlag but replaces the old module flag if it already exists.
518   void setModuleFlag(ModFlagBehavior Behavior, StringRef Key, Metadata *Val);
519 
520   /// @}
521   /// @name Materialization
522   /// @{
523 
524   /// Sets the GVMaterializer to GVM. This module must not yet have a
525   /// Materializer. To reset the materializer for a module that already has one,
526   /// call materializeAll first. Destroying this module will destroy
527   /// its materializer without materializing any more GlobalValues. Without
528   /// destroying the Module, there is no way to detach or destroy a materializer
529   /// without materializing all the GVs it controls, to avoid leaving orphan
530   /// unmaterialized GVs.
531   void setMaterializer(GVMaterializer *GVM);
532   /// Retrieves the GVMaterializer, if any, for this Module.
getMaterializer()533   GVMaterializer *getMaterializer() const { return Materializer.get(); }
isMaterialized()534   bool isMaterialized() const { return !getMaterializer(); }
535 
536   /// Make sure the GlobalValue is fully read.
537   llvm::Error materialize(GlobalValue *GV);
538 
539   /// Make sure all GlobalValues in this Module are fully read and clear the
540   /// Materializer.
541   llvm::Error materializeAll();
542 
543   llvm::Error materializeMetadata();
544 
545 /// @}
546 /// @name Direct access to the globals list, functions list, and symbol table
547 /// @{
548 
549   /// Get the Module's list of global variables (constant).
getGlobalList()550   const GlobalListType   &getGlobalList() const       { return GlobalList; }
551   /// Get the Module's list of global variables.
getGlobalList()552   GlobalListType         &getGlobalList()             { return GlobalList; }
553 
getSublistAccess(GlobalVariable *)554   static GlobalListType Module::*getSublistAccess(GlobalVariable*) {
555     return &Module::GlobalList;
556   }
557 
558   /// Get the Module's list of functions (constant).
getFunctionList()559   const FunctionListType &getFunctionList() const     { return FunctionList; }
560   /// Get the Module's list of functions.
getFunctionList()561   FunctionListType       &getFunctionList()           { return FunctionList; }
getSublistAccess(Function *)562   static FunctionListType Module::*getSublistAccess(Function*) {
563     return &Module::FunctionList;
564   }
565 
566   /// Get the Module's list of aliases (constant).
getAliasList()567   const AliasListType    &getAliasList() const        { return AliasList; }
568   /// Get the Module's list of aliases.
getAliasList()569   AliasListType          &getAliasList()              { return AliasList; }
570 
getSublistAccess(GlobalAlias *)571   static AliasListType Module::*getSublistAccess(GlobalAlias*) {
572     return &Module::AliasList;
573   }
574 
575   /// Get the Module's list of ifuncs (constant).
getIFuncList()576   const IFuncListType    &getIFuncList() const        { return IFuncList; }
577   /// Get the Module's list of ifuncs.
getIFuncList()578   IFuncListType          &getIFuncList()              { return IFuncList; }
579 
getSublistAccess(GlobalIFunc *)580   static IFuncListType Module::*getSublistAccess(GlobalIFunc*) {
581     return &Module::IFuncList;
582   }
583 
584   /// Get the Module's list of named metadata (constant).
getNamedMDList()585   const NamedMDListType  &getNamedMDList() const      { return NamedMDList; }
586   /// Get the Module's list of named metadata.
getNamedMDList()587   NamedMDListType        &getNamedMDList()            { return NamedMDList; }
588 
getSublistAccess(NamedMDNode *)589   static NamedMDListType Module::*getSublistAccess(NamedMDNode*) {
590     return &Module::NamedMDList;
591   }
592 
593   /// Get the symbol table of global variable and function identifiers
getValueSymbolTable()594   const ValueSymbolTable &getValueSymbolTable() const { return *ValSymTab; }
595   /// Get the Module's symbol table of global variable and function identifiers.
getValueSymbolTable()596   ValueSymbolTable       &getValueSymbolTable()       { return *ValSymTab; }
597 
598   /// Get the Module's symbol table for COMDATs (constant).
getComdatSymbolTable()599   const ComdatSymTabType &getComdatSymbolTable() const { return ComdatSymTab; }
600   /// Get the Module's symbol table for COMDATs.
getComdatSymbolTable()601   ComdatSymTabType &getComdatSymbolTable() { return ComdatSymTab; }
602 
603 /// @}
604 /// @name Global Variable Iteration
605 /// @{
606 
global_begin()607   global_iterator       global_begin()       { return GlobalList.begin(); }
global_begin()608   const_global_iterator global_begin() const { return GlobalList.begin(); }
global_end()609   global_iterator       global_end  ()       { return GlobalList.end(); }
global_end()610   const_global_iterator global_end  () const { return GlobalList.end(); }
global_size()611   size_t                global_size () const { return GlobalList.size(); }
global_empty()612   bool                  global_empty() const { return GlobalList.empty(); }
613 
globals()614   iterator_range<global_iterator> globals() {
615     return make_range(global_begin(), global_end());
616   }
globals()617   iterator_range<const_global_iterator> globals() const {
618     return make_range(global_begin(), global_end());
619   }
620 
621 /// @}
622 /// @name Function Iteration
623 /// @{
624 
begin()625   iterator                begin()       { return FunctionList.begin(); }
begin()626   const_iterator          begin() const { return FunctionList.begin(); }
end()627   iterator                end  ()       { return FunctionList.end();   }
end()628   const_iterator          end  () const { return FunctionList.end();   }
rbegin()629   reverse_iterator        rbegin()      { return FunctionList.rbegin(); }
rbegin()630   const_reverse_iterator  rbegin() const{ return FunctionList.rbegin(); }
rend()631   reverse_iterator        rend()        { return FunctionList.rend(); }
rend()632   const_reverse_iterator  rend() const  { return FunctionList.rend(); }
size()633   size_t                  size() const  { return FunctionList.size(); }
empty()634   bool                    empty() const { return FunctionList.empty(); }
635 
functions()636   iterator_range<iterator> functions() {
637     return make_range(begin(), end());
638   }
functions()639   iterator_range<const_iterator> functions() const {
640     return make_range(begin(), end());
641   }
642 
643 /// @}
644 /// @name Alias Iteration
645 /// @{
646 
alias_begin()647   alias_iterator       alias_begin()            { return AliasList.begin(); }
alias_begin()648   const_alias_iterator alias_begin() const      { return AliasList.begin(); }
alias_end()649   alias_iterator       alias_end  ()            { return AliasList.end();   }
alias_end()650   const_alias_iterator alias_end  () const      { return AliasList.end();   }
alias_size()651   size_t               alias_size () const      { return AliasList.size();  }
alias_empty()652   bool                 alias_empty() const      { return AliasList.empty(); }
653 
aliases()654   iterator_range<alias_iterator> aliases() {
655     return make_range(alias_begin(), alias_end());
656   }
aliases()657   iterator_range<const_alias_iterator> aliases() const {
658     return make_range(alias_begin(), alias_end());
659   }
660 
661 /// @}
662 /// @name IFunc Iteration
663 /// @{
664 
ifunc_begin()665   ifunc_iterator       ifunc_begin()            { return IFuncList.begin(); }
ifunc_begin()666   const_ifunc_iterator ifunc_begin() const      { return IFuncList.begin(); }
ifunc_end()667   ifunc_iterator       ifunc_end  ()            { return IFuncList.end();   }
ifunc_end()668   const_ifunc_iterator ifunc_end  () const      { return IFuncList.end();   }
ifunc_size()669   size_t               ifunc_size () const      { return IFuncList.size();  }
ifunc_empty()670   bool                 ifunc_empty() const      { return IFuncList.empty(); }
671 
ifuncs()672   iterator_range<ifunc_iterator> ifuncs() {
673     return make_range(ifunc_begin(), ifunc_end());
674   }
ifuncs()675   iterator_range<const_ifunc_iterator> ifuncs() const {
676     return make_range(ifunc_begin(), ifunc_end());
677   }
678 
679   /// @}
680   /// @name Convenience iterators
681   /// @{
682 
683   using global_object_iterator =
684       concat_iterator<GlobalObject, iterator, global_iterator>;
685   using const_global_object_iterator =
686       concat_iterator<const GlobalObject, const_iterator,
687                       const_global_iterator>;
688 
689   iterator_range<global_object_iterator> global_objects();
690   iterator_range<const_global_object_iterator> global_objects() const;
691 
692   using global_value_iterator =
693       concat_iterator<GlobalValue, iterator, global_iterator, alias_iterator,
694                       ifunc_iterator>;
695   using const_global_value_iterator =
696       concat_iterator<const GlobalValue, const_iterator, const_global_iterator,
697                       const_alias_iterator, const_ifunc_iterator>;
698 
699   iterator_range<global_value_iterator> global_values();
700   iterator_range<const_global_value_iterator> global_values() const;
701 
702   /// @}
703   /// @name Named Metadata Iteration
704   /// @{
705 
named_metadata_begin()706   named_metadata_iterator named_metadata_begin() { return NamedMDList.begin(); }
named_metadata_begin()707   const_named_metadata_iterator named_metadata_begin() const {
708     return NamedMDList.begin();
709   }
710 
named_metadata_end()711   named_metadata_iterator named_metadata_end() { return NamedMDList.end(); }
named_metadata_end()712   const_named_metadata_iterator named_metadata_end() const {
713     return NamedMDList.end();
714   }
715 
named_metadata_size()716   size_t named_metadata_size() const { return NamedMDList.size();  }
named_metadata_empty()717   bool named_metadata_empty() const { return NamedMDList.empty(); }
718 
named_metadata()719   iterator_range<named_metadata_iterator> named_metadata() {
720     return make_range(named_metadata_begin(), named_metadata_end());
721   }
named_metadata()722   iterator_range<const_named_metadata_iterator> named_metadata() const {
723     return make_range(named_metadata_begin(), named_metadata_end());
724   }
725 
726   /// An iterator for DICompileUnits that skips those marked NoDebug.
727   class debug_compile_units_iterator {
728     NamedMDNode *CUs;
729     unsigned Idx;
730 
731     void SkipNoDebugCUs();
732 
733   public:
734     using iterator_category = std::input_iterator_tag;
735     using value_type = DICompileUnit *;
736     using difference_type = std::ptrdiff_t;
737     using pointer = value_type *;
738     using reference = value_type &;
739 
debug_compile_units_iterator(NamedMDNode * CUs,unsigned Idx)740     explicit debug_compile_units_iterator(NamedMDNode *CUs, unsigned Idx)
741         : CUs(CUs), Idx(Idx) {
742       SkipNoDebugCUs();
743     }
744 
745     debug_compile_units_iterator &operator++() {
746       ++Idx;
747       SkipNoDebugCUs();
748       return *this;
749     }
750 
751     debug_compile_units_iterator operator++(int) {
752       debug_compile_units_iterator T(*this);
753       ++Idx;
754       return T;
755     }
756 
757     bool operator==(const debug_compile_units_iterator &I) const {
758       return Idx == I.Idx;
759     }
760 
761     bool operator!=(const debug_compile_units_iterator &I) const {
762       return Idx != I.Idx;
763     }
764 
765     DICompileUnit *operator*() const;
766     DICompileUnit *operator->() const;
767   };
768 
debug_compile_units_begin()769   debug_compile_units_iterator debug_compile_units_begin() const {
770     auto *CUs = getNamedMetadata("llvm.dbg.cu");
771     return debug_compile_units_iterator(CUs, 0);
772   }
773 
debug_compile_units_end()774   debug_compile_units_iterator debug_compile_units_end() const {
775     auto *CUs = getNamedMetadata("llvm.dbg.cu");
776     return debug_compile_units_iterator(CUs, CUs ? CUs->getNumOperands() : 0);
777   }
778 
779   /// Return an iterator for all DICompileUnits listed in this Module's
780   /// llvm.dbg.cu named metadata node and aren't explicitly marked as
781   /// NoDebug.
debug_compile_units()782   iterator_range<debug_compile_units_iterator> debug_compile_units() const {
783     auto *CUs = getNamedMetadata("llvm.dbg.cu");
784     return make_range(
785         debug_compile_units_iterator(CUs, 0),
786         debug_compile_units_iterator(CUs, CUs ? CUs->getNumOperands() : 0));
787   }
788 /// @}
789 
790   /// Destroy ConstantArrays in LLVMContext if they are not used.
791   /// ConstantArrays constructed during linking can cause quadratic memory
792   /// explosion. Releasing all unused constants can cause a 20% LTO compile-time
793   /// slowdown for a large application.
794   ///
795   /// NOTE: Constants are currently owned by LLVMContext. This can then only
796   /// be called where all uses of the LLVMContext are understood.
797   void dropTriviallyDeadConstantArrays();
798 
799 /// @name Utility functions for printing and dumping Module objects
800 /// @{
801 
802   /// Print the module to an output stream with an optional
803   /// AssemblyAnnotationWriter.  If \c ShouldPreserveUseListOrder, then include
804   /// uselistorder directives so that use-lists can be recreated when reading
805   /// the assembly.
806   void print(raw_ostream &OS, AssemblyAnnotationWriter *AAW,
807              bool ShouldPreserveUseListOrder = false,
808              bool IsForDebug = false) const;
809 
810   /// Dump the module to stderr (for debugging).
811   void dump() const;
812 
813   /// This function causes all the subinstructions to "let go" of all references
814   /// that they are maintaining.  This allows one to 'delete' a whole class at
815   /// a time, even though there may be circular references... first all
816   /// references are dropped, and all use counts go to zero.  Then everything
817   /// is delete'd for real.  Note that no operations are valid on an object
818   /// that has "dropped all references", except operator delete.
819   void dropAllReferences();
820 
821 /// @}
822 /// @name Utility functions for querying Debug information.
823 /// @{
824 
825   /// Returns the Number of Register ParametersDwarf Version by checking
826   /// module flags.
827   unsigned getNumberRegisterParameters() const;
828 
829   /// Returns the Dwarf Version by checking module flags.
830   unsigned getDwarfVersion() const;
831 
832   /// Returns the DWARF format by checking module flags.
833   bool isDwarf64() const;
834 
835   /// Returns the CodeView Version by checking module flags.
836   /// Returns zero if not present in module.
837   unsigned getCodeViewFlag() const;
838 
839 /// @}
840 /// @name Utility functions for querying and setting PIC level
841 /// @{
842 
843   /// Returns the PIC level (small or large model)
844   PICLevel::Level getPICLevel() const;
845 
846   /// Set the PIC level (small or large model)
847   void setPICLevel(PICLevel::Level PL);
848 /// @}
849 
850 /// @}
851 /// @name Utility functions for querying and setting PIE level
852 /// @{
853 
854   /// Returns the PIE level (small or large model)
855   PIELevel::Level getPIELevel() const;
856 
857   /// Set the PIE level (small or large model)
858   void setPIELevel(PIELevel::Level PL);
859 /// @}
860 
861   /// @}
862   /// @name Utility function for querying and setting code model
863   /// @{
864 
865   /// Returns the code model (tiny, small, kernel, medium or large model)
866   std::optional<CodeModel::Model> getCodeModel() const;
867 
868   /// Set the code model (tiny, small, kernel, medium or large)
869   void setCodeModel(CodeModel::Model CL);
870   /// @}
871 
872   /// @name Utility functions for querying and setting PGO summary
873   /// @{
874 
875   /// Attach profile summary metadata to this module.
876   void setProfileSummary(Metadata *M, ProfileSummary::Kind Kind);
877 
878   /// Returns profile summary metadata. When IsCS is true, use the context
879   /// sensitive profile summary.
880   Metadata *getProfileSummary(bool IsCS) const;
881   /// @}
882 
883   /// Returns whether semantic interposition is to be respected.
884   bool getSemanticInterposition() const;
885 
886   /// Set whether semantic interposition is to be respected.
887   void setSemanticInterposition(bool);
888 
889   /// Returns true if PLT should be avoided for RTLib calls.
890   bool getRtLibUseGOT() const;
891 
892   /// Set that PLT should be avoid for RTLib calls.
893   void setRtLibUseGOT();
894 
895   /// Get/set whether synthesized functions should get the uwtable attribute.
896   UWTableKind getUwtable() const;
897   void setUwtable(UWTableKind Kind);
898 
899   /// Get/set whether synthesized functions should get the "frame-pointer"
900   /// attribute.
901   FramePointerKind getFramePointer() const;
902   void setFramePointer(FramePointerKind Kind);
903 
904   /// Get/set what kind of stack protector guard to use.
905   StringRef getStackProtectorGuard() const;
906   void setStackProtectorGuard(StringRef Kind);
907 
908   /// Get/set which register to use as the stack protector guard register. The
909   /// empty string is equivalent to "global". Other values may be "tls" or
910   /// "sysreg".
911   StringRef getStackProtectorGuardReg() const;
912   void setStackProtectorGuardReg(StringRef Reg);
913 
914   /// Get/set a symbol to use as the stack protector guard.
915   StringRef getStackProtectorGuardSymbol() const;
916   void setStackProtectorGuardSymbol(StringRef Symbol);
917 
918   /// Get/set what offset from the stack protector to use.
919   int getStackProtectorGuardOffset() const;
920   void setStackProtectorGuardOffset(int Offset);
921 
922   /// Get/set the stack alignment overridden from the default.
923   unsigned getOverrideStackAlignment() const;
924   void setOverrideStackAlignment(unsigned Align);
925 
926   /// @name Utility functions for querying and setting the build SDK version
927   /// @{
928 
929   /// Attach a build SDK version metadata to this module.
930   void setSDKVersion(const VersionTuple &V);
931 
932   /// Get the build SDK version metadata.
933   ///
934   /// An empty version is returned if no such metadata is attached.
935   VersionTuple getSDKVersion() const;
936   /// @}
937 
938   /// Take ownership of the given memory buffer.
939   void setOwnedMemoryBuffer(std::unique_ptr<MemoryBuffer> MB);
940 
941   /// Set the partial sample profile ratio in the profile summary module flag,
942   /// if applicable.
943   void setPartialSampleProfileRatio(const ModuleSummaryIndex &Index);
944 
945   /// Get the target variant triple which is a string describing a variant of
946   /// the target host platform. For example, Mac Catalyst can be a variant
947   /// target triple for a macOS target.
948   /// @returns a string containing the target variant triple.
949   StringRef getDarwinTargetVariantTriple() const;
950 
951   /// Set the target variant triple which is a string describing a variant of
952   /// the target host platform.
953   void setDarwinTargetVariantTriple(StringRef T);
954 
955   /// Get the target variant version build SDK version metadata.
956   ///
957   /// An empty version is returned if no such metadata is attached.
958   VersionTuple getDarwinTargetVariantSDKVersion() const;
959 
960   /// Set the target variant version build SDK version metadata.
961   void setDarwinTargetVariantSDKVersion(VersionTuple Version);
962 };
963 
964 /// Given "llvm.used" or "llvm.compiler.used" as a global name, collect the
965 /// initializer elements of that global in a SmallVector and return the global
966 /// itself.
967 GlobalVariable *collectUsedGlobalVariables(const Module &M,
968                                            SmallVectorImpl<GlobalValue *> &Vec,
969                                            bool CompilerUsed);
970 
971 /// An raw_ostream inserter for modules.
972 inline raw_ostream &operator<<(raw_ostream &O, const Module &M) {
973   M.print(O, nullptr);
974   return O;
975 }
976 
977 // Create wrappers for C Binding types (see CBindingWrapping.h).
DEFINE_SIMPLE_CONVERSION_FUNCTIONS(Module,LLVMModuleRef)978 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(Module, LLVMModuleRef)
979 
980 /* LLVMModuleProviderRef exists for historical reasons, but now just holds a
981  * Module.
982  */
983 inline Module *unwrap(LLVMModuleProviderRef MP) {
984   return reinterpret_cast<Module*>(MP);
985 }
986 
987 } // end namespace llvm
988 
989 #endif // LLVM_IR_MODULE_H
990