[debuginfo][coro] Emit debug info labels for coroutine resume points

With this commit, we add `DILabel` debug infos (lowering to DW_TAG_label
in DWARF) to the various resume points of a coroutine. Those labels use
the naming convention `__coro_resume_<N>` where `<N>` is the suspension
point id.

That way, debugging scripts can figure out the exact line / column at
which a coroutine was suspended by looking up current `__coro_index`
value inside the coroutines frame, and then searching for the
corresponding `__coro_resume_<N>` inside the coroutine's resume
function.

While this is an artificial compiler-generated label, I did not apply
the DW_AT_artificial tag to it. The DWARFv5 standard only allows that
tag on type and variable definitions, but not on labels.

In gdb, those line numebers can then be looked up using the command
`info line -function my_coroutine -label __coro_resume_1`.

LLDB unfortunately does not parse DW_TAG_label debug information, yet. As
such, this debug information is currently not useful in LLDB.

Author: vogelsgesang

clang/docs/DebuggingCoroutines.rst

@@ -209,9 +209,24 @@ important. This member identifies the suspension point at which the coroutine
 is currently suspended.
 
 However, it is non-trivial to map this number back to a source code location.
-In simple cases, one might correctly guess the source code location. In more
-complex cases, we can modify the C++ code to store additional information in
-the promise type:
+The compiler emits debug info labels for the suspension points. This allows us
+to map the suspension point index back to a source code location. In gdb, we
+can use the ``info line`` command to get the source code location of the
+suspension point.
+
+::
+
+  (gdb) info line -function coro_task -label __coro_resume_2
+  Line 45 of "llvm-example.cpp" starts at address 0x1b1b <_ZL9coro_taski.resume+555> and ends at 0x1b46 <_ZL9coro_taski.resume+598>.
+  Line 45 of "llvm-example.cpp" starts at address 0x201b <_ZL9coro_taski.destroy+555> and ends at 0x2046 <_ZL9coro_taski.destroy+598>.
+  Line 45 of "llvm-example.cpp" starts at address 0x253b <_ZL9coro_taski.cleanup+555> and ends at 0x2566 <_ZL9coro_taski.cleanup+598>.
+
+LLDB does not support looking up labels. Furthmore, those labels are only emitted
+starting with clang 21.0.
+
+For simple cases, you might still be able to guess the suspension point correctly.
+Alternatively, you might also want to modify your coroutine library to store
+the line number of the current suspension point in the promise:
 
 .. code-block:: c++
 
@@ -221,8 +236,6 @@ the promise type:
     void* _coro_return_address = nullptr;
   };
 
-  #include <source_location>
-
   // For all the awaiter types we need:
   class awaiter {
     ...

llvm/lib/Transforms/Coroutines/CoroFrame.cpp

@@ -688,9 +688,9 @@ static DIType *solveDIType(DIBuilder &Builder, Type *Ty,
 static void buildFrameDebugInfo(Function &F, coro::Shape &Shape,
                                 FrameDataInfo &FrameData) {
   DISubprogram *DIS = F.getSubprogram();
-  // If there is no DISubprogram for F, it implies the Function are not compiled
-  // with debug info. So we also don't need to generate debug info for the frame
-  // neither.
+  // If there is no DISubprogram for F, it implies the function is compiled
+  // without debug info. So we also don't generate debug info for the frame,
+  // either.
   if (!DIS || !DIS->getUnit() ||
       !dwarf::isCPlusPlus(
           (dwarf::SourceLanguage)DIS->getUnit()->getSourceLanguage()) ||

llvm/lib/Transforms/Coroutines/CoroSplit.cpp

@@ -42,6 +42,7 @@
 #include "llvm/IR/CFG.h"
 #include "llvm/IR/CallingConv.h"
 #include "llvm/IR/Constants.h"
+#include "llvm/IR/DIBuilder.h"
 #include "llvm/IR/DataLayout.h"
 #include "llvm/IR/DebugInfo.h"
 #include "llvm/IR/DerivedTypes.h"
@@ -302,7 +303,7 @@ static void replaceFallthroughCoroEnd(AnyCoroEndInst *End,
 }
 
 // Mark a coroutine as done, which implies that the coroutine is finished and
-// never get resumed.
+// never gets resumed.
 //
 // In resume-switched ABI, the done state is represented by storing zero in
 // ResumeFnAddr.
@@ -1478,6 +1479,18 @@ struct SwitchCoroutineSplitter {
   static void createResumeEntryBlock(Function &F, coro::Shape &Shape) {
     LLVMContext &C = F.getContext();
 
+    DIBuilder DBuilder(*F.getParent(), /*AllowUnresolved*/ false);
+    DISubprogram *DIS = F.getSubprogram();
+    // If there is no DISubprogram for F, it implies the function is compiled
+    // without debug info. So we also don't generate debug info for the
+    // suspension points, either.
+    bool AddDebugLabels =
+        (DIS && DIS->getUnit() &&
+         (DIS->getUnit()->getEmissionKind() ==
+              DICompileUnit::DebugEmissionKind::FullDebug ||
+          DIS->getUnit()->getEmissionKind() ==
+              DICompileUnit::DebugEmissionKind::LineTablesOnly));
+
     // resume.entry:
     //  %index.addr = getelementptr inbounds %f.Frame, %f.Frame* %FramePtr, i32
     //  0, i32 2 % index = load i32, i32* %index.addr switch i32 %index, label
@@ -1500,6 +1513,7 @@ struct SwitchCoroutineSplitter {
         Builder.CreateSwitch(Index, UnreachBB, Shape.CoroSuspends.size());
     Shape.SwitchLowering.ResumeSwitch = Switch;
 
+    // Split all coro.suspend calls
     size_t SuspendIndex = 0;
     for (auto *AnyS : Shape.CoroSuspends) {
       auto *S = cast<CoroSuspendInst>(AnyS);
@@ -1538,6 +1552,7 @@ struct SwitchCoroutineSplitter {
       //     br label %resume.0.landing
       //
       //  resume.0: ; <--- jump from the switch in the resume.entry
+      //     XXX: label
       //     %0 = tail call i8 @llvm.coro.suspend(token none, i1 false)
       //     br label %resume.0.landing
       //
@@ -1560,11 +1575,23 @@ struct SwitchCoroutineSplitter {
       PN->addIncoming(Builder.getInt8(-1), SuspendBB);
       PN->addIncoming(S, ResumeBB);
 
+      if (AddDebugLabels) {
+        if (DebugLoc SuspendLoc = S->getDebugLoc()) {
+          std::string LabelName =
+              ("__coro_resume_" + Twine(SuspendIndex)).str();
+          DILocation& DILoc = *SuspendLoc.get();
+          DILabel *ResumeLabel = DBuilder.createLabel(
+              DIS, LabelName, DILoc.getFile(), SuspendLoc.getLine());
+          DBuilder.insertLabel(ResumeLabel, &DILoc, ResumeBB->begin());
+        }
+      }
+
       ++SuspendIndex;
     }
 
     Builder.SetInsertPoint(UnreachBB);
     Builder.CreateUnreachable();
+    DBuilder.finalize();
 
     Shape.SwitchLowering.ResumeEntryBlock = NewEntry;
   }