[Lldb-commits] [lldb] [lldb] Add scripted thread plan python base class to lldb & website (PR #97481)
Med Ismail Bennani via lldb-commits
lldb-commits at lists.llvm.org
Tue Jul 2 14:08:09 PDT 2024
https://github.com/medismailben created https://github.com/llvm/llvm-project/pull/97481
Following a feedback request in #97262, I took out the scripted thread plan python base class from it and make a separate PR for it.
This patch adds the scripted thread plan base python class to the lldb python module as well as the lldb documentation website.
>From bf26ddefb822636d07c383ecf695876acd8e2a93 Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Tue, 2 Jul 2024 14:06:16 -0700
Subject: [PATCH] [lldb] Add scripted thread plan python base class to lldb &
website
Following a feedback request in #97262, I took out the scripted thread
plan python base class from it and make a separate PR for it.
This patch adds the scripted thread plan base python class to the lldb
python module as well as the lldb documentation website.
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
lldb/bindings/python/CMakeLists.txt | 4 +-
lldb/docs/CMakeLists.txt | 1 +
lldb/docs/python_extensions.rst | 39 +++++++++++
.../python/templates/scripted_thread_plan.py | 70 +++++++++++++++++++
4 files changed, 113 insertions(+), 1 deletion(-)
create mode 100644 lldb/docs/python_extensions.rst
create mode 100644 lldb/examples/python/templates/scripted_thread_plan.py
diff --git a/lldb/bindings/python/CMakeLists.txt b/lldb/bindings/python/CMakeLists.txt
index def6941e802bb..69306a384e0b1 100644
--- a/lldb/bindings/python/CMakeLists.txt
+++ b/lldb/bindings/python/CMakeLists.txt
@@ -108,7 +108,9 @@ function(finish_swig_python swig_target lldb_python_bindings_dir lldb_python_tar
"${LLDB_SOURCE_DIR}/examples/python/templates/parsed_cmd.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")
+ "${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py"
+ "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_thread_plan.py"
+ )
if(APPLE)
create_python_package(
diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt
index ed4296bbf03a4..f1664a6965332 100644
--- a/lldb/docs/CMakeLists.txt
+++ b/lldb/docs/CMakeLists.txt
@@ -31,6 +31,7 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_process.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+ COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_thread_plan.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMENT "Copying lldb.py to pretend its a Python package.")
add_dependencies(lldb-python-doc-package swig_wrapper_python lldb-python)
diff --git a/lldb/docs/python_extensions.rst b/lldb/docs/python_extensions.rst
new file mode 100644
index 0000000000000..7e5f1ba6879db
--- /dev/null
+++ b/lldb/docs/python_extensions.rst
@@ -0,0 +1,39 @@
+Python Extensions
+=================
+
+LLDB provides scriptable extensions to augment the debugger's capabilities.
+This gives users the ability to tailor their debugging experience to their own needs.
+
+This page describes some of these scripting extensions:
+
+Operating System Thread Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.operating_system
+ :no-heading:
+ :skip: ScriptedThread
+ :no-inheritance-diagram:
+
+Scripted Process Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_process
+ :no-heading:
+ :skip: ABCMeta
+ :no-inheritance-diagram:
+
+Scripted Platform Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_platform
+ :no-heading:
+ :skip: ABCMeta
+ :no-inheritance-diagram:
+
+Scripted Thread Plan Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_thread_plan
+ :no-heading:
+ :no-inheritance-diagram:
+
diff --git a/lldb/examples/python/templates/scripted_thread_plan.py b/lldb/examples/python/templates/scripted_thread_plan.py
new file mode 100644
index 0000000000000..67396cdfc53a2
--- /dev/null
+++ b/lldb/examples/python/templates/scripted_thread_plan.py
@@ -0,0 +1,70 @@
+from abc import abstractmethod
+
+import lldb
+
+
+class ScriptedThreadPlan:
+ """
+ Class that provides data for an instance of a LLDB 'ScriptedThreadPlan' plug-in class used to construct custom stepping logic.
+
+ """
+
+ def __init__(self, thread_plan: lldb.SBThreadPlan):
+ """Initialization needs a valid lldb.SBThreadPlan object. This plug-in will get created after a live process is valid and has stopped.
+
+ Args:
+ thread_plan (lldb.SBThreadPlan): The underlying `ThreadPlan` that is pushed onto the plan stack.
+ """
+ self.thread_plan = thread_plan
+
+ def explains_stop(self, event: lldb.SBEvent) -> bool:
+ """Each plan is asked from youngest to oldest if it "explains" the stop. The first plan to claim the stop wins.
+
+ Args:
+ event (lldb.SBEvent): The process stop event.
+
+ Returns:
+ bool: `True` if this stop could be claimed by this thread plan, `False` otherwise.
+ Defaults to `True`.
+ """
+ return True
+
+ def is_stale(self) -> bool:
+ """If your plan is no longer relevant (for instance, you were stepping in a particular stack frame, but some other operation pushed that frame off the stack) return True and your plan will get popped.
+
+ Returns:
+ bool: `True` if this thread plan is stale, `False` otherwise.
+ Defaults to `False`.
+ """
+ return False
+
+ def should_stop(self, event: lldb.SBEvent) -> bool:
+ """Whether this thread plan should stop and return control to the user.
+ If your plan is done at this point, call SetPlanComplete on your thread plan instance. Also, do any work you need here to set up the next stage of stepping.
+
+ Args:
+ event (lldb.SBEvent): The process stop event.
+
+ Returns:
+ bool: `True` if this plan wants to stop and return control to the user at this point, `False` otherwise.
+ Defaults to `False`.
+ """
+ self.thread_plan.SetPlanComplete(True)
+ return True
+
+ def should_step(self) -> bool:
+ """Whether this thread plan should instruction step one instruction, or continue till the next breakpoint is hit.
+
+ Returns:
+ bool: `True` if this plan will instruction step one instruction, `False` otherwise.
+ Defaults to `True`.
+ """
+ return True
+
+ def stop_description(self, stream: lldb.SBStream) -> None:
+ """Customize the thread plan stop reason when the thread plan is complete.
+
+ Args:
+ stream (lldb.SBStream): The stream containing the stop description.
+ """
+ pass
More information about the lldb-commits
mailing list