Add a callout to the LanguageRuntime to override the normal UnwindPlan used for a frame

[jasonmolenda]

Summary

Swift is gaining asynchronous functions, which may not be executing when a function they call is executing. In the backtrace, we want to show the logical caller of this currently-executing function even though it is not present on the stack like a real frame. The LanguageRuntime can provide an UnwindPlan that will provide that function.

When the async function is actually executing, we'll use its normal UnwindPlans. But when it is not executing, we'll use the LanguageRuntime's UnwindPlan to show it in the stack.

The way this is actually implemented by the swift runtime is that the stack has a chain of these async-not-running functions and pointers to a data block with saved context for them, and as we walk the chain we will get back to real stack functions again. The swift language runtime uses a flag in the spilled fp register to tell when it should provide its special unwind plan.

This patch adds code to LanguageRuntime to see if any LanguageRuntime plugins can provide an UnwindPlan given a RegisterContext. It adds code to RegisterContextUnwind to see if the LanguageRuntime can provide an UnwindPlan before we start looking at the function's normal UnwindPlans, and uses the async unwind plan if it was provided. Pretty simple hooks out to the LanguageRuntime where the details are encapsulated.

Without interjecting a LanguageRuntime plugin in a live debug session, this isn't testable in standard lldb; in the swift branch of lldb I can have an API test that has some async calls on the stack and do a stack walk. But I need the LanguageRuntimeSwift support for one of these to get that to work.

Open to any comments or suggestions, not sure if anyone is really into the unwinder enough to spend time reviewing it.

[kastiglione]

"Asynced" sounds funny to me, but I don't have suggestions other than "Async".

Looks good to me.

lldb/source/Target/RegisterContextUnwind.cpp

556

Looks like active_row will always be valid here, as the code is currently constructed.

[JDevlieghere]

lldb/include/lldb/Target/LanguageRuntime.h

176

Please use /// so this becomes a Doxygen comment.

186

s/Asynced/Async/ maybe?

lldb/source/Target/RegisterContextUnwind.cpp

294

nit: This sounds like is supposed to be generic, I'd drop the Swift here, you already gave that as an example above.

[jingham]

lldb/include/lldb/Target/LanguageRuntime.h

186

Maybe "Pending"? From the standpoint of the API, it doesn't really matter why there are some not-currently executing stacks, just that they are not currently executing. Pending describes the state, not the why, so might be more appropriate.

[jasonmolenda]

lldb/include/lldb/Target/LanguageRuntime.h

186

Thanks for the comments all. Yeah the wording Asynced is a little weird, but I was trying to get across the idea that a function is executing normally on the stack, then it is descheduled (or the function it calls is executed on another thread) and it has been async'ified from its previous running state, and will later revivify. But it's probably more trouble than it's worth and I should just use Async here.

[clayborg]

Can each real stack frame inject N frames in the middle of a stack frame for these asynchronous functions? Or is this like the libdispatch stuff that show more frames at the end of a normal stack trace? Can you attach some sample backtraces with some annotations?

lldb/include/lldb/Target/LanguageRuntime.h

21

I don't think we need this in the header file as we only use pointers to a RegisterContext. So move this to the .cpp file?

187

Any reason we are passing in the register context and the thread instead of a stack frame? a stack frame has access to the register context and to the thread it belongs to. Or is this register context just a raw register context that was extracted from somewhere in memory?

192

What does "ThisLanguage" this mean? Is it the language of the stack frame that owns "regctx"? Should we pass in the current stack frame instead of a register context?

[jasonmolenda]

lldb/include/lldb/Target/LanguageRuntime.h

187

I'll rethink this though, but I don't think we have a StackFrame yet. We're constructing the register context and we'll use that in creating the stack frame in a bit. I might be off-by-one, these parts of the unwinder can take some mental gymnastics to model properly when you're changing things.

192

Yeah it's not a great method name. The LanguageRuntime base class has a list of registered LanguageRuntime plugins. I want to iterate over them, seeing if any LanguageRuntime can provide one of these special one-off UnwindPlans. Tbh the top-level method GetAsyncedFrameForThisLanguage could have gone in Process and it could call a method of the same name in all the LanguageRuntime plugins, would end up working the same.

