[IRGen] Change annotation metadata to support inserting tuple of strings into annotation metadata array.

[zjaffal]

Summary

Annotation metadata supports adding singular annotation strings to annotation block. This patch adds the ability to insert a tuple of strings into the metadata array.

The idea here is that each tuple of strings represents a piece of information that can be all related. It makes it easier to parse through related metadata information given it will be contained in one tuple.
For example in remarks any pass that implements annotation remarks can have different type of remarks and pass additional information for each.

The original behaviour of annotation remarks is preserved here and we can mix tuple annotations and single annotations for the same instruction.

[fhahn]

This would also require an update to https://llvm.org/docs/LangRef.html#annotation-metadata

Could you also add the motivation for this change to the description?

[zjaffal]

Update LangRef.rst

[paquette]

Currently annotation metadata can only support a tuple of strings.

I think the commit message is incorrect?

For example in remarks any pass that implements annotation remarks can have different type of remarks and pass additional information for each.

Is it possible to test the new tuple behaviour using any existing remarks? Or will that be in a follow-up?

llvm/lib/CodeGen/MachineFunction.cpp

122

This pattern appears a lot; should it be pulled out into a helper function?

llvm/lib/IR/Metadata.cpp

1555

Should this be captured by reference instead of copied?

llvm/lib/Transforms/Scalar/AnnotationRemarks.cpp

66

Since AnnotationTuple is only used in AnnotationStr, we can pull it into the getString() call and eliminate the braces around the else.

Or you could write it via the ternary operator:

StringRef AnnotationStr = isa<MDString>(Op.get())) ?
                                             cast<MDString>(Op.get())->getString() :
                                             cast<MDString>(cast<MDTuple>(Op.get())->getOperand(0).get())->getString();

[zjaffal]

• Address comments

[paquette]

I have one nit but other than that this LGTM

llvm/include/llvm/IR/Metadata.h

795

just return this?

llvm/docs/LangRef.rst

 operands give the execution count that each of the respective prior target
 functions was called.
 
 .. _md_annotation:
 
 '``annotation``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``annotation`` metadata can be used to attach a tuple of annotation strings
-to any instruction. This metadata does not impact the semantics of the program
-and may only be used to provide additional insight about the program and
-transformations to users.
+The ``annotation`` metadata can be used to attach a tuple of annotation strings 
+or a tuple of a tuple of annotation strings to any instruction. This metadata does 
+not impact the semantics of the program and may only be used to provide additional 
+insight about the program and transformations to users.
 
 Example:
 
 .. code-block:: text
 
     %a.addr = alloca ptr, align 8, !annotation !0
     !0 = !{!"auto-init"}
 
+Embedding tuple of strings example:
+
+.. code-block:: test
+  %a.ptr = getelementptr ptr, ptr %base, i64 0. !annotation !0
+  !0 = !{!1}
+  !1 = !{!"gep offset", !"0"}
+
 '``func_sanitize``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``func_sanitize`` metadata is used to attach two values for the function
 sanitizer instrumentation. The first value is the ubsan function signature.
 The second value is the address of the proxy variable which stores the address
 of the RTTI descriptor. If :ref:`prologue <prologuedata>` and '``func_sanitize``'
 are used at the same time, :ref:`prologue <prologuedata>` is emitted before

llvm/include/llvm/IR/Instruction.h

void dropUnknownNonDebugMetadata(unsigned ID1, unsigned ID2) {
     return dropUnknownNonDebugMetadata(IDs);
   }
   /// @}
 
   /// Adds an !annotation metadata node with \p Annotation to this instruction.
   /// If this instruction already has !annotation metadata, append \p Annotation
   /// to the existing node.
   void addAnnotationMetadata(StringRef Annotation);
-
+  /// Adds an !annotation metadata node with an array of \p Annotations
+  /// as a tuple to this instruction. If this instruction already has
+  /// !annotation metadata, append the tuple to
+  /// the existing node.
+  void addAnnotationMetadata(SmallVector<StringRef> Annotations);
   /// Returns the AA metadata for this instruction.
   AAMDNodes getAAMetadata() const;
 
   /// Sets the AA metadata on this instruction from the AAMDNodes structure.
   void setAAMetadata(const AAMDNodes &N);
 
   /// Retrieve total raw weight values of a branch.
   /// Returns true on success with profile total weights filled in.

llvm/include/llvm/IR/Metadata.h

public:
   MDOperand &operator=(const MDOperand &) = delete;
   MDOperand &operator=(MDOperand &&Op) {
     MD = Op.MD;
     if (MD)
       (void)MetadataTracking::retrack(Op.MD, MD);
     Op.MD = nullptr;
     return *this;
   }
