[lldb] Add AllocateMemory/DeallocateMemory to the SBProcess API

[housel]

Summary

This change adds AllocateMemory and DeallocateMemory methods to the SBProcess API, so that clients can allocate and deallocate memory blocks within the process being debugged (for storing JIT-compiled code or other uses).

(I am developing a debugger + REPL using the API; it will need to store JIT-compiled code within the target.)

[jingham]

Could you put a docstring describing the API's in the SBProcess.i file. It is annoying to have to do this in two places but given the way SWIG works we don't have a better alternative. This is where the help in the Python REPL comes from so it's useful to have it there. There are other example of how to do this in the .i file. Thanks!

It might also be good to test that the program can read from the newly allocated memory by, for instance, having a function in the program that returns the first character from a pointer passed in. You could call that using expr and you should also get 'a'... You could write another function that tries to write to that memory to test that setting the permissions to not writable works.

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

405–420

This can all be done more compactly by using lldbutil.run_to_source_breakpoint. The other tests in this test file are using the by-hand way of doing this, if you want to fix them as well, that would be great. But at least, we're trying not to write new tests this way.

[clayborg]

lldb/bindings/interface/SBProcess.i

420

Add doc string that describes this function for python users. Something about "permissions" is an integer formed by combining logical OR'ing "lldb.ePermissionsWritable" "lldb.ePermissionsReadable" and "lldb.ePermissionsExecutable".

423

doc string would be nice here too specifying that the address should have come from a call to "AllocateMemory(...)"

[housel]

Updated based on reviewer suggestions, thanks.

[clayborg]

LGTM. Jim, chime in soon if you have any other objections!

[jingham]

LGTM

[housel]

In D105389#2864941, @clayborg wrote:

LGTM. Jim, chime in soon if you have any other objections!

I don't have commit access, could some one take care of committing this for me? Thanks!

lldb/bindings/interface/SBProcess.i

public:
     use IsValid() to check if the info returned is valid. ::
 
         process_info = process.GetProcessInfo()
         if process_info.IsValid():
             process_info.GetProcessID()") GetProcessInfo;
     lldb::SBProcessInfo
     GetProcessInfo();
 
