[lldb/docs] Add scripting extensions documentation to the website

medismailben · medismailben · commit e08689b3e248 · 2024-07-02T00:26:41.000-07:00
This patch adds the documentation for a subset of scripting extensions
such as scripted process, scripted thread, operating system threads &amp;
scritped thread plans to the lldb website.

Signed-off-by: Med Ismail Bennani &lt;ismail@bennani.ma&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
