1 //===---- llvm/MDBuilder.h - Builder for LLVM metadata ----------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // This file defines the MDBuilder class, which is used as a convenient way to 10 // create LLVM metadata with a consistent and simplified interface. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_IR_MDBUILDER_H 15 #define LLVM_IR_MDBUILDER_H 16 17 #include "llvm/ADT/DenseSet.h" 18 #include "llvm/ADT/SmallVector.h" 19 #include "llvm/ADT/StringRef.h" 20 #include "llvm/IR/GlobalValue.h" 21 #include "llvm/Support/Compiler.h" 22 #include "llvm/Support/DataTypes.h" 23 #include <utility> 24 25 namespace llvm { 26 27 class APInt; 28 template <typename T> class ArrayRef; 29 class LLVMContext; 30 class Constant; 31 class ConstantAsMetadata; 32 class Function; 33 class MDNode; 34 class MDString; 35 class Metadata; 36 37 class MDBuilder { 38 LLVMContext &Context; 39 40 public: MDBuilder(LLVMContext & context)41 MDBuilder(LLVMContext &context) : Context(context) {} 42 43 /// Return the given string as metadata. 44 LLVM_ABI MDString *createString(StringRef Str); 45 46 /// Return the given constant as metadata. 47 LLVM_ABI ConstantAsMetadata *createConstant(Constant *C); 48 49 //===------------------------------------------------------------------===// 50 // FPMath metadata. 51 //===------------------------------------------------------------------===// 52 53 /// Return metadata with the given settings. The special value 0.0 54 /// for the Accuracy parameter indicates the default (maximal precision) 55 /// setting. 56 LLVM_ABI MDNode *createFPMath(float Accuracy); 57 58 //===------------------------------------------------------------------===// 59 // Prof metadata. 60 //===------------------------------------------------------------------===// 61 62 /// Return metadata containing two branch weights. 63 /// @param TrueWeight the weight of the true branch 64 /// @param FalseWeight the weight of the false branch 65 /// @param Do these weights come from __builtin_expect* 66 LLVM_ABI MDNode *createBranchWeights(uint32_t TrueWeight, 67 uint32_t FalseWeight, 68 bool IsExpected = false); 69 70 /// Return metadata containing two branch weights, with significant bias 71 /// towards `true` destination. 72 LLVM_ABI MDNode *createLikelyBranchWeights(); 73 74 /// Return metadata containing two branch weights, with significant bias 75 /// towards `false` destination. 76 LLVM_ABI MDNode *createUnlikelyBranchWeights(); 77 78 /// Return metadata containing a number of branch weights. 79 /// @param Weights the weights of all the branches 80 /// @param Do these weights come from __builtin_expect* 81 LLVM_ABI MDNode *createBranchWeights(ArrayRef<uint32_t> Weights, 82 bool IsExpected = false); 83 84 /// Return metadata specifying that a branch or switch is unpredictable. 85 LLVM_ABI MDNode *createUnpredictable(); 86 87 /// Return metadata containing the entry \p Count for a function, a boolean 88 /// \Synthetic indicating whether the counts were synthetized, and the 89 /// GUIDs stored in \p Imports that need to be imported for sample PGO, to 90 /// enable the same inlines as the profiled optimized binary 91 LLVM_ABI MDNode * 92 createFunctionEntryCount(uint64_t Count, bool Synthetic, 93 const DenseSet<GlobalValue::GUID> *Imports); 94 95 /// Return metadata containing the section prefix for a global object. 96 LLVM_ABI MDNode *createGlobalObjectSectionPrefix(StringRef Prefix); 97 98 /// Return metadata containing the pseudo probe descriptor for a function. 99 LLVM_ABI MDNode *createPseudoProbeDesc(uint64_t GUID, uint64_t Hash, 100 StringRef FName); 101 102 /// Return metadata containing llvm statistics. 103 LLVM_ABI MDNode * 104 createLLVMStats(ArrayRef<std::pair<StringRef, uint64_t>> LLVMStatsVec); 105 106 //===------------------------------------------------------------------===// 107 // Range metadata. 108 //===------------------------------------------------------------------===// 109 110 /// Return metadata describing the range [Lo, Hi). 111 LLVM_ABI MDNode *createRange(const APInt &Lo, const APInt &Hi); 112 113 /// Return metadata describing the range [Lo, Hi). 114 LLVM_ABI MDNode *createRange(Constant *Lo, Constant *Hi); 115 116 //===------------------------------------------------------------------===// 117 // Callees metadata. 118 //===------------------------------------------------------------------===// 119 120 /// Return metadata indicating the possible callees of indirect 121 /// calls. 122 LLVM_ABI MDNode *createCallees(ArrayRef<Function *> Callees); 123 124 //===------------------------------------------------------------------===// 125 // Callback metadata. 126 //===------------------------------------------------------------------===// 127 128 /// Return metadata describing a callback (see llvm::AbstractCallSite). 129 LLVM_ABI MDNode *createCallbackEncoding(unsigned CalleeArgNo, 130 ArrayRef<int> Arguments, 131 bool VarArgsArePassed); 132 133 /// Merge the new callback encoding \p NewCB into \p ExistingCallbacks. 134 LLVM_ABI MDNode *mergeCallbackEncodings(MDNode *ExistingCallbacks, 135 MDNode *NewCB); 136 137 /// Return metadata feeding to the CodeGen about how to generate a function 138 /// prologue for the "function" santizier. 139 LLVM_ABI MDNode *createRTTIPointerPrologue(Constant *PrologueSig, 140 Constant *RTTI); 141 142 //===------------------------------------------------------------------===// 143 // PC sections metadata. 144 //===------------------------------------------------------------------===// 145 146 /// A pair of PC section name with auxilliary constant data. 147 using PCSection = std::pair<StringRef, SmallVector<Constant *>>; 148 149 /// Return metadata for PC sections. 150 LLVM_ABI MDNode *createPCSections(ArrayRef<PCSection> Sections); 151 152 //===------------------------------------------------------------------===// 153 // AA metadata. 154 //===------------------------------------------------------------------===// 155 156 protected: 157 /// Return metadata appropriate for a AA root node (scope or TBAA). 158 /// Each returned node is distinct from all other metadata and will never 159 /// be identified (uniqued) with anything else. 160 LLVM_ABI MDNode *createAnonymousAARoot(StringRef Name = StringRef(), 161 MDNode *Extra = nullptr); 162 163 public: 164 /// Return metadata appropriate for a TBAA root node. Each returned 165 /// node is distinct from all other metadata and will never be identified 166 /// (uniqued) with anything else. createAnonymousTBAARoot()167 MDNode *createAnonymousTBAARoot() { 168 return createAnonymousAARoot(); 169 } 170 171 /// Return metadata appropriate for an alias scope domain node. 172 /// Each returned node is distinct from all other metadata and will never 173 /// be identified (uniqued) with anything else. 174 MDNode *createAnonymousAliasScopeDomain(StringRef Name = StringRef()) { 175 return createAnonymousAARoot(Name); 176 } 177 178 /// Return metadata appropriate for an alias scope root node. 179 /// Each returned node is distinct from all other metadata and will never 180 /// be identified (uniqued) with anything else. 181 MDNode *createAnonymousAliasScope(MDNode *Domain, 182 StringRef Name = StringRef()) { 183 return createAnonymousAARoot(Name, Domain); 184 } 185 186 /// Return metadata appropriate for a TBAA root node with the given 187 /// name. This may be identified (uniqued) with other roots with the same 188 /// name. 189 LLVM_ABI MDNode *createTBAARoot(StringRef Name); 190 191 /// Return metadata appropriate for an alias scope domain node with 192 /// the given name. This may be identified (uniqued) with other roots with 193 /// the same name. 194 LLVM_ABI MDNode *createAliasScopeDomain(StringRef Name); 195 196 /// Return metadata appropriate for an alias scope node with 197 /// the given name. This may be identified (uniqued) with other scopes with 198 /// the same name and domain. 199 LLVM_ABI MDNode *createAliasScope(StringRef Name, MDNode *Domain); 200 201 /// Return metadata for a non-root TBAA node with the given name, 202 /// parent in the TBAA tree, and value for 'pointsToConstantMemory'. 203 LLVM_ABI MDNode *createTBAANode(StringRef Name, MDNode *Parent, 204 bool isConstant = false); 205 206 struct TBAAStructField { 207 uint64_t Offset; 208 uint64_t Size; 209 MDNode *Type; TBAAStructFieldTBAAStructField210 TBAAStructField(uint64_t Offset, uint64_t Size, MDNode *Type) : 211 Offset(Offset), Size(Size), Type(Type) {} 212 }; 213 214 /// Return metadata for a tbaa.struct node with the given 215 /// struct field descriptions. 216 LLVM_ABI MDNode *createTBAAStructNode(ArrayRef<TBAAStructField> Fields); 217 218 /// Return metadata for a TBAA struct node in the type DAG 219 /// with the given name, a list of pairs (offset, field type in the type DAG). 220 LLVM_ABI MDNode * 221 createTBAAStructTypeNode(StringRef Name, 222 ArrayRef<std::pair<MDNode *, uint64_t>> Fields); 223 224 /// Return metadata for a TBAA scalar type node with the 225 /// given name, an offset and a parent in the TBAA type DAG. 226 LLVM_ABI MDNode *createTBAAScalarTypeNode(StringRef Name, MDNode *Parent, 227 uint64_t Offset = 0); 228 229 /// Return metadata for a TBAA tag node with the given 230 /// base type, access type and offset relative to the base type. 231 LLVM_ABI MDNode *createTBAAStructTagNode(MDNode *BaseType, MDNode *AccessType, 232 uint64_t Offset, 233 bool IsConstant = false); 234 235 /// Return metadata for a TBAA type node in the TBAA type DAG with the 236 /// given parent type, size in bytes, type identifier and a list of fields. 237 LLVM_ABI MDNode *createTBAATypeNode( 238 MDNode *Parent, uint64_t Size, Metadata *Id, 239 ArrayRef<TBAAStructField> Fields = ArrayRef<TBAAStructField>()); 240 241 /// Return metadata for a TBAA access tag with the given base type, 242 /// final access type, offset of the access relative to the base type, size of 243 /// the access and flag indicating whether the accessed object can be 244 /// considered immutable for the purposes of the TBAA analysis. 245 LLVM_ABI MDNode *createTBAAAccessTag(MDNode *BaseType, MDNode *AccessType, 246 uint64_t Offset, uint64_t Size, 247 bool IsImmutable = false); 248 249 /// Return mutable version of the given mutable or immutable TBAA 250 /// access tag. 251 LLVM_ABI MDNode *createMutableTBAAAccessTag(MDNode *Tag); 252 253 /// Return metadata containing an irreducible loop header weight. 254 LLVM_ABI MDNode *createIrrLoopHeaderWeight(uint64_t Weight); 255 }; 256 257 } // end namespace llvm 258 259 #endif 260