[lldb/Target] Add SyntheticFrameProvider class

This patch introduces a new way to reconstruct the thread stackframe
list.

New SyntheticFrameProvider classes can lazy fetch a StackFrame at
index using a provided StackFrameList.

In can either be the real unwinder StackFrameList or we could also chain
SyntheticFrameProviders to each others.

This is the foundation work to implement ScriptedFrameProviders, which
will come in a follow-up patch.

Signed-off-by: Med Ismail Bennani <[email protected]>

Author: medismailben

lldb/include/lldb/Core/PluginManager.h

@@ -356,6 +356,17 @@ class PluginManager {
   GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang,
                                   Debugger &debugger);
 
+  // SyntheticFrameProvider
+  static bool
+  RegisterPlugin(llvm::StringRef name, llvm::StringRef description,
+                 SyntheticFrameProviderCreateInstance create_callback);
+
+  static bool
+  UnregisterPlugin(SyntheticFrameProviderCreateInstance create_callback);
+
+  static SyntheticFrameProviderCreateInstance
+  GetSyntheticFrameProviderCreateCallbackAtIndex(uint32_t idx);
+
   // StructuredDataPlugin
 
   /// Register a StructuredDataPlugin class along with optional

lldb/include/lldb/Target/SyntheticFrameProvider.h

@@ -0,0 +1,133 @@
+
+//===------------------------------------------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H
+#define LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H
+
+#include "lldb/Core/PluginInterface.h"
+#include "lldb/Target/StackFrameList.h"
+#include "lldb/Target/ThreadSpec.h"
+#include "lldb/Utility/ScriptedMetadata.h"
+#include "lldb/Utility/Status.h"
+#include "lldb/lldb-forward.h"
+#include "llvm/Support/Error.h"
+
+#include <optional>
+#include <vector>
+
+namespace lldb_private {
+
+/// Descriptor for configuring a synthetic frame provider.
+///
+/// This struct contains the metadata needed to instantiate a frame provider
+/// and optional filters to control which threads it applies to.
+struct SyntheticFrameProviderDescriptor {
+  /// Metadata for instantiating the provider (e.g., script class name and args)
+  lldb::ScriptedMetadataSP scripted_metadata_sp;
+
+  /// Optional list of thread specifications to which this provider applies.
+  /// If empty, the provider applies to all threads. A thread matches if it
+  /// satisfies ANY of the specs in this vector (OR logic).
+  std::vector<ThreadSpec> thread_specs;
+
+  SyntheticFrameProviderDescriptor() = default;
+
+  SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp)
+      : scripted_metadata_sp(metadata_sp) {}
+
+  SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp,
+                                   const std::vector<ThreadSpec> &specs)
+      : scripted_metadata_sp(metadata_sp), thread_specs(specs) {}
+
+  /// Get the name of this descriptor (the scripted class name).
+  llvm::StringRef GetName() const {
+    return scripted_metadata_sp ? scripted_metadata_sp->GetClassName() : "";
+  }
+
+  /// Check if this descriptor applies to the given thread.
+  bool AppliesToThread(Thread &thread) const {
+    // If no thread specs specified, applies to all threads
+    if (thread_specs.empty())
+      return true;
+
+    // Check if the thread matches any of the specs (OR logic)
+    for (const auto &spec : thread_specs) {
+      if (spec.ThreadPassesBasicTests(thread))
+        return true;
+    }
+    return false;
+  }
+
+  /// Check if this descriptor has valid metadata.
+  bool IsValid() const { return scripted_metadata_sp != nullptr; }
+
+  void Dump(Stream *s) const;
+};
+
+/// Base class for all synthetic frame providers.
+///
+/// Synthetic frame providers allow modifying or replacing the stack frames
+/// shown for a thread. This is useful for:
+/// - Providing frames for custom calling conventions or languages
+/// - Reconstructing missing frames from crash dumps or core files
+/// - Adding diagnostic or synthetic frames for debugging
+/// - Visualizing state machines or async execution contexts
+class SyntheticFrameProvider : public PluginInterface {
+public:
+  /// Try to create a SyntheticFrameProvider instance for the given input
+  /// frames and descriptor.
+  ///
+  /// This method iterates through all registered SyntheticFrameProvider
+  /// plugins and returns the first one that can handle the given descriptor.
+  ///
+  /// \param[in] input_frames
+  ///     The input stack frame list that this provider will transform.
+  ///     This could be real unwound frames or output from another provider.
+  ///
+  /// \param[in] descriptor
+  ///     The descriptor containing metadata for the provider.
+  ///
+  /// \return
+  ///     A shared pointer to a SyntheticFrameProvider if one could be created,
+  ///     otherwise an \a llvm::Error.
+  static llvm::Expected<lldb::SyntheticFrameProviderSP>
+  CreateInstance(lldb::StackFrameListSP input_frames,
+                 const SyntheticFrameProviderDescriptor &descriptor);
+
+  ~SyntheticFrameProvider() override;
+
+  /// Get a single stack frame at the specified index.
+  ///
+  /// This method is called lazily - frames are only created when requested.
+  /// The provider can access its input frames via GetInputFrames() if needed.
+  ///
+  /// \param[in] idx
+  ///     The index of the frame to create.
+  ///
+  /// \return
+  ///     An Expected containing the StackFrameSP if successful. Returns an
+  ///     error when the index is beyond the last frame to signal the end of
+  ///     the frame list.
+  virtual llvm::Expected<lldb::StackFrameSP> GetFrameAtIndex(uint32_t idx) = 0;
+
+  /// Get the thread associated with this provider.
+  Thread &GetThread() { return m_input_frames->GetThread(); }
+
+  /// Get the input frames that this provider transforms.
+  lldb::StackFrameListSP GetInputFrames() const { return m_input_frames; }
+
+protected:
+  SyntheticFrameProvider(lldb::StackFrameListSP input_frames);
+
+  lldb::StackFrameListSP m_input_frames;
+};
+
+} // namespace lldb_private
+
+#endif // LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H

