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 171 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 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. 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(). 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(). 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. 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 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. 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. 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. 291 void setModuleIdentifier(StringRef ID) { ModuleID = std::string(ID); } 292 293 /// Set the module's original source file 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. 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. 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. 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> 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> 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. 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. 429 const GlobalVariable *getNamedGlobal(StringRef Name) const { 430 return getGlobalVariable(Name, true); 431 } 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. 533 GVMaterializer *getMaterializer() const { return Materializer.get(); } 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 /// Detach global variable \p GV from the list but don't delete it. 546 void removeGlobalVariable(GlobalVariable *GV) { GlobalList.remove(GV); } 547 /// Remove global variable \p GV from the list and delete it. 548 void eraseGlobalVariable(GlobalVariable *GV) { GlobalList.erase(GV); } 549 /// Insert global variable \p GV at the end of the global variable list and 550 /// take ownership. 551 void insertGlobalVariable(GlobalVariable *GV) { 552 insertGlobalVariable(GlobalList.end(), GV); 553 } 554 /// Insert global variable \p GV into the global variable list before \p 555 /// Where and take ownership. 556 void insertGlobalVariable(GlobalListType::iterator Where, GlobalVariable *GV) { 557 GlobalList.insert(Where, GV); 558 } 559 // Use global_size() to get the total number of global variables. 560 // Use globals() to get the range of all global variables. 561 562 private: 563 /// @} 564 /// @name Direct access to the globals list, functions list, and symbol table 565 /// @{ 566 567 /// Get the Module's list of global variables (constant). 568 const GlobalListType &getGlobalList() const { return GlobalList; } 569 /// Get the Module's list of global variables. 570 GlobalListType &getGlobalList() { return GlobalList; } 571 572 static GlobalListType Module::*getSublistAccess(GlobalVariable*) { 573 return &Module::GlobalList; 574 } 575 friend class llvm::SymbolTableListTraits<llvm::GlobalVariable>; 576 577 public: 578 /// Get the Module's list of functions (constant). 579 const FunctionListType &getFunctionList() const { return FunctionList; } 580 /// Get the Module's list of functions. 581 FunctionListType &getFunctionList() { return FunctionList; } 582 static FunctionListType Module::*getSublistAccess(Function*) { 583 return &Module::FunctionList; 584 } 585 586 /// Detach \p Alias from the list but don't delete it. 587 void removeAlias(GlobalAlias *Alias) { AliasList.remove(Alias); } 588 /// Remove \p Alias from the list and delete it. 589 void eraseAlias(GlobalAlias *Alias) { AliasList.erase(Alias); } 590 /// Insert \p Alias at the end of the alias list and take ownership. 591 void insertAlias(GlobalAlias *Alias) { AliasList.insert(AliasList.end(), Alias); } 592 // Use alias_size() to get the size of AliasList. 593 // Use aliases() to get a range of all Alias objects in AliasList. 594 595 /// Detach \p IFunc from the list but don't delete it. 596 void removeIFunc(GlobalIFunc *IFunc) { IFuncList.remove(IFunc); } 597 /// Remove \p IFunc from the list and delete it. 598 void eraseIFunc(GlobalIFunc *IFunc) { IFuncList.erase(IFunc); } 599 /// Insert \p IFunc at the end of the alias list and take ownership. 600 void insertIFunc(GlobalIFunc *IFunc) { IFuncList.push_back(IFunc); } 601 // Use ifunc_size() to get the number of functions in IFuncList. 602 // Use ifuncs() to get the range of all IFuncs. 603 604 /// Detach \p MDNode from the list but don't delete it. 605 void removeNamedMDNode(NamedMDNode *MDNode) { NamedMDList.remove(MDNode); } 606 /// Remove \p MDNode from the list and delete it. 607 void eraseNamedMDNode(NamedMDNode *MDNode) { NamedMDList.erase(MDNode); } 608 /// Insert \p MDNode at the end of the alias list and take ownership. 609 void insertNamedMDNode(NamedMDNode *MDNode) { 610 NamedMDList.push_back(MDNode); 611 } 612 // Use named_metadata_size() to get the size of the named meatadata list. 613 // Use named_metadata() to get the range of all named metadata. 614 615 private: // Please use functions like insertAlias(), removeAlias() etc. 616 /// Get the Module's list of aliases (constant). 617 const AliasListType &getAliasList() const { return AliasList; } 618 /// Get the Module's list of aliases. 619 AliasListType &getAliasList() { return AliasList; } 620 621 static AliasListType Module::*getSublistAccess(GlobalAlias*) { 622 return &Module::AliasList; 623 } 624 friend class llvm::SymbolTableListTraits<llvm::GlobalAlias>; 625 626 /// Get the Module's list of ifuncs (constant). 627 const IFuncListType &getIFuncList() const { return IFuncList; } 628 /// Get the Module's list of ifuncs. 629 IFuncListType &getIFuncList() { return IFuncList; } 630 631 static IFuncListType Module::*getSublistAccess(GlobalIFunc*) { 632 return &Module::IFuncList; 633 } 634 friend class llvm::SymbolTableListTraits<llvm::GlobalIFunc>; 635 636 /// Get the Module's list of named metadata (constant). 637 const NamedMDListType &getNamedMDList() const { return NamedMDList; } 638 /// Get the Module's list of named metadata. 639 NamedMDListType &getNamedMDList() { return NamedMDList; } 640 641 static NamedMDListType Module::*getSublistAccess(NamedMDNode*) { 642 return &Module::NamedMDList; 643 } 644 645 public: 646 /// Get the symbol table of global variable and function identifiers 647 const ValueSymbolTable &getValueSymbolTable() const { return *ValSymTab; } 648 /// Get the Module's symbol table of global variable and function identifiers. 649 ValueSymbolTable &getValueSymbolTable() { return *ValSymTab; } 650 651 /// Get the Module's symbol table for COMDATs (constant). 652 const ComdatSymTabType &getComdatSymbolTable() const { return ComdatSymTab; } 653 /// Get the Module's symbol table for COMDATs. 654 ComdatSymTabType &getComdatSymbolTable() { return ComdatSymTab; } 655 656 /// @} 657 /// @name Global Variable Iteration 658 /// @{ 659 660 global_iterator global_begin() { return GlobalList.begin(); } 661 const_global_iterator global_begin() const { return GlobalList.begin(); } 662 global_iterator global_end () { return GlobalList.end(); } 663 const_global_iterator global_end () const { return GlobalList.end(); } 664 size_t global_size () const { return GlobalList.size(); } 665 bool global_empty() const { return GlobalList.empty(); } 666 667 iterator_range<global_iterator> globals() { 668 return make_range(global_begin(), global_end()); 669 } 670 iterator_range<const_global_iterator> globals() const { 671 return make_range(global_begin(), global_end()); 672 } 673 674 /// @} 675 /// @name Function Iteration 676 /// @{ 677 678 iterator begin() { return FunctionList.begin(); } 679 const_iterator begin() const { return FunctionList.begin(); } 680 iterator end () { return FunctionList.end(); } 681 const_iterator end () const { return FunctionList.end(); } 682 reverse_iterator rbegin() { return FunctionList.rbegin(); } 683 const_reverse_iterator rbegin() const{ return FunctionList.rbegin(); } 684 reverse_iterator rend() { return FunctionList.rend(); } 685 const_reverse_iterator rend() const { return FunctionList.rend(); } 686 size_t size() const { return FunctionList.size(); } 687 bool empty() const { return FunctionList.empty(); } 688 689 iterator_range<iterator> functions() { 690 return make_range(begin(), end()); 691 } 692 iterator_range<const_iterator> functions() const { 693 return make_range(begin(), end()); 694 } 695 696 /// @} 697 /// @name Alias Iteration 698 /// @{ 699 700 alias_iterator alias_begin() { return AliasList.begin(); } 701 const_alias_iterator alias_begin() const { return AliasList.begin(); } 702 alias_iterator alias_end () { return AliasList.end(); } 703 const_alias_iterator alias_end () const { return AliasList.end(); } 704 size_t alias_size () const { return AliasList.size(); } 705 bool alias_empty() const { return AliasList.empty(); } 706 707 iterator_range<alias_iterator> aliases() { 708 return make_range(alias_begin(), alias_end()); 709 } 710 iterator_range<const_alias_iterator> aliases() const { 711 return make_range(alias_begin(), alias_end()); 712 } 713 714 /// @} 715 /// @name IFunc Iteration 716 /// @{ 717 718 ifunc_iterator ifunc_begin() { return IFuncList.begin(); } 719 const_ifunc_iterator ifunc_begin() const { return IFuncList.begin(); } 720 ifunc_iterator ifunc_end () { return IFuncList.end(); } 721 const_ifunc_iterator ifunc_end () const { return IFuncList.end(); } 722 size_t ifunc_size () const { return IFuncList.size(); } 723 bool ifunc_empty() const { return IFuncList.empty(); } 724 725 iterator_range<ifunc_iterator> ifuncs() { 726 return make_range(ifunc_begin(), ifunc_end()); 727 } 728 iterator_range<const_ifunc_iterator> ifuncs() const { 729 return make_range(ifunc_begin(), ifunc_end()); 730 } 731 732 /// @} 733 /// @name Convenience iterators 734 /// @{ 735 736 using global_object_iterator = 737 concat_iterator<GlobalObject, iterator, global_iterator>; 738 using const_global_object_iterator = 739 concat_iterator<const GlobalObject, const_iterator, 740 const_global_iterator>; 741 742 iterator_range<global_object_iterator> global_objects(); 743 iterator_range<const_global_object_iterator> global_objects() const; 744 745 using global_value_iterator = 746 concat_iterator<GlobalValue, iterator, global_iterator, alias_iterator, 747 ifunc_iterator>; 748 using const_global_value_iterator = 749 concat_iterator<const GlobalValue, const_iterator, const_global_iterator, 750 const_alias_iterator, const_ifunc_iterator>; 751 752 iterator_range<global_value_iterator> global_values(); 753 iterator_range<const_global_value_iterator> global_values() const; 754 755 /// @} 756 /// @name Named Metadata Iteration 757 /// @{ 758 759 named_metadata_iterator named_metadata_begin() { return NamedMDList.begin(); } 760 const_named_metadata_iterator named_metadata_begin() const { 761 return NamedMDList.begin(); 762 } 763 764 named_metadata_iterator named_metadata_end() { return NamedMDList.end(); } 765 const_named_metadata_iterator named_metadata_end() const { 766 return NamedMDList.end(); 767 } 768 769 size_t named_metadata_size() const { return NamedMDList.size(); } 770 bool named_metadata_empty() const { return NamedMDList.empty(); } 771 772 iterator_range<named_metadata_iterator> named_metadata() { 773 return make_range(named_metadata_begin(), named_metadata_end()); 774 } 775 iterator_range<const_named_metadata_iterator> named_metadata() const { 776 return make_range(named_metadata_begin(), named_metadata_end()); 777 } 778 779 /// An iterator for DICompileUnits that skips those marked NoDebug. 780 class debug_compile_units_iterator { 781 NamedMDNode *CUs; 782 unsigned Idx; 783 784 void SkipNoDebugCUs(); 785 786 public: 787 using iterator_category = std::input_iterator_tag; 788 using value_type = DICompileUnit *; 789 using difference_type = std::ptrdiff_t; 790 using pointer = value_type *; 791 using reference = value_type &; 792 793 explicit debug_compile_units_iterator(NamedMDNode *CUs, unsigned Idx) 794 : CUs(CUs), Idx(Idx) { 795 SkipNoDebugCUs(); 796 } 797 798 debug_compile_units_iterator &operator++() { 799 ++Idx; 800 SkipNoDebugCUs(); 801 return *this; 802 } 803 804 debug_compile_units_iterator operator++(int) { 805 debug_compile_units_iterator T(*this); 806 ++Idx; 807 return T; 808 } 809 810 bool operator==(const debug_compile_units_iterator &I) const { 811 return Idx == I.Idx; 812 } 813 814 bool operator!=(const debug_compile_units_iterator &I) const { 815 return Idx != I.Idx; 816 } 817 818 DICompileUnit *operator*() const; 819 DICompileUnit *operator->() const; 820 }; 821 822 debug_compile_units_iterator debug_compile_units_begin() const { 823 auto *CUs = getNamedMetadata("llvm.dbg.cu"); 824 return debug_compile_units_iterator(CUs, 0); 825 } 826 827 debug_compile_units_iterator debug_compile_units_end() const { 828 auto *CUs = getNamedMetadata("llvm.dbg.cu"); 829 return debug_compile_units_iterator(CUs, CUs ? CUs->getNumOperands() : 0); 830 } 831 832 /// Return an iterator for all DICompileUnits listed in this Module's 833 /// llvm.dbg.cu named metadata node and aren't explicitly marked as 834 /// NoDebug. 835 iterator_range<debug_compile_units_iterator> debug_compile_units() const { 836 auto *CUs = getNamedMetadata("llvm.dbg.cu"); 837 return make_range( 838 debug_compile_units_iterator(CUs, 0), 839 debug_compile_units_iterator(CUs, CUs ? CUs->getNumOperands() : 0)); 840 } 841 /// @} 842 843 /// Destroy ConstantArrays in LLVMContext if they are not used. 844 /// ConstantArrays constructed during linking can cause quadratic memory 845 /// explosion. Releasing all unused constants can cause a 20% LTO compile-time 846 /// slowdown for a large application. 847 /// 848 /// NOTE: Constants are currently owned by LLVMContext. This can then only 849 /// be called where all uses of the LLVMContext are understood. 850 void dropTriviallyDeadConstantArrays(); 851 852 /// @name Utility functions for printing and dumping Module objects 853 /// @{ 854 855 /// Print the module to an output stream with an optional 856 /// AssemblyAnnotationWriter. If \c ShouldPreserveUseListOrder, then include 857 /// uselistorder directives so that use-lists can be recreated when reading 858 /// the assembly. 859 void print(raw_ostream &OS, AssemblyAnnotationWriter *AAW, 860 bool ShouldPreserveUseListOrder = false, 861 bool IsForDebug = false) const; 862 863 /// Dump the module to stderr (for debugging). 864 void dump() const; 865 866 /// This function causes all the subinstructions to "let go" of all references 867 /// that they are maintaining. This allows one to 'delete' a whole class at 868 /// a time, even though there may be circular references... first all 869 /// references are dropped, and all use counts go to zero. Then everything 870 /// is delete'd for real. Note that no operations are valid on an object 871 /// that has "dropped all references", except operator delete. 872 void dropAllReferences(); 873 874 /// @} 875 /// @name Utility functions for querying Debug information. 876 /// @{ 877 878 /// Returns the Number of Register ParametersDwarf Version by checking 879 /// module flags. 880 unsigned getNumberRegisterParameters() const; 881 882 /// Returns the Dwarf Version by checking module flags. 883 unsigned getDwarfVersion() const; 884 885 /// Returns the DWARF format by checking module flags. 886 bool isDwarf64() const; 887 888 /// Returns the CodeView Version by checking module flags. 889 /// Returns zero if not present in module. 890 unsigned getCodeViewFlag() const; 891 892 /// @} 893 /// @name Utility functions for querying and setting PIC level 894 /// @{ 895 896 /// Returns the PIC level (small or large model) 897 PICLevel::Level getPICLevel() const; 898 899 /// Set the PIC level (small or large model) 900 void setPICLevel(PICLevel::Level PL); 901 /// @} 902 903 /// @} 904 /// @name Utility functions for querying and setting PIE level 905 /// @{ 906 907 /// Returns the PIE level (small or large model) 908 PIELevel::Level getPIELevel() const; 909 910 /// Set the PIE level (small or large model) 911 void setPIELevel(PIELevel::Level PL); 912 /// @} 913 914 /// @} 915 /// @name Utility function for querying and setting code model 916 /// @{ 917 918 /// Returns the code model (tiny, small, kernel, medium or large model) 919 std::optional<CodeModel::Model> getCodeModel() const; 920 921 /// Set the code model (tiny, small, kernel, medium or large) 922 void setCodeModel(CodeModel::Model CL); 923 /// @} 924 925 /// @name Utility functions for querying and setting PGO summary 926 /// @{ 927 928 /// Attach profile summary metadata to this module. 929 void setProfileSummary(Metadata *M, ProfileSummary::Kind Kind); 930 931 /// Returns profile summary metadata. When IsCS is true, use the context 932 /// sensitive profile summary. 933 Metadata *getProfileSummary(bool IsCS) const; 934 /// @} 935 936 /// Returns whether semantic interposition is to be respected. 937 bool getSemanticInterposition() const; 938 939 /// Set whether semantic interposition is to be respected. 940 void setSemanticInterposition(bool); 941 942 /// Returns true if PLT should be avoided for RTLib calls. 943 bool getRtLibUseGOT() const; 944 945 /// Set that PLT should be avoid for RTLib calls. 946 void setRtLibUseGOT(); 947 948 /// Get/set whether referencing global variables can use direct access 949 /// relocations on ELF targets. 950 bool getDirectAccessExternalData() const; 951 void setDirectAccessExternalData(bool Value); 952 953 /// Get/set whether synthesized functions should get the uwtable attribute. 954 UWTableKind getUwtable() const; 955 void setUwtable(UWTableKind Kind); 956 957 /// Get/set whether synthesized functions should get the "frame-pointer" 958 /// attribute. 959 FramePointerKind getFramePointer() const; 960 void setFramePointer(FramePointerKind Kind); 961 962 /// Get/set what kind of stack protector guard to use. 963 StringRef getStackProtectorGuard() const; 964 void setStackProtectorGuard(StringRef Kind); 965 966 /// Get/set which register to use as the stack protector guard register. The 967 /// empty string is equivalent to "global". Other values may be "tls" or 968 /// "sysreg". 969 StringRef getStackProtectorGuardReg() const; 970 void setStackProtectorGuardReg(StringRef Reg); 971 972 /// Get/set a symbol to use as the stack protector guard. 973 StringRef getStackProtectorGuardSymbol() const; 974 void setStackProtectorGuardSymbol(StringRef Symbol); 975 976 /// Get/set what offset from the stack protector to use. 977 int getStackProtectorGuardOffset() const; 978 void setStackProtectorGuardOffset(int Offset); 979 980 /// Get/set the stack alignment overridden from the default. 981 unsigned getOverrideStackAlignment() const; 982 void setOverrideStackAlignment(unsigned Align); 983 984 unsigned getMaxTLSAlignment() const; 985 986 /// @name Utility functions for querying and setting the build SDK version 987 /// @{ 988 989 /// Attach a build SDK version metadata to this module. 990 void setSDKVersion(const VersionTuple &V); 991 992 /// Get the build SDK version metadata. 993 /// 994 /// An empty version is returned if no such metadata is attached. 995 VersionTuple getSDKVersion() const; 996 /// @} 997 998 /// Take ownership of the given memory buffer. 999 void setOwnedMemoryBuffer(std::unique_ptr<MemoryBuffer> MB); 1000 1001 /// Set the partial sample profile ratio in the profile summary module flag, 1002 /// if applicable. 1003 void setPartialSampleProfileRatio(const ModuleSummaryIndex &Index); 1004 1005 /// Get the target variant triple which is a string describing a variant of 1006 /// the target host platform. For example, Mac Catalyst can be a variant 1007 /// target triple for a macOS target. 1008 /// @returns a string containing the target variant triple. 1009 StringRef getDarwinTargetVariantTriple() const; 1010 1011 /// Set the target variant triple which is a string describing a variant of 1012 /// the target host platform. 1013 void setDarwinTargetVariantTriple(StringRef T); 1014 1015 /// Get the target variant version build SDK version metadata. 1016 /// 1017 /// An empty version is returned if no such metadata is attached. 1018 VersionTuple getDarwinTargetVariantSDKVersion() const; 1019 1020 /// Set the target variant version build SDK version metadata. 1021 void setDarwinTargetVariantSDKVersion(VersionTuple Version); 1022 }; 1023 1024 /// Given "llvm.used" or "llvm.compiler.used" as a global name, collect the 1025 /// initializer elements of that global in a SmallVector and return the global 1026 /// itself. 1027 GlobalVariable *collectUsedGlobalVariables(const Module &M, 1028 SmallVectorImpl<GlobalValue *> &Vec, 1029 bool CompilerUsed); 1030 1031 /// An raw_ostream inserter for modules. 1032 inline raw_ostream &operator<<(raw_ostream &O, const Module &M) { 1033 M.print(O, nullptr); 1034 return O; 1035 } 1036 1037 // Create wrappers for C Binding types (see CBindingWrapping.h). 1038 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(Module, LLVMModuleRef) 1039 1040 /* LLVMModuleProviderRef exists for historical reasons, but now just holds a 1041 * Module. 1042 */ 1043 inline Module *unwrap(LLVMModuleProviderRef MP) { 1044 return reinterpret_cast<Module*>(MP); 1045 } 1046 1047 } // end namespace llvm 1048 1049 #endif // LLVM_IR_MODULE_H 1050