1//===---- llvm/MDBuilder.h - Builder for LLVM metadata ----------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file defines the MDBuilder class, which is used as a convenient way to
11// create LLVM metadata with a consistent and simplified interface.
12//
13//===----------------------------------------------------------------------===//
14
15#ifndef LLVM_IR_MDBUILDER_H
16#define LLVM_IR_MDBUILDER_H
17
18#include "llvm/ADT/DenseSet.h"
19#include "llvm/ADT/StringRef.h"
20#include "llvm/IR/GlobalValue.h"
21#include "llvm/Support/DataTypes.h"
22#include <utility>
23
24namespace llvm {
25
26class APInt;
27template <typename T> class ArrayRef;
28class LLVMContext;
29class Constant;
30class ConstantAsMetadata;
31class MDNode;
32class MDString;
33
34class MDBuilder {
35  LLVMContext &Context;
36
37public:
38  MDBuilder(LLVMContext &context) : Context(context) {}
39
40  /// \brief Return the given string as metadata.
41  MDString *createString(StringRef Str);
42
43  /// \brief Return the given constant as metadata.
44  ConstantAsMetadata *createConstant(Constant *C);
45
46  //===------------------------------------------------------------------===//
47  // FPMath metadata.
48  //===------------------------------------------------------------------===//
49
50  /// \brief Return metadata with the given settings.  The special value 0.0
51  /// for the Accuracy parameter indicates the default (maximal precision)
52  /// setting.
53  MDNode *createFPMath(float Accuracy);
54
55  //===------------------------------------------------------------------===//
56  // Prof metadata.
57  //===------------------------------------------------------------------===//
58
59  /// \brief Return metadata containing two branch weights.
60  MDNode *createBranchWeights(uint32_t TrueWeight, uint32_t FalseWeight);
61
62  /// \brief Return metadata containing a number of branch weights.
63  MDNode *createBranchWeights(ArrayRef<uint32_t> Weights);
64
65  /// Return metadata specifying that a branch or switch is unpredictable.
66  MDNode *createUnpredictable();
67
68  /// Return metadata containing the entry \p Count for a function, and the
69  /// GUIDs stored in \p Imports that need to be imported for sample PGO, to
70  /// enable the same inlines as the profiled optimized binary
71  MDNode *createFunctionEntryCount(uint64_t Count,
72                                   const DenseSet<GlobalValue::GUID> *Imports);
73
74  /// Return metadata containing the section prefix for a function.
75  MDNode *createFunctionSectionPrefix(StringRef Prefix);
76
77  //===------------------------------------------------------------------===//
78  // Range metadata.
79  //===------------------------------------------------------------------===//
80
81  /// \brief Return metadata describing the range [Lo, Hi).
82  MDNode *createRange(const APInt &Lo, const APInt &Hi);
83
84  /// \brief Return metadata describing the range [Lo, Hi).
85  MDNode *createRange(Constant *Lo, Constant *Hi);
86
87  //===------------------------------------------------------------------===//
88  // AA metadata.
89  //===------------------------------------------------------------------===//
90
91protected:
92  /// \brief Return metadata appropriate for a AA root node (scope or TBAA).
93  /// Each returned node is distinct from all other metadata and will never
94  /// be identified (uniqued) with anything else.
95  MDNode *createAnonymousAARoot(StringRef Name = StringRef(),
96                                MDNode *Extra = nullptr);
97
98public:
99  /// \brief Return metadata appropriate for a TBAA root node. Each returned
100  /// node is distinct from all other metadata and will never be identified
101  /// (uniqued) with anything else.
102  MDNode *createAnonymousTBAARoot() {
103    return createAnonymousAARoot();
104  }
105
106  /// \brief Return metadata appropriate for an alias scope domain node.
107  /// Each returned node is distinct from all other metadata and will never
108  /// be identified (uniqued) with anything else.
109  MDNode *createAnonymousAliasScopeDomain(StringRef Name = StringRef()) {
110    return createAnonymousAARoot(Name);
111  }
112
113  /// \brief Return metadata appropriate for an alias scope root node.
114  /// Each returned node is distinct from all other metadata and will never
115  /// be identified (uniqued) with anything else.
116  MDNode *createAnonymousAliasScope(MDNode *Domain,
117                                    StringRef Name = StringRef()) {
118    return createAnonymousAARoot(Name, Domain);
119  }
120
121  /// \brief Return metadata appropriate for a TBAA root node with the given
122  /// name.  This may be identified (uniqued) with other roots with the same
123  /// name.
124  MDNode *createTBAARoot(StringRef Name);
125
126  /// \brief Return metadata appropriate for an alias scope domain node with
127  /// the given name. This may be identified (uniqued) with other roots with
128  /// the same name.
129  MDNode *createAliasScopeDomain(StringRef Name);
130
131  /// \brief Return metadata appropriate for an alias scope node with
132  /// the given name. This may be identified (uniqued) with other scopes with
133  /// the same name and domain.
134  MDNode *createAliasScope(StringRef Name, MDNode *Domain);
135
136  /// \brief Return metadata for a non-root TBAA node with the given name,
137  /// parent in the TBAA tree, and value for 'pointsToConstantMemory'.
138  MDNode *createTBAANode(StringRef Name, MDNode *Parent,
139                         bool isConstant = false);
140
141  struct TBAAStructField {
142    uint64_t Offset;
143    uint64_t Size;
144    MDNode *TBAA;
145    TBAAStructField(uint64_t Offset, uint64_t Size, MDNode *TBAA) :
146      Offset(Offset), Size(Size), TBAA(TBAA) {}
147  };
148
149  /// \brief Return metadata for a tbaa.struct node with the given
150  /// struct field descriptions.
151  MDNode *createTBAAStructNode(ArrayRef<TBAAStructField> Fields);
152
153  /// \brief Return metadata for a TBAA struct node in the type DAG
154  /// with the given name, a list of pairs (offset, field type in the type DAG).
155  MDNode *
156  createTBAAStructTypeNode(StringRef Name,
157                           ArrayRef<std::pair<MDNode *, uint64_t>> Fields);
158
159  /// \brief Return metadata for a TBAA scalar type node with the
160  /// given name, an offset and a parent in the TBAA type DAG.
161  MDNode *createTBAAScalarTypeNode(StringRef Name, MDNode *Parent,
162                                   uint64_t Offset = 0);
163
164  /// \brief Return metadata for a TBAA tag node with the given
165  /// base type, access type and offset relative to the base type.
166  MDNode *createTBAAStructTagNode(MDNode *BaseType, MDNode *AccessType,
167                                  uint64_t Offset, bool IsConstant = false);
168};
169
170} // end namespace llvm
171
172#endif
173