+
+  // Check if MDOperand is of type MDString and equals `Str`.
+  bool equalsStr(StringRef Str) const {
+    return isa<MDString>(this->get()) &&
+           cast<MDString>(this->get())->getString() == Str;
+  }
+
   ~MDOperand() { untrack(); }
 
   Metadata *get() const { return MD; }
   operator Metadata *() const { return get(); }
   Metadata *operator->() const { return get(); }
   Metadata &operator*() const { return *get(); }
 
   void reset() {

llvm/lib/CodeGen/BasicBlockSections.cpp

static bool hasInstrProfHashMismatch(MachineFunction &MF) {
   if (!BBSectionsDetectSourceDrift)
     return false;
 
   const char MetadataName[] = "instr_prof_hash_mismatch";
   auto *Existing = MF.getFunction().getMetadata(LLVMContext::MD_annotation);
   if (Existing) {
     MDTuple *Tuple = cast<MDTuple>(Existing);
     for (const auto &N : Tuple->operands())
-      if (cast<MDString>(N.get())->getString() == MetadataName)
+      if (N.equalsStr(MetadataName))
         return true;
   }
 
   return false;
 }
 
 bool BasicBlockSections::runOnMachineFunction(MachineFunction &MF) {
   auto BBSectionsType = MF.getTarget().getBBSectionsType();

llvm/lib/CodeGen/MachineFunction.cpp

void setUnsafeStackSize(const Function &F, MachineFrameInfo &FrameInfo) {
   auto *Existing =
       dyn_cast_or_null<MDTuple>(F.getMetadata(LLVMContext::MD_annotation));
 
   if (!Existing || Existing->getNumOperands() != 2)
     return;
 
   auto *MetadataName = "unsafe-stack-size";
   if (auto &N = Existing->getOperand(0)) {
-    if (cast<MDString>(N.get())->getString() == MetadataName) {
+    if (N.equalsStr(MetadataName)) {
       if (auto &Op = Existing->getOperand(1)) {
         auto Val = mdconst::extract<ConstantInt>(Op)->getZExtValue();
         FrameInfo.setUnsafeStackSize(Val);
       }
     }
   }
 }
 

llvm/lib/IR/Metadata.cpp

if (KindID == LLVMContext::MD_DIAssignID) {
     assert((!Node || !Node->isTemporary()) &&
            "Temporary DIAssignIDs are invalid");
     updateDIAssignIDMapping(cast_or_null<DIAssignID>(Node));
   }
 
   Value::setMetadata(KindID, Node);
 }
 
+void Instruction::addAnnotationMetadata(SmallVector<StringRef> Annotations) {
+  SmallSetVector<StringRef, 2> AnnotationsSet(Annotations.begin(),
+                                              Annotations.end());
+  MDBuilder MDB(getContext());
+
+  auto *Existing = getMetadata(LLVMContext::MD_annotation);
+  SmallVector<Metadata *, 4> Names;
+  if (Existing) {
+    auto *Tuple = cast<MDTuple>(Existing);
+    for (auto &N : Tuple->operands()) {
+      if (isa<MDString>(N.get()))
+        continue;
+      auto *MDAnnotationTuple = cast<MDTuple>(N);
+      if (any_of(MDAnnotationTuple->operands(), [&AnnotationsSet](auto &Op) {
+            return AnnotationsSet.contains(cast<MDString>(Op)->getString());
+          }))
+        return;
+      Names.push_back(N);
+    }
+  }
+
+  SmallVector<Metadata *> MDAnnotationStrings;
+  for (StringRef Annotation : Annotations)
+    MDAnnotationStrings.push_back(MDB.createString(Annotation));
+  MDNode *InfoTuple = MDTuple::get(getContext(), MDAnnotationStrings);
+  Names.push_back(InfoTuple);
+  MDNode *MD = MDTuple::get(getContext(), Names);
+  setMetadata(LLVMContext::MD_annotation, MD);
+}
+
 void Instruction::addAnnotationMetadata(StringRef Name) {
   MDBuilder MDB(getContext());
 
   auto *Existing = getMetadata(LLVMContext::MD_annotation);
   SmallVector<Metadata *, 4> Names;
-  bool AppendName = true;
   if (Existing) {
     auto *Tuple = cast<MDTuple>(Existing);
     for (auto &N : Tuple->operands()) {
-      if (cast<MDString>(N.get())->getString() == Name)
-        AppendName = false;
+      if (isa<MDString>(N.get()) &&
+          cast<MDString>(N.get())->getString() == Name)
+        return;
       Names.push_back(N.get());
     }
   }
-  if (AppendName)
-    Names.push_back(MDB.createString(Name));
 
+  Names.push_back(MDB.createString(Name));
   MDNode *MD = MDTuple::get(getContext(), Names);
   setMetadata(LLVMContext::MD_annotation, MD);
 }
 
 AAMDNodes Instruction::getAAMetadata() const {
   AAMDNodes Result;
   // Not using Instruction::hasMetadata() because we're not interested in
   // DebugInfoMetadata.

llvm/lib/IR/Verifier.cpp

void Verifier::visitCallsiteMetadata(Instruction &I, MDNode *MD) {
   // is a part of a profiled allocation callstack.
   visitCallStackMetadata(MD);
 }
 
 void Verifier::visitAnnotationMetadata(MDNode *Annotation) {
   Check(isa<MDTuple>(Annotation), "annotation must be a tuple");
   Check(Annotation->getNumOperands() >= 1,
         "annotation must have at least one operand");
-  for (const MDOperand &Op : Annotation->operands())
-    Check(isa<MDString>(Op.get()), "operands must be strings");
+  for (const MDOperand &Op : Annotation->operands()) {
+    bool TupleOfStrings =
+        isa<MDTuple>(Op.get()) &&
+        all_of(cast<MDTuple>(Op)->operands(), [](auto &Annotation) {
+          return isa<MDString>(Annotation.get());
+        });
+    Check(isa<MDString>(Op.get()) || TupleOfStrings,
+          "operands must be a string or a tuple of strings");
+  }
 }
 
 void Verifier::visitAliasScopeMetadata(const MDNode *MD) {
   unsigned NumOps = MD->getNumOperands();
   Check(NumOps >= 2 && NumOps <= 3, "scope must have two or three operands",
         MD);
   Check(MD->getOperand(0).get() == MD || isa<MDString>(MD->getOperand(0)),
         "first scope operand must be self-referential or string", MD);

llvm/lib/Transforms/Instrumentation/PGOInstrumentation.cpp

 static void annotateFunctionWithHashMismatch(Function &F, LLVMContext &ctx) {
   const char MetadataName[] = "instr_prof_hash_mismatch";
   SmallVector<Metadata *, 2> Names;
   // If this metadata already exists, ignore.
   auto *Existing = F.getMetadata(LLVMContext::MD_annotation);
   if (Existing) {
     MDTuple *Tuple = cast<MDTuple>(Existing);
     for (const auto &N : Tuple->operands()) {
-      if (cast<MDString>(N.get())->getString() == MetadataName)
+      if (N.equalsStr(MetadataName))
         return;
       Names.push_back(N.get());
     }
   }
 
   MDBuilder MDB(ctx);
   Names.push_back(MDB.createString(MetadataName));
   MDNode *MD = MDTuple::get(ctx, Names);

llvm/lib/Transforms/Scalar/AnnotationRemarks.cpp

static void runImpl(Function &F, const TargetLibraryInfo &TLI) {
   for (Instruction &I : instructions(F)) {
     if (!I.hasMetadata(LLVMContext::MD_annotation))
       continue;
     auto Iter = DebugLoc2Annotated.insert({I.getDebugLoc().getAsMDNode(), {}});
     Iter.first->second.push_back(&I);
 
     for (const MDOperand &Op :
          I.getMetadata(LLVMContext::MD_annotation)->operands()) {
-      auto Iter = Mapping.insert({cast<MDString>(Op.get())->getString(), 0});
+      StringRef AnnotationStr =
+          isa<MDString>(Op.get())
+              ? cast<MDString>(Op.get())->getString()
+              : cast<MDString>(cast<MDTuple>(Op.get())->getOperand(0).get())
+                    ->getString();
+      auto Iter = Mapping.insert({AnnotationStr, 0});
       Iter.first->second++;
     }
   }
 
   for (const auto &KV : Mapping)
     ORE.emit(OptimizationRemarkAnalysis(REMARK_PASS, "AnnotationSummary",
                                         F.getSubprogram(), &F.front())
              << "Annotated " << NV("count", KV.second) << " instructions with "
              << NV("type", KV.first));

llvm/lib/Transforms/Utils/MemoryOpRemark.cpp

void MemoryOpRemark::visitPtr(Value *Ptr, bool IsRead, DiagnosticInfoIROptimization &R) {
   R << ".";
 }
 
 bool AutoInitRemark::canHandle(const Instruction *I) {
   if (!I->hasMetadata(LLVMContext::MD_annotation))
     return false;
   return any_of(I->getMetadata(LLVMContext::MD_annotation)->operands(),
                 [](const MDOperand &Op) {
-                  return cast<MDString>(Op.get())->getString() == "auto-init";
+                  return isa<MDString>(Op.get()) &&
+                         cast<MDString>(Op.get())->getString() == "auto-init";
                 });
 }
 
 std::string AutoInitRemark::explainSource(StringRef Type) const {
   return (Type + " inserted by -ftrivial-auto-var-init.").str();
 }
 
 StringRef AutoInitRemark::remarkName(RemarkKind RK) const {

llvm/test/Verifier/annotation-metadata.ll

 ; RUN: not llvm-as -disable-output < %s -o /dev/null 2>&1 | FileCheck %s
 
 define void @test1(ptr %a) {
 entry:
 ; CHECK: annotation must have at least one operand
   %a.addr = alloca ptr, align 8, !annotation !0
 
-; CHECK-NEXT: operands must be strings
+; CHECK-NEXT: operands must be a string or a tuple of strings
   ret void, !annotation !1
 }
 
 !0 = !{}
 !1 = !{i32 10}