intel/llvm
1
0
Fork 0
mirror of https://github.com/intel/llvm.git synced 2026-01-13 19:08:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

[lldb/docs] Add scripting extensions documentation to the website (#97262)

Browse Source 
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@bennani.ma>
This commit is contained in:
Med Ismail Bennani
2024-07-02 12:52:50 -07:00
committed by GitHub
parent 3584a82333
commit 59f4267c8e
5 changed files with 48 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
lldb/docs/CMakeLists.txt
View File

@@ -27,8 +27,13 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
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/"
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

1
lldb/docs/index.rst
View File

@@ -141,6 +141,7 @@ interesting areas to contribute to lldb.
use/python
use/python-reference
Python API <python_api>
Python Extensions <python_extensions>
.. toctree::

20
lldb/examples/python/templates/operating_system.py
View File

@@ -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)

25
lldb/examples/python/templates/scripted_platform.py
View File

@@ -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 @@ class ScriptedPlatform(metaclass=ABCMeta):
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

42
lldb/examples/python/templates/scripted_process.py
View File

@@ -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 @@ class ScriptedProcess(metaclass=ABCMeta):
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 @@ class ScriptedProcess(metaclass=ABCMeta):
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 @@ class ScriptedThread(metaclass=ABCMeta):
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 @@ class ScriptedThread(metaclass=ABCMeta):
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