[Lldb-commits] [lldb] [lldb/docs] Add scripting extensions documentation to the website (PR #97262)
Med Ismail Bennani via lldb-commits
lldb-commits at lists.llvm.org
Tue Jul 2 00:27:28 PDT 2024
https://github.com/medismailben updated https://github.com/llvm/llvm-project/pull/97262
>From e08689b3e2482305755b56e4029f201fcf7af05b Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Tue, 2 Jul 2024 00:26:41 -0700
Subject: [PATCH] [lldb/docs] Add scripting extensions documentation to the
website
This patch adds the documentation for a subset of scripting extensions
such as scripted process, scripted thread, operating system threads &
scritped thread plans to the lldb website.
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
lldb/docs/CMakeLists.txt | 9 ++-
lldb/docs/index.rst | 1 +
lldb/docs/python_extensions.rst | 36 ++++++++++
.../python/templates/operating_system.py | 20 +++---
.../python/templates/scripted_platform.py | 25 ++++---
.../python/templates/scripted_process.py | 42 +++++------
.../python/templates/scripted_thread_plan.py | 70 +++++++++++++++++++
7 files changed, 156 insertions(+), 47 deletions(-)
create mode 100644 lldb/docs/python_extensions.rst
create mode 100644 lldb/examples/python/templates/scripted_thread_plan.py
diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt
index f482e91d1b10c..f327596f3ef31 100644
--- a/lldb/docs/CMakeLists.txt
+++ b/lldb/docs/CMakeLists.txt
@@ -25,10 +25,17 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
# Pretend that the SWIG generated API is a Python package.
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lldb)
get_target_property(lldb_bindings_dir swig_wrapper_python BINARY_DIR)
+
add_custom_target(lldb-python-doc-package
COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_bindings_dir}/lldb.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
+ COMMAND "${CMAKE_COMMAND}" -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins"
+ 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)
+
+ add_dependencies(lldb-python-doc-package swig_wrapper_python lldb-python)
# FIXME: Don't treat Sphinx warnings as errors. The files generated by
# automodapi are full of warnings (partly caused by SWIG, our documentation
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index 1e7d69002dd3e..3ce23beec2a5e 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -141,6 +141,7 @@ interesting areas to contribute to lldb.
use/python
use/python-reference
Python API <python_api>
+ Python Extensions <python_extensions>
.. toctree::
diff --git a/lldb/docs/python_extensions.rst b/lldb/docs/python_extensions.rst
new file mode 100644
index 0000000000000..716e3b066c36f
--- /dev/null
+++ b/lldb/docs/python_extensions.rst
@@ -0,0 +1,36 @@
+Python Extensions
+=================
+
+LLDB provides many scriptable extensions to augment the debugger capabilities
+and give the ability to the user to tailor their experience to their own needs.
+
+This page describes some of these scripting extension:
+
+Operating System Thread Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.operating_system
+ :no-heading:
+ :no-inheritance-diagram:
+
+Scripted Process Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_process
+ :no-heading:
+ :no-inheritance-diagram:
+
+Scripted Platform Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_platform
+ :no-heading:
+ :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/operating_system.py b/lldb/examples/python/templates/operating_system.py
index a8053bcaa21af..d83019079ee90 100644
--- a/lldb/examples/python/templates/operating_system.py
+++ b/lldb/examples/python/templates/operating_system.py
@@ -10,16 +10,16 @@ class OperatingSystem(ScriptedThread):
"""
Class that provides data for an instance of a LLDB 'OperatingSystemPython' plug-in class.
- ```
- thread_info = {
- "tid": tid,
- "name": "four",
- "queue": "queue4",
- "state": "stopped",
- "stop_reason": "none",
- "core" : 2
- }
- ```
+ .. code-block:: python
+
+ thread_info = {
+ "tid": tid,
+ "name": "four",
+ "queue": "queue4",
+ "state": "stopped",
+ "stop_reason": "none",
+ "core" : 2
+ }
- tid : thread ID (mandatory)
- name : thread name (optional key/value pair)
diff --git a/lldb/examples/python/templates/scripted_platform.py b/lldb/examples/python/templates/scripted_platform.py
index fb1bde8fd4cb7..5805f99dea4ca 100644
--- a/lldb/examples/python/templates/scripted_platform.py
+++ b/lldb/examples/python/templates/scripted_platform.py
@@ -10,9 +10,6 @@ class ScriptedPlatform(metaclass=ABCMeta):
Most of the base class methods are `@abstractmethod` that need to be
overwritten by the inheriting class.
-
- DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
- THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
"""
processes = None
@@ -32,16 +29,18 @@ def __init__(self, exe_ctx, args):
def list_processes(self):
"""Get a list of processes that are running or that can be attached to on the platform.
- processes = {
- 420: {
- name: a.out,
- arch: aarch64,
- pid: 420,
- parent_pid: 42 (optional),
- uid: 0 (optional),
- gid: 0 (optional),
- },
- }
+ .. code-block:: python
+
+ processes = {
+ 420: {
+ name: a.out,
+ arch: aarch64,
+ pid: 420,
+ parent_pid: 42 (optional),
+ uid: 0 (optional),
+ gid: 0 (optional),
+ },
+ }
Returns:
Dict: The processes represented as a dictionary, with at least the
diff --git a/lldb/examples/python/templates/scripted_process.py b/lldb/examples/python/templates/scripted_process.py
index 3ddcebd128eaa..b7b6499580e50 100644
--- a/lldb/examples/python/templates/scripted_process.py
+++ b/lldb/examples/python/templates/scripted_process.py
@@ -11,9 +11,6 @@ class ScriptedProcess(metaclass=ABCMeta):
Most of the base class methods are `@abstractmethod` that need to be
overwritten by the inheriting class.
-
- DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
- THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
"""
capabilities = None
@@ -106,8 +103,8 @@ def write_memory_at_address(self, addr, data, error):
Args:
addr (int): Address from which we should start reading.
- data (lldb.SBData): An `lldb.SBData` buffer to write to the
- process memory.
+ data (lldb.SBData): An `lldb.SBData` buffer to write to the process
+ memory.
error (lldb.SBError): Error object.
Returns:
@@ -121,13 +118,13 @@ def write_memory_at_address(self, addr, data, error):
def get_loaded_images(self):
"""Get the list of loaded images for the scripted process.
- ```
- scripted_image = {
- uuid = "c6ea2b64-f77c-3d27-9528-74f507b9078b",
- path = "/usr/lib/dyld"
- load_addr = 0xbadc0ffee
- }
- ```
+ .. code-block:: python
+
+ scripted_image = {
+ uuid = "c6ea2b64-f77c-3d27-9528-74f507b9078b",
+ path = "/usr/lib/dyld"
+ load_addr = 0xbadc0ffee
+ }
Returns:
List[scripted_image]: A list of `scripted_image` dictionaries
@@ -238,9 +235,6 @@ class ScriptedThread(metaclass=ABCMeta):
Most of the base class methods are `@abstractmethod` that need to be
overwritten by the inheriting class.
-
- DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
- THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
"""
@abstractmethod
@@ -305,10 +299,12 @@ def get_name(self):
def get_state(self):
"""Get the scripted thread state type.
+ .. code-block:: python
+
eStateStopped, ///< Process or thread is stopped and can be examined.
eStateRunning, ///< Process or thread is running and can't be examined.
- eStateStepping, ///< Process or thread is in the process of stepping and can
- /// not be examined.
+ eStateStepping, ///< Process or thread is in the process of stepping and
+ /// can not be examined.
eStateCrashed, ///< Process or thread has crashed and can be examined.
Returns:
@@ -340,12 +336,12 @@ def get_stop_reason(self):
def get_stackframes(self):
"""Get the list of stack frames for the scripted thread.
- ```
- scripted_frame = {
- idx = 0,
- pc = 0xbadc0ffee
- }
- ```
+ .. code-block:: python
+
+ scripted_frame = {
+ idx = 0,
+ pc = 0xbadc0ffee
+ }
Returns:
List[scripted_frame]: A list of `scripted_frame` dictionaries
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