[lldb/Target] Add SyntheticFrameProvider class

lldb/include/lldb/Core/PluginManager.h

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

lldb/include/lldb/Target/SyntheticFrameProvider.h

@@ -0,0 +1,156 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 {
+
+/// 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 for script-based providers.
+  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);
+
+  /// Try to create a SyntheticFrameProvider instance for the given input
+  /// frames using a specific C++ plugin.
+  ///
+  /// This method directly invokes a specific SyntheticFrameProvider plugin
+  /// by name, bypassing the descriptor-based plugin iteration. This is useful
+  /// for C++ plugins that don't require scripted metadata.
+  ///
+  /// \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] plugin_name
+  ///     The name of the plugin to use for creating the provider.
+  ///
+  /// \param[in] thread_specs
+  ///     Optional list of thread specifications to which this provider applies.
+  ///     If empty, the provider applies to all threads.
+  ///
+  /// \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,
+                 llvm::StringRef plugin_name,
+                 const std::vector<ThreadSpec> &thread_specs = {});
+
+  ~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

@@ -235,6 +235,7 @@ class SymbolVendor;
 class Symtab;
 class SyntheticChildren;
 class SyntheticChildrenFrontEnd;
+class SyntheticFrameProvider;
 class SystemRuntime;
 class Progress;
 class Target;
@@ -411,6 +412,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,14 @@ typedef lldb::RegisterTypeBuilderSP (*RegisterTypeBuilderCreateInstance)(
     Target &target);
 typedef lldb::ScriptInterpreterSP (*ScriptInterpreterCreateInstance)(
     Debugger &debugger);
+typedef llvm::Expected<lldb::SyntheticFrameProviderSP> (
+    *ScriptedFrameProviderCreateInstance)(
+    lldb::StackFrameListSP input_frames,
+    const lldb_private::SyntheticFrameProviderDescriptor &descriptor);
+typedef llvm::Expected<lldb::SyntheticFrameProviderSP> (
+    *SyntheticFrameProviderCreateInstance)(
+    lldb::StackFrameListSP input_frames,
+    const std::vector<lldb_private::ThreadSpec> &thread_specs);
 typedef SymbolFile *(*SymbolFileCreateInstance)(lldb::ObjectFileSP objfile_sp);
 typedef SymbolVendor *(*SymbolVendorCreateInstance)(
     const lldb::ModuleSP &module_sp,

lldb/source/Core/PluginManager.cpp

@@ -1300,6 +1300,61 @@ PluginManager::GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang,
   return none_instance(debugger);
 }
 
+#pragma mark SyntheticFrameProvider
+
+typedef PluginInstance<SyntheticFrameProviderCreateInstance>
+    SyntheticFrameProviderInstance;
+typedef PluginInstance<ScriptedFrameProviderCreateInstance>
+    ScriptedFrameProviderInstance;
+typedef PluginInstances<SyntheticFrameProviderInstance>
+    SyntheticFrameProviderInstances;
+typedef PluginInstances<ScriptedFrameProviderInstance>
+    ScriptedFrameProviderInstances;
+
+static SyntheticFrameProviderInstances &GetSyntheticFrameProviderInstances() {
+  static SyntheticFrameProviderInstances g_instances;
+  return g_instances;
+}
+
+static ScriptedFrameProviderInstances &GetScriptedFrameProviderInstances() {
+  static ScriptedFrameProviderInstances g_instances;
+  return g_instances;
+}
+
+bool PluginManager::RegisterPlugin(
+    llvm::StringRef name, llvm::StringRef description,
+    SyntheticFrameProviderCreateInstance create_native_callback,
+    ScriptedFrameProviderCreateInstance create_scripted_callback) {
+  if (create_native_callback)
+    return GetSyntheticFrameProviderInstances().RegisterPlugin(
+        name, description, create_native_callback);
+  else if (create_scripted_callback)
+    return GetScriptedFrameProviderInstances().RegisterPlugin(
+        name, description, create_scripted_callback);
+  return false;
+}
+
+bool PluginManager::UnregisterPlugin(
+    SyntheticFrameProviderCreateInstance create_callback) {
+  return GetSyntheticFrameProviderInstances().UnregisterPlugin(create_callback);
+}
+
+bool PluginManager::UnregisterPlugin(
+    ScriptedFrameProviderCreateInstance create_callback) {
+  return GetScriptedFrameProviderInstances().UnregisterPlugin(create_callback);
+}
+
+SyntheticFrameProviderCreateInstance
+PluginManager::GetSyntheticFrameProviderCreateCallbackForPluginName(
+    llvm::StringRef name) {
+  return GetSyntheticFrameProviderInstances().GetCallbackForName(name);
+}
+
+ScriptedFrameProviderCreateInstance
+PluginManager::GetScriptedFrameProviderCreateCallbackAtIndex(uint32_t idx) {
+  return GetScriptedFrameProviderInstances().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,100 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 ScriptedFrameProvider plugins.
+  ScriptedFrameProviderCreateInstance create_callback = nullptr;
+  for (uint32_t idx = 0;
+       (create_callback =
+            PluginManager::GetScriptedFrameProviderCreateCallbackAtIndex(
+                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");
+}
+
+llvm::Expected<SyntheticFrameProviderSP> SyntheticFrameProvider::CreateInstance(
+    StackFrameListSP input_frames, llvm::StringRef plugin_name,
+    const std::vector<ThreadSpec> &thread_specs) {
+  if (!input_frames)
+    return llvm::createStringError(
+        "cannot create synthetic frame provider: invalid input frames");
+
+  // Look up the specific C++ plugin by name.
+  SyntheticFrameProviderCreateInstance create_callback =
+      PluginManager::GetSyntheticFrameProviderCreateCallbackForPluginName(
+          plugin_name);
+
+  if (!create_callback)
+    return llvm::createStringError(
+        "cannot create synthetic frame provider: C++ plugin '%s' not found",
+        plugin_name.str().c_str());
+
+  auto provider_or_err = create_callback(input_frames, thread_specs);
+  if (!provider_or_err)
+    return provider_or_err.takeError();
+
+  if (auto frame_provider_sp = std::move(*provider_or_err))
+    return std::move(frame_provider_sp);
+
+  return llvm::createStringError(
+      "cannot create synthetic frame provider: C++ plugin '%s' returned null",
+      plugin_name.str().c_str());
+}