From df8d9ee8ab8a811ebbda42ddad54d2e0c059f409 Mon Sep 17 00:00:00 2001 From: Med Ismail Bennani Date: Thu, 6 Nov 2025 11:30:58 -0800 Subject: [PATCH] [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 --- lldb/include/lldb/Core/PluginManager.h | 18 ++ .../lldb/Target/SyntheticFrameProvider.h | 156 ++++++++++++++++++ lldb/include/lldb/lldb-forward.h | 3 + lldb/include/lldb/lldb-private-interfaces.h | 9 + lldb/source/Core/PluginManager.cpp | 55 ++++++ lldb/source/Target/CMakeLists.txt | 1 + lldb/source/Target/SyntheticFrameProvider.cpp | 100 +++++++++++ 7 files changed, 342 insertions(+) create mode 100644 lldb/include/lldb/Target/SyntheticFrameProvider.h create mode 100644 lldb/source/Target/SyntheticFrameProvider.cpp diff --git a/lldb/include/lldb/Core/PluginManager.h b/lldb/include/lldb/Core/PluginManager.h index aa60b7c6693ca..ab2ca58a88ddd 100644 --- a/lldb/include/lldb/Core/PluginManager.h +++ b/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 diff --git a/lldb/include/lldb/Target/SyntheticFrameProvider.h b/lldb/include/lldb/Target/SyntheticFrameProvider.h new file mode 100644 index 0000000000000..61a492f356ece --- /dev/null +++ b/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 +#include + +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 thread_specs; + + SyntheticFrameProviderDescriptor() = default; + + SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp) + : scripted_metadata_sp(metadata_sp) {} + + SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp, + const std::vector &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 + 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 + CreateInstance(lldb::StackFrameListSP input_frames, + llvm::StringRef plugin_name, + const std::vector &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 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 diff --git a/lldb/include/lldb/lldb-forward.h b/lldb/include/lldb/lldb-forward.h index af5656b3dcad1..7af7cd8947531 100644 --- a/lldb/include/lldb/lldb-forward.h +++ b/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 typedef std::shared_ptr ScriptInterpreterSP; typedef std::shared_ptr ScriptedFrameInterfaceSP; +typedef std::shared_ptr + SyntheticFrameProviderSP; typedef std::shared_ptr ScriptedMetadataSP; typedef std::unique_ptr ScriptedPlatformInterfaceUP; diff --git a/lldb/include/lldb/lldb-private-interfaces.h b/lldb/include/lldb/lldb-private-interfaces.h index 249b25c251ac2..2fe3af7c62e00 100644 --- a/lldb/include/lldb/lldb-private-interfaces.h +++ b/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 (*ArchitectureCreateInstance)( @@ -86,6 +87,14 @@ typedef lldb::RegisterTypeBuilderSP (*RegisterTypeBuilderCreateInstance)( Target &target); typedef lldb::ScriptInterpreterSP (*ScriptInterpreterCreateInstance)( Debugger &debugger); +typedef llvm::Expected ( + *ScriptedFrameProviderCreateInstance)( + lldb::StackFrameListSP input_frames, + const lldb_private::SyntheticFrameProviderDescriptor &descriptor); +typedef llvm::Expected ( + *SyntheticFrameProviderCreateInstance)( + lldb::StackFrameListSP input_frames, + const std::vector &thread_specs); typedef SymbolFile *(*SymbolFileCreateInstance)(lldb::ObjectFileSP objfile_sp); typedef SymbolVendor *(*SymbolVendorCreateInstance)( const lldb::ModuleSP &module_sp, diff --git a/lldb/source/Core/PluginManager.cpp b/lldb/source/Core/PluginManager.cpp index 588736715f817..4e3563cf419fe 100644 --- a/lldb/source/Core/PluginManager.cpp +++ b/lldb/source/Core/PluginManager.cpp @@ -1300,6 +1300,61 @@ PluginManager::GetScriptInterpreterForLanguage(lldb::ScriptLanguage script_lang, return none_instance(debugger); } +#pragma mark SyntheticFrameProvider + +typedef PluginInstance + SyntheticFrameProviderInstance; +typedef PluginInstance + ScriptedFrameProviderInstance; +typedef PluginInstances + SyntheticFrameProviderInstances; +typedef PluginInstances + 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 diff --git a/lldb/source/Target/CMakeLists.txt b/lldb/source/Target/CMakeLists.txt index 8e6d51efad1f3..cff59049cdce5 100644 --- a/lldb/source/Target/CMakeLists.txt +++ b/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 diff --git a/lldb/source/Target/SyntheticFrameProvider.cpp b/lldb/source/Target/SyntheticFrameProvider.cpp new file mode 100644 index 0000000000000..241ce82c39be3 --- /dev/null +++ b/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 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 SyntheticFrameProvider::CreateInstance( + StackFrameListSP input_frames, llvm::StringRef plugin_name, + const std::vector &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()); +}