[lldb] Extend frame recognizers to hide frames from backtraces

Compilers and language runtimes often use helper functions that are
fundamentally uninteresting when debugging anything but the
compiler/runtime itself. This patch introduces a user-extensible
mechanism that allows for these frames to be hidden from backtraces
and automatically skipped over when navigating the stack with `up` and
`down`, and when stepping out of the current frame.

This does not affect the numbering of frames, so `f <N>` will still
provide access to the hidden frames. The `bt` output will also print a
hint that frames have been hidden.

My primary motivation for this feature is to hide thunks in the Swift
programming language, but I'm including an example recognizer for
`std::function::operator()` that I wished for myself many times while
debugging LLDB.

The functionality is user-extensible via Python recognizers and
exposed through the SBAPI via SBFrame::IsHidden().

rdar://126629381

Author: adrian-prantl

lldb/bindings/python/python-wrapper.swig

@@ -813,7 +813,7 @@ PythonObject lldb_private::python::SWIGBridge::LLDBSWIGPython_CreateFrameRecogni
 }
 
 PyObject *lldb_private::python::SWIGBridge::LLDBSwigPython_GetRecognizedArguments(
-    PyObject * implementor, const lldb::StackFrameSP &frame_sp) {
+    PyObject *implementor, const lldb::StackFrameSP &frame_sp) {
   static char callee_name[] = "get_recognized_arguments";
 
   PythonObject arg = SWIGBridge::ToSWIGWrapper(frame_sp);
@@ -824,6 +824,22 @@ PyObject *lldb_private::python::SWIGBridge::LLDBSwigPython_GetRecognizedArgument
   return result;
 }
 
