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