lldb/include/lldb/Target/LanguageRuntime.h

 #include "lldb/Breakpoint/BreakpointResolver.h"
 #include "lldb/Breakpoint/BreakpointResolverName.h"
 #include "lldb/Core/PluginInterface.h"
 #include "lldb/Core/Value.h"
 #include "lldb/Core/ValueObject.h"
 #include "lldb/Expression/LLVMUserExpression.h"
 #include "lldb/Symbol/DeclVendor.h"
 #include "lldb/Target/ExecutionContextScope.h"
 #include "lldb/Target/Runtime.h"
 #include "lldb/lldb-private.h"
 #include "lldb/lldb-public.h"
 
 namespace lldb_private {
 
 class ExceptionSearchFilter : public SearchFilter {
 public:
   ExceptionSearchFilter(const lldb::TargetSP &target_sp,
public:
   // would be. Useful when the underlying binary is stripped.
   virtual lldb::addr_t LookupRuntimeSymbol(ConstString name) {
     return LLDB_INVALID_ADDRESS;
   }
 
   virtual bool isA(const void *ClassID) const { return ClassID == &ID; }
   static char ID;
 
+  /// A language runtime may be able to provide a special UnwindPlan for
+  /// the frame represented by the register contents \a regctx when that
+  /// frame is not following the normal ABI conventions.
+  /// Instead of using the normal UnwindPlan for the function, we will use
+  /// this special UnwindPlan for this one backtrace.
+  /// One example of this would be a language that has asynchronous functions,
+  /// functions that may not be currently-executing, while waiting on other
+  /// asynchronous calls they made, but are part of a logical backtrace that
+  /// we want to show the developer because that's how they think of the
+  /// program flow.
+  static lldb::UnwindPlanSP
+  GetRuntimeUnwindPlan(lldb_private::Thread &thread,
+                       lldb_private::RegisterContext *regctx);
+
 protected:
+  // The static GetRuntimeUnwindPlan method above is only implemented in the
+  // base class; subclasses may override this protected member if they can
+  // provide one of these UnwindPlans.
+  virtual lldb::UnwindPlanSP
+  GetRuntimeUnwindPlan(lldb::ProcessSP process_sp,
+                       lldb_private::RegisterContext *regctx) {
+    return lldb::UnwindPlanSP();
+  }
+
   LanguageRuntime(Process *process);
 };
 
 } // namespace lldb_private
 
 #endif // LLDB_TARGET_LANGUAGERUNTIME_H

lldb/source/Target/LanguageRuntime.cpp

if (exc_breakpt_sp) {
 
     if (is_internal)
       exc_breakpt_sp->SetBreakpointKind("exception");
   }
 
   return exc_breakpt_sp;
 }
 
