[lldb] Add a way to get a scripted process implementation from the SBAPI

[mib]

Summary

This patch introduces a new GetScriptedImplementation method to the
SBProcess class in the SBAPI. It will allow users of Scripted Processes to
fetch the scripted implementation object from to script interpreter to be
able to interact with it directly (without having to go through lldb).

This allows to user to perform action that are not specified in the
scripted process interface, like calling un-specified methods, but also
to enrich the implementation, by passing it complex objects.

Signed-off-by: Med Ismail Bennani <[e-mail]>

[bulbazord]

This is an interesting idea.

I suppose I find it a little strange that something from the SB API is passing a void * back to the caller instead of something more well defined (like another SB class or some primitive) but I suppose that's not the worst thing in the world. I'm not sure how else you would get a C++ method to return a type that is dependent on which language the method was called from...

lldb/bindings/interface/SBProcess.i

347–348

Maybe a docstring is in order? Something to explain how to use this.

[mib]

In D143236#4101429, @bulbazord wrote:

This is an interesting idea.

I suppose I find it a little strange that something from the SB API is passing a void * back to the caller instead of something more well defined (like another SB class or some primitive) but I suppose that's not the worst thing in the world. I'm not sure how else you would get a C++ method to return a type that is dependent on which language the method was called from...

So, technically, we could also do something similar with SBStructuredData since now they don't allow holding generic objects. You can then image that the user will be able to unwrap the structured data to get the original object. I think @jingham also had other examples in mind, like for breakpoint python commands, if I'm not mistaken.

[mib]

Add docstring.

[jingham]

lldb/bindings/python/python-typemaps.swig

57

Won't this make every out void * claim to be a Python Object in the SWIG-ed output? That seems dangerous. Maybe you should make a typedef "LLDBScriptObjectPointer" or whatever, and that's what the SB API returns. Then you could bind to that in the SWIG type map.

[mib]

Address @jingham comment.

[JDevlieghere]

I'd call it GetScriptedImplementation() to make it clear this isn't going to give you the underlying lldb_private class or anything like that.

What happens in Python when you don't have a scripted implementation? Is the result None? Let's add a test for that too.

Besides that this LGTM.

lldb/bindings/python/python-typemaps.swig

59–62

if (const void* impl = $1)
    $result = (PyObject*) impl;

[jingham]

LGTM if Jonas is also happy.

[mib]

Address @JDevlieghere feedback:

• Rename API to GetScriptedImplementation
• Add test for non scripted process plugins

lldb/bindings/interface/SBProcess.i

public:
     EventIsStructuredDataEvent (const lldb::SBEvent &event);
 
     lldb::SBBroadcaster
     GetBroadcaster () const;
 
     bool
     GetDescription (lldb::SBStream &description);
 
     %feature("autodoc", "
+    Returns the implementation object of the process plugin if available. None
+    otherwise.") GetScriptedImplementation;
+    ScriptedObject
+    GetScriptedImplementation();
+
+    %feature("autodoc", "
     Returns the process' extended crash information.") GetExtendedCrashInformation;
     lldb::SBStructuredData
     GetExtendedCrashInformation ();
 
     uint32_t
     GetNumSupportedHardwareWatchpoints (lldb::SBError &error) const;
 
     uint32_t

lldb/bindings/python/python-typemaps.swig

if (PythonList::Check($input)) {
     $1 = (($input == Py_None) ? 1 : 0);
   }
 }
 
 %typemap(freearg) char** {
   free((char *) $1);
 }
 
+%typemap(out) lldb::ScriptedObject {
+  $result = nullptr;
+  if (const void* impl = $1)
+    $result = (PyObject*) impl;
+  if (!$result) {
+    $result = Py_None;
+    Py_INCREF(Py_None);
+  }
+}
+
 %typemap(out) char** {
   int len;
   int i;
   len = 0;
   while ($1[len])
     len++;
   PythonList list(len);
   for (i = 0; i < len; i++)

lldb/include/lldb/API/SBDefines.h

 class LLDB_API SBValueList;
 class LLDB_API SBVariablesOptions;
 class LLDB_API SBWatchpoint;
 class LLDB_API SBUnixSignals;
 
 typedef bool (*SBBreakpointHitCallback)(void *baton, SBProcess &process,
                                         SBThread &thread,
                                         lldb::SBBreakpointLocation &location);
+typedef void *ScriptedObject;
 }
 
 #endif // LLDB_API_SBDEFINES_H

lldb/include/lldb/API/SBProcess.h

public:
   ///     want to deallocate.
   ///
   /// \return
   ///     An error object describes any errors that occurred while
   ///     deallocating.
   ///
   lldb::SBError DeallocateMemory(lldb::addr_t ptr);
 
+  lldb::ScriptedObject GetScriptedImplementation();
+
 protected:
   friend class SBAddress;
   friend class SBBreakpoint;
   friend class SBBreakpointLocation;
   friend class SBCommandInterpreter;
   friend class SBDebugger;
   friend class SBExecutionContext;
   friend class SBFunction;

lldb/include/lldb/Target/Process.h

void PruneThreadPlans();
   /// one way to tell whether a feature is available.
   ///
   /// \return
   ///     The plugin if one is available for the specified feature;
   ///     otherwise, returns an empty shared pointer.
   lldb::StructuredDataPluginSP
   GetStructuredDataPlugin(ConstString type_name) const;
 
+  virtual void *GetImplementation() { return nullptr; }
+
 protected:
   friend class Trace;
 
   /// Construct with a shared pointer to a target, and the Process listener.
   /// Uses the Host UnixSignalsSP by default.
   Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp);
 
   /// Construct with a shared pointer to a target, the Process listener, and