+bool lldb_private::python::SWIGBridge::LLDBSwigPython_ShouldHide(
+    PyObject *implementor, const lldb::StackFrameSP &frame_sp) {
+  static char callee_name[] = "should_hide";
+
+  PythonObject arg = SWIGBridge::ToSWIGWrapper(frame_sp);
+
+  PythonString str(callee_name);
+
+  PyObject *result =
+      PyObject_CallMethodObjArgs(implementor, str.get(), arg.get(), NULL);
+  bool ret_val = result ? PyObject_IsTrue(result) : false;
+  Py_XDECREF(result);
+
+  return result;
+}
+
 void *lldb_private::python::SWIGBridge::LLDBSWIGPython_GetDynamicSetting(
     void *module, const char *setting, const lldb::TargetSP &target_sp) {
   if (!module || !setting)

lldb/include/lldb/API/SBFrame.h

@@ -104,6 +104,10 @@ class LLDB_API SBFrame {
 
   bool IsArtificial() const;
 
+  /// Return whether a frame recognizer decided this frame should not
+  /// be displayes in backtraces etc.
+  bool IsHidden() const;
+
   /// The version that doesn't supply a 'use_dynamic' value will use the
   /// target's default.
   lldb::SBValue EvaluateExpression(const char *expr);

lldb/include/lldb/Interpreter/ScriptInterpreter.h

@@ -252,6 +252,11 @@ class ScriptInterpreter : public PluginInterface {
     return lldb::ValueObjectListSP();
   }
 
+  virtual bool ShouldHide(const StructuredData::ObjectSP &implementor,
+                          lldb::StackFrameSP frame_sp) {
+    return false;
+  }
+
   virtual StructuredData::GenericSP
   CreateScriptedBreakpointResolver(const char *class_name,
                                    const StructuredDataImpl &args_data,

lldb/include/lldb/Target/StackFrame.h

@@ -407,6 +407,11 @@ class StackFrame : public ExecutionContextScope,
   /// may have limited support for inspecting variables.
   bool IsArtificial() const;
 
+  /// Query whether this frame should be hidden from backtraces. Frame
+  /// recognizers can customize this behavior and hide distracting
+  /// system implementation details this way.
+  bool IsHidden();
+
   /// Query this frame to find what frame it is in this Thread's
   /// StackFrameList.
   ///
@@ -518,33 +523,33 @@ class StackFrame : public ExecutionContextScope,
   bool HasCachedData() const;
 
 private:
-  // For StackFrame only
+  /// For StackFrame only.
   lldb::ThreadWP m_thread_wp;
   uint32_t m_frame_index;
   uint32_t m_concrete_frame_index;
   lldb::RegisterContextSP m_reg_context_sp;
   StackID m_id;
-  Address m_frame_code_addr; // The frame code address (might not be the same as
-                             // the actual PC for inlined frames) as a
-                             // section/offset address
+  /// The frame code address (might not be the same as the actual PC
+  /// for inlined frames) as a section/offset address.
+  Address m_frame_code_addr;
   SymbolContext m_sc;
   Flags m_flags;
   Scalar m_frame_base;
   Status m_frame_base_error;
-  bool m_cfa_is_valid; // Does this frame have a CFA?  Different from CFA ==
-                       // LLDB_INVALID_ADDRESS
+  uint16_t m_frame_recognizer_generation;
+  /// Does this frame have a CFA?  Different from CFA == LLDB_INVALID_ADDRESS.
+  bool m_cfa_is_valid;
   Kind m_stack_frame_kind;
 
-  // Whether this frame behaves like the zeroth frame, in the sense
-  // that its pc value might not immediately follow a call (and thus might
-  // be the first address of its function). True for actual frame zero as
-  // well as any other frame with the same trait.
+  /// Whether this frame behaves like the zeroth frame, in the sense
+  /// that its pc value might not immediately follow a call (and thus might
+  /// be the first address of its function). True for actual frame zero as
+  /// well as any other frame with the same trait.
   bool m_behaves_like_zeroth_frame;
   lldb::VariableListSP m_variable_list_sp;
-  ValueObjectList m_variable_list_value_objects; // Value objects for each
-                                                 // variable in
-                                                 // m_variable_list_sp
-  lldb::RecognizedStackFrameSP m_recognized_frame_sp;
+  /// Value objects for each variable in m_variable_list_sp.
+  ValueObjectList m_variable_list_value_objects;
+  std::optional<lldb::RecognizedStackFrameSP> m_recognized_frame_sp;
   StreamString m_disassembly;
   std::recursive_mutex m_mutex;
 

lldb/include/lldb/Target/StackFrameList.h

@@ -91,7 +91,7 @@ class StackFrameList {
 
   size_t GetStatus(Stream &strm, uint32_t first_frame, uint32_t num_frames,
                    bool show_frame_info, uint32_t num_frames_with_source,
-                   bool show_unique = false,
+                   bool show_unique = false, bool should_filter = true,
                    const char *frame_marker = nullptr);
 
 protected:

lldb/include/lldb/Target/StackFrameRecognizer.h

@@ -17,6 +17,7 @@
 #include "lldb/lldb-private-forward.h"
 #include "lldb/lldb-public.h"
 
+#include <_types/_uint16_t.h>
 #include <deque>
 #include <optional>
 #include <vector>
@@ -28,20 +29,23 @@ namespace lldb_private {
 /// This class provides extra information about a stack frame that was
 /// provided by a specific stack frame recognizer. Right now, this class only
 /// holds recognized arguments (via GetRecognizedArguments).
-
 class RecognizedStackFrame
     : public std::enable_shared_from_this<RecognizedStackFrame> {
 public:
+  virtual ~RecognizedStackFrame() = default;
+
   virtual lldb::ValueObjectListSP GetRecognizedArguments() {
     return m_arguments;
   }
   virtual lldb::ValueObjectSP GetExceptionObject() {
     return lldb::ValueObjectSP();
   }
-  virtual lldb::StackFrameSP GetMostRelevantFrame() { return nullptr; };
-  virtual ~RecognizedStackFrame() = default;
+  virtual lldb::StackFrameSP GetMostRelevantFrame() { return nullptr; }
 
   std::string GetStopDescription() { return m_stop_desc; }
+  /// Controls whether this frame should be filtered out when
+  /// displaying backtraces, for example.
+  virtual bool ShouldHide() { return false; }
 
 protected:
   lldb::ValueObjectListSP m_arguments;
@@ -53,7 +57,6 @@ class RecognizedStackFrame
 /// A base class for frame recognizers. Subclasses (actual frame recognizers)
 /// should implement RecognizeFrame to provide a RecognizedStackFrame for a
 /// given stack frame.
-
 class StackFrameRecognizer
     : public std::enable_shared_from_this<StackFrameRecognizer> {
 public:
@@ -73,10 +76,10 @@ class StackFrameRecognizer
 /// Python implementation for frame recognizers. An instance of this class
 /// tracks a particular Python classobject, which will be asked to recognize
 /// stack frames.
-
 class ScriptedStackFrameRecognizer : public StackFrameRecognizer {
   lldb_private::ScriptInterpreter *m_interpreter;
   lldb_private::StructuredData::ObjectSP m_python_object_sp;
+
   std::string m_python_class;
 
 public:
@@ -123,8 +126,13 @@ class StackFrameRecognizerManager {
   lldb::StackFrameRecognizerSP GetRecognizerForFrame(lldb::StackFrameSP frame);
 
   lldb::RecognizedStackFrameSP RecognizeFrame(lldb::StackFrameSP frame);
+  /// This number changes whenever the list of recognizers has been modified.
+  uint16_t GetGeneration() const { return m_generation; }
 
 private:
+  /// Increase the generation counter.
+  void BumpGeneration();
+
   struct RegisteredEntry {
     uint32_t recognizer_id;
     lldb::StackFrameRecognizerSP recognizer;
@@ -137,14 +145,14 @@ class StackFrameRecognizerManager {
   };
 
   std::deque<RegisteredEntry> m_recognizers;
+  uint16_t m_generation;
 };
 
 /// \class ValueObjectRecognizerSynthesizedValue
 ///
 /// ValueObject subclass that presents the passed ValueObject as a recognized
 /// value with the specified ValueType. Frame recognizers should return
 /// instances of this class as the returned objects in GetRecognizedArguments().
-
 class ValueObjectRecognizerSynthesizedValue : public ValueObject {
  public:
   static lldb::ValueObjectSP Create(ValueObject &parent, lldb::ValueType type) {

lldb/include/lldb/Target/Thread.h

@@ -1128,11 +1128,12 @@ class Thread : public std::enable_shared_from_this<Thread>,
 
   size_t GetStatus(Stream &strm, uint32_t start_frame, uint32_t num_frames,
                    uint32_t num_frames_with_source, bool stop_format,
-                   bool only_stacks = false);
+                   bool should_filter, bool only_stacks = false);
 
   size_t GetStackFrameStatus(Stream &strm, uint32_t first_frame,
                              uint32_t num_frames, bool show_frame_info,
-                             uint32_t num_frames_with_source);
+                             uint32_t num_frames_with_source,
+                             bool should_filter);
 
   // We need a way to verify that even though we have a thread in a shared
   // pointer that the object itself is still valid. Currently this won't be the

lldb/source/API/SBFrame.cpp

@@ -1202,6 +1202,19 @@ bool SBFrame::IsArtificial() const {
   return false;
 }
 
+bool SBFrame::IsHidden() const {
+  LLDB_INSTRUMENT_VA(this);
+
+  std::unique_lock<std::recursive_mutex> lock;
+  ExecutionContext exe_ctx(m_opaque_sp.get(), lock);
+
+  StackFrame *frame = exe_ctx.GetFramePtr();
+  if (frame)
+    return frame->IsHidden();
+
+  return false;
+}
+
 const char *SBFrame::GetFunctionName() {
   LLDB_INSTRUMENT_VA(this);
 

lldb/source/API/SBThread.cpp

@@ -1208,7 +1208,8 @@ bool SBThread::GetStatus(SBStream &status) const {
   ExecutionContext exe_ctx(m_opaque_sp.get(), lock);
 
   if (exe_ctx.HasThreadScope()) {
-    exe_ctx.GetThreadPtr()->GetStatus(strm, 0, 1, 1, true);
+    exe_ctx.GetThreadPtr()->GetStatus(strm, 0, 1, 1, true,
+                                      /*should_filter*/ false);
   } else
     strm.PutCString("No status");
 

lldb/source/Commands/CommandCompletions.cpp

@@ -791,7 +791,7 @@ void CommandCompletions::ThreadIndexes(CommandInterpreter &interpreter,
   lldb::ThreadSP thread_sp;
   for (uint32_t idx = 0; (thread_sp = threads.GetThreadAtIndex(idx)); ++idx) {
     StreamString strm;
-    thread_sp->GetStatus(strm, 0, 1, 1, true);
+    thread_sp->GetStatus(strm, 0, 1, 1, true, /*should_filter*/ false);
     request.TryCompleteCurrentArg(std::to_string(thread_sp->GetIndexID()),
                                   strm.GetString());
   }
@@ -835,7 +835,7 @@ void CommandCompletions::ThreadIDs(CommandInterpreter &interpreter,
   lldb::ThreadSP thread_sp;
   for (uint32_t idx = 0; (thread_sp = threads.GetThreadAtIndex(idx)); ++idx) {
     StreamString strm;
-    thread_sp->GetStatus(strm, 0, 1, 1, true);
+    thread_sp->GetStatus(strm, 0, 1, 1, true, /*should_filter*/ false);
     request.TryCompleteCurrentArg(std::to_string(thread_sp->GetID()),
                                   strm.GetString());
   }