1 //===---- llvm/MDBuilder.h - Builder for LLVM metadata ----------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
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.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_IR_MDBUILDER_H
15 #define LLVM_IR_MDBUILDER_H
17 #include "llvm/ADT/DenseSet.h"
18 #include "llvm/ADT/StringRef.h"
19 #include "llvm/IR/Constants.h"
20 #include "llvm/IR/GlobalValue.h"
21 #include "llvm/Support/DataTypes.h"
27 template <typename T
> class ArrayRef
;
30 class ConstantAsMetadata
;
39 MDBuilder(LLVMContext
&context
) : Context(context
) {}
41 /// Return the given string as metadata.
42 MDString
*createString(StringRef Str
);
44 /// Return the given constant as metadata.
45 ConstantAsMetadata
*createConstant(Constant
*C
);
47 //===------------------------------------------------------------------===//
49 //===------------------------------------------------------------------===//
51 /// Return metadata with the given settings. The special value 0.0
52 /// for the Accuracy parameter indicates the default (maximal precision)
54 MDNode
*createFPMath(float Accuracy
);
56 //===------------------------------------------------------------------===//
58 //===------------------------------------------------------------------===//
60 /// Return metadata containing two branch weights.
61 MDNode
*createBranchWeights(uint32_t TrueWeight
, uint32_t FalseWeight
);
63 /// Return metadata containing a number of branch weights.
64 MDNode
*createBranchWeights(ArrayRef
<uint32_t> Weights
);
66 /// Return metadata specifying that a branch or switch is unpredictable.
67 MDNode
*createUnpredictable();
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
);
76 /// Return metadata containing the section prefix for a function.
77 MDNode
*createFunctionSectionPrefix(StringRef Prefix
);
79 /// return metadata containing expected value
80 MDNode
*createMisExpect(uint64_t Index
, uint64_t LikelyWeight
,
81 uint64_t UnlikelyWeight
);
83 //===------------------------------------------------------------------===//
85 //===------------------------------------------------------------------===//
87 /// Return metadata describing the range [Lo, Hi).
88 MDNode
*createRange(const APInt
&Lo
, const APInt
&Hi
);
90 /// Return metadata describing the range [Lo, Hi).
91 MDNode
*createRange(Constant
*Lo
, Constant
*Hi
);
93 //===------------------------------------------------------------------===//
95 //===------------------------------------------------------------------===//
97 /// Return metadata indicating the possible callees of indirect
99 MDNode
*createCallees(ArrayRef
<Function
*> Callees
);
101 //===------------------------------------------------------------------===//
102 // Callback metadata.
103 //===------------------------------------------------------------------===//
105 /// Return metadata describing a callback (see llvm::AbstractCallSite).
106 MDNode
*createCallbackEncoding(unsigned CalleeArgNo
, ArrayRef
<int> Arguments
,
107 bool VarArgsArePassed
);
109 /// Merge the new callback encoding \p NewCB into \p ExistingCallbacks.
110 MDNode
*mergeCallbackEncodings(MDNode
*ExistingCallbacks
, MDNode
*NewCB
);
112 //===------------------------------------------------------------------===//
114 //===------------------------------------------------------------------===//
117 /// Return metadata appropriate for a AA root node (scope or TBAA).
118 /// Each returned node is distinct from all other metadata and will never
119 /// be identified (uniqued) with anything else.
120 MDNode
*createAnonymousAARoot(StringRef Name
= StringRef(),
121 MDNode
*Extra
= nullptr);
124 /// Return metadata appropriate for a TBAA root node. Each returned
125 /// node is distinct from all other metadata and will never be identified
126 /// (uniqued) with anything else.
127 MDNode
*createAnonymousTBAARoot() {
128 return createAnonymousAARoot();
131 /// Return metadata appropriate for an alias scope domain node.
132 /// Each returned node is distinct from all other metadata and will never
133 /// be identified (uniqued) with anything else.
134 MDNode
*createAnonymousAliasScopeDomain(StringRef Name
= StringRef()) {
135 return createAnonymousAARoot(Name
);
138 /// Return metadata appropriate for an alias scope root node.
139 /// Each returned node is distinct from all other metadata and will never
140 /// be identified (uniqued) with anything else.
141 MDNode
*createAnonymousAliasScope(MDNode
*Domain
,
142 StringRef Name
= StringRef()) {
143 return createAnonymousAARoot(Name
, Domain
);
146 /// Return metadata appropriate for a TBAA root node with the given
147 /// name. This may be identified (uniqued) with other roots with the same
149 MDNode
*createTBAARoot(StringRef Name
);
151 /// Return metadata appropriate for an alias scope domain node with
152 /// the given name. This may be identified (uniqued) with other roots with
154 MDNode
*createAliasScopeDomain(StringRef Name
);
156 /// Return metadata appropriate for an alias scope node with
157 /// the given name. This may be identified (uniqued) with other scopes with
158 /// the same name and domain.
159 MDNode
*createAliasScope(StringRef Name
, MDNode
*Domain
);
161 /// Return metadata for a non-root TBAA node with the given name,
162 /// parent in the TBAA tree, and value for 'pointsToConstantMemory'.
163 MDNode
*createTBAANode(StringRef Name
, MDNode
*Parent
,
164 bool isConstant
= false);
166 struct TBAAStructField
{
170 TBAAStructField(uint64_t Offset
, uint64_t Size
, MDNode
*Type
) :
171 Offset(Offset
), Size(Size
), Type(Type
) {}
174 /// Return metadata for a tbaa.struct node with the given
175 /// struct field descriptions.
176 MDNode
*createTBAAStructNode(ArrayRef
<TBAAStructField
> Fields
);
178 /// Return metadata for a TBAA struct node in the type DAG
179 /// with the given name, a list of pairs (offset, field type in the type DAG).
181 createTBAAStructTypeNode(StringRef Name
,
182 ArrayRef
<std::pair
<MDNode
*, uint64_t>> Fields
);
184 /// Return metadata for a TBAA scalar type node with the
185 /// given name, an offset and a parent in the TBAA type DAG.
186 MDNode
*createTBAAScalarTypeNode(StringRef Name
, MDNode
*Parent
,
187 uint64_t Offset
= 0);
189 /// Return metadata for a TBAA tag node with the given
190 /// base type, access type and offset relative to the base type.
191 MDNode
*createTBAAStructTagNode(MDNode
*BaseType
, MDNode
*AccessType
,
192 uint64_t Offset
, bool IsConstant
= false);
194 /// Return metadata for a TBAA type node in the TBAA type DAG with the
195 /// given parent type, size in bytes, type identifier and a list of fields.
196 MDNode
*createTBAATypeNode(MDNode
*Parent
, uint64_t Size
, Metadata
*Id
,
197 ArrayRef
<TBAAStructField
> Fields
=
198 ArrayRef
<TBAAStructField
>());
200 /// Return metadata for a TBAA access tag with the given base type,
201 /// final access type, offset of the access relative to the base type, size of
202 /// the access and flag indicating whether the accessed object can be
203 /// considered immutable for the purposes of the TBAA analysis.
204 MDNode
*createTBAAAccessTag(MDNode
*BaseType
, MDNode
*AccessType
,
205 uint64_t Offset
, uint64_t Size
,
206 bool IsImmutable
= false);
208 /// Return mutable version of the given mutable or immutable TBAA
210 MDNode
*createMutableTBAAAccessTag(MDNode
*Tag
);
212 /// Return metadata containing an irreducible loop header weight.
213 MDNode
*createIrrLoopHeaderWeight(uint64_t Weight
);
216 } // end namespace llvm