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 /// @} 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). 550 const GlobalListType &getGlobalList() const { return GlobalList; } 551 /// Get the Module's list of global variables. 552 GlobalListType &getGlobalList() { return GlobalList; } 553 554 static GlobalListType Module::*getSublistAccess(GlobalVariable*) { 555 return &Module::GlobalList; 556 } 557 558 /// Get the Module's list of functions (constant). 559 const FunctionListType &getFunctionList() const { return FunctionList; } 560 /// Get the Module's list of functions. 561 FunctionListType &getFunctionList() { return FunctionList; } 562 static FunctionListType Module::*getSublistAccess(Function*) { 563 return &Module::FunctionList; 564 } 565 566 /// Get the Module's list of aliases (constant). 567 const AliasListType &getAliasList() const { return AliasList; } 568 /// Get the Module's list of aliases. 569 AliasListType &getAliasList() { return AliasList; } 570 571 static AliasListType Module::*getSublistAccess(GlobalAlias*) { 572 return &Module::AliasList; 573 } 574 575 /// Get the Module's list of ifuncs (constant). 576 const IFuncListType &getIFuncList() const { return IFuncList; } 577 /// Get the Module's list of ifuncs. 578 IFuncListType &getIFuncList() { return IFuncList; } 579 580 static IFuncListType Module::*getSublistAccess(GlobalIFunc*) { 581 return &Module::IFuncList; 582 } 583 584 /// Get the Module's list of named metadata (constant). 585 const NamedMDListType &getNamedMDList() const { return NamedMDList; } 586 /// Get the Module's list of named metadata. 587 NamedMDListType &getNamedMDList() { return NamedMDList; } 588 589 static NamedMDListType Module::*getSublistAccess(NamedMDNode*) { 590 return &Module::NamedMDList; 591 } 592 593 /// Get the symbol table of global variable and function identifiers 594 const ValueSymbolTable &getValueSymbolTable() const { return *ValSymTab; } 595 /// Get the Module's symbol table of global variable and function identifiers. 596 ValueSymbolTable &getValueSymbolTable() { return *ValSymTab; } 597 598 /// Get the Module's symbol table for COMDATs (constant). 599 const ComdatSymTabType &getComdatSymbolTable() const { return ComdatSymTab; } 600 /// Get the Module's symbol table for COMDATs. 601 ComdatSymTabType &getComdatSymbolTable() { return ComdatSymTab; } 602 603 /// @} 604 /// @name Global Variable Iteration 605 /// @{ 606 607 global_iterator global_begin() { return GlobalList.begin(); } 608 const_global_iterator global_begin() const { return GlobalList.begin(); } 609 global_iterator global_end () { return GlobalList.end(); } 610 const_global_iterator global_end () const { return GlobalList.end(); } 611 size_t global_size () const { return GlobalList.size(); } 612 bool global_empty() const { return GlobalList.empty(); } 613 614 iterator_range<global_iterator> globals() { 615 return make_range(global_begin(), global_end()); 616 } 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 625 iterator begin() { return FunctionList.begin(); } 626 const_iterator begin() const { return FunctionList.begin(); } 627 iterator end () { return FunctionList.end(); } 628 const_iterator end () const { return FunctionList.end(); } 629 reverse_iterator rbegin() { return FunctionList.rbegin(); } 630 const_reverse_iterator rbegin() const{ return FunctionList.rbegin(); } 631 reverse_iterator rend() { return FunctionList.rend(); } 632 const_reverse_iterator rend() const { return FunctionList.rend(); } 633 size_t size() const { return FunctionList.size(); } 634 bool empty() const { return FunctionList.empty(); } 635 636 iterator_range<iterator> functions() { 637 return make_range(begin(), end()); 638 } 639 iterator_range<const_iterator> functions() const { 640 return make_range(begin(), end()); 641 } 642 643 /// @} 644 /// @name Alias Iteration 645 /// @{ 646 647 alias_iterator alias_begin() { return AliasList.begin(); } 648 const_alias_iterator alias_begin() const { return AliasList.begin(); } 649 alias_iterator alias_end () { return AliasList.end(); } 650 const_alias_iterator alias_end () const { return AliasList.end(); } 651 size_t alias_size () const { return AliasList.size(); } 652 bool alias_empty() const { return AliasList.empty(); } 653 654 iterator_range<alias_iterator> aliases() { 655 return make_range(alias_begin(), alias_end()); 656 } 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 665 ifunc_iterator ifunc_begin() { return IFuncList.begin(); } 666 const_ifunc_iterator ifunc_begin() const { return IFuncList.begin(); } 667 ifunc_iterator ifunc_end () { return IFuncList.end(); } 668 const_ifunc_iterator ifunc_end () const { return IFuncList.end(); } 669 size_t ifunc_size () const { return IFuncList.size(); } 670 bool ifunc_empty() const { return IFuncList.empty(); } 671 672 iterator_range<ifunc_iterator> ifuncs() { 673 return make_range(ifunc_begin(), ifunc_end()); 674 } 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 706 named_metadata_iterator named_metadata_begin() { return NamedMDList.begin(); } 707 const_named_metadata_iterator named_metadata_begin() const { 708 return NamedMDList.begin(); 709 } 710 711 named_metadata_iterator named_metadata_end() { return NamedMDList.end(); } 712 const_named_metadata_iterator named_metadata_end() const { 713 return NamedMDList.end(); 714 } 715 716 size_t named_metadata_size() const { return NamedMDList.size(); } 717 bool named_metadata_empty() const { return NamedMDList.empty(); } 718 719 iterator_range<named_metadata_iterator> named_metadata() { 720 return make_range(named_metadata_begin(), named_metadata_end()); 721 } 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 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 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 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. 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). 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