lldb/source/API/SBProcess.cpp

if (process_sp) {
     } else {
       sb_error.SetErrorString("process is running");
     }
   } else {
     sb_error.SetErrorString("SBProcess is invalid");
   }
   return sb_error;
 }
+
+ScriptedObject SBProcess::GetScriptedImplementation() {
+  LLDB_INSTRUMENT_VA(this);
+  ProcessSP process_sp(GetSP());
+  return (process_sp) ? process_sp->GetImplementation() : nullptr;
+}

lldb/source/Plugins/Process/scripted/ScriptedProcess.h

public:
 
   lldb_private::StructuredData::ObjectSP
   GetLoadedDynamicLibrariesInfos() override;
 
   lldb_private::StructuredData::DictionarySP GetMetadata() override;
 
   void UpdateQueueListIfNeeded() override;
 
+  void *GetImplementation() override;
+
 protected:
   ScriptedProcess(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp,
                   const ScriptedMetadata &scripted_metadata, Status &error);
 
   Status DoStop();
 
   void Clear();
 

lldb/source/Plugins/Process/scripted/ScriptedProcess.cpp

if (const char *queue_name = thread_sp->GetQueueName()) {
       m_queue_list.AddQueue(queue_sp);
     }
   }
 }
 
 ScriptedProcessInterface &ScriptedProcess::GetInterface() const {
   return m_interpreter->GetScriptedProcessInterface();
 }
+
+void *ScriptedProcess::GetImplementation() {
+  if (m_script_object_sp &&
+      m_script_object_sp->GetType() == eStructuredDataTypeGeneric)
+    return m_script_object_sp->GetAsGeneric()->GetValue();
+  return nullptr;
+}

lldb/test/API/functionalities/scripted_process/TestScriptedProcess.py

 """
 Test python scripted process in lldb
 """
 
 import os, shutil
 
 import lldb
 from lldbsuite.test.decorators import *
 from lldbsuite.test.lldbtest import *
 from lldbsuite.test import lldbutil
 from lldbsuite.test import lldbtest
 
+import dummy_scripted_process
+
 class ScriptedProcesTestCase(TestBase):
 
     NO_DEBUG_INFO_TESTCASE = True
 
     @skipUnlessDarwin
     def test_python_plugin_package(self):
         """Test that the lldb python module has a `plugins.scripted_process`
         package."""
def test_scripted_process_and_scripted_thread(self):
         launch_info.SetScriptedProcessClassName("dummy_scripted_process.DummyScriptedProcess")
 
         error = lldb.SBError()
         process = target.Launch(launch_info, error)
         self.assertTrue(process and process.IsValid(), PROCESS_IS_VALID)
         self.assertEqual(process.GetProcessID(), 42)
         self.assertEqual(process.GetNumThreads(), 1)
 
+        py_impl = process.GetScriptedImplementation()
+        self.assertTrue(py_impl)
+        self.assertTrue(isinstance(py_impl, dummy_scripted_process.DummyScriptedProcess))
+        self.assertFalse(hasattr(py_impl, 'my_super_secret_member'))
+        py_impl.my_super_secret_member = 42
+        self.assertTrue(hasattr(py_impl, 'my_super_secret_member'))
+        self.assertEqual(py_impl.my_super_secret_method(), 42)
+
         addr = 0x500000000
         message = "Hello, world!"
         buff = process.ReadCStringFromMemory(addr, len(message) + 1, error)
         self.assertSuccess(error)
         self.assertEqual(buff, message)
 
         thread = process.GetSelectedThread()
         self.assertTrue(thread, "Invalid thread.")

lldb/test/API/functionalities/scripted_process/dummy_scripted_process.py

def should_stop(self) -> bool:
         return True
 
     def is_alive(self) -> bool:
         return True
 
     def get_scripted_thread_plugin(self):
         return DummyScriptedThread.__module__ + "." + DummyScriptedThread.__name__
 
+    def my_super_secret_method(self):
+        if hasattr(self, 'my_super_secret_member'):
+            return self.my_super_secret_member
+        else:
+            return None
+
 
 class DummyScriptedThread(ScriptedThread):
     def __init__(self, process, args):
         super().__init__(process, args)
         self.frames.append({"pc": 0x0100001b00 })
 
     def get_thread_id(self) -> int:
         return 0x19

lldb/test/API/python_api/process/TestProcessAPI.py

class ProcessAPITestCase(TestBase):
     def setUp(self):
         # Call super's setUp().
         TestBase.setUp(self)
         # Find the line number to break inside main().
         self.line = line_number(
             "main.cpp",
             "// Set break point at this line and check variable 'my_char'.")
 
+    def test_scripted_implementation(self):
+        self.build()
+        exe = self.getBuildArtifact("a.out")
+
+        (target, process, _, _) = \
+            lldbutil.run_to_source_breakpoint(self, "Set break point",
+                                              lldb.SBFileSpec("main.cpp"))
+
+        self.assertTrue(process, PROCESS_IS_VALID)
+        self.assertEqual(process.GetScriptedImplementation(), None)
+
+
     def test_read_memory(self):
         """Test Python SBProcess.ReadMemory() API."""
         self.build()
         exe = self.getBuildArtifact("a.out")
 
         target = self.dbg.CreateTarget(exe)
         self.assertTrue(target, VALID_TARGET)