[lldb/Plugins] Add support for ScriptedThread in ScriptedProcess

This patch introduces the `ScriptedThread` class with its python
interface.

When used with `ScriptedProcess`, `ScriptedThreaad` can provide various
information such as the thread state, stop reason or even its register
context.

This can be used to reconstruct the program stack frames using lldb's unwinder.

rdar://74503836

Differential Revision: https://reviews.llvm.org/D107585

Signed-off-by: Med Ismail Bennani <[email protected]>

Author: medismailben

lldb/bindings/python/python-wrapper.swig

@@ -340,6 +340,63 @@ LLDBSwigPythonCreateScriptedProcess
     Py_RETURN_NONE;
 }
 
+SWIGEXPORT void*
+LLDBSwigPythonCreateScriptedThread
+(
+    const char *python_class_name,
+    const char *session_dictionary_name,
+    const lldb::TargetSP& target_sp,
+    std::string &error_string
+)
+{
+    if (python_class_name == NULL || python_class_name[0] == '\0' || !session_dictionary_name)
+        Py_RETURN_NONE;
+
+    PyErr_Cleaner py_err_cleaner(true);
+
+    auto dict = PythonModule::MainModule().ResolveName<PythonDictionary>(session_dictionary_name);
+    auto pfunc = PythonObject::ResolveNameWithDictionary<PythonCallable>(python_class_name, dict);
+
+    if (!pfunc.IsAllocated()) {
+        error_string.append("could not find script class: ");
+        error_string.append(python_class_name);
+        return nullptr;
+    }
+
+    // I do not want the SBTarget to be deallocated when going out of scope
+    // because python has ownership of it and will manage memory for this
+    // object by itself
+    PythonObject target_arg(PyRefType::Owned, SBTypeToSWIGWrapper(new lldb::SBTarget(target_sp)));
+
+    if (!target_arg.IsAllocated())
+        Py_RETURN_NONE;
+
+    llvm::Expected<PythonCallable::ArgInfo> arg_info = pfunc.GetArgInfo();
+    if (!arg_info) {
+        llvm::handleAllErrors(
+            arg_info.takeError(),
+            [&](PythonException &E) {
+                error_string.append(E.ReadBacktrace());
+            },
+            [&](const llvm::ErrorInfoBase &E) {
+                error_string.append(E.message());
+            });
+        Py_RETURN_NONE;
+    }
+
+    PythonObject result = {};
+    if (arg_info.get().max_positional_args == 1) {
+        result = pfunc(target_arg);
+    } else {
+        error_string.assign("wrong number of arguments in __init__, should be 2 or 3 (not including self)");
+        Py_RETURN_NONE;
+    }
+
+    if (result.IsAllocated())
+        return result.release();
+    Py_RETURN_NONE;
+}
+
 SWIGEXPORT void*
 LLDBSwigPythonCreateScriptedThreadPlan
 (

lldb/examples/python/scripted_process/my_scripted_process.py

@@ -1,7 +1,10 @@
-import os
+import os,struct,signal
+
+from typing import Any, Dict
 
 import lldb
 from lldb.plugins.scripted_process import ScriptedProcess
+from lldb.plugins.scripted_process import ScriptedThread
 
 class MyScriptedProcess(ScriptedProcess):
     def __init__(self, target: lldb.SBTarget, args : lldb.SBStructuredData):
@@ -35,6 +38,45 @@ def should_stop(self) -> bool:
     def is_alive(self) -> bool:
         return True
 
+    def get_scripted_thread_plugin(self):
+        return MyScriptedThread.__module__ + "." + MyScriptedThread.__name__
+
+
+class MyScriptedThread(ScriptedThread):
+    def __init__(self, target):
+        super().__init__(target)
+
+    def get_thread_id(self) -> int:
+        return 0x19
+
+    def get_name(self) -> str:
+        return MyScriptedThread.__name__ + ".thread-1"
+
+    def get_stop_reason(self) -> Dict[str, Any]:
+        return { "type": lldb.eStopReasonSignal, "data": {
+            "signal": signal.SIGINT
+        } }
+
+    def get_stackframes(self):
+        class ScriptedStackFrame:
+            def __init__(idx, cfa, pc, symbol_ctx):
+                self.idx = idx
+                self.cfa = cfa
+                self.pc = pc
+                self.symbol_ctx = symbol_ctx
+
+
+        symbol_ctx = lldb.SBSymbolContext()
+        frame_zero = ScriptedStackFrame(0, 0x42424242, 0x5000000, symbol_ctx)
+        self.frames.append(frame_zero)
+
+        return self.frame_zero[0:0]
+
+    def get_register_context(self) -> str:
+        return struct.pack(
+                '21Q', 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21)
+
+
 def __lldb_init_module(debugger, dict):
     if not 'SKIP_SCRIPTED_PROCESS_LAUNCH' in os.environ:
         debugger.HandleCommand(

lldb/examples/python/scripted_process/scripted_process.py

@@ -163,3 +163,163 @@ def is_alive(self):
             bool: True if scripted process is alive. False otherwise.
         """
         pass
+
+    @abstractmethod
+    def get_scripted_thread_plugin(self):
+        """ Get scripted thread plugin name.
+
+        Returns:
+            str: Name of the scripted thread plugin.
+        """
+        return None
+
+@six.add_metaclass(ABCMeta)
+class ScriptedThread:
+
+    """
+    The base class for a scripted thread.
+
+    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
+    def __init__(self, target):
+        """ Construct a scripted thread.
+
+        Args:
+            target (lldb.SBTarget): The target launching the scripted process.
+            args (lldb.SBStructuredData): A Dictionary holding arbitrary
+                key/value pairs used by the scripted process.
+        """
+        self.target = None
+        self.args = None
+        if isinstance(target, lldb.SBTarget) and target.IsValid():
+            self.target = target
+
+        self.id = None
+        self.name = None
+        self.queue = None
+        self.state = None
+        self.stop_reason = None
+        self.register_info = None
+        self.register_ctx = []
+        self.frames = []
+
+    @abstractmethod
+    def get_thread_id(self):
+        """ Get the scripted thread identifier.
+
+        Returns:
+            int: The identifier of the scripted thread.
+        """
+        pass
+
+    @abstractmethod
+    def get_name(self):
+        """ Get the scripted thread name.
+
+        Returns:
+            str: The name of the scripted thread.
+        """
+        pass
+
+    def get_state(self):
+        """ Get the scripted thread state type.
+
+            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.
+
+        Returns:
+            int: The state type of the scripted thread.
+                 Returns lldb.eStateStopped by default.
+        """
+        return lldb.eStateStopped
+
+    def get_queue(self):
+        """ Get the scripted thread associated queue name.
+            This method is optional.
+
+        Returns:
+            str: The queue name associated with the scripted thread.
+        """
+        pass
+
+    @abstractmethod
+    def get_stop_reason(self):
+        """ Get the dictionary describing the stop reason type with some data.
+            This method is optional.
+
+        Returns:
+            Dict: The dictionary holding the stop reason type and the possibly
+            the stop reason data.
+        """
+        pass
+
+    def get_stackframes(self):
+        """ Get the list of stack frames for the scripted thread.
+
+        ```
+        class ScriptedStackFrame:
+            def __init__(idx, cfa, pc, symbol_ctx):
+                self.idx = idx
+                self.cfa = cfa
+                self.pc = pc
+                self.symbol_ctx = symbol_ctx
+        ```
+
+        Returns:
+            List[ScriptedFrame]: A list of `ScriptedStackFrame`
+                containing for each entry, the frame index, the canonical
+                frame address, the program counter value for that frame
+                and a symbol context.
+                None if the list is empty.
+        """
+        return 0
+
+    def get_register_info(self):
+        if self.register_info is None:
+            self.register_info = dict()
+            triple = self.target.triple
+            if triple:
+                arch = triple.split('-')[0]
+                if arch == 'x86_64':
+                    self.register_info['sets'] = ['GPR', 'FPU', 'EXC']
+                    self.register_info['registers'] = [
+                        {'name': 'rax', 'bitsize': 64, 'offset': 0, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 0, 'dwarf': 0},
+                        {'name': 'rbx', 'bitsize': 64, 'offset': 8, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 3, 'dwarf': 3},
+                        {'name': 'rcx', 'bitsize': 64, 'offset': 16, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 2, 'dwarf': 2, 'generic': 'arg4', 'alt-name': 'arg4', },
+                        {'name': 'rdx', 'bitsize': 64, 'offset': 24, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 1, 'dwarf': 1, 'generic': 'arg3', 'alt-name': 'arg3', },
+                        {'name': 'rdi', 'bitsize': 64, 'offset': 32, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 5, 'dwarf': 5, 'generic': 'arg1', 'alt-name': 'arg1', },
+                        {'name': 'rsi', 'bitsize': 64, 'offset': 40, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 4, 'dwarf': 4, 'generic': 'arg2', 'alt-name': 'arg2', },
+                        {'name': 'rbp', 'bitsize': 64, 'offset': 48, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 6, 'dwarf': 6, 'generic': 'fp', 'alt-name': 'fp', },
+                        {'name': 'rsp', 'bitsize': 64, 'offset': 56, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 7, 'dwarf': 7, 'generic': 'sp', 'alt-name': 'sp', },
+                        {'name': 'r8', 'bitsize': 64, 'offset': 64, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 8, 'dwarf': 8, 'generic': 'arg5', 'alt-name': 'arg5', },
+                        {'name': 'r9', 'bitsize': 64, 'offset': 72, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 9, 'dwarf': 9, 'generic': 'arg6', 'alt-name': 'arg6', },
+                        {'name': 'r10', 'bitsize': 64, 'offset': 80, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 10, 'dwarf': 10},
+                        {'name': 'r11', 'bitsize': 64, 'offset': 88, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 11, 'dwarf': 11},
+                        {'name': 'r12', 'bitsize': 64, 'offset': 96, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 12, 'dwarf': 12},
+                        {'name': 'r13', 'bitsize': 64, 'offset': 104, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 13, 'dwarf': 13},
+                        {'name': 'r14', 'bitsize': 64, 'offset': 112, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 14, 'dwarf': 14},
+                        {'name': 'r15', 'bitsize': 64, 'offset': 120, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 15, 'dwarf': 15},
+                        {'name': 'rip', 'bitsize': 64, 'offset': 128, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'gcc': 16, 'dwarf': 16, 'generic': 'pc', 'alt-name': 'pc'},
+                        {'name': 'rflags', 'bitsize': 64, 'offset': 136, 'encoding': 'uint', 'format': 'hex', 'set': 0, 'generic': 'flags', 'alt-name': 'flags'},
+                        {'name': 'cs', 'bitsize': 64, 'offset': 144, 'encoding': 'uint', 'format': 'hex', 'set': 0},
+                        {'name': 'fs', 'bitsize': 64, 'offset': 152, 'encoding': 'uint', 'format': 'hex', 'set': 0},
+                        {'name': 'gs', 'bitsize': 64, 'offset': 160, 'encoding': 'uint', 'format': 'hex', 'set': 0},
+                    ]
+        return self.register_info
+
+    @abstractmethod
+    def get_register_context(self):
+        """ Get the scripted thread register context
+
+        Returns:
+            str: A byte representing all register's value.
+        """
+        pass

lldb/include/lldb/Interpreter/ScriptedInterface.h

@@ -11,6 +11,8 @@
 
 #include "lldb/Core/StructuredDataImpl.h"
 #include "lldb/Target/ExecutionContext.h"
+#include "lldb/Utility/Log.h"
+#include "lldb/Utility/Logging.h"
 #include "lldb/lldb-private.h"
 
 #include <string>
@@ -25,6 +27,44 @@ class ScriptedInterface {
   CreatePluginObject(llvm::StringRef class_name, ExecutionContext &exe_ctx,
                      StructuredData::DictionarySP args_sp) = 0;
 
+  template <typename Ret>
+  Ret ErrorWithMessage(llvm::StringRef caller_name, llvm::StringRef error_msg,
+                       Status &error,
+                       uint32_t log_caterogy = LIBLLDB_LOG_PROCESS) {
+    LLDB_LOGF(GetLogIfAllCategoriesSet(log_caterogy), "%s ERROR = %s",
+              caller_name.data(), error_msg.data());
+    error.SetErrorString(llvm::Twine(caller_name + llvm::Twine(" ERROR = ") +
+                                     llvm::Twine(error_msg))
+                             .str());
+    return {};
+  }
+
+  template <typename T = StructuredData::ObjectSP>
+  bool CheckStructuredDataObject(llvm::StringRef caller, T obj, Status &error) {
+    if (!obj) {
+      return ErrorWithMessage<bool>(caller,
+                                    llvm::Twine("Null StructuredData object (" +
+                                                llvm::Twine(error.AsCString()) +
+                                                llvm::Twine(")."))
+                                        .str(),
+                                    error);
+    }
+
+    if (!obj->IsValid()) {
+      return ErrorWithMessage<bool>(
+          caller,
+          llvm::Twine("Invalid StructuredData object (" +
+                      llvm::Twine(error.AsCString()) + llvm::Twine(")."))
+              .str(),
+          error);
+    }
+
+    if (error.Fail())
+      return ErrorWithMessage<bool>(caller, error.AsCString(), error);
+
+    return true;
+  }
+
 protected:
   StructuredData::GenericSP m_object_instance_sp;
 };

lldb/include/lldb/Interpreter/ScriptedProcessInterface.h

@@ -57,6 +57,45 @@ class ScriptedProcessInterface : virtual public ScriptedInterface {
   virtual lldb::pid_t GetProcessID() { return LLDB_INVALID_PROCESS_ID; }
 
   virtual bool IsAlive() { return true; }
+
+  virtual llvm::Optional<std::string> GetScriptedThreadPluginName() {
+    return llvm::None;
+  }
+
+protected:
+  friend class ScriptedThread;
+  virtual lldb::ScriptedThreadInterfaceSP GetScriptedThreadInterface() {
+    return nullptr;
+  }
+
+  lldb::ScriptedThreadInterfaceSP m_scripted_thread_interface_sp = nullptr;
+};
+
+class ScriptedThreadInterface : virtual public ScriptedInterface {
+public:
+  StructuredData::GenericSP
+  CreatePluginObject(llvm::StringRef class_name, ExecutionContext &exe_ctx,
+                     StructuredData::DictionarySP args_sp) override {
+    return nullptr;
+  }
+
+  virtual lldb::tid_t GetThreadID() { return LLDB_INVALID_THREAD_ID; }
+
+  virtual llvm::Optional<std::string> GetName() { return llvm::None; }
+
+  virtual lldb::StateType GetState() { return lldb::eStateInvalid; }
+
+  virtual llvm::Optional<std::string> GetQueue() { return llvm::None; }
+
+  virtual StructuredData::DictionarySP GetStopReason() { return nullptr; }
+
+  virtual StructuredData::ArraySP GetStackFrames() { return nullptr; }
+
+  virtual StructuredData::DictionarySP GetRegisterInfo() { return nullptr; }
+
+  virtual llvm::Optional<std::string> GetRegisterContext() {
+    return llvm::None;
+  }
 };
 } // namespace lldb_private