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