[Lldb-commits] [lldb] [lldb] Introduce ScriptedFrameProvider for real threads (PR #161870)
Med Ismail Bennani via lldb-commits
lldb-commits at lists.llvm.org
Tue Oct 28 02:10:24 PDT 2025
https://github.com/medismailben updated https://github.com/llvm/llvm-project/pull/161870
>From 6d9e67647e1e383b9331c1649de964399f664a92 Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Wed, 8 Oct 2025 14:21:35 +0100
Subject: [PATCH 1/4] [lldb] Introduce SBFrameList for lazy frame iteration
This patch introduces `SBFrameList`, a new SBAPI class that allows
iterating over stack frames lazily without calling
`SBThread::GetFrameAtIndex` in a loop.
The new `SBThread::GetFrames()` method returns an `SBFrameList` that
supports Python iteration (`for frame in frame_list:`), indexing
(`frame_list[0]`, `frame_list[-1]`), and length queries (`len()`).
The implementation uses `StackFrameListSP` as the opaque pointer,
sharing the thread's underlying frame list to ensure frames are
materialized on-demand.
This is particularly useful for ScriptedFrameProviders, where user
scripts can now iterate, filter, and replace frames lazily without
materializing the entire stack upfront.
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
.../interface/SBFrameListDocstrings.i | 13 ++
.../interface/SBFrameListExtensions.i | 46 +++++
lldb/bindings/interface/SBThreadExtensions.i | 3 +-
lldb/bindings/interfaces.swig | 3 +
lldb/include/lldb/API/LLDB.h | 1 +
lldb/include/lldb/API/SBDefines.h | 1 +
lldb/include/lldb/API/SBFrame.h | 1 +
lldb/include/lldb/API/SBFrameList.h | 55 ++++++
lldb/include/lldb/API/SBStream.h | 1 +
lldb/include/lldb/API/SBThread.h | 2 +
lldb/include/lldb/Target/Thread.h | 12 ++
lldb/source/API/CMakeLists.txt | 1 +
lldb/source/API/SBFrameList.cpp | 101 ++++++++++
lldb/source/API/SBThread.cpp | 21 +++
lldb/test/API/python_api/frame_list/Makefile | 3 +
.../python_api/frame_list/TestSBFrameList.py | 172 ++++++++++++++++++
lldb/test/API/python_api/frame_list/main.cpp | 22 +++
17 files changed, 457 insertions(+), 1 deletion(-)
create mode 100644 lldb/bindings/interface/SBFrameListDocstrings.i
create mode 100644 lldb/bindings/interface/SBFrameListExtensions.i
create mode 100644 lldb/include/lldb/API/SBFrameList.h
create mode 100644 lldb/source/API/SBFrameList.cpp
create mode 100644 lldb/test/API/python_api/frame_list/Makefile
create mode 100644 lldb/test/API/python_api/frame_list/TestSBFrameList.py
create mode 100644 lldb/test/API/python_api/frame_list/main.cpp
diff --git a/lldb/bindings/interface/SBFrameListDocstrings.i b/lldb/bindings/interface/SBFrameListDocstrings.i
new file mode 100644
index 0000000000000..2ca10b3b4c72b
--- /dev/null
+++ b/lldb/bindings/interface/SBFrameListDocstrings.i
@@ -0,0 +1,13 @@
+%feature("docstring",
+"Represents a list of :py:class:`SBFrame` objects."
+) lldb::SBFrameList;
+
+%feature("autodoc", "GetSize(SBFrameList self) -> uint32_t") lldb::SBFrameList::GetSize;
+%feature("docstring", "
+ Returns the number of frames in the list."
+) lldb::SBFrameList::GetSize;
+
+%feature("autodoc", "GetFrameAtIndex(SBFrameList self, uint32_t idx) -> SBFrame") lldb::SBFrameList::GetFrameAtIndex;
+%feature("docstring", "
+ Returns the frame at the given index."
+) lldb::SBFrameList::GetFrameAtIndex;
\ No newline at end of file
diff --git a/lldb/bindings/interface/SBFrameListExtensions.i b/lldb/bindings/interface/SBFrameListExtensions.i
new file mode 100644
index 0000000000000..6466234577aae
--- /dev/null
+++ b/lldb/bindings/interface/SBFrameListExtensions.i
@@ -0,0 +1,46 @@
+%extend lldb::SBFrameList {
+
+#ifdef SWIGPYTHON
+ %nothreadallow;
+#endif
+ std::string lldb::SBFrameList::__str__ (){
+ lldb::SBStream description;
+ const size_t n = $self->GetSize();
+ if (n)
+ {
+ for (size_t i=0; i<n; ++i)
+ $self->GetFrameAtIndex(i).GetDescription(description);
+ }
+ else
+ {
+ description.Printf("<empty> lldb.SBFrameList()");
+ }
+ const char *desc = description.GetData();
+ size_t desc_len = description.GetSize();
+ if (desc_len > 0 && (desc[desc_len-1] == '\n' || desc[desc_len-1] == '\r'))
+ --desc_len;
+ return std::string(desc, desc_len);
+ }
+#ifdef SWIGPYTHON
+ %clearnothreadallow;
+#endif
+
+#ifdef SWIGPYTHON
+ %pythoncode %{
+ def __iter__(self):
+ '''Iterate over all frames in a lldb.SBFrameList object.'''
+ return lldb_iter(self, 'GetSize', 'GetFrameAtIndex')
+
+ def __len__(self):
+ return int(self.GetSize())
+
+ def __getitem__(self, key):
+ count = len(self)
+ if type(key) is int:
+ if -count <= key < count:
+ key %= count
+ return self.GetFrameAtIndex(key)
+ return None
+ %}
+#endif
+}
\ No newline at end of file
diff --git a/lldb/bindings/interface/SBThreadExtensions.i b/lldb/bindings/interface/SBThreadExtensions.i
index 4ec9f10b1a256..c9ae4103d7b60 100644
--- a/lldb/bindings/interface/SBThreadExtensions.i
+++ b/lldb/bindings/interface/SBThreadExtensions.i
@@ -41,7 +41,8 @@ STRING_EXTENSION_OUTSIDE(SBThread)
def get_thread_frames(self):
'''An accessor function that returns a list() that contains all frames in a lldb.SBThread object.'''
frames = []
- for frame in self:
+ frame_list = self.GetFrames()
+ for frame in frame_list:
frames.append(frame)
return frames
diff --git a/lldb/bindings/interfaces.swig b/lldb/bindings/interfaces.swig
index b3d44979c916c..5fe058e33e619 100644
--- a/lldb/bindings/interfaces.swig
+++ b/lldb/bindings/interfaces.swig
@@ -39,6 +39,7 @@
%include "./interface/SBFileSpecListDocstrings.i"
%include "./interface/SBFormatDocstrings.i"
%include "./interface/SBFrameDocstrings.i"
+%include "./interface/SBFrameListDocstrings.i"
%include "./interface/SBFunctionDocstrings.i"
%include "./interface/SBHostOSDocstrings.i"
%include "./interface/SBInstructionDocstrings.i"
@@ -119,6 +120,7 @@
%include "lldb/API/SBFileSpecList.h"
%include "lldb/API/SBFormat.h"
%include "lldb/API/SBFrame.h"
+%include "lldb/API/SBFrameList.h"
%include "lldb/API/SBFunction.h"
%include "lldb/API/SBHostOS.h"
%include "lldb/API/SBInstruction.h"
@@ -193,6 +195,7 @@
%include "./interface/SBFileSpecExtensions.i"
%include "./interface/SBFileSpecListExtensions.i"
%include "./interface/SBFrameExtensions.i"
+%include "./interface/SBFrameListExtensions.i"
%include "./interface/SBFunctionExtensions.i"
%include "./interface/SBInstructionExtensions.i"
%include "./interface/SBInstructionListExtensions.i"
diff --git a/lldb/include/lldb/API/LLDB.h b/lldb/include/lldb/API/LLDB.h
index 6485f35302a1c..6ac35bb4a364b 100644
--- a/lldb/include/lldb/API/LLDB.h
+++ b/lldb/include/lldb/API/LLDB.h
@@ -37,6 +37,7 @@
#include "lldb/API/SBFileSpecList.h"
#include "lldb/API/SBFormat.h"
#include "lldb/API/SBFrame.h"
+#include "lldb/API/SBFrameList.h"
#include "lldb/API/SBFunction.h"
#include "lldb/API/SBHostOS.h"
#include "lldb/API/SBInstruction.h"
diff --git a/lldb/include/lldb/API/SBDefines.h b/lldb/include/lldb/API/SBDefines.h
index 85f6bbeea5bf9..5fcc685050c0b 100644
--- a/lldb/include/lldb/API/SBDefines.h
+++ b/lldb/include/lldb/API/SBDefines.h
@@ -76,6 +76,7 @@ class LLDB_API SBFileSpec;
class LLDB_API SBFileSpecList;
class LLDB_API SBFormat;
class LLDB_API SBFrame;
+class LLDB_API SBFrameList;
class LLDB_API SBFunction;
class LLDB_API SBHostOS;
class LLDB_API SBInstruction;
diff --git a/lldb/include/lldb/API/SBFrame.h b/lldb/include/lldb/API/SBFrame.h
index 92917e57fc125..5283cdfe53faa 100644
--- a/lldb/include/lldb/API/SBFrame.h
+++ b/lldb/include/lldb/API/SBFrame.h
@@ -222,6 +222,7 @@ class LLDB_API SBFrame {
protected:
friend class SBBlock;
friend class SBExecutionContext;
+ friend class SBFrameList;
friend class SBInstruction;
friend class SBThread;
friend class SBValue;
diff --git a/lldb/include/lldb/API/SBFrameList.h b/lldb/include/lldb/API/SBFrameList.h
new file mode 100644
index 0000000000000..87b72a76384df
--- /dev/null
+++ b/lldb/include/lldb/API/SBFrameList.h
@@ -0,0 +1,55 @@
+//===-- SBFrameList.h -------------------------------------------*- 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_API_SBFRAMELIST_H
+#define LLDB_API_SBFRAMELIST_H
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+
+class LLDB_API SBFrameList {
+public:
+ SBFrameList();
+
+ SBFrameList(const lldb::SBFrameList &rhs);
+
+ ~SBFrameList();
+
+ const lldb::SBFrameList &operator=(const lldb::SBFrameList &rhs);
+
+ explicit operator bool() const;
+
+ bool IsValid() const;
+
+ uint32_t GetSize() const;
+
+ lldb::SBFrame GetFrameAtIndex(uint32_t idx) const;
+
+ void Clear();
+
+ void Append(const lldb::SBFrame &frame);
+
+ void Append(const lldb::SBFrameList &frame_list);
+
+ bool GetDescription(lldb::SBStream &description) const;
+
+protected:
+ friend class SBThread;
+
+private:
+ SBFrameList(const lldb::StackFrameListSP &frame_list_sp);
+
+ void SetOpaque(const lldb::StackFrameListSP &frame_list_sp);
+
+ lldb::StackFrameListSP m_opaque_sp;
+};
+
+} // namespace lldb
+
+#endif // LLDB_API_SBFRAMELIST_H
diff --git a/lldb/include/lldb/API/SBStream.h b/lldb/include/lldb/API/SBStream.h
index d230da6123fb3..21f9d21e0e717 100644
--- a/lldb/include/lldb/API/SBStream.h
+++ b/lldb/include/lldb/API/SBStream.h
@@ -81,6 +81,7 @@ class LLDB_API SBStream {
friend class SBFileSpec;
friend class SBFileSpecList;
friend class SBFrame;
+ friend class SBFrameList;
friend class SBFunction;
friend class SBInstruction;
friend class SBInstructionList;
diff --git a/lldb/include/lldb/API/SBThread.h b/lldb/include/lldb/API/SBThread.h
index e9fe5858d125e..9293a7f9ebab9 100644
--- a/lldb/include/lldb/API/SBThread.h
+++ b/lldb/include/lldb/API/SBThread.h
@@ -178,6 +178,8 @@ class LLDB_API SBThread {
lldb::SBFrame GetFrameAtIndex(uint32_t idx);
+ lldb::SBFrameList GetFrames();
+
lldb::SBFrame GetSelectedFrame();
lldb::SBFrame SetSelectedFrame(uint32_t frame_idx);
diff --git a/lldb/include/lldb/Target/Thread.h b/lldb/include/lldb/Target/Thread.h
index 688c056da2633..ca356d546db5d 100644
--- a/lldb/include/lldb/Target/Thread.h
+++ b/lldb/include/lldb/Target/Thread.h
@@ -1295,6 +1295,8 @@ class Thread : public std::enable_shared_from_this<Thread>,
/// an empty std::optional is returned in that case.
std::optional<lldb::addr_t> GetPreviousFrameZeroPC();
+ lldb::StackFrameListSP GetStackFrameList();
+
protected:
friend class ThreadPlan;
friend class ThreadList;
@@ -1336,8 +1338,18 @@ class Thread : public std::enable_shared_from_this<Thread>,
return StructuredData::ObjectSP();
}
+<<<<<<< HEAD
+ lldb::StackFrameListSP GetStackFrameList();
+
+||||||| parent of e4e31827a1bf ([lldb] Introduce SBFrameList for lazy frame iteration)
lldb::StackFrameListSP GetStackFrameList();
+ llvm::Expected<lldb::StackFrameListSP> GetScriptedFrameList();
+
+=======
+ llvm::Expected<lldb::StackFrameListSP> GetScriptedFrameList();
+
+>>>>>>> e4e31827a1bf ([lldb] Introduce SBFrameList for lazy frame iteration)
void SetTemporaryResumeState(lldb::StateType new_state) {
m_temporary_resume_state = new_state;
}
diff --git a/lldb/source/API/CMakeLists.txt b/lldb/source/API/CMakeLists.txt
index ce59ee505cd3d..ac47580d60840 100644
--- a/lldb/source/API/CMakeLists.txt
+++ b/lldb/source/API/CMakeLists.txt
@@ -69,6 +69,7 @@ add_lldb_library(liblldb SHARED ${option_framework}
SBFileSpecList.cpp
SBFormat.cpp
SBFrame.cpp
+ SBFrameList.cpp
SBFunction.cpp
SBHostOS.cpp
SBInstruction.cpp
diff --git a/lldb/source/API/SBFrameList.cpp b/lldb/source/API/SBFrameList.cpp
new file mode 100644
index 0000000000000..07cb29518401f
--- /dev/null
+++ b/lldb/source/API/SBFrameList.cpp
@@ -0,0 +1,101 @@
+//===-- SBFrameList.cpp ---------------------------------------------------===//
+//
+// 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/API/SBFrameList.h"
+#include "lldb/API/SBFrame.h"
+#include "lldb/API/SBStream.h"
+#include "lldb/Target/StackFrameList.h"
+#include "lldb/Target/Thread.h"
+#include "lldb/Utility/Instrumentation.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+SBFrameList::SBFrameList() : m_opaque_sp() { LLDB_INSTRUMENT_VA(this); }
+
+SBFrameList::SBFrameList(const SBFrameList &rhs)
+ : m_opaque_sp(rhs.m_opaque_sp) {
+ LLDB_INSTRUMENT_VA(this, rhs);
+}
+
+SBFrameList::~SBFrameList() = default;
+
+const SBFrameList &SBFrameList::operator=(const SBFrameList &rhs) {
+ LLDB_INSTRUMENT_VA(this, rhs);
+
+ if (this != &rhs)
+ m_opaque_sp = rhs.m_opaque_sp;
+ return *this;
+}
+
+SBFrameList::SBFrameList(const lldb::StackFrameListSP &frame_list_sp)
+ : m_opaque_sp(frame_list_sp) {}
+
+void SBFrameList::SetOpaque(const lldb::StackFrameListSP &frame_list_sp) {
+ m_opaque_sp = frame_list_sp;
+}
+
+SBFrameList::operator bool() const {
+ LLDB_INSTRUMENT_VA(this);
+
+ return m_opaque_sp.get() != nullptr;
+}
+
+bool SBFrameList::IsValid() const {
+ LLDB_INSTRUMENT_VA(this);
+ return this->operator bool();
+}
+
+uint32_t SBFrameList::GetSize() const {
+ LLDB_INSTRUMENT_VA(this);
+
+ if (m_opaque_sp)
+ return m_opaque_sp->GetNumFrames();
+ return 0;
+}
+
+SBFrame SBFrameList::GetFrameAtIndex(uint32_t idx) const {
+ LLDB_INSTRUMENT_VA(this, idx);
+
+ SBFrame sb_frame;
+ if (m_opaque_sp)
+ sb_frame.SetFrameSP(m_opaque_sp->GetFrameAtIndex(idx));
+ return sb_frame;
+}
+
+void SBFrameList::Clear() {
+ LLDB_INSTRUMENT_VA(this);
+
+ if (m_opaque_sp)
+ m_opaque_sp->Clear();
+}
+
+void SBFrameList::Append(const SBFrame &frame) {
+ LLDB_INSTRUMENT_VA(this, frame);
+
+ // Note: StackFrameList doesn't have an Append method, so this is a no-op
+ // This method is kept for API consistency with other SB*List classes
+}
+
+void SBFrameList::Append(const SBFrameList &frame_list) {
+ LLDB_INSTRUMENT_VA(this, frame_list);
+
+ // Note: StackFrameList doesn't have an Append method, so this is a no-op
+ // This method is kept for API consistency with other SB*List classes
+}
+
+bool SBFrameList::GetDescription(SBStream &description) const {
+ LLDB_INSTRUMENT_VA(this, description);
+
+ Stream &strm = description.ref();
+ if (m_opaque_sp) {
+ m_opaque_sp->Dump(&strm);
+ return true;
+ }
+ return false;
+}
diff --git a/lldb/source/API/SBThread.cpp b/lldb/source/API/SBThread.cpp
index 4e4aa48bc9a2e..ba1a492069ea6 100644
--- a/lldb/source/API/SBThread.cpp
+++ b/lldb/source/API/SBThread.cpp
@@ -14,6 +14,7 @@
#include "lldb/API/SBFileSpec.h"
#include "lldb/API/SBFormat.h"
#include "lldb/API/SBFrame.h"
+#include "lldb/API/SBFrameList.h"
#include "lldb/API/SBProcess.h"
#include "lldb/API/SBStream.h"
#include "lldb/API/SBStructuredData.h"
@@ -1079,6 +1080,26 @@ SBFrame SBThread::GetFrameAtIndex(uint32_t idx) {
return sb_frame;
}
+lldb::SBFrameList SBThread::GetFrames() {
+ LLDB_INSTRUMENT_VA(this);
+
+ SBFrameList sb_frame_list;
+ llvm::Expected<StoppedExecutionContext> exe_ctx =
+ GetStoppedExecutionContext(m_opaque_sp);
+ if (!exe_ctx) {
+ LLDB_LOG_ERROR(GetLog(LLDBLog::API), exe_ctx.takeError(), "{0}");
+ return SBFrameList();
+ }
+
+ if (exe_ctx->HasThreadScope()) {
+ StackFrameListSP frame_list_sp =
+ exe_ctx->GetThreadPtr()->GetStackFrameList();
+ sb_frame_list.SetOpaque(frame_list_sp);
+ }
+
+ return sb_frame_list;
+}
+
lldb::SBFrame SBThread::GetSelectedFrame() {
LLDB_INSTRUMENT_VA(this);
diff --git a/lldb/test/API/python_api/frame_list/Makefile b/lldb/test/API/python_api/frame_list/Makefile
new file mode 100644
index 0000000000000..2bb9ce046a907
--- /dev/null
+++ b/lldb/test/API/python_api/frame_list/Makefile
@@ -0,0 +1,3 @@
+CXX_SOURCES := main.cpp
+
+include Makefile.rules
\ No newline at end of file
diff --git a/lldb/test/API/python_api/frame_list/TestSBFrameList.py b/lldb/test/API/python_api/frame_list/TestSBFrameList.py
new file mode 100644
index 0000000000000..88345f97080f5
--- /dev/null
+++ b/lldb/test/API/python_api/frame_list/TestSBFrameList.py
@@ -0,0 +1,172 @@
+"""
+Test SBFrameList API.
+"""
+
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+
+class FrameListAPITestCase(TestBase):
+ def test_frame_list_api(self):
+ """Test SBThread.GetFrames() returns a valid SBFrameList."""
+ self.build()
+ self.frame_list_api()
+
+ def test_frame_list_iterator(self):
+ """Test SBFrameList iterator functionality."""
+ self.build()
+ self.frame_list_iterator()
+
+ def test_frame_list_indexing(self):
+ """Test SBFrameList indexing and length."""
+ self.build()
+ self.frame_list_indexing()
+
+ def setUp(self):
+ TestBase.setUp(self)
+ self.main_source = "main.cpp"
+ self.break_line = line_number(
+ self.main_source, "// Set break point at this line"
+ )
+
+ def frame_list_api(self):
+ """Test SBThread.GetFrames() returns a valid SBFrameList."""
+ exe = self.getBuildArtifact("a.out")
+
+ target = self.dbg.CreateTarget(exe)
+ self.assertTrue(target, VALID_TARGET)
+
+ breakpoint = target.BreakpointCreateByLocation(
+ self.main_source, self.break_line
+ )
+ self.assertTrue(breakpoint, VALID_BREAKPOINT)
+
+ process = target.LaunchSimple(None, None, self.get_process_working_directory())
+
+ thread = lldbutil.get_stopped_thread(process, lldb.eStopReasonBreakpoint)
+ self.assertTrue(
+ thread.IsValid(), "There should be a thread stopped due to breakpoint"
+ )
+
+ # Test GetFrames() returns a valid SBFrameList
+ frame_list = thread.GetFrames()
+ self.assertTrue(frame_list.IsValid(), "Frame list should be valid")
+ self.assertGreater(
+ frame_list.GetSize(), 0, "Frame list should have at least one frame"
+ )
+
+ # Verify frame list size matches thread frame count
+ self.assertEqual(
+ frame_list.GetSize(),
+ thread.GetNumFrames(),
+ "Frame list size should match thread frame count",
+ )
+
+ # Verify frames are the same
+ for i in range(frame_list.GetSize()):
+ frame_from_list = frame_list.GetFrameAtIndex(i)
+ frame_from_thread = thread.GetFrameAtIndex(i)
+ self.assertTrue(
+ frame_from_list.IsValid(), f"Frame {i} from list should be valid"
+ )
+ self.assertEqual(
+ frame_from_list.GetPC(),
+ frame_from_thread.GetPC(),
+ f"Frame {i} PC should match",
+ )
+
+ def frame_list_iterator(self):
+ """Test SBFrameList iterator functionality."""
+ exe = self.getBuildArtifact("a.out")
+
+ target = self.dbg.CreateTarget(exe)
+ self.assertTrue(target, VALID_TARGET)
+
+ breakpoint = target.BreakpointCreateByLocation(
+ self.main_source, self.break_line
+ )
+ self.assertTrue(breakpoint, VALID_BREAKPOINT)
+
+ process = target.LaunchSimple(None, None, self.get_process_working_directory())
+
+ thread = lldbutil.get_stopped_thread(process, lldb.eStopReasonBreakpoint)
+ frame_list = thread.GetFrames()
+
+ # Test iteration
+ frame_count = 0
+ for frame in frame_list:
+ self.assertTrue(frame.IsValid(), "Each frame should be valid")
+ frame_count += 1
+
+ self.assertEqual(
+ frame_count,
+ frame_list.GetSize(),
+ "Iterator should visit all frames",
+ )
+
+ # Test that we can iterate multiple times
+ second_count = 0
+ for frame in frame_list:
+ second_count += 1
+
+ self.assertEqual(
+ frame_count, second_count, "Should be able to iterate multiple times"
+ )
+
+ def frame_list_indexing(self):
+ """Test SBFrameList indexing and length."""
+ exe = self.getBuildArtifact("a.out")
+
+ target = self.dbg.CreateTarget(exe)
+ self.assertTrue(target, VALID_TARGET)
+
+ breakpoint = target.BreakpointCreateByLocation(
+ self.main_source, self.break_line
+ )
+ self.assertTrue(breakpoint, VALID_BREAKPOINT)
+
+ process = target.LaunchSimple(None, None, self.get_process_working_directory())
+
+ thread = lldbutil.get_stopped_thread(process, lldb.eStopReasonBreakpoint)
+ frame_list = thread.GetFrames()
+
+ # Test len()
+ self.assertEqual(
+ len(frame_list), frame_list.GetSize(), "len() should return frame count"
+ )
+
+ # Test positive indexing
+ first_frame = frame_list[0]
+ self.assertTrue(first_frame.IsValid(), "First frame should be valid")
+ self.assertEqual(
+ first_frame.GetPC(),
+ thread.GetFrameAtIndex(0).GetPC(),
+ "Indexed frame should match",
+ )
+
+ # Test negative indexing
+ if len(frame_list) > 0:
+ last_frame = frame_list[-1]
+ self.assertTrue(last_frame.IsValid(), "Last frame should be valid")
+ self.assertEqual(
+ last_frame.GetPC(),
+ thread.GetFrameAtIndex(len(frame_list) - 1).GetPC(),
+ "Negative indexing should work",
+ )
+
+ # Test out of bounds returns None
+ out_of_bounds = frame_list[10000]
+ self.assertIsNone(out_of_bounds, "Out of bounds index should return None")
+
+ # Test bool conversion
+ self.assertTrue(bool(frame_list), "Non-empty frame list should be truthy")
+
+ # Test Clear()
+ frame_list.Clear()
+ # Note: Clear() clears the underlying StackFrameList cache,
+ # but the frame list object itself should still be valid
+ self.assertTrue(
+ frame_list.IsValid(), "Frame list should still be valid after Clear()"
+ )
diff --git a/lldb/test/API/python_api/frame_list/main.cpp b/lldb/test/API/python_api/frame_list/main.cpp
new file mode 100644
index 0000000000000..a10ae5cf11f80
--- /dev/null
+++ b/lldb/test/API/python_api/frame_list/main.cpp
@@ -0,0 +1,22 @@
+#include <stdio.h>
+
+int c(int val) {
+ // Set break point at this line
+ return val + 3;
+}
+
+int b(int val) {
+ int result = c(val);
+ return result;
+}
+
+int a(int val) {
+ int result = b(val);
+ return result;
+}
+
+int main() {
+ int result = a(1);
+ printf("Result: %d\n", result);
+ return 0;
+}
\ No newline at end of file
>From 20c677975892f730ab3aefbd090eca4f8cd70d9d Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Mon, 27 Oct 2025 13:54:41 -0700
Subject: [PATCH 2/4] [lldb/Interpreter] Implement
ScriptedFrameProvider{,Python}Interface
This patch implements the base and python interface for the
ScriptedFrameProvider class.
This is necessary to call python APIs from the ScriptedFrameProvider
that will come in a follow-up.
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
lldb/bindings/python/CMakeLists.txt | 1 +
lldb/bindings/python/python-swigsafecast.swig | 5 +
lldb/bindings/python/python-wrapper.swig | 12 ++
.../templates/scripted_frame_provider.py | 119 ++++++++++++++++++
lldb/include/lldb/API/SBFrameList.h | 14 +++
.../ScriptedFrameProviderInterface.h | 30 +++++
.../lldb/Interpreter/ScriptInterpreter.h | 10 ++
lldb/include/lldb/Target/Thread.h | 12 --
lldb/include/lldb/lldb-forward.h | 6 +
lldb/source/Interpreter/ScriptInterpreter.cpp | 5 +
.../Plugins/Process/scripted/ScriptedFrame.h | 1 -
.../Python/Interfaces/CMakeLists.txt | 1 +
.../ScriptInterpreterPythonInterfaces.h | 1 +
.../ScriptedFrameProviderPythonInterface.cpp | 58 +++++++++
.../ScriptedFrameProviderPythonInterface.h | 44 +++++++
.../Interfaces/ScriptedPythonInterface.cpp | 17 +++
.../Interfaces/ScriptedPythonInterface.h | 13 ++
.../Python/SWIGPythonBridge.h | 2 +
.../Python/ScriptInterpreterPython.cpp | 5 +
.../Python/ScriptInterpreterPythonImpl.h | 3 +
.../Python/PythonTestSuite.cpp | 10 ++
21 files changed, 356 insertions(+), 13 deletions(-)
create mode 100644 lldb/examples/python/templates/scripted_frame_provider.py
create mode 100644 lldb/include/lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h
create mode 100644 lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.cpp
create mode 100644 lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.h
diff --git a/lldb/bindings/python/CMakeLists.txt b/lldb/bindings/python/CMakeLists.txt
index ef6def3f26872..28a8af8f06319 100644
--- a/lldb/bindings/python/CMakeLists.txt
+++ b/lldb/bindings/python/CMakeLists.txt
@@ -107,6 +107,7 @@ function(finish_swig_python swig_target lldb_python_bindings_dir lldb_python_tar
"plugins"
FILES
"${LLDB_SOURCE_DIR}/examples/python/templates/parsed_cmd.py"
+ "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_frame_provider.py"
"${LLDB_SOURCE_DIR}/examples/python/templates/scripted_process.py"
"${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py"
"${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py"
diff --git a/lldb/bindings/python/python-swigsafecast.swig b/lldb/bindings/python/python-swigsafecast.swig
index 3ea24f1a31414..a86dc44ce4106 100644
--- a/lldb/bindings/python/python-swigsafecast.swig
+++ b/lldb/bindings/python/python-swigsafecast.swig
@@ -37,6 +37,11 @@ PythonObject SWIGBridge::ToSWIGWrapper(lldb::ThreadPlanSP thread_plan_sp) {
SWIGTYPE_p_lldb__SBThreadPlan);
}
+PythonObject SWIGBridge::ToSWIGWrapper(lldb::StackFrameListSP frames_sp) {
+ return ToSWIGHelper(new lldb::SBFrameList(std::move(frames_sp)),
+ SWIGTYPE_p_lldb__SBFrameList);
+}
+
PythonObject SWIGBridge::ToSWIGWrapper(lldb::BreakpointSP breakpoint_sp) {
return ToSWIGHelper(new lldb::SBBreakpoint(std::move(breakpoint_sp)),
SWIGTYPE_p_lldb__SBBreakpoint);
diff --git a/lldb/bindings/python/python-wrapper.swig b/lldb/bindings/python/python-wrapper.swig
index 64b7dc8381073..6ba0276fcb05e 100644
--- a/lldb/bindings/python/python-wrapper.swig
+++ b/lldb/bindings/python/python-wrapper.swig
@@ -556,6 +556,18 @@ void *lldb_private::python::LLDBSWIGPython_CastPyObjectToSBExecutionContext(PyOb
return sb_ptr;
}
+void *lldb_private::python::LLDBSWIGPython_CastPyObjectToSBFrameList(PyObject *data) {
+ lldb::SBFrameList *sb_ptr = NULL;
+
+ int valid_cast = SWIG_ConvertPtr(data, (void **)&sb_ptr,
+ SWIGTYPE_p_lldb__SBFrameList, 0);
+
+ if (valid_cast == -1)
+ return NULL;
+
+ return sb_ptr;
+}
+
bool lldb_private::python::SWIGBridge::LLDBSwigPythonCallCommand(
const char *python_function_name, const char *session_dictionary_name,
lldb::DebuggerSP debugger, const char *args,
diff --git a/lldb/examples/python/templates/scripted_frame_provider.py b/lldb/examples/python/templates/scripted_frame_provider.py
new file mode 100644
index 0000000000000..574469553b43c
--- /dev/null
+++ b/lldb/examples/python/templates/scripted_frame_provider.py
@@ -0,0 +1,119 @@
+from abc import ABCMeta, abstractmethod
+
+import lldb
+
+
+class ScriptedFrameProvider(metaclass=ABCMeta):
+ """
+ The base class for a scripted frame provider.
+
+ A scripted frame provider allows you to provide custom stack frames for a
+ thread, which can be used to augment or replace the standard unwinding
+ mechanism. 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
+
+ Most of the base class methods are `@abstractmethod` that need to be
+ overwritten by the inheriting class.
+
+ Example usage:
+
+ .. code-block:: python
+
+ # Attach a frame provider to a thread
+ thread = process.GetSelectedThread()
+ error = thread.SetScriptedFrameProvider(
+ "my_module.MyFrameProvider",
+ lldb.SBStructuredData()
+ )
+ """
+
+ @abstractmethod
+ def __init__(self, thread, args):
+ """Construct a scripted frame provider.
+
+ Args:
+ thread (lldb.SBThread): The thread for which to provide frames.
+ args (lldb.SBStructuredData): A Dictionary holding arbitrary
+ key/value pairs used by the scripted frame provider.
+ """
+ self.thread = None
+ self.args = None
+ self.target = None
+ self.process = None
+
+ if isinstance(thread, lldb.SBThread) and thread.IsValid():
+ self.thread = thread
+ self.process = thread.GetProcess()
+ if self.process and self.process.IsValid():
+ self.target = self.process.GetTarget()
+
+ if isinstance(args, lldb.SBStructuredData) and args.IsValid():
+ self.args = args
+
+ @abstractmethod
+ def get_frame_at_index(self, real_frames, index):
+ """Get a single stack frame at the given index.
+
+ This method is called lazily when a specific frame is needed in the
+ thread's backtrace (e.g., via the 'bt' command). Each frame is
+ requested individually as needed.
+
+ Args:
+ real_frames (lldb.SBFrameList): The actual unwound frames from the
+ thread's normal unwinder. This allows you to access real frames
+ by index. The frames are materialized lazily as you access them.
+ index (int): The frame index to retrieve (0 for innermost/top frame).
+
+ Returns:
+ Dict or None: A frame dictionary describing the stack frame, or None
+ if no frame exists at this index. The dictionary should contain:
+
+ Required fields:
+ - idx (int): The frame index (0 for innermost/top frame)
+ - pc (int): The program counter address for this frame
+
+ Alternatively, you can return:
+ - A ScriptedFrame object for full control over frame behavior
+ - An integer representing a real frame index to reuse
+ - None to indicate no more frames exist
+
+ Example:
+
+ .. code-block:: python
+
+ def get_frame_at_index(self, real_frames, index):
+ # Return None when there are no more frames
+ if index >= self.total_frames:
+ return None
+
+ # Re-use a real frame by returning its index
+ if self.should_use_real_frame(index):
+ return index # Returns real frame at this index
+
+ # Or create a custom frame
+ if index == 0:
+ return {
+ "idx": 0,
+ "pc": 0x100001234,
+ }
+
+ # Filter out some real frames
+ real_frame = real_frames[index]
+ if self.should_include_frame(real_frame):
+ return {
+ "idx": index,
+ "pc": real_frame.GetPC(),
+ }
+
+ return None
+
+ Note:
+ The frames are indexed from 0 (innermost/newest) to N (outermost/oldest).
+ This method will be called repeatedly with increasing indices until
+ None is returned.
+ """
+ pass
diff --git a/lldb/include/lldb/API/SBFrameList.h b/lldb/include/lldb/API/SBFrameList.h
index 87b72a76384df..680dd62f9ce4a 100644
--- a/lldb/include/lldb/API/SBFrameList.h
+++ b/lldb/include/lldb/API/SBFrameList.h
@@ -11,6 +11,16 @@
#include "lldb/API/SBDefines.h"
+namespace lldb_private {
+class ScriptInterpreter;
+namespace python {
+class SWIGBridge;
+}
+namespace lua {
+class SWIGBridge;
+}
+} // namespace lldb_private
+
namespace lldb {
class LLDB_API SBFrameList {
@@ -42,6 +52,10 @@ class LLDB_API SBFrameList {
protected:
friend class SBThread;
+ friend class lldb_private::python::SWIGBridge;
+ friend class lldb_private::lua::SWIGBridge;
+ friend class lldb_private::ScriptInterpreter;
+
private:
SBFrameList(const lldb::StackFrameListSP &frame_list_sp);
diff --git a/lldb/include/lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h b/lldb/include/lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h
new file mode 100644
index 0000000000000..e1f086a81ee96
--- /dev/null
+++ b/lldb/include/lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h
@@ -0,0 +1,30 @@
+//===-- ScriptedFrameProviderInterface.h ------------------------*- 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_INTERPRETER_INTERFACES_SCRIPTEDFRAMEPROVIDERINTERFACE_H
+#define LLDB_INTERPRETER_INTERFACES_SCRIPTEDFRAMEPROVIDERINTERFACE_H
+
+#include "lldb/lldb-private.h"
+
+#include "ScriptedInterface.h"
+
+namespace lldb_private {
+class ScriptedFrameProviderInterface : public ScriptedInterface {
+public:
+ virtual llvm::Expected<StructuredData::GenericSP>
+ CreatePluginObject(llvm::StringRef class_name, lldb::ThreadSP thread_sp,
+ StructuredData::DictionarySP args_sp) = 0;
+
+ virtual StructuredData::ObjectSP
+ GetFrameAtIndex(lldb::StackFrameListSP real_frames, uint32_t index) {
+ return {};
+ }
+};
+} // namespace lldb_private
+
+#endif // LLDB_INTERPRETER_INTERFACES_SCRIPTEDFRAMEPROVIDERINTERFACE_H
diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreter.h b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
index 6c0054a1ec1d1..f4c204d5c08e5 100644
--- a/lldb/include/lldb/Interpreter/ScriptInterpreter.h
+++ b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
@@ -16,6 +16,7 @@
#include "lldb/API/SBError.h"
#include "lldb/API/SBEvent.h"
#include "lldb/API/SBExecutionContext.h"
+#include "lldb/API/SBFrameList.h"
#include "lldb/API/SBLaunchInfo.h"
#include "lldb/API/SBMemoryRegionInfo.h"
#include "lldb/API/SBStream.h"
@@ -28,6 +29,7 @@
#include "lldb/Host/StreamFile.h"
#include "lldb/Interpreter/Interfaces/OperatingSystemInterface.h"
#include "lldb/Interpreter/Interfaces/ScriptedFrameInterface.h"
+#include "lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h"
#include "lldb/Interpreter/Interfaces/ScriptedPlatformInterface.h"
#include "lldb/Interpreter/Interfaces/ScriptedProcessInterface.h"
#include "lldb/Interpreter/Interfaces/ScriptedThreadInterface.h"
@@ -537,6 +539,11 @@ class ScriptInterpreter : public PluginInterface {
return {};
}
+ virtual lldb::ScriptedFrameProviderInterfaceSP
+ CreateScriptedFrameProviderInterface() {
+ return {};
+ }
+
virtual lldb::ScriptedThreadPlanInterfaceSP
CreateScriptedThreadPlanInterface() {
return {};
@@ -596,6 +603,9 @@ class ScriptInterpreter : public PluginInterface {
lldb::ExecutionContextRefSP GetOpaqueTypeFromSBExecutionContext(
const lldb::SBExecutionContext &exe_ctx) const;
+ lldb::StackFrameListSP
+ GetOpaqueTypeFromSBFrameList(const lldb::SBFrameList &exe_ctx) const;
+
protected:
Debugger &m_debugger;
lldb::ScriptLanguage m_script_lang;
diff --git a/lldb/include/lldb/Target/Thread.h b/lldb/include/lldb/Target/Thread.h
index ca356d546db5d..841f80cd1b1eb 100644
--- a/lldb/include/lldb/Target/Thread.h
+++ b/lldb/include/lldb/Target/Thread.h
@@ -1338,18 +1338,6 @@ class Thread : public std::enable_shared_from_this<Thread>,
return StructuredData::ObjectSP();
}
-<<<<<<< HEAD
- lldb::StackFrameListSP GetStackFrameList();
-
-||||||| parent of e4e31827a1bf ([lldb] Introduce SBFrameList for lazy frame iteration)
- lldb::StackFrameListSP GetStackFrameList();
-
- llvm::Expected<lldb::StackFrameListSP> GetScriptedFrameList();
-
-=======
- llvm::Expected<lldb::StackFrameListSP> GetScriptedFrameList();
-
->>>>>>> e4e31827a1bf ([lldb] Introduce SBFrameList for lazy frame iteration)
void SetTemporaryResumeState(lldb::StateType new_state) {
m_temporary_resume_state = new_state;
}
diff --git a/lldb/include/lldb/lldb-forward.h b/lldb/include/lldb/lldb-forward.h
index af5656b3dcad1..70da8288e6dbe 100644
--- a/lldb/include/lldb/lldb-forward.h
+++ b/lldb/include/lldb/lldb-forward.h
@@ -188,6 +188,7 @@ class Scalar;
class ScriptInterpreter;
class ScriptInterpreterLocker;
class ScriptedFrameInterface;
+class ScriptedFrameProviderInterface;
class ScriptedMetadata;
class ScriptedBreakpointInterface;
class ScriptedPlatformInterface;
@@ -195,6 +196,7 @@ class ScriptedProcessInterface;
class ScriptedStopHookInterface;
class ScriptedThreadInterface;
class ScriptedThreadPlanInterface;
+class SyntheticFrameProvider;
class ScriptedSyntheticChildren;
class SearchFilter;
class Section;
@@ -411,6 +413,10 @@ 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::ScriptedFrameProviderInterface>
+ ScriptedFrameProviderInterfaceSP;
+typedef std::shared_ptr<lldb_private::SyntheticFrameProvider>
+ SyntheticFrameProviderSP;
typedef std::shared_ptr<lldb_private::ScriptedMetadata> ScriptedMetadataSP;
typedef std::unique_ptr<lldb_private::ScriptedPlatformInterface>
ScriptedPlatformInterfaceUP;
diff --git a/lldb/source/Interpreter/ScriptInterpreter.cpp b/lldb/source/Interpreter/ScriptInterpreter.cpp
index ca768db1199c1..211868b51facb 100644
--- a/lldb/source/Interpreter/ScriptInterpreter.cpp
+++ b/lldb/source/Interpreter/ScriptInterpreter.cpp
@@ -150,6 +150,11 @@ ScriptInterpreter::GetOpaqueTypeFromSBExecutionContext(
return exe_ctx.m_exe_ctx_sp;
}
+lldb::StackFrameListSP ScriptInterpreter::GetOpaqueTypeFromSBFrameList(
+ const lldb::SBFrameList &frame_list) const {
+ return frame_list.m_opaque_sp;
+}
+
lldb::ScriptLanguage
ScriptInterpreter::StringToLanguage(const llvm::StringRef &language) {
if (language.equals_insensitive(LanguageToString(eScriptLanguageNone)))
diff --git a/lldb/source/Plugins/Process/scripted/ScriptedFrame.h b/lldb/source/Plugins/Process/scripted/ScriptedFrame.h
index 6e01e2fd7653e..b6b77c4a7d160 100644
--- a/lldb/source/Plugins/Process/scripted/ScriptedFrame.h
+++ b/lldb/source/Plugins/Process/scripted/ScriptedFrame.h
@@ -9,7 +9,6 @@
#ifndef LLDB_SOURCE_PLUGINS_SCRIPTED_FRAME_H
#define LLDB_SOURCE_PLUGINS_SCRIPTED_FRAME_H
-#include "Plugins/Process/Utility/RegisterContextMemory.h"
#include "ScriptedThread.h"
#include "lldb/Interpreter/ScriptInterpreter.h"
#include "lldb/Target/DynamicRegisterInfo.h"
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/CMakeLists.txt b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/CMakeLists.txt
index 09103573b89c5..50569cdefaafa 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/CMakeLists.txt
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/CMakeLists.txt
@@ -23,6 +23,7 @@ add_lldb_library(lldbPluginScriptInterpreterPythonInterfaces PLUGIN
OperatingSystemPythonInterface.cpp
ScriptInterpreterPythonInterfaces.cpp
ScriptedFramePythonInterface.cpp
+ ScriptedFrameProviderPythonInterface.cpp
ScriptedPlatformPythonInterface.cpp
ScriptedProcessPythonInterface.cpp
ScriptedPythonInterface.cpp
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptInterpreterPythonInterfaces.h b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptInterpreterPythonInterfaces.h
index 3814f46615078..b2a347951d0f2 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptInterpreterPythonInterfaces.h
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptInterpreterPythonInterfaces.h
@@ -17,6 +17,7 @@
#include "OperatingSystemPythonInterface.h"
#include "ScriptedBreakpointPythonInterface.h"
+#include "ScriptedFrameProviderPythonInterface.h"
#include "ScriptedFramePythonInterface.h"
#include "ScriptedPlatformPythonInterface.h"
#include "ScriptedProcessPythonInterface.h"
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.cpp b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.cpp
new file mode 100644
index 0000000000000..f8f3e415a93cd
--- /dev/null
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.cpp
@@ -0,0 +1,58 @@
+//===-- ScriptedFrameProviderPythonInterface.cpp -------------------------===//
+//
+// 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/Host/Config.h"
+#include "lldb/Target/Thread.h"
+#include "lldb/Utility/Log.h"
+#include "lldb/lldb-enumerations.h"
+
+#if LLDB_ENABLE_PYTHON
+
+// LLDB Python header must be included first
+#include "../lldb-python.h"
+
+#include "../SWIGPythonBridge.h"
+#include "../ScriptInterpreterPythonImpl.h"
+#include "ScriptedFrameProviderPythonInterface.h"
+#include <optional>
+
+using namespace lldb;
+using namespace lldb_private;
+using namespace lldb_private::python;
+using Locker = ScriptInterpreterPythonImpl::Locker;
+
+ScriptedFrameProviderPythonInterface::ScriptedFrameProviderPythonInterface(
+ ScriptInterpreterPythonImpl &interpreter)
+ : ScriptedFrameProviderInterface(), ScriptedPythonInterface(interpreter) {}
+
+llvm::Expected<StructuredData::GenericSP>
+ScriptedFrameProviderPythonInterface::CreatePluginObject(
+ const llvm::StringRef class_name, lldb::ThreadSP thread_sp,
+ StructuredData::DictionarySP args_sp) {
+ if (!thread_sp)
+ return llvm::createStringError("Invalid thread");
+
+ StructuredDataImpl sd_impl(args_sp);
+ return ScriptedPythonInterface::CreatePluginObject(class_name, nullptr,
+ thread_sp, sd_impl);
+}
+
+StructuredData::ObjectSP ScriptedFrameProviderPythonInterface::GetFrameAtIndex(
+ lldb::StackFrameListSP real_frames, uint32_t index) {
+ Status error;
+ StructuredData::ObjectSP obj =
+ Dispatch("get_frame_at_index", error, real_frames, index);
+
+ if (!ScriptedInterface::CheckStructuredDataObject(LLVM_PRETTY_FUNCTION, obj,
+ error))
+ return {};
+
+ return obj;
+}
+
+#endif
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.h b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.h
new file mode 100644
index 0000000000000..a0ededf59c4cc
--- /dev/null
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedFrameProviderPythonInterface.h
@@ -0,0 +1,44 @@
+//===-- ScriptedFrameProviderPythonInterface.h -----------------*- 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_PLUGINS_SCRIPTINTERPRETER_PYTHON_INTERFACES_SCRIPTEDFRAMEPROVIDERPYTHONINTERFACE_H
+#define LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_INTERFACES_SCRIPTEDFRAMEPROVIDERPYTHONINTERFACE_H
+
+#include "lldb/Host/Config.h"
+
+#if LLDB_ENABLE_PYTHON
+
+#include "ScriptedPythonInterface.h"
+#include "lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h"
+#include <optional>
+
+namespace lldb_private {
+class ScriptedFrameProviderPythonInterface
+ : public ScriptedFrameProviderInterface,
+ public ScriptedPythonInterface {
+public:
+ ScriptedFrameProviderPythonInterface(
+ ScriptInterpreterPythonImpl &interpreter);
+
+ llvm::Expected<StructuredData::GenericSP>
+ CreatePluginObject(llvm::StringRef class_name, lldb::ThreadSP thread_sp,
+ StructuredData::DictionarySP args_sp) override;
+
+ llvm::SmallVector<AbstractMethodRequirement>
+ GetAbstractMethodRequirements() const override {
+ return llvm::SmallVector<AbstractMethodRequirement>(
+ {{"get_frame_at_index"}});
+ }
+
+ StructuredData::ObjectSP GetFrameAtIndex(lldb::StackFrameListSP real_frames,
+ uint32_t index) override;
+};
+} // namespace lldb_private
+
+#endif // LLDB_ENABLE_PYTHON
+#endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_INTERFACES_SCRIPTEDFRAMEPROVIDERPYTHONINTERFACE_H
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.cpp b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.cpp
index 4fdf2b12a5500..05e91ab5507c7 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.cpp
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.cpp
@@ -243,4 +243,21 @@ ScriptedPythonInterface::ExtractValueFromPythonObject<lldb::DescriptionLevel>(
return static_cast<lldb::DescriptionLevel>(unsigned_val);
}
+template <>
+lldb::StackFrameListSP
+ScriptedPythonInterface::ExtractValueFromPythonObject<lldb::StackFrameListSP>(
+ python::PythonObject &p, Status &error) {
+
+ lldb::SBFrameList *sb_frame_list = reinterpret_cast<lldb::SBFrameList *>(
+ python::LLDBSWIGPython_CastPyObjectToSBFrameList(p.get()));
+
+ if (!sb_frame_list) {
+ error = Status::FromErrorStringWithFormat(
+ "Couldn't cast lldb::SBFrameList to lldb::StackFrameListSP.");
+ return {};
+ }
+
+ return m_interpreter.GetOpaqueTypeFromSBFrameList(*sb_frame_list);
+}
+
#endif
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.h b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.h
index 2335b2ef0f171..ec1dd9910d8a6 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.h
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/Interfaces/ScriptedPythonInterface.h
@@ -444,6 +444,14 @@ class ScriptedPythonInterface : virtual public ScriptedInterface {
return python::SWIGBridge::ToSWIGWrapper(arg);
}
+ python::PythonObject Transform(lldb::ThreadSP arg) {
+ return python::SWIGBridge::ToSWIGWrapper(arg);
+ }
+
+ python::PythonObject Transform(lldb::StackFrameListSP arg) {
+ return python::SWIGBridge::ToSWIGWrapper(arg);
+ }
+
python::PythonObject Transform(lldb::ThreadPlanSP arg) {
return python::SWIGBridge::ToSWIGWrapper(arg);
}
@@ -628,6 +636,11 @@ lldb::DescriptionLevel
ScriptedPythonInterface::ExtractValueFromPythonObject<lldb::DescriptionLevel>(
python::PythonObject &p, Status &error);
+template <>
+lldb::StackFrameListSP
+ScriptedPythonInterface::ExtractValueFromPythonObject<lldb::StackFrameListSP>(
+ python::PythonObject &p, Status &error);
+
} // namespace lldb_private
#endif // LLDB_ENABLE_PYTHON
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h b/lldb/source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h
index 7b39d29ba2b20..bf31ce9c7760e 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h
@@ -93,6 +93,7 @@ class SWIGBridge {
static PythonObject ToSWIGWrapper(const StructuredDataImpl &data_impl);
static PythonObject ToSWIGWrapper(lldb::ThreadSP thread_sp);
static PythonObject ToSWIGWrapper(lldb::StackFrameSP frame_sp);
+ static PythonObject ToSWIGWrapper(lldb::StackFrameListSP frames_sp);
static PythonObject ToSWIGWrapper(lldb::DebuggerSP debugger_sp);
static PythonObject ToSWIGWrapper(lldb::WatchpointSP watchpoint_sp);
static PythonObject ToSWIGWrapper(lldb::BreakpointLocationSP bp_loc_sp);
@@ -268,6 +269,7 @@ void *LLDBSWIGPython_CastPyObjectToSBSymbolContext(PyObject *data);
void *LLDBSWIGPython_CastPyObjectToSBValue(PyObject *data);
void *LLDBSWIGPython_CastPyObjectToSBMemoryRegionInfo(PyObject *data);
void *LLDBSWIGPython_CastPyObjectToSBExecutionContext(PyObject *data);
+void *LLDBSWIGPython_CastPyObjectToSBFrameList(PyObject *data);
} // namespace python
} // namespace lldb_private
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.cpp b/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.cpp
index 73c5c72932ff1..9ef5ac4acb6a3 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.cpp
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPython.cpp
@@ -1526,6 +1526,11 @@ ScriptInterpreterPythonImpl::CreateScriptedFrameInterface() {
return std::make_shared<ScriptedFramePythonInterface>(*this);
}
+ScriptedFrameProviderInterfaceSP
+ScriptInterpreterPythonImpl::CreateScriptedFrameProviderInterface() {
+ return std::make_shared<ScriptedFrameProviderPythonInterface>(*this);
+}
+
ScriptedThreadPlanInterfaceSP
ScriptInterpreterPythonImpl::CreateScriptedThreadPlanInterface() {
return std::make_shared<ScriptedThreadPlanPythonInterface>(*this);
diff --git a/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h b/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h
index dedac280788f4..0dd5ae52c8955 100644
--- a/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h
+++ b/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h
@@ -101,6 +101,9 @@ class ScriptInterpreterPythonImpl : public ScriptInterpreterPython {
lldb::ScriptedFrameInterfaceSP CreateScriptedFrameInterface() override;
+ lldb::ScriptedFrameProviderInterfaceSP
+ CreateScriptedFrameProviderInterface() override;
+
lldb::ScriptedThreadPlanInterfaceSP
CreateScriptedThreadPlanInterface() override;
diff --git a/lldb/unittests/ScriptInterpreter/Python/PythonTestSuite.cpp b/lldb/unittests/ScriptInterpreter/Python/PythonTestSuite.cpp
index 6f5d9fd97ee28..b0680ef15b42d 100644
--- a/lldb/unittests/ScriptInterpreter/Python/PythonTestSuite.cpp
+++ b/lldb/unittests/ScriptInterpreter/Python/PythonTestSuite.cpp
@@ -160,6 +160,11 @@ void *lldb_private::python::LLDBSWIGPython_CastPyObjectToSBExecutionContext(
return nullptr;
}
+void *
+lldb_private::python::LLDBSWIGPython_CastPyObjectToSBFrameList(PyObject *data) {
+ return nullptr;
+}
+
lldb::ValueObjectSP
lldb_private::python::SWIGBridge::LLDBSWIGPython_GetValueObjectSPFromSBValue(
void *data) {
@@ -328,6 +333,11 @@ lldb_private::python::SWIGBridge::ToSWIGWrapper(lldb::ProcessSP) {
return python::PythonObject();
}
+python::PythonObject
+lldb_private::python::SWIGBridge::ToSWIGWrapper(lldb::StackFrameListSP) {
+ return python::PythonObject();
+}
+
python::PythonObject lldb_private::python::SWIGBridge::ToSWIGWrapper(
const lldb_private::StructuredDataImpl &) {
return python::PythonObject();
>From dc85137f79601417f3924e6483137641d473373a Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Mon, 27 Oct 2025 15:10:32 -0700
Subject: [PATCH 3/4] [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 the real StackFrameList.
This is the foundation work to implement ScriptedFrameProviders, which
will come in a follow-up patch.
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
lldb/include/lldb/Core/PluginManager.h | 11 ++
.../lldb/Target/SyntheticFrameProvider.h | 115 ++++++++++++++++++
lldb/include/lldb/lldb-private-interfaces.h | 2 +
lldb/source/Core/PluginManager.cpp | 29 +++++
lldb/source/Target/CMakeLists.txt | 1 +
lldb/source/Target/SyntheticFrameProvider.cpp | 50 ++++++++
6 files changed, 208 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..fb8248d544b86 100644
--- a/lldb/include/lldb/Core/PluginManager.h
+++ b/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
diff --git a/lldb/include/lldb/Target/SyntheticFrameProvider.h b/lldb/include/lldb/Target/SyntheticFrameProvider.h
new file mode 100644
index 0000000000000..5ef3efe21e9c3
--- /dev/null
+++ b/lldb/include/lldb/Target/SyntheticFrameProvider.h
@@ -0,0 +1,115 @@
+//===-- SyntheticFrameProvider.h --------------------------------*- 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/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 IDs to which this provider applies.
+ /// If empty, the provider applies to all threads.
+ std::vector<lldb::tid_t> thread_ids;
+
+ SyntheticFrameProviderDescriptor() = default;
+
+ SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp)
+ : scripted_metadata_sp(metadata_sp) {}
+
+ SyntheticFrameProviderDescriptor(lldb::ScriptedMetadataSP metadata_sp,
+ const std::vector<lldb::tid_t> &tids)
+ : scripted_metadata_sp(metadata_sp), thread_ids(tids) {}
+
+ /// Check if this descriptor applies to the given thread ID.
+ bool AppliesToThread(lldb::tid_t tid) const {
+ // If no thread IDs specified, applies to all threads
+ if (thread_ids.empty())
+ return true;
+
+ // Check if the thread ID is in the filter list
+ return std::find(thread_ids.begin(), thread_ids.end(), tid) !=
+ thread_ids.end();
+ }
+
+ /// Check if this descriptor has valid metadata.
+ bool IsValid() const { return scripted_metadata_sp != nullptr; }
+};
+
+/// 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 thread
+ /// and metadata.
+ ///
+ /// This method iterates through all registered SyntheticFrameProvider
+ /// plugins and returns the first one that can handle the given metadata.
+ ///
+ /// \param[in] thread_sp
+ /// The thread for which to provide synthetic frames.
+ ///
+ /// \return
+ /// A shared pointer to a SyntheticFrameProvider if one could be created,
+ /// otherwise an \a llvm::Error.
+ static llvm::Expected<lldb::SyntheticFrameProviderSP>
+ CreateInstance(lldb::ThreadSP thread_sp);
+
+ ~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 real unwound frames via
+ /// GetThread()->GetStackFrameList() if needed for reference.
+ ///
+ /// \param[in] real_frames
+ /// The actual unwound frames from the thread's normal unwinder.
+ ///
+ /// \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(lldb::StackFrameListSP real_frames, uint32_t idx) = 0;
+
+ /// Get the thread associated with this provider.
+ lldb::ThreadSP GetThread() const { return m_thread_sp; }
+
+protected:
+ SyntheticFrameProvider(lldb::ThreadSP thread_sp);
+
+ lldb::ThreadSP m_thread_sp;
+};
+
+} // namespace lldb_private
+
+#endif // LLDB_TARGET_SYNTHETICFRAMEPROVIDER_H
diff --git a/lldb/include/lldb/lldb-private-interfaces.h b/lldb/include/lldb/lldb-private-interfaces.h
index 249b25c251ac2..dad0dccfe8873 100644
--- a/lldb/include/lldb/lldb-private-interfaces.h
+++ b/lldb/include/lldb/lldb-private-interfaces.h
@@ -86,6 +86,8 @@ typedef lldb::RegisterTypeBuilderSP (*RegisterTypeBuilderCreateInstance)(
Target &target);
typedef lldb::ScriptInterpreterSP (*ScriptInterpreterCreateInstance)(
Debugger &debugger);
+typedef llvm::Expected<lldb::SyntheticFrameProviderSP> (
+ *SyntheticFrameProviderCreateInstance)(lldb::ThreadSP thread_sp);
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..720ded14613dd 100644
--- a/lldb/source/Core/PluginManager.cpp
+++ b/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
diff --git a/lldb/source/Target/CMakeLists.txt b/lldb/source/Target/CMakeLists.txt
index b7788e80eecac..de020f3d57d7f 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..964838c39d7f9
--- /dev/null
+++ b/lldb/source/Target/SyntheticFrameProvider.cpp
@@ -0,0 +1,50 @@
+//===-- SyntheticFrameProvider.cpp ----------------------------------------===//
+//
+// 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(ThreadSP thread_sp)
+ : m_thread_sp(std::move(thread_sp)) {}
+
+SyntheticFrameProvider::~SyntheticFrameProvider() = default;
+
+llvm::Expected<SyntheticFrameProviderSP>
+SyntheticFrameProvider::CreateInstance(ThreadSP thread_sp) {
+ if (!thread_sp)
+ return llvm::createStringError(
+ "cannot create synthetic frame provider: Invalid thread");
+
+ // 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(thread_sp);
+ 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");
+}
>From 575de5d96edef7308673b6c55f8180b02fe17e85 Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Tue, 28 Oct 2025 02:10:02 -0700
Subject: [PATCH 4/4] [lldb] Add support for ScriptedFrame with real threads
This patch extends ScriptedFrame to work with real (non-scripted) threads,
enabling frame providers to synthesize frames for native processes.
Previously, ScriptedFrame only worked within ScriptedProcess/ScriptedThread
contexts. This patch decouples ScriptedFrame from ScriptedThread, allowing
users to augment or replace stack frames in real debugging sessions for use
cases like custom calling conventions, reconstructing corrupted frames from
core files, or adding diagnostic frames.
Key changes:
- ScriptedFrame::Create() now accepts ThreadSP instead of requiring
ScriptedThread, extracting architecture from the target triple rather
than ScriptedProcess.arch
- Added SBTarget::RegisterScriptedFrameProvider() and
ClearScriptedFrameProvider() APIs, with Target storing a
SyntheticFrameProviderDescriptor template for new threads
- Added "target frame-provider register/clear" commands for CLI access
- Thread class gains LoadScriptedFrameProvider(), ClearScriptedFrameProvider(),
and GetFrameProvider() methods for per-thread frame provider management
- New SyntheticStackFrameList overrides FetchFramesUpTo() to lazily provide
frames from either the frame provider or the real stack
This enables practical use of the SyntheticFrameProvider infrastructure in
real debugging workflows.
rdar://161834688
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
.../python/templates/scripted_process.py | 41 ++-
lldb/include/lldb/API/SBTarget.h | 19 ++
lldb/include/lldb/Target/StackFrame.h | 5 +-
lldb/include/lldb/Target/StackFrameList.h | 35 ++-
lldb/include/lldb/Target/Target.h | 21 ++
lldb/include/lldb/Target/Thread.h | 11 +
lldb/include/lldb/Utility/ScriptedMetadata.h | 3 +
lldb/source/API/SBTarget.cpp | 54 ++++
lldb/source/Commands/CommandObjectTarget.cpp | 107 ++++++++
lldb/source/Plugins/CMakeLists.txt | 1 +
.../Process/scripted/ScriptedFrame.cpp | 87 ++++--
.../Plugins/Process/scripted/ScriptedFrame.h | 34 ++-
.../Process/scripted/ScriptedThread.cpp | 6 +-
.../SyntheticFrameProvider/CMakeLists.txt | 1 +
.../ScriptedFrameProvider/CMakeLists.txt | 12 +
.../ScriptedFrameProvider.cpp | 232 ++++++++++++++++
.../ScriptedFrameProvider.h | 62 +++++
lldb/source/Target/StackFrameList.cpp | 33 +++
lldb/source/Target/Target.cpp | 31 +++
lldb/source/Target/Thread.cpp | 59 +++-
.../scripted_frame_provider/Makefile | 3 +
.../TestScriptedFrameProvider.py | 254 ++++++++++++++++++
.../c_python_frame_provider.py | 61 +++++
.../scripted_frame_provider/main.c | 14 +
.../test_frame_providers.py | 134 +++++++++
25 files changed, 1257 insertions(+), 63 deletions(-)
create mode 100644 lldb/source/Plugins/SyntheticFrameProvider/CMakeLists.txt
create mode 100644 lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/CMakeLists.txt
create mode 100644 lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.cpp
create mode 100644 lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.h
create mode 100644 lldb/test/API/functionalities/scripted_frame_provider/Makefile
create mode 100644 lldb/test/API/functionalities/scripted_frame_provider/TestScriptedFrameProvider.py
create mode 100644 lldb/test/API/functionalities/scripted_frame_provider/c_python_frame_provider.py
create mode 100644 lldb/test/API/functionalities/scripted_frame_provider/main.c
create mode 100644 lldb/test/API/functionalities/scripted_frame_provider/test_frame_providers.py
diff --git a/lldb/examples/python/templates/scripted_process.py b/lldb/examples/python/templates/scripted_process.py
index 49059d533f38a..6242978100711 100644
--- a/lldb/examples/python/templates/scripted_process.py
+++ b/lldb/examples/python/templates/scripted_process.py
@@ -245,6 +245,7 @@ def __init__(self, process, args):
key/value pairs used by the scripted thread.
"""
self.target = None
+ self.arch = None
self.originating_process = None
self.process = None
self.args = None
@@ -266,6 +267,9 @@ def __init__(self, process, args):
and process.IsValid()
):
self.target = process.target
+ triple = self.target.triple
+ if triple:
+ self.arch = triple.split("-")[0]
self.originating_process = process
self.process = self.target.GetProcess()
self.get_register_info()
@@ -352,17 +356,14 @@ def get_stackframes(self):
def get_register_info(self):
if self.register_info is None:
self.register_info = dict()
- if "x86_64" in self.originating_process.arch:
+ if "x86_64" in self.arch:
self.register_info["sets"] = ["General Purpose Registers"]
self.register_info["registers"] = INTEL64_GPR
- elif (
- "arm64" in self.originating_process.arch
- or self.originating_process.arch == "aarch64"
- ):
+ elif "arm64" in self.arch or self.arch == "aarch64":
self.register_info["sets"] = ["General Purpose Registers"]
self.register_info["registers"] = ARM64_GPR
else:
- raise ValueError("Unknown architecture", self.originating_process.arch)
+ raise ValueError("Unknown architecture", self.arch)
return self.register_info
@abstractmethod
@@ -405,11 +406,12 @@ def __init__(self, thread, args):
"""Construct a scripted frame.
Args:
- thread (ScriptedThread): The thread owning this frame.
+ thread (ScriptedThread/lldb.SBThread): The thread owning this frame.
args (lldb.SBStructuredData): A Dictionary holding arbitrary
key/value pairs used by the scripted frame.
"""
self.target = None
+ self.arch = None
self.originating_thread = None
self.thread = None
self.args = None
@@ -424,10 +426,14 @@ def __init__(self, thread, args):
or isinstance(thread, lldb.SBThread)
and thread.IsValid()
):
- self.target = thread.target
self.process = thread.process
+ self.target = self.process.target
+ triple = self.target.triple
+ if triple:
+ self.arch = triple.split("-")[0]
+ tid = thread.tid if isinstance(thread, ScriptedThread) else thread.id
self.originating_thread = thread
- self.thread = self.process.GetThreadByIndexID(thread.tid)
+ self.thread = self.process.GetThreadByIndexID(tid)
self.get_register_info()
@abstractmethod
@@ -508,7 +514,18 @@ def get_variables(self, filters):
def get_register_info(self):
if self.register_info is None:
- self.register_info = self.originating_thread.get_register_info()
+ if isinstance(self.originating_thread, ScriptedThread):
+ self.register_info = self.originating_thread.get_register_info()
+ elif isinstance(self.originating_thread, lldb.SBThread):
+ self.register_info = dict()
+ if "x86_64" in self.arch:
+ self.register_info["sets"] = ["General Purpose Registers"]
+ self.register_info["registers"] = INTEL64_GPR
+ elif "arm64" in self.arch or self.arch == "aarch64":
+ self.register_info["sets"] = ["General Purpose Registers"]
+ self.register_info["registers"] = ARM64_GPR
+ else:
+ raise ValueError("Unknown architecture", self.arch)
return self.register_info
@abstractmethod
@@ -642,12 +659,12 @@ def get_stop_reason(self):
# TODO: Passthrough stop reason from driving process
if self.driving_thread.GetStopReason() != lldb.eStopReasonNone:
- if "arm64" in self.originating_process.arch:
+ if "arm64" in self.arch:
stop_reason["type"] = lldb.eStopReasonException
stop_reason["data"]["desc"] = (
self.driving_thread.GetStopDescription(100)
)
- elif self.originating_process.arch == "x86_64":
+ elif self.arch == "x86_64":
stop_reason["type"] = lldb.eStopReasonSignal
stop_reason["data"]["signal"] = signal.SIGTRAP
else:
diff --git a/lldb/include/lldb/API/SBTarget.h b/lldb/include/lldb/API/SBTarget.h
index 173fd05b54a13..2c5d4f9b81bc3 100644
--- a/lldb/include/lldb/API/SBTarget.h
+++ b/lldb/include/lldb/API/SBTarget.h
@@ -986,6 +986,25 @@ class LLDB_API SBTarget {
lldb::SBMutex GetAPIMutex() const;
+ /// Register a scripted frame provider for this target.
+ ///
+ /// \param[in] class_name
+ /// The name of the Python class that implements the frame provider.
+ ///
+ /// \param[in] args_dict
+ /// A dictionary of arguments to pass to the frame provider class.
+ ///
+ /// \return
+ /// An error object indicating success or failure.
+ lldb::SBError RegisterScriptedFrameProvider(const char *class_name,
+ lldb::SBStructuredData args_dict);
+
+ /// Clear the scripted frame provider for this target.
+ ///
+ /// \return
+ /// An error object indicating success or failure.
+ lldb::SBError ClearScriptedFrameProvider();
+
protected:
friend class SBAddress;
friend class SBAddressRange;
diff --git a/lldb/include/lldb/Target/StackFrame.h b/lldb/include/lldb/Target/StackFrame.h
index cdbe8ae3c6779..9cfbf58df0e2d 100644
--- a/lldb/include/lldb/Target/StackFrame.h
+++ b/lldb/include/lldb/Target/StackFrame.h
@@ -442,7 +442,10 @@ class StackFrame : public ExecutionContextScope,
uint32_t GetFrameIndex() const;
/// Set this frame's synthetic frame index.
- void SetFrameIndex(uint32_t index) { m_frame_index = index; }
+ void SetFrameIndex(uint32_t index) {
+ m_frame_index = index;
+ m_concrete_frame_index = index;
+ }
/// Query this frame to find what frame it is in this Thread's
/// StackFrameList, not counting inlined frames.
diff --git a/lldb/include/lldb/Target/StackFrameList.h b/lldb/include/lldb/Target/StackFrameList.h
index ea9aab86b8ea1..176f2752e0452 100644
--- a/lldb/include/lldb/Target/StackFrameList.h
+++ b/lldb/include/lldb/Target/StackFrameList.h
@@ -20,13 +20,13 @@ namespace lldb_private {
class ScriptedThread;
-class StackFrameList {
+class StackFrameList : public std::enable_shared_from_this<StackFrameList> {
public:
// Constructors and Destructors
StackFrameList(Thread &thread, const lldb::StackFrameListSP &prev_frames_sp,
bool show_inline_frames);
- ~StackFrameList();
+ virtual ~StackFrameList();
/// Get the number of visible frames. Frames may be created if \p can_create
/// is true. Synthetic (inline) frames expanded from the concrete frame #0
@@ -103,6 +103,7 @@ class StackFrameList {
protected:
friend class Thread;
+ friend class ScriptedFrameProvider;
friend class ScriptedThread;
/// Use this API to build a stack frame list (used for scripted threads, for
@@ -208,18 +209,20 @@ class StackFrameList {
/// Whether or not to show synthetic (inline) frames. Immutable.
const bool m_show_inlined_frames;
+ /// These two Fetch frames APIs and SynthesizeTailCallFrames are called in
+ /// GetFramesUpTo, they are the ones that actually add frames. They must be
+ /// called with the writer end of the list mutex held.
+
+ /// Returns true if fetching frames was interrupted, false otherwise.
+ virtual bool FetchFramesUpTo(uint32_t end_idx,
+ InterruptionControl allow_interrupt);
+
private:
uint32_t SetSelectedFrameNoLock(lldb_private::StackFrame *frame);
lldb::StackFrameSP
GetFrameAtIndexNoLock(uint32_t idx,
std::shared_lock<std::shared_mutex> &guard);
- /// These two Fetch frames APIs and SynthesizeTailCallFrames are called in
- /// GetFramesUpTo, they are the ones that actually add frames. They must be
- /// called with the writer end of the list mutex held.
-
- /// Returns true if fetching frames was interrupted, false otherwise.
- bool FetchFramesUpTo(uint32_t end_idx, InterruptionControl allow_interrupt);
/// Not currently interruptible so returns void.
void FetchOnlyConcreteFramesUpTo(uint32_t end_idx);
void SynthesizeTailCallFrames(StackFrame &next_frame);
@@ -228,6 +231,22 @@ class StackFrameList {
const StackFrameList &operator=(const StackFrameList &) = delete;
};
+/// A StackFrameList that wraps another StackFrameList and uses a
+/// SyntheticFrameProvider to lazily provide frames from either the provider
+/// or the underlying real stack frame list.
+class SyntheticStackFrameList : public StackFrameList {
+public:
+ SyntheticStackFrameList(Thread &thread,
+ const lldb::StackFrameListSP &prev_frames_sp,
+ bool show_inline_frames);
+
+protected:
+ /// Override FetchFramesUpTo to lazily return frames from the provider
+ /// or from the actual stack frame list.
+ bool FetchFramesUpTo(uint32_t end_idx,
+ InterruptionControl allow_interrupt) override;
+};
+
} // namespace lldb_private
#endif // LLDB_TARGET_STACKFRAMELIST_H
diff --git a/lldb/include/lldb/Target/Target.h b/lldb/include/lldb/Target/Target.h
index c375df248154f..e1e24128c105b 100644
--- a/lldb/include/lldb/Target/Target.h
+++ b/lldb/include/lldb/Target/Target.h
@@ -32,6 +32,7 @@
#include "lldb/Target/PathMappingList.h"
#include "lldb/Target/SectionLoadHistory.h"
#include "lldb/Target/Statistics.h"
+#include "lldb/Target/SyntheticFrameProvider.h"
#include "lldb/Target/ThreadSpec.h"
#include "lldb/Utility/ArchSpec.h"
#include "lldb/Utility/Broadcaster.h"
@@ -697,6 +698,21 @@ class Target : public std::enable_shared_from_this<Target>,
Status Attach(ProcessAttachInfo &attach_info,
Stream *stream); // Optional stream to receive first stop info
+ // Frame provider methods
+
+ /// Set the scripted frame provider descriptor for this target.
+ /// All new threads in this target will use this descriptor to create their
+ /// frame providers.
+ Status SetScriptedFrameProviderDescriptor(
+ const SyntheticFrameProviderDescriptor &descriptor);
+
+ /// Clear the scripted frame provider descriptor for this target.
+ void ClearScriptedFrameProviderDescriptor();
+
+ /// Get the scripted frame provider descriptor for this target, if set.
+ std::optional<SyntheticFrameProviderDescriptor>
+ GetScriptedFrameProviderDescriptor() const;
+
// This part handles the breakpoints.
BreakpointList &GetBreakpointList(bool internal = false);
@@ -1682,6 +1698,11 @@ class Target : public std::enable_shared_from_this<Target>,
PathMappingList m_image_search_paths;
TypeSystemMap m_scratch_type_system_map;
+ /// The scripted frame provider descriptor for this target, if set.
+ /// Used to initialize frame providers for new threads.
+ std::optional<SyntheticFrameProviderDescriptor> m_frame_provider_descriptor;
+ mutable std::recursive_mutex m_frame_provider_descriptor_mutex;
+
typedef std::map<lldb::LanguageType, lldb::REPLSP> REPLMap;
REPLMap m_repl_map;
diff --git a/lldb/include/lldb/Target/Thread.h b/lldb/include/lldb/Target/Thread.h
index 841f80cd1b1eb..ba0a0566a56af 100644
--- a/lldb/include/lldb/Target/Thread.h
+++ b/lldb/include/lldb/Target/Thread.h
@@ -1297,6 +1297,14 @@ class Thread : public std::enable_shared_from_this<Thread>,
lldb::StackFrameListSP GetStackFrameList();
+ llvm::Error LoadScriptedFrameProvider();
+
+ void ClearScriptedFrameProvider();
+
+ lldb::SyntheticFrameProviderSP GetFrameProvider() const {
+ return m_frame_provider_sp;
+ }
+
protected:
friend class ThreadPlan;
friend class ThreadList;
@@ -1400,6 +1408,9 @@ class Thread : public std::enable_shared_from_this<Thread>,
/// The Thread backed by this thread, if any.
lldb::ThreadWP m_backed_thread;
+ /// The Scripted Frame Provider, if any.
+ lldb::SyntheticFrameProviderSP m_frame_provider_sp;
+
private:
bool m_extended_info_fetched; // Have we tried to retrieve the m_extended_info
// for this thread?
diff --git a/lldb/include/lldb/Utility/ScriptedMetadata.h b/lldb/include/lldb/Utility/ScriptedMetadata.h
index 69c83edce909a..369e7ca720a3b 100644
--- a/lldb/include/lldb/Utility/ScriptedMetadata.h
+++ b/lldb/include/lldb/Utility/ScriptedMetadata.h
@@ -27,6 +27,9 @@ class ScriptedMetadata {
}
}
+ ScriptedMetadata(const ScriptedMetadata &other)
+ : m_class_name(other.m_class_name), m_args_sp(other.m_args_sp) {}
+
explicit operator bool() const { return !m_class_name.empty(); }
llvm::StringRef GetClassName() const { return m_class_name; }
diff --git a/lldb/source/API/SBTarget.cpp b/lldb/source/API/SBTarget.cpp
index 98d10aa07c53f..80e55373dda99 100644
--- a/lldb/source/API/SBTarget.cpp
+++ b/lldb/source/API/SBTarget.cpp
@@ -50,6 +50,7 @@
#include "lldb/Target/LanguageRuntime.h"
#include "lldb/Target/Process.h"
#include "lldb/Target/StackFrame.h"
+#include "lldb/Target/SyntheticFrameProvider.h"
#include "lldb/Target/Target.h"
#include "lldb/Target/TargetList.h"
#include "lldb/Utility/ArchSpec.h"
@@ -59,6 +60,7 @@
#include "lldb/Utility/LLDBLog.h"
#include "lldb/Utility/ProcessInfo.h"
#include "lldb/Utility/RegularExpression.h"
+#include "lldb/Utility/ScriptedMetadata.h"
#include "lldb/ValueObject/ValueObjectConstResult.h"
#include "lldb/ValueObject/ValueObjectList.h"
#include "lldb/ValueObject/ValueObjectVariable.h"
@@ -2408,3 +2410,55 @@ lldb::SBMutex SBTarget::GetAPIMutex() const {
return lldb::SBMutex(target_sp);
return lldb::SBMutex();
}
+
+lldb::SBError
+SBTarget::RegisterScriptedFrameProvider(const char *class_name,
+ lldb::SBStructuredData args_dict) {
+ LLDB_INSTRUMENT_VA(this, class_name, args_dict);
+
+ SBError error;
+ TargetSP target_sp = GetSP();
+ if (!target_sp) {
+ error.SetErrorString("invalid target");
+ return error;
+ }
+
+ if (!class_name || !class_name[0]) {
+ error.SetErrorString("invalid class name");
+ return error;
+ }
+
+ // Extract the dictionary from SBStructuredData
+ StructuredData::DictionarySP dict_sp;
+ if (args_dict.IsValid() && args_dict.m_impl_up) {
+ StructuredData::ObjectSP obj_sp = args_dict.m_impl_up->GetObjectSP();
+ if (obj_sp && obj_sp->GetType() == lldb::eStructuredDataTypeDictionary) {
+ dict_sp = std::make_shared<StructuredData::Dictionary>(obj_sp);
+ }
+ }
+
+ // Create the ScriptedMetadata
+ ScriptedMetadataSP metadata_sp =
+ std::make_shared<ScriptedMetadata>(class_name, dict_sp);
+
+ // Create a descriptor (applies to all threads by default)
+ SyntheticFrameProviderDescriptor descriptor(metadata_sp);
+
+ // Register the descriptor with the target
+ return target_sp->SetScriptedFrameProviderDescriptor(descriptor);
+}
+
+lldb::SBError SBTarget::ClearScriptedFrameProvider() {
+ LLDB_INSTRUMENT_VA(this);
+
+ SBError error;
+ TargetSP target_sp = GetSP();
+ if (!target_sp) {
+ error.SetErrorString("invalid target");
+ return error;
+ }
+
+ target_sp->ClearScriptedFrameProviderDescriptor();
+
+ return {};
+}
diff --git a/lldb/source/Commands/CommandObjectTarget.cpp b/lldb/source/Commands/CommandObjectTarget.cpp
index 8de6521e65b25..f6a3d0119d44e 100644
--- a/lldb/source/Commands/CommandObjectTarget.cpp
+++ b/lldb/source/Commands/CommandObjectTarget.cpp
@@ -51,6 +51,7 @@
#include "lldb/Utility/ConstString.h"
#include "lldb/Utility/FileSpec.h"
#include "lldb/Utility/LLDBLog.h"
+#include "lldb/Utility/ScriptedMetadata.h"
#include "lldb/Utility/State.h"
#include "lldb/Utility/Stream.h"
#include "lldb/Utility/StructuredData.h"
@@ -5392,6 +5393,109 @@ class CommandObjectTargetDump : public CommandObjectMultiword {
~CommandObjectTargetDump() override = default;
};
+#pragma mark CommandObjectTargetFrameProvider
+
+#define LLDB_OPTIONS_target_frame_provider_register
+#include "CommandOptions.inc"
+
+class CommandObjectTargetFrameProviderRegister : public CommandObjectParsed {
+public:
+ CommandObjectTargetFrameProviderRegister(CommandInterpreter &interpreter)
+ : CommandObjectParsed(
+ interpreter, "target frame-provider register",
+ "Register frame provider for all threads in this target.", nullptr,
+ eCommandRequiresTarget),
+
+ m_class_options("target frame-provider", true, 'C', 'k', 'v', 0) {
+ m_all_options.Append(&m_class_options, LLDB_OPT_SET_1 | LLDB_OPT_SET_2,
+ LLDB_OPT_SET_ALL);
+ m_all_options.Finalize();
+
+ AddSimpleArgumentList(eArgTypeRunArgs, eArgRepeatOptional);
+ }
+
+ ~CommandObjectTargetFrameProviderRegister() override = default;
+
+ Options *GetOptions() override { return &m_all_options; }
+
+ std::optional<std::string> GetRepeatCommand(Args ¤t_command_args,
+ uint32_t index) override {
+ return std::string("");
+ }
+
+protected:
+ void DoExecute(Args &launch_args, CommandReturnObject &result) override {
+ ScriptedMetadataSP metadata_sp = std::make_shared<ScriptedMetadata>(
+ m_class_options.GetName(), m_class_options.GetStructuredData());
+
+ Target *target = m_exe_ctx.GetTargetPtr();
+ if (!target) {
+ result.AppendError("invalid target");
+ return;
+ }
+
+ // Create a descriptor from the metadata (applies to all threads by default)
+ SyntheticFrameProviderDescriptor descriptor(metadata_sp);
+
+ Status error = target->SetScriptedFrameProviderDescriptor(descriptor);
+ if (error.Success())
+ result.AppendMessageWithFormat(
+ "Successfully registered scripted frame provider '%s' for target\n",
+ m_class_options.GetName().c_str());
+ result.SetError(std::move(error));
+ }
+
+ OptionGroupPythonClassWithDict m_class_options;
+ OptionGroupOptions m_all_options;
+};
+
+class CommandObjectTargetFrameProviderClear : public CommandObjectParsed {
+public:
+ CommandObjectTargetFrameProviderClear(CommandInterpreter &interpreter)
+ : CommandObjectParsed(interpreter, "target frame-provider clear",
+ "Delete registered frame provider from target.",
+ nullptr, eCommandRequiresTarget) {}
+
+ ~CommandObjectTargetFrameProviderClear() override = default;
+
+protected:
+ void DoExecute(Args &command, CommandReturnObject &result) override {
+ Target *target = m_exe_ctx.GetTargetPtr();
+ if (!target) {
+ result.AppendError("invalid target");
+ return;
+ }
+
+ target->ClearScriptedFrameProviderDescriptor();
+ if (ProcessSP process_sp = target->GetProcessSP()) {
+ for (ThreadSP thread_sp : process_sp->Threads()) {
+ thread_sp->ClearScriptedFrameProvider();
+ }
+ }
+
+ result.SetStatus(eReturnStatusSuccessFinishResult);
+ }
+};
+
+class CommandObjectTargetFrameProvider : public CommandObjectMultiword {
+public:
+ CommandObjectTargetFrameProvider(CommandInterpreter &interpreter)
+ : CommandObjectMultiword(
+ interpreter, "target frame-provider",
+ "Commands for registering and viewing frame providers for the "
+ "target.",
+ "target frame-provider [<sub-command-options>] ") {
+ LoadSubCommand("register",
+ CommandObjectSP(new CommandObjectTargetFrameProviderRegister(
+ interpreter)));
+ LoadSubCommand("clear",
+ CommandObjectSP(
+ new CommandObjectTargetFrameProviderClear(interpreter)));
+ }
+
+ ~CommandObjectTargetFrameProvider() override = default;
+};
+
#pragma mark CommandObjectMultiwordTarget
// CommandObjectMultiwordTarget
@@ -5407,6 +5511,9 @@ CommandObjectMultiwordTarget::CommandObjectMultiwordTarget(
CommandObjectSP(new CommandObjectTargetDelete(interpreter)));
LoadSubCommand("dump",
CommandObjectSP(new CommandObjectTargetDump(interpreter)));
+ LoadSubCommand(
+ "frame-provider",
+ CommandObjectSP(new CommandObjectTargetFrameProvider(interpreter)));
LoadSubCommand("list",
CommandObjectSP(new CommandObjectTargetList(interpreter)));
LoadSubCommand("select",
diff --git a/lldb/source/Plugins/CMakeLists.txt b/lldb/source/Plugins/CMakeLists.txt
index 08f444e7b15e8..b6878b21ff71a 100644
--- a/lldb/source/Plugins/CMakeLists.txt
+++ b/lldb/source/Plugins/CMakeLists.txt
@@ -22,6 +22,7 @@ add_subdirectory(SymbolFile)
add_subdirectory(SystemRuntime)
add_subdirectory(SymbolLocator)
add_subdirectory(SymbolVendor)
+add_subdirectory(SyntheticFrameProvider)
add_subdirectory(Trace)
add_subdirectory(TraceExporter)
add_subdirectory(TypeSystem)
diff --git a/lldb/source/Plugins/Process/scripted/ScriptedFrame.cpp b/lldb/source/Plugins/Process/scripted/ScriptedFrame.cpp
index 6519df9185df0..1b68408031f07 100644
--- a/lldb/source/Plugins/Process/scripted/ScriptedFrame.cpp
+++ b/lldb/source/Plugins/Process/scripted/ScriptedFrame.cpp
@@ -1,4 +1,4 @@
-//===----------------------------------------------------------------------===//
+//===-- ScriptedFrame.cpp -------------------------------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
@@ -7,8 +7,22 @@
//===----------------------------------------------------------------------===//
#include "ScriptedFrame.h"
-
+#include "Plugins/Process/Utility/RegisterContextMemory.h"
+
+#include "lldb/Core/Address.h"
+#include "lldb/Core/Debugger.h"
+#include "lldb/Interpreter/Interfaces/ScriptedFrameInterface.h"
+#include "lldb/Interpreter/Interfaces/ScriptedThreadInterface.h"
+#include "lldb/Interpreter/ScriptInterpreter.h"
+#include "lldb/Symbol/SymbolContext.h"
+#include "lldb/Target/ExecutionContext.h"
+#include "lldb/Target/Process.h"
+#include "lldb/Target/RegisterContext.h"
+#include "lldb/Target/Thread.h"
#include "lldb/Utility/DataBufferHeap.h"
+#include "lldb/Utility/LLDBLog.h"
+#include "lldb/Utility/Log.h"
+#include "lldb/Utility/StructuredData.h"
using namespace lldb;
using namespace lldb_private;
@@ -19,42 +33,56 @@ void ScriptedFrame::CheckInterpreterAndScriptObject() const {
}
llvm::Expected<std::shared_ptr<ScriptedFrame>>
-ScriptedFrame::Create(ScriptedThread &thread,
+ScriptedFrame::Create(ThreadSP thread_sp,
+ ScriptedThreadInterfaceSP scripted_thread_interface_sp,
StructuredData::DictionarySP args_sp,
StructuredData::Generic *script_object) {
- if (!thread.IsValid())
- return llvm::createStringError("Invalid scripted thread.");
+ if (!thread_sp || !thread_sp->IsValid())
+ return llvm::createStringError("Invalid thread.");
- thread.CheckInterpreterAndScriptObject();
+ ProcessSP process_sp = thread_sp->GetProcess();
+ if (!process_sp || !process_sp->IsValid())
+ return llvm::createStringError("Invalid process.");
- auto scripted_frame_interface =
- thread.GetInterface()->CreateScriptedFrameInterface();
+ ScriptInterpreter *script_interp =
+ process_sp->GetTarget().GetDebugger().GetScriptInterpreter();
+ if (!script_interp)
+ return llvm::createStringError("No script interpreter.");
+
+ auto scripted_frame_interface = script_interp->CreateScriptedFrameInterface();
if (!scripted_frame_interface)
- return llvm::createStringError("failed to create scripted frame interface");
+ return llvm::createStringError("Failed to create scripted frame interface");
llvm::StringRef frame_class_name;
if (!script_object) {
- std::optional<std::string> class_name =
- thread.GetInterface()->GetScriptedFramePluginName();
- if (!class_name || class_name->empty())
+ // If no script object is provided and we have a scripted thread interface,
+ // try to get the frame class name from it
+ if (scripted_thread_interface_sp) {
+ std::optional<std::string> class_name =
+ scripted_thread_interface_sp->GetScriptedFramePluginName();
+ if (!class_name || class_name->empty())
+ return llvm::createStringError(
+ "Failed to get scripted frame class name");
+ frame_class_name = *class_name;
+ } else {
return llvm::createStringError(
- "failed to get scripted thread class name");
- frame_class_name = *class_name;
+ "No script object provided and no scripted thread interface");
+ }
}
- ExecutionContext exe_ctx(thread);
+ ExecutionContext exe_ctx(thread_sp);
auto obj_or_err = scripted_frame_interface->CreatePluginObject(
frame_class_name, exe_ctx, args_sp, script_object);
if (!obj_or_err)
return llvm::createStringError(
- "failed to create script object: %s",
+ "Failed to create script object: %s",
llvm::toString(obj_or_err.takeError()).c_str());
StructuredData::GenericSP owned_script_object_sp = *obj_or_err;
if (!owned_script_object_sp->IsValid())
- return llvm::createStringError("created script object is invalid");
+ return llvm::createStringError("Created script object is invalid");
lldb::user_id_t frame_id = scripted_frame_interface->GetID();
@@ -62,7 +90,7 @@ ScriptedFrame::Create(ScriptedThread &thread,
SymbolContext sc;
Address symbol_addr;
if (pc != LLDB_INVALID_ADDRESS) {
- symbol_addr.SetLoadAddress(pc, &thread.GetProcess()->GetTarget());
+ symbol_addr.SetLoadAddress(pc, &process_sp->GetTarget());
symbol_addr.CalculateSymbolContext(&sc);
}
@@ -77,11 +105,11 @@ ScriptedFrame::Create(ScriptedThread &thread,
if (!reg_info)
return llvm::createStringError(
- "failed to get scripted thread registers info");
+ "Failed to get scripted frame registers info");
std::shared_ptr<DynamicRegisterInfo> register_info_sp =
- DynamicRegisterInfo::Create(
- *reg_info, thread.GetProcess()->GetTarget().GetArchitecture());
+ DynamicRegisterInfo::Create(*reg_info,
+ process_sp->GetTarget().GetArchitecture());
lldb::RegisterContextSP reg_ctx_sp;
@@ -92,36 +120,39 @@ ScriptedFrame::Create(ScriptedThread &thread,
std::make_shared<DataBufferHeap>(reg_data->c_str(), reg_data->size()));
if (!data_sp->GetByteSize())
- return llvm::createStringError("failed to copy raw registers data");
+ return llvm::createStringError("Failed to copy raw registers data");
std::shared_ptr<RegisterContextMemory> reg_ctx_memory =
std::make_shared<RegisterContextMemory>(
- thread, frame_id, *register_info_sp, LLDB_INVALID_ADDRESS);
+ *thread_sp, frame_id, *register_info_sp, LLDB_INVALID_ADDRESS);
if (!reg_ctx_memory)
- return llvm::createStringError("failed to create a register context.");
+ return llvm::createStringError("Failed to create a register context.");
reg_ctx_memory->SetAllRegisterData(data_sp);
reg_ctx_sp = reg_ctx_memory;
}
return std::make_shared<ScriptedFrame>(
- thread, scripted_frame_interface, frame_id, pc, sc, reg_ctx_sp,
+ thread_sp, scripted_frame_interface, frame_id, pc, sc, reg_ctx_sp,
register_info_sp, owned_script_object_sp);
}
-ScriptedFrame::ScriptedFrame(ScriptedThread &thread,
+ScriptedFrame::ScriptedFrame(ThreadSP thread_sp,
ScriptedFrameInterfaceSP interface_sp,
lldb::user_id_t id, lldb::addr_t pc,
SymbolContext &sym_ctx,
lldb::RegisterContextSP reg_ctx_sp,
std::shared_ptr<DynamicRegisterInfo> reg_info_sp,
StructuredData::GenericSP script_object_sp)
- : StackFrame(thread.shared_from_this(), /*frame_idx=*/id,
+ : StackFrame(thread_sp, /*frame_idx=*/id,
/*concrete_frame_idx=*/id, /*reg_context_sp=*/reg_ctx_sp,
/*cfa=*/0, /*pc=*/pc,
/*behaves_like_zeroth_frame=*/!id, /*symbol_ctx=*/&sym_ctx),
m_scripted_frame_interface_sp(interface_sp),
- m_script_object_sp(script_object_sp), m_register_info_sp(reg_info_sp) {}
+ m_script_object_sp(script_object_sp), m_register_info_sp(reg_info_sp) {
+ // FIXME: This should be part of the base class constructor
+ m_stack_frame_kind = StackFrame::Kind::Synthetic;
+}
ScriptedFrame::~ScriptedFrame() {}
diff --git a/lldb/source/Plugins/Process/scripted/ScriptedFrame.h b/lldb/source/Plugins/Process/scripted/ScriptedFrame.h
index b6b77c4a7d160..452ce6dc53ad2 100644
--- a/lldb/source/Plugins/Process/scripted/ScriptedFrame.h
+++ b/lldb/source/Plugins/Process/scripted/ScriptedFrame.h
@@ -1,4 +1,4 @@
-//===----------------------------------------------------------------------===//
+//===-- ScriptedFrame.h -----------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
@@ -10,21 +10,19 @@
#define LLDB_SOURCE_PLUGINS_SCRIPTED_FRAME_H
#include "ScriptedThread.h"
-#include "lldb/Interpreter/ScriptInterpreter.h"
#include "lldb/Target/DynamicRegisterInfo.h"
#include "lldb/Target/StackFrame.h"
+#include "lldb/lldb-forward.h"
+#include "llvm/Support/Error.h"
+#include <memory>
#include <string>
-namespace lldb_private {
-class ScriptedThread;
-}
-
namespace lldb_private {
class ScriptedFrame : public lldb_private::StackFrame {
public:
- ScriptedFrame(ScriptedThread &thread,
+ ScriptedFrame(lldb::ThreadSP thread_sp,
lldb::ScriptedFrameInterfaceSP interface_sp,
lldb::user_id_t frame_idx, lldb::addr_t pc,
SymbolContext &sym_ctx, lldb::RegisterContextSP reg_ctx_sp,
@@ -33,8 +31,28 @@ class ScriptedFrame : public lldb_private::StackFrame {
~ScriptedFrame() override;
+ /// Create a ScriptedFrame from a script object.
+ ///
+ /// \param[in] thread_sp
+ /// The thread this frame belongs to.
+ ///
+ /// \param[in] scripted_thread_interface_sp
+ /// The scripted thread interface (needed for ScriptedThread
+ /// compatibility). Can be nullptr for frames on real threads.
+ ///
+ /// \param[in] args_sp
+ /// Arguments to pass to the frame creation.
+ ///
+ /// \param[in] script_object
+ /// The script object representing this frame.
+ ///
+ /// \return
+ /// An Expected containing the ScriptedFrame shared pointer if successful,
+ /// otherwise an error.
static llvm::Expected<std::shared_ptr<ScriptedFrame>>
- Create(ScriptedThread &thread, StructuredData::DictionarySP args_sp,
+ Create(lldb::ThreadSP thread_sp,
+ lldb::ScriptedThreadInterfaceSP scripted_thread_interface_sp,
+ StructuredData::DictionarySP args_sp,
StructuredData::Generic *script_object = nullptr);
bool IsInlined() override;
diff --git a/lldb/source/Plugins/Process/scripted/ScriptedThread.cpp b/lldb/source/Plugins/Process/scripted/ScriptedThread.cpp
index 491efac5aadef..1dd9c48f56a59 100644
--- a/lldb/source/Plugins/Process/scripted/ScriptedThread.cpp
+++ b/lldb/source/Plugins/Process/scripted/ScriptedThread.cpp
@@ -210,7 +210,7 @@ bool ScriptedThread::LoadArtificialStackFrames() {
SymbolContext sc;
symbol_addr.CalculateSymbolContext(&sc);
- return std::make_shared<StackFrame>(this->shared_from_this(), idx, idx, cfa,
+ return std::make_shared<StackFrame>(shared_from_this(), idx, idx, cfa,
cfa_is_valid, pc,
StackFrame::Kind::Synthetic, artificial,
behaves_like_zeroth_frame, &sc);
@@ -231,8 +231,8 @@ bool ScriptedThread::LoadArtificialStackFrames() {
return error.ToError();
}
- auto frame_or_error =
- ScriptedFrame::Create(*this, nullptr, object_sp->GetAsGeneric());
+ auto frame_or_error = ScriptedFrame::Create(
+ shared_from_this(), GetInterface(), nullptr, object_sp->GetAsGeneric());
if (!frame_or_error) {
ScriptedInterface::ErrorWithMessage<bool>(
diff --git a/lldb/source/Plugins/SyntheticFrameProvider/CMakeLists.txt b/lldb/source/Plugins/SyntheticFrameProvider/CMakeLists.txt
new file mode 100644
index 0000000000000..85b405e648c1f
--- /dev/null
+++ b/lldb/source/Plugins/SyntheticFrameProvider/CMakeLists.txt
@@ -0,0 +1 @@
+add_subdirectory(ScriptedFrameProvider)
diff --git a/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/CMakeLists.txt b/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/CMakeLists.txt
new file mode 100644
index 0000000000000..fe67d39efdf11
--- /dev/null
+++ b/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/CMakeLists.txt
@@ -0,0 +1,12 @@
+add_lldb_library(lldbPluginScriptedFrameProvider PLUGIN
+ ScriptedFrameProvider.cpp
+
+ LINK_COMPONENTS
+ Support
+
+ LINK_LIBS
+ lldbCore
+ lldbInterpreter
+ lldbTarget
+ lldbUtility
+ )
diff --git a/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.cpp b/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.cpp
new file mode 100644
index 0000000000000..11383b8d995ef
--- /dev/null
+++ b/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.cpp
@@ -0,0 +1,232 @@
+//===-- ScriptedFrameProvider.cpp ----------------------------------------===//
+//
+// 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 "ScriptedFrameProvider.h"
+#include "Plugins/Process/scripted/ScriptedFrame.h"
+#include "lldb/Core/Debugger.h"
+#include "lldb/Core/PluginManager.h"
+#include "lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h"
+#include "lldb/Interpreter/ScriptInterpreter.h"
+#include "lldb/Target/Process.h"
+#include "lldb/Target/StackFrame.h"
+#include "lldb/Target/Thread.h"
+#include "lldb/Utility/ScriptedMetadata.h"
+#include "lldb/Utility/Status.h"
+#include "llvm/Support/Error.h"
+#include <cstdint>
+
+using namespace lldb;
+using namespace lldb_private;
+
+void ScriptedFrameProvider::Initialize() {
+ PluginManager::RegisterPlugin(GetPluginNameStatic(),
+ "Provides synthetic frames via scripting",
+ ScriptedFrameProvider::CreateInstance);
+}
+
+void ScriptedFrameProvider::Terminate() {
+ PluginManager::UnregisterPlugin(ScriptedFrameProvider::CreateInstance);
+}
+
+llvm::Expected<lldb::SyntheticFrameProviderSP>
+ScriptedFrameProvider::CreateInstance(lldb::ThreadSP thread_sp) {
+ if (!thread_sp)
+ return llvm::createStringError(
+ "failed to create scripted frame: invalid thread");
+
+ ProcessSP process_sp = thread_sp->GetProcess();
+ if (!process_sp)
+ return nullptr;
+
+ Target &target = process_sp->GetTarget();
+
+ Status error;
+ if (auto descriptor = target.GetScriptedFrameProviderDescriptor()) {
+ if (!descriptor->IsValid())
+ return llvm::createStringError(
+ "failed to create scripted frame: invalid scripted metadata");
+
+ if (!descriptor->AppliesToThread(thread_sp->GetID()))
+ return nullptr;
+
+ auto provider_sp = std::make_shared<ScriptedFrameProvider>(
+ thread_sp, *descriptor->scripted_metadata_sp, error);
+ if (!provider_sp || error.Fail())
+ return error.ToError();
+
+ return provider_sp;
+ }
+
+ return llvm::createStringError(
+ "failed to create scripted frame: invalid scripted metadata");
+}
+
+ScriptedFrameProvider::ScriptedFrameProvider(
+ ThreadSP thread_sp, const ScriptedMetadata &scripted_metadata,
+ Status &error)
+ : SyntheticFrameProvider(thread_sp), m_interface_sp(nullptr) {
+ if (!m_thread_sp) {
+ error = Status::FromErrorString(
+ "cannot create scripted frame provider: Invalid thread");
+ return;
+ }
+
+ ProcessSP process_sp = m_thread_sp->GetProcess();
+ if (!process_sp) {
+ error = Status::FromErrorString(
+ "cannot create scripted frame provider: Invalid process");
+ return;
+ }
+
+ ScriptInterpreter *script_interp =
+ process_sp->GetTarget().GetDebugger().GetScriptInterpreter();
+ if (!script_interp) {
+ error = Status::FromErrorString("cannot create scripted frame provider: No "
+ "script interpreter installed");
+ return;
+ }
+
+ m_interface_sp = script_interp->CreateScriptedFrameProviderInterface();
+ if (!m_interface_sp) {
+ error = Status::FromErrorString(
+ "cannot create scripted frame provider: Script interpreter couldn't "
+ "create Scripted Frame Provider Interface");
+ return;
+ }
+
+ auto obj_or_err = m_interface_sp->CreatePluginObject(
+ scripted_metadata.GetClassName(), m_thread_sp,
+ scripted_metadata.GetArgsSP());
+ if (!obj_or_err) {
+ error = Status::FromError(obj_or_err.takeError());
+ return;
+ }
+
+ StructuredData::ObjectSP object_sp = *obj_or_err;
+ if (!object_sp || !object_sp->IsValid()) {
+ error = Status::FromErrorString(
+ "cannot create scripted frame provider: Failed to create valid script "
+ "object");
+ return;
+ }
+
+ error.Clear();
+}
+
+ScriptedFrameProvider::~ScriptedFrameProvider() = default;
+
+llvm::Expected<StackFrameSP>
+ScriptedFrameProvider::GetFrameAtIndex(StackFrameListSP real_frames,
+ uint32_t idx) {
+ if (!m_interface_sp)
+ return llvm::createStringError(
+ "cannot get stack frame: Scripted frame provider not initialized");
+
+ auto create_frame_from_dict =
+ [this](StructuredData::Dictionary *dict,
+ uint32_t index) -> llvm::Expected<StackFrameSP> {
+ lldb::addr_t pc;
+ if (!dict->GetValueForKeyAsInteger("pc", pc))
+ return llvm::createStringError(
+ "missing 'pc' key from scripted frame dictionary.");
+
+ Address symbol_addr;
+ symbol_addr.SetLoadAddress(pc, &m_thread_sp->GetProcess()->GetTarget());
+
+ lldb::addr_t cfa = LLDB_INVALID_ADDRESS;
+ bool cfa_is_valid = false;
+ const bool artificial = false;
+ const bool behaves_like_zeroth_frame = false;
+ SymbolContext sc;
+ symbol_addr.CalculateSymbolContext(&sc);
+
+ return std::make_shared<StackFrame>(m_thread_sp, index, index, cfa,
+ cfa_is_valid, pc,
+ StackFrame::Kind::Synthetic, artificial,
+ behaves_like_zeroth_frame, &sc);
+ };
+
+ auto create_frame_from_script_object =
+ [this](
+ StructuredData::ObjectSP object_sp) -> llvm::Expected<StackFrameSP> {
+ Status error;
+ if (!object_sp || !object_sp->GetAsGeneric())
+ return llvm::createStringError("invalid script object");
+
+ auto frame_or_error = ScriptedFrame::Create(m_thread_sp, nullptr, nullptr,
+ object_sp->GetAsGeneric());
+
+ if (!frame_or_error) {
+ ScriptedInterface::ErrorWithMessage<bool>(
+ LLVM_PRETTY_FUNCTION, toString(frame_or_error.takeError()), error);
+ return error.ToError();
+ }
+
+ StackFrameSP frame_sp = frame_or_error.get();
+ lldbassert(frame_sp && "Couldn't initialize scripted frame.");
+
+ return frame_sp;
+ };
+
+ StructuredData::ObjectSP obj_sp =
+ m_interface_sp->GetFrameAtIndex(real_frames, idx);
+
+ // None/null means no more frames or error
+ if (!obj_sp || !obj_sp->IsValid())
+ return llvm::createStringError("invalid script object returned for frame " +
+ llvm::Twine(idx));
+
+ StackFrameSP synth_frame_sp = nullptr;
+ if (auto *int_obj = obj_sp->GetAsUnsignedInteger()) {
+ uint32_t real_frame_index = int_obj->GetValue();
+ if (real_frame_index < real_frames->GetNumFrames()) {
+ synth_frame_sp = real_frames->GetFrameAtIndex(real_frame_index);
+ }
+ } else if (auto *dict = obj_sp->GetAsDictionary()) {
+ // Check if it's a dictionary describing a frame
+ auto frame_from_dict_or_err = create_frame_from_dict(dict, idx);
+ if (!frame_from_dict_or_err) {
+ return llvm::createStringError(llvm::Twine(
+ "Couldn't create frame from dictionary at index " + llvm::Twine(idx) +
+ ": " + toString(frame_from_dict_or_err.takeError())));
+ }
+ synth_frame_sp = *frame_from_dict_or_err;
+ } else if (obj_sp->GetAsGeneric()) {
+ // It's a ScriptedFrame object
+ auto frame_from_script_obj_or_err = create_frame_from_script_object(obj_sp);
+ if (!frame_from_script_obj_or_err) {
+ return llvm::createStringError(
+ llvm::Twine("Couldn't create frame from script object at index " +
+ llvm::Twine(idx) + ": " +
+ toString(frame_from_script_obj_or_err.takeError())));
+ }
+ synth_frame_sp = *frame_from_script_obj_or_err;
+ } else {
+ return llvm::createStringError(
+ llvm::Twine("Invalid return type from get_frame_at_index at index " +
+ llvm::Twine(idx)));
+ }
+
+ if (!synth_frame_sp)
+ return llvm::createStringError(
+ llvm::Twine("Failed to create frame at index " + llvm::Twine(idx)));
+
+ synth_frame_sp->SetFrameIndex(idx);
+
+ return synth_frame_sp;
+}
+
+namespace lldb_private {
+void lldb_initialize_ScriptedFrameProvider() {
+ ScriptedFrameProvider::Initialize();
+}
+
+void lldb_terminate_ScriptedFrameProvider() {
+ ScriptedFrameProvider::Terminate();
+}
+} // namespace lldb_private
diff --git a/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.h b/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.h
new file mode 100644
index 0000000000000..fe21a12dbf704
--- /dev/null
+++ b/lldb/source/Plugins/SyntheticFrameProvider/ScriptedFrameProvider/ScriptedFrameProvider.h
@@ -0,0 +1,62 @@
+//===-- ScriptedFrameProvider.h --------------------------------*- 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_PLUGINS_SYNTHETICFRAMEPROVIDER_SCRIPTEDFRAMEPROVIDER_SCRIPTEDFRAMEPROVIDER_H
+#define LLDB_PLUGINS_SYNTHETICFRAMEPROVIDER_SCRIPTEDFRAMEPROVIDER_SCRIPTEDFRAMEPROVIDER_H
+
+#include "lldb/Target/SyntheticFrameProvider.h"
+#include "lldb/Utility/ScriptedMetadata.h"
+#include "lldb/Utility/Status.h"
+#include "lldb/lldb-forward.h"
+#include "llvm/Support/Error.h"
+
+namespace lldb_private {
+
+class ScriptedFrameProvider : public SyntheticFrameProvider {
+public:
+ static llvm::StringRef GetPluginNameStatic() {
+ return "ScriptedFrameProvider";
+ }
+
+ static llvm::Expected<lldb::SyntheticFrameProviderSP>
+ CreateInstance(lldb::ThreadSP thread_sp);
+
+ static void Initialize();
+
+ static void Terminate();
+
+ /// Constructor that initializes the scripted frame provider.
+ ///
+ /// \param[in] thread_sp
+ /// The thread for which to provide scripted frames.
+ ///
+ /// \param[in] scripted_metadata
+ /// The metadata containing the class name and arguments for the
+ /// scripted frame provider.
+ ///
+ /// \param[out] error
+ /// Status object to report any errors during initialization.
+ ScriptedFrameProvider(lldb::ThreadSP thread_sp,
+ const ScriptedMetadata &scripted_metadata,
+ Status &error);
+ ~ScriptedFrameProvider() override;
+
+ // PluginInterface methods
+ llvm::StringRef GetPluginName() override { return GetPluginNameStatic(); }
+
+ /// Get a single stack frame at the specified index.
+ llvm::Expected<lldb::StackFrameSP>
+ GetFrameAtIndex(lldb::StackFrameListSP real_frames, uint32_t idx) override;
+
+private:
+ lldb::ScriptedFrameProviderInterfaceSP m_interface_sp;
+};
+
+} // namespace lldb_private
+
+#endif // LLDB_PLUGINS_SYNTHETICFRAMEPROVIDER_SCRIPTEDFRAMEPROVIDER_SCRIPTEDFRAMEPROVIDER_H
diff --git a/lldb/source/Target/StackFrameList.cpp b/lldb/source/Target/StackFrameList.cpp
index ccf874fc03ebd..61bf1290a72c9 100644
--- a/lldb/source/Target/StackFrameList.cpp
+++ b/lldb/source/Target/StackFrameList.cpp
@@ -20,6 +20,7 @@
#include "lldb/Target/StackFrame.h"
#include "lldb/Target/StackFrameRecognizer.h"
#include "lldb/Target/StopInfo.h"
+#include "lldb/Target/SyntheticFrameProvider.h"
#include "lldb/Target/Target.h"
#include "lldb/Target/Thread.h"
#include "lldb/Target/Unwind.h"
@@ -55,6 +56,38 @@ StackFrameList::~StackFrameList() {
Clear();
}
+SyntheticStackFrameList::SyntheticStackFrameList(
+ Thread &thread, const lldb::StackFrameListSP &prev_frames_sp,
+ bool show_inline_frames)
+ : StackFrameList(thread, prev_frames_sp, show_inline_frames) {}
+
+bool SyntheticStackFrameList::FetchFramesUpTo(
+ uint32_t end_idx, InterruptionControl allow_interrupt) {
+ // Check if the thread has a synthetic frame provider
+ if (auto provider_sp = m_thread.GetFrameProvider()) {
+ // Use the synthetic frame provider to generate frames lazily
+ // Keep fetching until we reach end_idx or the provider returns an error
+ StackFrameListSP real_frames = std::make_shared<StackFrameList>(
+ m_thread, m_prev_frames_sp, m_show_inlined_frames);
+ for (uint32_t idx = m_frames.size(); idx <= end_idx; idx++) {
+ auto frame_or_err = provider_sp->GetFrameAtIndex(real_frames, idx);
+ if (!frame_or_err) {
+ // Provider returned error - we've reached the end
+ LLDB_LOG_ERROR(GetLog(LLDBLog::Thread), frame_or_err.takeError(),
+ "Frame provider reached end at index {0}: {1}", idx);
+ SetAllFramesFetched();
+ break;
+ }
+ m_frames.push_back(*frame_or_err);
+ }
+
+ return false; // Not interrupted
+ }
+
+ // If no provider, fall back to the base implementation
+ return StackFrameList::FetchFramesUpTo(end_idx, allow_interrupt);
+}
+
void StackFrameList::CalculateCurrentInlinedDepth() {
uint32_t cur_inlined_depth = GetCurrentInlinedDepth();
if (cur_inlined_depth == UINT32_MAX) {
diff --git a/lldb/source/Target/Target.cpp b/lldb/source/Target/Target.cpp
index d070c3d953d4a..8f23d0fd823fa 100644
--- a/lldb/source/Target/Target.cpp
+++ b/lldb/source/Target/Target.cpp
@@ -3712,6 +3712,37 @@ Status Target::Attach(ProcessAttachInfo &attach_info, Stream *stream) {
return error;
}
+Status Target::SetScriptedFrameProviderDescriptor(
+ const SyntheticFrameProviderDescriptor &descriptor) {
+ std::lock_guard<std::recursive_mutex> guard(
+ m_frame_provider_descriptor_mutex);
+ m_frame_provider_descriptor = descriptor;
+ if (ProcessSP process_sp = GetProcessSP()) {
+ for (ThreadSP thread_sp : process_sp->Threads()) {
+ thread_sp->ClearScriptedFrameProvider();
+ }
+ }
+ return {};
+}
+
+void Target::ClearScriptedFrameProviderDescriptor() {
+ std::lock_guard<std::recursive_mutex> guard(
+ m_frame_provider_descriptor_mutex);
+ m_frame_provider_descriptor.reset();
+ if (ProcessSP process_sp = GetProcessSP()) {
+ for (ThreadSP thread_sp : process_sp->Threads()) {
+ thread_sp->ClearScriptedFrameProvider();
+ }
+ }
+}
+
+std::optional<SyntheticFrameProviderDescriptor>
+Target::GetScriptedFrameProviderDescriptor() const {
+ std::lock_guard<std::recursive_mutex> guard(
+ m_frame_provider_descriptor_mutex);
+ return m_frame_provider_descriptor;
+}
+
void Target::FinalizeFileActions(ProcessLaunchInfo &info) {
Log *log = GetLog(LLDBLog::Process);
diff --git a/lldb/source/Target/Thread.cpp b/lldb/source/Target/Thread.cpp
index 8c3e19725f8cb..94b8954e8c7e2 100644
--- a/lldb/source/Target/Thread.cpp
+++ b/lldb/source/Target/Thread.cpp
@@ -13,9 +13,12 @@
#include "lldb/Core/Module.h"
#include "lldb/Core/StructuredDataImpl.h"
#include "lldb/Host/Host.h"
+#include "lldb/Interpreter/Interfaces/ScriptedFrameInterface.h"
+#include "lldb/Interpreter/Interfaces/ScriptedFrameProviderInterface.h"
#include "lldb/Interpreter/OptionValueFileSpecList.h"
#include "lldb/Interpreter/OptionValueProperties.h"
#include "lldb/Interpreter/Property.h"
+#include "lldb/Interpreter/ScriptInterpreter.h"
#include "lldb/Symbol/Function.h"
#include "lldb/Target/ABI.h"
#include "lldb/Target/DynamicLoader.h"
@@ -26,6 +29,7 @@
#include "lldb/Target/ScriptedThreadPlan.h"
#include "lldb/Target/StackFrameRecognizer.h"
#include "lldb/Target/StopInfo.h"
+#include "lldb/Target/SyntheticFrameProvider.h"
#include "lldb/Target/SystemRuntime.h"
#include "lldb/Target/Target.h"
#include "lldb/Target/ThreadPlan.h"
@@ -45,6 +49,7 @@
#include "lldb/Utility/LLDBLog.h"
#include "lldb/Utility/Log.h"
#include "lldb/Utility/RegularExpression.h"
+#include "lldb/Utility/ScriptedMetadata.h"
#include "lldb/Utility/State.h"
#include "lldb/Utility/Stream.h"
#include "lldb/Utility/StreamString.h"
@@ -257,6 +262,7 @@ void Thread::DestroyThread() {
std::lock_guard<std::recursive_mutex> guard(m_frame_mutex);
m_curr_frames_sp.reset();
m_prev_frames_sp.reset();
+ m_frame_provider_sp.reset();
m_prev_framezero_pc.reset();
}
@@ -1439,13 +1445,59 @@ void Thread::CalculateExecutionContext(ExecutionContext &exe_ctx) {
StackFrameListSP Thread::GetStackFrameList() {
std::lock_guard<std::recursive_mutex> guard(m_frame_mutex);
- if (!m_curr_frames_sp)
- m_curr_frames_sp =
- std::make_shared<StackFrameList>(*this, m_prev_frames_sp, true);
+ if (!m_curr_frames_sp) {
+ // Try to load the frame provider if we don't have one yet
+ if (!m_frame_provider_sp) {
+ ProcessSP process_sp = GetProcess();
+ if (process_sp) {
+ Target &target = process_sp->GetTarget();
+ auto descriptor = target.GetScriptedFrameProviderDescriptor();
+ if (descriptor && descriptor->IsValid()) {
+ // Check if this descriptor applies to this thread
+ if (descriptor->AppliesToThread(GetID())) {
+ if (llvm::Error error = LoadScriptedFrameProvider()) {
+ LLDB_LOG_ERROR(GetLog(LLDBLog::Thread), std::move(error),
+ "Failed to load scripted frame provider: {0}");
+
+ } else {
+ m_curr_frames_sp = std::make_shared<SyntheticStackFrameList>(
+ *this, m_prev_frames_sp, true);
+ }
+ }
+ }
+ }
+ } else {
+ m_curr_frames_sp = std::make_shared<SyntheticStackFrameList>(
+ *this, m_prev_frames_sp, true);
+ }
+ }
return m_curr_frames_sp;
}
+llvm::Error Thread::LoadScriptedFrameProvider() {
+ std::lock_guard<std::recursive_mutex> guard(m_frame_mutex);
+
+ auto provider_or_err =
+ SyntheticFrameProvider::CreateInstance(shared_from_this());
+ if (!provider_or_err)
+ return provider_or_err.takeError();
+
+ ClearScriptedFrameProvider();
+ m_frame_provider_sp = *provider_or_err;
+ return llvm::Error::success();
+}
+
+void Thread::ClearScriptedFrameProvider() {
+ std::lock_guard<std::recursive_mutex> guard(m_frame_mutex);
+ if (m_frame_provider_sp)
+ m_frame_provider_sp.reset();
+ if (m_curr_frames_sp)
+ m_curr_frames_sp.reset();
+ if (m_prev_frames_sp)
+ m_prev_frames_sp.reset();
+}
+
std::optional<addr_t> Thread::GetPreviousFrameZeroPC() {
return m_prev_framezero_pc;
}
@@ -1466,6 +1518,7 @@ void Thread::ClearStackFrames() {
m_prev_frames_sp.swap(m_curr_frames_sp);
m_curr_frames_sp.reset();
+ m_frame_provider_sp.reset();
m_extended_info.reset();
m_extended_info_fetched = false;
}
diff --git a/lldb/test/API/functionalities/scripted_frame_provider/Makefile b/lldb/test/API/functionalities/scripted_frame_provider/Makefile
new file mode 100644
index 0000000000000..451278a0946ef
--- /dev/null
+++ b/lldb/test/API/functionalities/scripted_frame_provider/Makefile
@@ -0,0 +1,3 @@
+C_SOURCES := main.c
+
+include Makefile.rules
\ No newline at end of file
diff --git a/lldb/test/API/functionalities/scripted_frame_provider/TestScriptedFrameProvider.py b/lldb/test/API/functionalities/scripted_frame_provider/TestScriptedFrameProvider.py
new file mode 100644
index 0000000000000..a0cf6462562f9
--- /dev/null
+++ b/lldb/test/API/functionalities/scripted_frame_provider/TestScriptedFrameProvider.py
@@ -0,0 +1,254 @@
+"""
+Test scripted frame provider functionality with all merge strategies.
+"""
+
+import os
+
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+
+class ScriptedFrameProviderTestCase(TestBase):
+ NO_DEBUG_INFO_TESTCASE = True
+
+ def setUp(self):
+ TestBase.setUp(self)
+ self.source = "main.c"
+
+ def test_replace_strategy(self):
+ """Test that Replace strategy replaces entire stack."""
+ self.build()
+ exe = self.getBuildArtifact("a.out")
+
+ target = self.dbg.CreateTarget(exe)
+ self.assertTrue(target, VALID_TARGET)
+
+ # Import the test frame provider
+ script_path = os.path.join(self.getSourceDir(), "test_frame_providers.py")
+ self.runCmd("command script import " + script_path)
+
+ # Attach the Replace provider
+ target.RegisterScriptedFrameProvider(
+ "test_frame_providers.ReplaceFrameProvider", lldb.SBStructuredData()
+ )
+
+ target, process, thread, bkpt = lldbutil.run_to_source_breakpoint(
+ self, "Break here", lldb.SBFileSpec(self.source)
+ )
+
+ # Verify we have exactly 3 synthetic frames
+ self.assertEqual(thread.GetNumFrames(), 3, "Should have 3 synthetic frames")
+
+ # Verify frame indices and PCs (dictionary-based frames don't have custom function names)
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertIsNotNone(frame0)
+ self.assertEqual(frame0.GetPC(), 0x1000)
+
+ frame1 = thread.GetFrameAtIndex(1)
+ self.assertIsNotNone(frame1)
+ self.assertIn("main", frame1.GetFunctionName())
+
+ frame2 = thread.GetFrameAtIndex(2)
+ self.assertIsNotNone(frame2)
+ self.assertEqual(frame2.GetPC(), 0x3000)
+
+ def test_prepend_strategy(self):
+ """Test that Prepend strategy adds frames before real stack."""
+ self.build()
+ exe = self.getBuildArtifact("a.out")
+
+ target = self.dbg.CreateTarget(exe)
+ self.assertTrue(target, VALID_TARGET)
+
+ target, process, thread, bkpt = lldbutil.run_to_source_breakpoint(
+ self, "Break here", lldb.SBFileSpec(self.source)
+ )
+
+ # Get original frame count and PC
+ original_frame_count = thread.GetNumFrames()
+ self.assertGreaterEqual(
+ original_frame_count, 2, "Should have at least 2 real frames"
+ )
+ original_frame_0_pc = thread.GetFrameAtIndex(0).GetPC()
+
+ # Import and attach Prepend provider
+ script_path = os.path.join(self.getSourceDir(), "test_frame_providers.py")
+ self.runCmd("command script import " + script_path)
+
+ target.RegisterScriptedFrameProvider(
+ "test_frame_providers.PrependFrameProvider", lldb.SBStructuredData()
+ )
+
+ # Verify we have 2 more frames
+ new_frame_count = thread.GetNumFrames()
+ self.assertEqual(new_frame_count, original_frame_count + 2)
+
+ # Verify first 2 frames are synthetic (check PCs, not function names)
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertEqual(frame0.GetPC(), 0x9000)
+
+ frame1 = thread.GetFrameAtIndex(1)
+ self.assertEqual(frame1.GetPC(), 0xA000)
+
+ # Verify frame 2 is the original real frame 0
+ frame2 = thread.GetFrameAtIndex(2)
+ self.assertIn("foo", frame2.GetFunctionName())
+
+ def test_append_strategy(self):
+ """Test that Append strategy adds frames after real stack."""
+ self.build()
+ target, process, thread, bkpt = lldbutil.run_to_source_breakpoint(
+ self, "Break here", lldb.SBFileSpec(self.source)
+ )
+
+ # Get original frame count
+ original_frame_count = thread.GetNumFrames()
+
+ # Import and attach Append provider
+ script_path = os.path.join(self.getSourceDir(), "test_frame_providers.py")
+ self.runCmd("command script import " + script_path)
+
+ target.RegisterScriptedFrameProvider(
+ "test_frame_providers.AppendFrameProvider", lldb.SBStructuredData()
+ )
+
+ # Verify we have 2 more frames
+ new_frame_count = thread.GetNumFrames()
+ self.assertEqual(new_frame_count, original_frame_count + 1)
+
+ # Verify first frames are still real
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertIn("foo", frame0.GetFunctionName())
+
+ frame_n_plus_1 = thread.GetFrameAtIndex(new_frame_count - 1)
+ self.assertEqual(frame_n_plus_1.GetPC(), 0x10)
+
+ def test_replace_by_index_strategy(self):
+ """Test that ReplaceByIndex strategy replaces specific frames."""
+ self.build()
+ target, process, thread, bkpt = lldbutil.run_to_source_breakpoint(
+ self, "Break here", lldb.SBFileSpec(self.source)
+ )
+
+ # Get original frame count and info
+ original_frame_count = thread.GetNumFrames()
+ self.assertGreaterEqual(original_frame_count, 3, "Need at least 3 frames")
+
+ original_frame_0_pc = thread.GetFrameAtIndex(0).GetPC()
+ original_frame_1 = thread.GetFrameAtIndex(1)
+ original_frame_1_name = original_frame_1.GetFunctionName()
+ original_frame_2_pc = thread.GetFrameAtIndex(2).GetPC()
+
+ # Import and attach ReplaceByIndex provider
+ script_path = os.path.join(self.getSourceDir(), "test_frame_providers.py")
+ self.runCmd("command script import " + script_path)
+
+ target.RegisterScriptedFrameProvider(
+ "test_frame_providers.ReplaceByIndexFrameProvider", lldb.SBStructuredData()
+ )
+
+ # Verify frame count unchanged
+ self.assertEqual(
+ thread.GetNumFrames(),
+ original_frame_count,
+ "Frame count should remain the same",
+ )
+
+ # Verify frame 0 is replaced (PC should match original since provider uses it)
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertIsNotNone(frame0)
+ self.assertEqual(
+ frame0.GetPC(), original_frame_0_pc, "Frame 0 should be replaced"
+ )
+
+ # Verify frame 1 is still the original (not replaced)
+ frame1 = thread.GetFrameAtIndex(1)
+ self.assertIsNotNone(frame1)
+ self.assertEqual(
+ frame1.GetFunctionName(),
+ original_frame_1_name,
+ "Frame 1 should remain unchanged",
+ )
+
+ # Verify frame 2 is replaced (PC should match original since provider uses it)
+ frame2 = thread.GetFrameAtIndex(2)
+ self.assertIsNotNone(frame2)
+ self.assertEqual(
+ frame2.GetPC(), original_frame_2_pc, "Frame 2 should be replaced"
+ )
+
+ def test_clear_frame_provider(self):
+ """Test that clearing provider restores normal unwinding."""
+ self.build()
+ target, process, thread, bkpt = lldbutil.run_to_source_breakpoint(
+ self, "Break here", lldb.SBFileSpec(self.source)
+ )
+
+ # Get original state
+ original_frame_0 = thread.GetFrameAtIndex(0)
+ original_frame_0_name = original_frame_0.GetFunctionName()
+ original_frame_count = thread.GetNumFrames()
+
+ # Import and attach provider
+ script_path = os.path.join(self.getSourceDir(), "test_frame_providers.py")
+ self.runCmd("command script import " + script_path)
+
+ target.RegisterScriptedFrameProvider(
+ "test_frame_providers.ReplaceFrameProvider", lldb.SBStructuredData()
+ )
+
+ # Verify frames are synthetic (3 frames with specific PCs)
+ self.assertEqual(thread.GetNumFrames(), 3)
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertEqual(frame0.GetPC(), 0x1000)
+
+ # Clear the provider
+ target.ClearScriptedFrameProvider()
+
+ # Verify frames are back to normal
+ self.assertEqual(thread.GetNumFrames(), original_frame_count)
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertEqual(
+ frame0.GetFunctionName(),
+ original_frame_0_name,
+ "Should restore original frames after clearing provider",
+ )
+
+ def test_scripted_frame_objects(self):
+ """Test that provider can return ScriptedFrame objects."""
+ self.build()
+ target, process, thread, bkpt = lldbutil.run_to_source_breakpoint(
+ self, "Break here", lldb.SBFileSpec(self.source)
+ )
+
+ # Import the provider that returns ScriptedFrame objects
+ script_path = os.path.join(self.getSourceDir(), "test_frame_providers.py")
+ self.runCmd("command script import " + script_path)
+
+ target.RegisterScriptedFrameProvider(
+ "test_frame_providers.ScriptedFrameObjectProvider", lldb.SBStructuredData()
+ )
+
+ # Verify we have 5 frames
+ self.assertEqual(
+ thread.GetNumFrames(), 5, "Should have 5 custom scripted frames"
+ )
+
+ # Verify frame properties from CustomScriptedFrame
+ frame0 = thread.GetFrameAtIndex(0)
+ self.assertIsNotNone(frame0)
+ self.assertEqual(frame0.GetFunctionName(), "custom_scripted_frame_0")
+ self.assertEqual(frame0.GetPC(), 0x5000)
+ self.assertTrue(frame0.IsSynthetic(), "Frame should be marked as synthetic")
+
+ frame1 = thread.GetFrameAtIndex(1)
+ self.assertIsNotNone(frame1)
+ self.assertEqual(frame1.GetPC(), 0x6000)
+
+ frame2 = thread.GetFrameAtIndex(2)
+ self.assertIsNotNone(frame2)
+ self.assertEqual(frame2.GetFunctionName(), "custom_scripted_frame_2")
+ self.assertEqual(frame2.GetPC(), 0x7000)
+ self.assertTrue(frame2.IsSynthetic(), "Frame should be marked as synthetic")
diff --git a/lldb/test/API/functionalities/scripted_frame_provider/c_python_frame_provider.py b/lldb/test/API/functionalities/scripted_frame_provider/c_python_frame_provider.py
new file mode 100644
index 0000000000000..9aebf14059b8f
--- /dev/null
+++ b/lldb/test/API/functionalities/scripted_frame_provider/c_python_frame_provider.py
@@ -0,0 +1,61 @@
+import lldb
+from lldb.plugins.scripted_process import ScriptedFrame
+from lldb.plugins.scripted_frame_provider import ScriptedFrameProvider
+
+import inspect, re
+
+
+class CPythonScriptedFrame(ScriptedFrame):
+ """CPython scripted frame with full control over frame behavior."""
+
+ def __init__(self, thread, idx, py_frame_info):
+ # Initialize structured data args
+ args = lldb.SBStructuredData()
+ super().__init__(thread, args)
+
+ self.idx = idx
+ self.pc = id(py_frame_info.frame)
+ self.function_name = py_frame_info.frame.f_code.co_qualname
+
+ line_entry = lldb.SBLineEntry()
+ line_entry.SetFileSpec(lldb.SBFileSpec(py_frame_info.filename, True))
+ line_entry.SetLine(py_frame_info.positions.lineno)
+ line_entry.SetColumn(py_frame_info.positions.col_offset)
+
+ self.sym_ctx = lldb.SBSymbolContext()
+ self.sym_ctx.SetLineEntry(line_entry)
+
+ def get_id(self):
+ return self.idx
+
+ def get_pc(self):
+ return self.pc
+
+ def get_function_name(self):
+ return self.function_name
+
+ def is_artificial(self):
+ return False
+
+ def is_hidden(self):
+ return False
+
+ def get_symbol_context(self):
+ return self.sym_ctx
+
+ def get_register_context(self):
+ return None
+
+
+class CPythonScriptedFrameProvider(ScriptedFrameProvider):
+ """Provider that returns ScriptedFrame objects instead of dictionaries."""
+
+ def __init__(self, thread, args):
+ super().__init__(thread, args)
+ self.python_frames = inspect.stack()
+
+ def get_frame_at_index(self, real_frames, index):
+ """Return ScriptedFrame object at given index."""
+ if index >= len(self.python_frames):
+ return None
+ return CPythonScriptedFrame(self.thread, index, self.python_frames[index])
diff --git a/lldb/test/API/functionalities/scripted_frame_provider/main.c b/lldb/test/API/functionalities/scripted_frame_provider/main.c
new file mode 100644
index 0000000000000..3ca941fb587a5
--- /dev/null
+++ b/lldb/test/API/functionalities/scripted_frame_provider/main.c
@@ -0,0 +1,14 @@
+// Simple test program with a few stack frames
+
+#include <stdio.h>
+
+int foo(int x) {
+ printf("In foo: %d\n", x); // Break here
+ return x * 2;
+}
+
+int main(int argc, char **argv) {
+ int result = foo(42);
+ printf("Result: %d\n", result);
+ return 0;
+}
\ No newline at end of file
diff --git a/lldb/test/API/functionalities/scripted_frame_provider/test_frame_providers.py b/lldb/test/API/functionalities/scripted_frame_provider/test_frame_providers.py
new file mode 100644
index 0000000000000..1bdc0ea7ac5c6
--- /dev/null
+++ b/lldb/test/API/functionalities/scripted_frame_provider/test_frame_providers.py
@@ -0,0 +1,134 @@
+"""
+Test frame providers for scripted frame provider functionality.
+
+These providers demonstrates various merge strategies:
+- Replace: Replace entire stack
+- Prepend: Add frames before real stack
+- Append: Add frames after real stack
+
+It also shows the ability to mix a dictionary, a ScriptedFrame or an SBFrame
+index to create stackframes
+"""
+
+import lldb
+from lldb.plugins.scripted_process import ScriptedFrame
+from lldb.plugins.scripted_frame_provider import ScriptedFrameProvider
+
+
+class ReplaceFrameProvider(ScriptedFrameProvider):
+ """Replace entire stack with custom frames."""
+
+ def __init__(self, thread, args):
+ super().__init__(thread, args)
+ self.frames = [
+ {
+ "idx": 0,
+ "pc": 0x1000,
+ },
+ 1,
+ {
+ "idx": 2,
+ "pc": 0x3000,
+ },
+ ]
+
+ def get_frame_at_index(self, real_frames, index):
+ # breakpoint()
+ if index >= len(self.frames):
+ return None
+ return self.frames[index]
+
+
+class PrependFrameProvider(ScriptedFrameProvider):
+ """Prepend synthetic frames before real stack."""
+
+ def __init__(self, thread, args):
+ super().__init__(thread, args)
+
+ def get_frame_at_index(self, real_frames, index):
+ if index == 0:
+ return {"pc": 0x9000}
+ elif index == 1:
+ return {"pc": 0xA000}
+ elif index - 2 < len(real_frames):
+ return index - 2 # Return real frame index
+ return None
+
+
+class AppendFrameProvider(ScriptedFrameProvider):
+ """Append synthetic frames after real stack."""
+
+ def __init__(self, thread, args):
+ super().__init__(thread, args)
+
+ def get_frame_at_index(self, real_frames, index):
+ if index < len(real_frames):
+ return index # Return real frame index
+ elif index == len(real_frames):
+ return {
+ "idx": 1,
+ "pc": 0x10,
+ }
+ return None
+
+
+class CustomScriptedFrame(ScriptedFrame):
+ """Custom scripted frame with full control over frame behavior."""
+
+ def __init__(self, thread, idx, pc, function_name):
+ # Initialize structured data args
+ args = lldb.SBStructuredData()
+ super().__init__(thread, args)
+
+ self.idx = idx
+ self.pc = pc
+ self.function_name = function_name
+
+ def get_id(self):
+ """Return the frame index."""
+ return self.idx
+
+ def get_pc(self):
+ """Return the program counter."""
+ return self.pc
+
+ def get_function_name(self):
+ """Return the function name."""
+ return self.function_name
+
+ def is_artificial(self):
+ """Mark as artificial frame."""
+ return False
+
+ def is_hidden(self):
+ """Not hidden."""
+ return False
+
+ def get_register_context(self):
+ """No register context for this test."""
+ return None
+
+
+class ScriptedFrameObjectProvider(ScriptedFrameProvider):
+ """Provider that returns ScriptedFrame objects instead of dictionaries."""
+
+ def __init__(self, thread, args):
+ super().__init__(thread, args)
+
+ def get_frame_at_index(self, real_frames, index):
+ """Return ScriptedFrame objects or dictionaries based on index."""
+ if index == 0:
+ return CustomScriptedFrame(
+ self.thread, 0, 0x5000, "custom_scripted_frame_0"
+ )
+ elif index == 1:
+ return {"pc": 0x6000}
+ elif index == 2:
+ return CustomScriptedFrame(
+ self.thread, 2, 0x7000, "custom_scripted_frame_2"
+ )
+ elif index == 3:
+ return len(real_frames) - 2 # Real frame index
+ elif index == 4:
+ return len(real_frames) - 1 # Real frame index
+ return None
More information about the lldb-commits
mailing list