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