mirror of
https://github.com/llvm/llvm-project.git
synced 2026-10-26 13:53:31 +08:00
Med Ismail Bennani
f10ede5111
This patch adds type annotations to every method (parameters and return types) and every `self.<name>` attribute of the scripted extension base classes shipped under `lldb/examples/python/templates/`. Extension authors reading the base classes -- or an IDE navigating them -- can now see the `lldb.SB*` contract each method exposes without having to cross-reference the docstring. `scripting extension generate` also picks the annotations up: derived class docstrings advertise each inherited attribute together with its declared type, and the generated method signatures carry their parameter and return annotations too. The classes covered are `ScriptedProcess`, `ScriptedThread`, `ScriptedFrame`, `PassthroughScriptedProcess`, `PassthroughScriptedThread`, `ScriptedFrameProvider`, `ScriptedBreakpointResolver`, `ScriptedThreadPlan`, `ScriptedHook`, `ScriptedPlatform`, and `OperatingSystem`. Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
98 lines
2.9 KiB
Python
98 lines
2.9 KiB
Python
from abc import ABCMeta, abstractmethod
|
|
from typing import Optional
|
|
|
|
import lldb
|
|
|
|
|
|
class ScriptedPlatform(metaclass=ABCMeta):
|
|
|
|
"""
|
|
The base class for a scripted platform.
|
|
|
|
Most of the base class methods are `@abstractmethod` that need to be
|
|
overwritten by the inheriting class.
|
|
"""
|
|
|
|
processes: Optional[dict[int, dict]] = None
|
|
|
|
@abstractmethod
|
|
def __init__(self, exe_ctx: lldb.SBExecutionContext, args: lldb.SBStructuredData):
|
|
"""Construct a scripted platform.
|
|
|
|
Args:
|
|
exe_ctx (lldb.SBExecutionContext): The execution context for the scripted platform
|
|
args (lldb.SBStructuredData): A Dictionary holding arbitrary
|
|
key/value pairs used by the scripted platform.
|
|
"""
|
|
processes = []
|
|
|
|
@abstractmethod
|
|
def list_processes(self) -> dict[int, dict]:
|
|
"""Get a list of processes that are running or that can be attached to on the platform.
|
|
|
|
.. 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
|
|
process ID, name, architecture. Optionally, the user can also
|
|
provide the parent process ID and the user and group IDs.
|
|
The dictionary can be empty.
|
|
"""
|
|
pass
|
|
|
|
def get_process_info(self, pid: int) -> Optional[dict]:
|
|
"""Get the dictionary describing the process.
|
|
|
|
Returns:
|
|
Dict: The dictionary of process info that matched process ID.
|
|
None if the process doesn't exists
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
def attach_to_process(self, attach_info: lldb.SBAttachInfo) -> lldb.SBError:
|
|
"""Attach to a process.
|
|
|
|
Args:
|
|
attach_info (lldb.SBAttachInfo): The information related to attach to a process.
|
|
|
|
Returns:
|
|
lldb.SBError: A status object notifying if the attach succeeded.
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
def launch_process(self, launch_info: lldb.SBLaunchInfo) -> lldb.SBError:
|
|
"""Launch a process.
|
|
|
|
Args:
|
|
launch_info (lldb.SBLaunchInfo): The information related to the process launch.
|
|
|
|
Returns:
|
|
lldb.SBError: A status object notifying if the launch succeeded.
|
|
"""
|
|
pass
|
|
|
|
@abstractmethod
|
|
def kill_process(self, pid: int) -> lldb.SBError:
|
|
"""Kill a process.
|
|
|
|
Args:
|
|
pid (int): Process ID for the process to be killed.
|
|
|
|
Returns:
|
|
lldb.SBError: A status object notifying if the shutdown succeeded.
|
|
"""
|
|
pass
|