[Lldb-commits] [lldb] [lldb/docs] Add scripting extensions documentation to the website (PR #97262)
via lldb-commits
lldb-commits at lists.llvm.org
Mon Jul 1 00:33:20 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: Med Ismail Bennani (medismailben)
<details>
<summary>Changes</summary>
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.
---
Full diff: https://github.com/llvm/llvm-project/pull/97262.diff
6 Files Affected:
- (modified) lldb/docs/CMakeLists.txt (+8-1)
- (modified) lldb/docs/use/python.rst (+59)
- (modified) lldb/examples/python/templates/operating_system.py (+9-10)
- (modified) lldb/examples/python/templates/scripted_platform.py (+11-13)
- (modified) lldb/examples/python/templates/scripted_process.py (+16-23)
- (added) lldb/examples/python/templates/scripted_thread_plan.py (+70)
``````````diff
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/use/python.rst b/lldb/docs/use/python.rst
index d9c29d95708c1..39a488c2d84f5 100644
--- a/lldb/docs/use/python.rst
+++ b/lldb/docs/use/python.rst
@@ -11,6 +11,65 @@ some of these things by going through an example, explaining how to use
Python scripting to find a bug in a program that searches for text in a
large binary tree.
+Operating System Thread Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.operating_system
+ :no-heading:
+ :members:
+ :undoc-members:
+ :skip: command
+ :skip: declaration
+ :skip: in_range
+ :skip: is_numeric_type
+ :skip: lldb_iter
+ :no-inheritance-diagram:
+
+Scripted Process Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_process
+ :no-heading:
+ :members:
+ :undoc-members:
+ :skip: ABCMeta
+ :skip: command
+ :skip: declaration
+ :skip: in_range
+ :skip: is_numeric_type
+ :skip: lldb_iter
+ :no-inheritance-diagram:
+
+Scripted Platform Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_platform
+ :no-heading:
+ :members:
+ :undoc-members:
+ :skip: ABCMeta
+ :skip: command
+ :skip: declaration
+ :skip: in_range
+ :skip: is_numeric_type
+ :skip: lldb_iter
+ :no-inheritance-diagram:
+
+Scripted Thread Plan Plugins
+-------------------------------
+
+.. automodapi:: lldb.plugins.scripted_thread_plan
+ :no-heading:
+ :members:
+ :undoc-members:
+ :skip: ABCMeta
+ :skip: command
+ :skip: declaration
+ :skip: in_range
+ :skip: is_numeric_type
+ :skip: lldb_iter
+ :no-inheritance-diagram:
+
The Test Program and Input
--------------------------
diff --git a/lldb/examples/python/templates/operating_system.py b/lldb/examples/python/templates/operating_system.py
index a8053bcaa21af..e5c106de473bf 100644
--- a/lldb/examples/python/templates/operating_system.py
+++ b/lldb/examples/python/templates/operating_system.py
@@ -10,16 +10,15 @@ 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..b9ead9e80741f 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,17 @@ 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..ea5d073715319 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,12 @@ 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 +234,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 +298,11 @@ 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 +334,11 @@ 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..71ac236956e0b
--- /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 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 `True`.
+ """
+ return True
+
+ 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.
+ """
+ return True
``````````
</details>
https://github.com/llvm/llvm-project/pull/97262
More information about the lldb-commits
mailing list