include/llvm/IR/MDBuilder.h

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