+UnwindPlanSP LanguageRuntime::GetRuntimeUnwindPlan(Thread &thread,
+                                                   RegisterContext *regctx) {
+  ProcessSP process_sp = thread.GetProcess();
+  if (!process_sp.get())
+    return UnwindPlanSP();
+  for (const lldb::LanguageType lang_type : Language::GetSupportedLanguages()) {
+    if (LanguageRuntime *runtime = process_sp->GetLanguageRuntime(lang_type)) {
+      UnwindPlanSP plan_sp = runtime->GetRuntimeUnwindPlan(process_sp, regctx);
+      if (plan_sp.get())
+        return plan_sp;
+    }
+  }
+  return UnwindPlanSP();
+}
+
 void LanguageRuntime::InitializeCommands(CommandObject *parent) {
   if (!parent)
     return;
 
   if (!parent->IsMultiwordObject())
     return;
 
   LanguageRuntimeCreateInstance create_callback;

lldb/source/Target/RegisterContextUnwind.cpp

 #include "lldb/Symbol/Function.h"
 #include "lldb/Symbol/ObjectFile.h"
 #include "lldb/Symbol/Symbol.h"
 #include "lldb/Symbol/SymbolContext.h"
 #include "lldb/Symbol/SymbolFile.h"
 #include "lldb/Target/ABI.h"
 #include "lldb/Target/DynamicLoader.h"
 #include "lldb/Target/ExecutionContext.h"
+#include "lldb/Target/LanguageRuntime.h"
 #include "lldb/Target/Platform.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/StackFrame.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Utility/DataBufferHeap.h"
 #include "lldb/Utility/Log.h"
void RegisterContextUnwind::InitializeNonZerothFrame() {
   }
   if (!m_thread.GetRegisterContext()) {
     m_frame_type = eNotAValidFrame;
     UnwindLogMsg("Could not get register context for this thread, marking this "
                  "frame as invalid.");
     return;
   }
 
+  ExecutionContext exe_ctx(m_thread.shared_from_this());
+  Process *process = exe_ctx.GetProcessPtr();
+
+  // Some languages may have a logical parent stack frame which is
+  // not a real stack frame, but the programmer would consider it to
+  // be the caller of the frame, e.g. Swift asynchronous frames.
+  //
+  // A LanguageRuntime may provide an UnwindPlan that is used in this
+  // stack trace base on the RegisterContext contents, intsead
+  // of the normal UnwindPlans we would use for the return-pc.
+  UnwindPlanSP lang_runtime_plan_sp =
+      LanguageRuntime::GetRuntimeUnwindPlan(m_thread, this);
+  if (lang_runtime_plan_sp.get()) {
+    UnwindLogMsg("This is an async frame");
+  }
+
   addr_t pc;
   if (!ReadGPRValue(eRegisterKindGeneric, LLDB_REGNUM_GENERIC_PC, pc)) {
     UnwindLogMsg("could not get pc value");
     m_frame_type = eNotAValidFrame;
     return;
   }
 
-  ExecutionContext exe_ctx(m_thread.shared_from_this());
-  Process *process = exe_ctx.GetProcessPtr();
   // Let ABIs fixup code addresses to make sure they are valid. In ARM ABIs
   // this will strip bit zero in case we read a PC from memory or from the LR.
   ABI *abi = process->GetABI().get();
   if (abi)
     pc = abi->FixCodeAddress(pc);
 
   if (log) {
     UnwindLogMsg("pc = 0x%" PRIx64, pc);
void RegisterContextUnwind::InitializeNonZerothFrame() {
   } else {
     // FIXME:  Detect eDebuggerFrame here.
     if (m_frame_type != eSkipFrame) // don't override eSkipFrame
     {
       m_frame_type = eNormalFrame;
     }
   }
 
-  // We've set m_frame_type and m_sym_ctx before this call.
-  m_fast_unwind_plan_sp = GetFastUnwindPlanForFrame();
-
   UnwindPlan::RowSP active_row;
   RegisterKind row_register_kind = eRegisterKindGeneric;
 
+  // If we have LanguageRuntime UnwindPlan for this unwind, use those
+  // rules to find the caller frame instead of the function's normal
+  // UnwindPlans.  The full unwind plan for this frame will be
+  // the LanguageRuntime-provided unwind plan, and there will not be a
+  // fast unwind plan.
+  if (lang_runtime_plan_sp.get()) {
+    active_row =
+        lang_runtime_plan_sp->GetRowForFunctionOffset(m_current_offset);
+    row_register_kind = lang_runtime_plan_sp->GetRegisterKind();
+    if (!ReadFrameAddress(row_register_kind, active_row->GetCFAValue(),
+                          m_cfa)) {
+      UnwindLogMsg("Cannot set cfa");
+    } else {
+      m_full_unwind_plan_sp = lang_runtime_plan_sp;
+      if (log) {
+        StreamString active_row_strm;
+        active_row->Dump(active_row_strm, lang_runtime_plan_sp.get(), &m_thread,
+                         m_start_pc.GetLoadAddress(exe_ctx.GetTargetPtr()));
+        UnwindLogMsg("async active row: %s", active_row_strm.GetData());
+      }
+      UnwindLogMsg("m_cfa = 0x%" PRIx64 " m_afa = 0x%" PRIx64, m_cfa, m_afa);
+      UnwindLogMsg(
+          "initialized async frame current pc is 0x%" PRIx64
+          " cfa is 0x%" PRIx64 " afa is 0x%" PRIx64,
+          (uint64_t)m_current_pc.GetLoadAddress(exe_ctx.GetTargetPtr()),
+          (uint64_t)m_cfa, (uint64_t)m_afa);
+
+      return;
+    }
+  }
+
+  // We've set m_frame_type and m_sym_ctx before this call.
+  m_fast_unwind_plan_sp = GetFastUnwindPlanForFrame();
+
   // Try to get by with just the fast UnwindPlan if possible - the full
   // UnwindPlan may be expensive to get (e.g. if we have to parse the entire
   // eh_frame section of an ObjectFile for the first time.)
 
   if (m_fast_unwind_plan_sp &&
       m_fast_unwind_plan_sp->PlanValidAtAddress(m_current_pc)) {
     active_row =
         m_fast_unwind_plan_sp->GetRowForFunctionOffset(m_current_offset);