+    %feature("autodoc", "
+    Allocates a block of memory within the process, with size and
+    access permissions specified in the arguments. The permisssions
+    argument is an or-combination of zero or more of
+    lldb.ePermissionsWritable, lldb.ePermissionsReadable, and
+    lldb.ePermissionsExecutable. Returns the address
+    of the allocated buffer in the process, or
+    lldb.LLDB_INVALID_ADDRESS if the allocation failed.") AllocateMemory;
+
+    lldb::addr_t
+    AllocateMemory(size_t size, uint32_t permissions, lldb::SBError &error);
+
+    %feature("autodoc", "
+    Deallocates the block of memory (previously allocated using
+    AllocateMemory) given in the argument.") DeallocateMemory;
+
+    lldb::SBError
+    DeallocateMemory(lldb::addr_t ptr);
+
     STRING_EXTENSION(SBProcess)
 
 #ifdef SWIGPYTHON
     %pythoncode %{
         def __get_is_alive__(self):
             '''Returns "True" if the process is currently alive, "False" otherwise'''
             s = self.GetState()
             if (s == eStateAttaching or

lldb/include/lldb/API/SBProcess.h

public:
 
   /// Return information about the process.
   ///
   /// Valid process info will only be returned when the process is
   /// alive, use SBProcessInfo::IsValid() to check returned info is
   /// valid.
   lldb::SBProcessInfo GetProcessInfo();
 
+  /// Allocate memory within the process.
+  ///
+  /// This function will allocate memory in the process's address space.
+  ///
+  /// \param[in] size
+  ///     The size of the allocation requested.
+  ///
+  /// \param[in] permissions
+  ///     Or together any of the lldb::Permissions bits.  The
+  ///     permissions on a given memory allocation can't be changed
+  ///     after allocation.  Note that a block that isn't set writable
+  ///     can still be written from lldb, just not by the process
+  ///     itself.
+  ///
+  /// \param[out] error
+  ///     An error object that gets filled in with any errors that
+  ///     might occur when trying allocate.
+  ///
+  /// \return
+  ///     The address of the allocated buffer in the process, or
+  ///     LLDB_INVALID_ADDRESS if the allocation failed.
+  lldb::addr_t AllocateMemory(size_t size, uint32_t permissions,
+                              lldb::SBError &error);
+
+  /// Deallocate memory in the process.
+  ///
+  /// This function will deallocate memory in the process's address
+  /// space that was allocated with AllocateMemory.
+  ///
+  /// \param[in] ptr
+  ///     A return value from AllocateMemory, pointing to the memory you
+  ///     want to deallocate.
+  ///
+  /// \return
+  ///     An error object describes any errors that occurred while
+  ///     deallocating.
+  ///
+  lldb::SBError DeallocateMemory(lldb::addr_t ptr);
+
 protected:
   friend class SBAddress;
   friend class SBBreakpoint;
   friend class SBBreakpointLocation;
   friend class SBCommandInterpreter;
   friend class SBDebugger;
   friend class SBExecutionContext;
   friend class SBFunction;

lldb/source/API/SBProcess.cpp

lldb::SBProcessInfo SBProcess::GetProcessInfo() {
   ProcessSP process_sp(GetSP());
   ProcessInstanceInfo proc_info;
   if (process_sp && process_sp->GetProcessInfo(proc_info)) {
     sb_proc_info.SetProcessInfo(proc_info);
   }
   return LLDB_RECORD_RESULT(sb_proc_info);
 }
 
+lldb::addr_t SBProcess::AllocateMemory(size_t size, uint32_t permissions,
+                                       lldb::SBError &sb_error) {
+  LLDB_RECORD_METHOD(lldb::addr_t, SBProcess, AllocateMemory,
+                     (size_t, uint32_t, lldb::SBError &), size, permissions,
+                     sb_error);
+
+  lldb::addr_t addr = LLDB_INVALID_ADDRESS;
+  ProcessSP process_sp(GetSP());
+  if (process_sp) {
+    Process::StopLocker stop_locker;
+    if (stop_locker.TryLock(&process_sp->GetRunLock())) {
+      std::lock_guard<std::recursive_mutex> guard(
+          process_sp->GetTarget().GetAPIMutex());
+      addr = process_sp->AllocateMemory(size, permissions, sb_error.ref());
+    } else {
+      sb_error.SetErrorString("process is running");
+    }
+  } else {
+    sb_error.SetErrorString("SBProcess is invalid");
+  }
+  return addr;
+}
+
+lldb::SBError SBProcess::DeallocateMemory(lldb::addr_t ptr) {
+  LLDB_RECORD_METHOD(lldb::SBError, SBProcess, DeallocateMemory, (lldb::addr_t),
+                     ptr);
+
+  lldb::SBError sb_error;
+  ProcessSP process_sp(GetSP());
+  if (process_sp) {
+    Process::StopLocker stop_locker;
+    if (stop_locker.TryLock(&process_sp->GetRunLock())) {
+      std::lock_guard<std::recursive_mutex> guard(
+          process_sp->GetTarget().GetAPIMutex());
+      Status error = process_sp->DeallocateMemory(ptr);
+      sb_error.SetError(error);
+    } else {
+      sb_error.SetErrorString("process is running");
+    }
+  } else {
+    sb_error.SetErrorString("SBProcess is invalid");
+  }
+  return sb_error;
+}
+
 namespace lldb_private {
 namespace repro {
 
 template <>
 void RegisterMethods<SBProcess>(Registry &R) {
   LLDB_REGISTER_CONSTRUCTOR(SBProcess, ());
   LLDB_REGISTER_CONSTRUCTOR(SBProcess, (const lldb::SBProcess &));
   LLDB_REGISTER_CONSTRUCTOR(SBProcess, (const lldb::ProcessSP &));
void RegisterMethods<SBProcess>(Registry &R) {
   LLDB_REGISTER_METHOD(bool, SBProcess, IsInstrumentationRuntimePresent,
                        (lldb::InstrumentationRuntimeType));
   LLDB_REGISTER_METHOD(lldb::SBError, SBProcess, SaveCore, (const char *));
   LLDB_REGISTER_METHOD(lldb::SBError, SBProcess, GetMemoryRegionInfo,
                        (lldb::addr_t, lldb::SBMemoryRegionInfo &));
   LLDB_REGISTER_METHOD(lldb::SBMemoryRegionInfoList, SBProcess,
                        GetMemoryRegions, ());
   LLDB_REGISTER_METHOD(lldb::SBProcessInfo, SBProcess, GetProcessInfo, ());
+  LLDB_REGISTER_METHOD(lldb::addr_t, SBProcess, AllocateMemory,
+                       (size_t, uint32_t, lldb::SBError &));
+  LLDB_REGISTER_METHOD(lldb::SBError, SBProcess, DeallocateMemory,
+                       (lldb::addr_t));
 
   LLDB_REGISTER_CHAR_PTR_METHOD_CONST(size_t, SBProcess, GetSTDOUT);
   LLDB_REGISTER_CHAR_PTR_METHOD_CONST(size_t, SBProcess, GetSTDERR);
   LLDB_REGISTER_CHAR_PTR_METHOD_CONST(size_t, SBProcess, GetAsyncProfileData);
 }
 
 }
 }

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

def test_get_process_info(self):
                 process_info.GetEffectiveGroupID(), lldb.UINT32_MAX,
                 "Process effective group ID is valid")
         else:
             self.assertEqual(
                 process_info.GetEffectiveGroupID(), lldb.UINT32_MAX,
                 "Process effective group ID is invalid")
 
         process_info.GetParentProcessID()
+
+    def test_allocate_deallocate_memory(self):
+        """Test Python SBProcess.AllocateMemory() and SBProcess.DeallocateMemory() APIs."""
+        self.build()
+        (target, process, main_thread, main_breakpoint) = lldbutil.run_to_source_breakpoint(
+            self, "// Set break point at this line", lldb.SBFileSpec("main.cpp"))
+
+        # Allocate a block of memory in the target process
+        error = lldb.SBError()
+        addr = process.AllocateMemory(16384, lldb.ePermissionsReadable, error)
+        if not error.Success() or addr == lldb.LLDB_INVALID_ADDRESS:
+            self.fail("SBProcess.AllocateMemory() failed")
+
+        # Now use WriteMemory() API to write 'a' into the allocated
+        # memory. Note that the debugger can do this even though the
+        # block is not set writable.
+        result = process.WriteMemory(addr, 'a', error)
+        if not error.Success() or result != 1:
+            self.fail("SBProcess.WriteMemory() failed")
+
+        # Read from the memory location.  This time it should be 'a'.
+        # Due to the typemap magic (see lldb.swig), we pass in 1 to ReadMemory and
+        # expect to get a Python string as the result object!
+        content = process.ReadMemory(addr, 1, error)
+        if not error.Success():
+            self.fail("SBProcess.ReadMemory() failed")
+        if self.TraceOn():
+            print("memory content:", content)
+
+        self.expect(
+            content,
+            "Result from SBProcess.ReadMemory() matches our expected output: 'a'",
+            exe=False,
+            startstr=b'a')
+
+        # Verify that the process itself can read the allocated memory
+        frame = main_thread.GetFrameAtIndex(0)
+        val = frame.EvaluateExpression(
+            "test_read(reinterpret_cast<char *>({:#x}))".format(addr))
+        self.expect(val.GetValue(),
+                    "Result of test_read() matches expected output 'a'",
+                    exe=False,
+                    startstr="'a'")
+
+        # Verify that the process cannot write into the block
+        val = frame.EvaluateExpression(
+            "test_write(reinterpret_cast<char *>({:#x}), 'b')".format(addr))
+        if val.GetError().Success():
+            self.fail(
+                "test_write() to allocated memory without write permission unexpectedly succeeded")
+
+        # Deallocate the memory
+        error = process.DeallocateMemory(addr)
+        if not error.Success():
+            self.fail("SBProcess.DeallocateMemory() failed")

lldb/test/API/python_api/process/main.cpp

for (int i = 0; i < 3; ++i) {
         ++my_char;
     }
 
     printf("after the loop: my_char='%c'\n", my_char); // 'my_char' should print out as 'x'.
 
     return 0; // Set break point at this line and check variable 'my_char'.
               // Use lldb Python API to set memory content for my_int and check the result.
 }
+
+char test_read (char *ptr)
+{
+    return *ptr;
+}
+
+void test_write (char *ptr, char c)
+{
+    *ptr = c;
+}