lldb/include/lldb/lldb-forward.h

@@ -411,6 +411,8 @@ typedef std::shared_ptr<lldb_private::ScriptSummaryFormat>
 typedef std::shared_ptr<lldb_private::ScriptInterpreter> ScriptInterpreterSP;
 typedef std::shared_ptr<lldb_private::ScriptedFrameInterface>
     ScriptedFrameInterfaceSP;
+typedef std::shared_ptr<lldb_private::SyntheticFrameProvider>
+    SyntheticFrameProviderSP;
 typedef std::shared_ptr<lldb_private::ScriptedMetadata> ScriptedMetadataSP;
 typedef std::unique_ptr<lldb_private::ScriptedPlatformInterface>
     ScriptedPlatformInterfaceUP;

lldb/include/lldb/lldb-private-interfaces.h

@@ -25,6 +25,7 @@ class Value;
 
 namespace lldb_private {
 class ScriptedInterfaceUsages;
+struct SyntheticFrameProviderDescriptor;
 typedef lldb::ABISP (*ABICreateInstance)(lldb::ProcessSP process_sp,
                                          const ArchSpec &arch);
 typedef std::unique_ptr<Architecture> (*ArchitectureCreateInstance)(
@@ -86,6 +87,10 @@ typedef lldb::RegisterTypeBuilderSP (*RegisterTypeBuilderCreateInstance)(
     Target &target);
 typedef lldb::ScriptInterpreterSP (*ScriptInterpreterCreateInstance)(
     Debugger &debugger);
+typedef llvm::Expected<lldb::SyntheticFrameProviderSP> (
+    *SyntheticFrameProviderCreateInstance)(
+    lldb::StackFrameListSP input_frames,
+    const lldb_private::SyntheticFrameProviderDescriptor &descriptor);
 typedef SymbolFile *(*SymbolFileCreateInstance)(lldb::ObjectFileSP objfile_sp);
 typedef SymbolVendor *(*SymbolVendorCreateInstance)(
     const lldb::ModuleSP &module_sp,

lldb/source/Core/PluginManager.cpp

@@ -1300,6 +1300,35 @@ PluginManager::GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang,
   return none_instance(debugger);
 }
 
+#pragma mark SyntheticFrameProvider
+
+typedef PluginInstance<SyntheticFrameProviderCreateInstance>
+    SyntheticFrameProviderInstance;
+typedef PluginInstances<SyntheticFrameProviderInstance>
+    SyntheticFrameProviderInstances;
+
+static SyntheticFrameProviderInstances &GetSyntheticFrameProviderInstances() {
+  static SyntheticFrameProviderInstances g_instances;
+  return g_instances;
+}
+
+bool PluginManager::RegisterPlugin(
+    llvm::StringRef name, llvm::StringRef description,
+    SyntheticFrameProviderCreateInstance create_callback) {
+  return GetSyntheticFrameProviderInstances().RegisterPlugin(name, description,
+                                                             create_callback);
+}
+
+bool PluginManager::UnregisterPlugin(
+    SyntheticFrameProviderCreateInstance create_callback) {
+  return GetSyntheticFrameProviderInstances().UnregisterPlugin(create_callback);
+}
+
+SyntheticFrameProviderCreateInstance
+PluginManager::GetSyntheticFrameProviderCreateCallbackAtIndex(uint32_t idx) {
+  return GetSyntheticFrameProviderInstances().GetCallbackAtIndex(idx);
+}
+
 #pragma mark StructuredDataPlugin
 
 struct StructuredDataPluginInstance

lldb/source/Target/CMakeLists.txt

@@ -38,6 +38,7 @@ add_lldb_library(lldbTarget
   RegisterNumber.cpp
   RemoteAwarePlatform.cpp
   ScriptedThreadPlan.cpp
+  SyntheticFrameProvider.cpp
   SectionLoadHistory.cpp
   SectionLoadList.cpp
   StackFrame.cpp

lldb/source/Target/SyntheticFrameProvider.cpp

@@ -0,0 +1,71 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "lldb/Target/SyntheticFrameProvider.h"
+#include "lldb/Core/PluginManager.h"
+#include "lldb/Target/Thread.h"
+#include "lldb/Utility/LLDBLog.h"
+#include "lldb/Utility/Log.h"
+#include "lldb/Utility/Status.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+SyntheticFrameProvider::SyntheticFrameProvider(StackFrameListSP input_frames)
+    : m_input_frames(std::move(input_frames)) {}
+
+SyntheticFrameProvider::~SyntheticFrameProvider() = default;
+
+void SyntheticFrameProviderDescriptor::Dump(Stream *s) const {
+  if (!s)
+    return;
+
+  s->Printf("  Name: %s\n", GetName().str().c_str());
+
+  // Show thread filter information
+  if (thread_specs.empty()) {
+    s->PutCString("  Thread Filter: (applies to all threads)\n");
+  } else {
+    s->Printf("  Thread Filter: %zu specification(s)\n", thread_specs.size());
+    for (size_t i = 0; i < thread_specs.size(); ++i) {
+      const ThreadSpec &spec = thread_specs[i];
+      s->Printf("    [%zu] ", i);
+      spec.GetDescription(s, lldb::eDescriptionLevelVerbose);
+      s->PutChar('\n');
+    }
+  }
+}
+
+llvm::Expected<SyntheticFrameProviderSP> SyntheticFrameProvider::CreateInstance(
+    StackFrameListSP input_frames,
+    const SyntheticFrameProviderDescriptor &descriptor) {
+  if (!input_frames)
+    return llvm::createStringError(
+        "cannot create synthetic frame provider: Invalid input frames");
+
+  // Iterate through all registered SyntheticFrameProvider plugins
+  SyntheticFrameProviderCreateInstance create_callback = nullptr;
+  for (uint32_t idx = 0;
+       (create_callback =
+            PluginManager::GetSyntheticFrameProviderCreateCallbackAtIndex(
+                idx)) != nullptr;
+       ++idx) {
+    auto provider_or_err = create_callback(input_frames, descriptor);
+    if (!provider_or_err) {
+      LLDB_LOG_ERROR(GetLog(LLDBLog::Target), provider_or_err.takeError(),
+                     "Failed to create synthetic frame provider: {0}");
+      continue;
+    }
+
+    if (auto frame_provider_up = std::move(*provider_or_err))
+      return std::move(frame_provider_up);
+  }
+
+  return llvm::createStringError(
+      "cannot create synthetic frame provider: No suitable plugin found");
+}