[swift-inspect] minor cleanup and documentation

Author: andrurogerz

tools/swift-inspect/Sources/AndroidCLib/heap.c

@@ -57,7 +57,7 @@
 #error("only aarch64 and x86_64 are supported")
 #endif
 
-// Callback for heap_iterate. Because this function is meant to be copied to
+// Callback for malloc_iterate. Because this function is meant to be copied to
 // a different process for execution, it must not make any function calls. It
 // could be written as asm, but simple C is more readable/maintainable and
 // should consistently compile to movable, position-independent code.

tools/swift-inspect/Sources/SwiftInspectLinux/PTrace.swift

@@ -1,3 +1,15 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
 import Foundation
 import LinuxSystemHeaders
 
@@ -10,6 +22,9 @@ public class PTrace {
 
   let pid: pid_t
 
+  // Initializing a PTrace instance attaches to the target process, waits for
+  // it to stop, and leaves it in a stopped state. The caller may resume the
+  // process by calling cont().
   public init(process pid: pid_t) throws {
     guard ptrace_attach(pid) != -1 else {
       throw PTraceError.ptraceFailure(PTRACE_ATTACH, pid: pid)
@@ -34,11 +49,17 @@ public class PTrace {
   deinit { _ = ptrace_detach(self.pid) }
 
   public func cont() throws {
-    guard ptrace_continue(self.pid) != -1 else {
+    guard ptrace_cont(self.pid) != -1 else {
       throw PTraceError.ptraceFailure(PTRACE_CONT, pid: self.pid)
     }
   }
 
+  public func interrupt() throws {
+    guard ptrace_interrupt(self.pid) != -1 else {
+      throw PTraceError.ptraceFailure(PTRACE_INTERRUPT, pid: self.pid)
+    }
+  }
+
   public func getSigInfo() throws -> siginfo_t {
     var sigInfo = siginfo_t()
     guard ptrace_getsiginfo(self.pid, &sigInfo) != -1 else {
@@ -62,6 +83,7 @@ public class PTrace {
         throw PTraceError.ptraceFailure(PTRACE_GETREGSET, pid: self.pid)
       }
     }
+
     return regSet
   }
 
@@ -75,6 +97,10 @@ public class PTrace {
     }
   }
 
+  // Call the function at the specified address in the attached process. Caller
+  // may pass up to six 8-byte arguments. The optional callback is invoked when
+  // the process is stopped with a SIGTRAP signal. In this case, the caller is
+  // responsible for taking action on the signal.
   public func callRemoteFunction(
     at address: UInt64, with args: [UInt64] = [], onTrap callback: (() throws -> Void)? = nil
   ) throws -> UInt64 {
@@ -111,7 +137,6 @@ public class PTrace {
 
       // give the caller the opportunity to handle SIGTRAP
       try callback()
-      try self.cont()
     }
 
     let sigInfo = try self.getSigInfo()

tools/swift-inspect/Sources/SwiftInspectLinux/SystemHeaders/ptrace.h

@@ -38,10 +38,15 @@ int ptrace_detach(pid_t pid) {
 }
 
 static inline
-int ptrace_continue(pid_t pid) {
+int ptrace_cont(pid_t pid) {
   return ptrace_retry(PTRACE_CONT, pid, 0, 0);
 }
 
+static inline
+int ptrace_interrupt(pid_t pid) {
+  return ptrace_retry(PTRACE_INTERRUPT, pid, 0, 0);
+}
+
 static inline
 int ptrace_getsiginfo(pid_t pid, siginfo_t *siginfo) {
   return ptrace_retry(PTRACE_GETSIGINFO, pid, 0, siginfo);

tools/swift-inspect/Sources/swift-inspect/AndroidRemoteProcess.swift

@@ -12,8 +12,8 @@
 
 #if os(Android)
 
-import Foundation
 import AndroidCLib
+import Foundation
 import LinuxSystemHeaders
 import SwiftInspectLinux
 import SwiftRemoteMirror
@@ -49,20 +49,24 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
     super.init(processId: processId)
   }
 
+  // Linux and Android have no supported method to enumerate allocations in the
+  // heap of a remote process. Android does, however, support the malloc_iterate
+  // API, which enumerates allocations in the current process. We leverage this
+  // API by invoking it in the remote process with ptrace and using simple IPC
+  // (SIGTRAP and process_vm_readv and process_vm_writev) to fetch the results.
   override internal func iterateHeap(_ body: (swift_addr_t, UInt64) -> Void) {
     var regionCount = 0
     var allocCount = 0
     for entry in self.memoryMap.entries {
       // Limiting malloc_iterate calls to only memory regions that are known
       // to contain heap allocations is not strictly necessary but it does
-      // significantly improves the speed of heap iteration.
+      // significantly improve the speed of heap iteration.
       guard entry.isHeapRegion() else { continue }
 
       // collect all of the allocations in this heap region
       let allocations: [(base: swift_addr_t, len: UInt64)]
       do {
-        allocations = try self.iterateHeapRegion(
-          startAddr: entry.startAddr, endAddr: entry.endAddr)
+        allocations = try self.iterateHeapRegion(region: entry)
         regionCount += 1
       } catch {
         print("failed iterating remote heap: \(error)")
@@ -75,7 +79,7 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
       for alloc in allocations { body(alloc.base, alloc.len) }
     }
 
-    if allocCount == 0 {
+    if regionCount == 0 {
       // This condition most likely indicates the MemoryMap.Entry.isHeapRegion
       // filtering is needs to be modified to support a new heap region naming
       // convention in a newer Android version.
@@ -86,12 +90,7 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
     }
   }
 
-  // Linux and Android have no supported method to enumerate allocations in the
-  // heap of a remote process. Android does, however, support the malloc_iterate
-  // API, which enumerates allocations in the current process. We leverage this
-  // API by invoking it in the remote process using ptrace and using simple IPC
-  // (SIGTRAP and process_vm_readv and process_vm_writev).
-  internal func iterateHeapRegion(startAddr: UInt64, endAddr: UInt64) throws -> [(
+  internal func iterateHeapRegion(region: MemoryMap.Entry) throws -> [(
     base: swift_addr_t, len: UInt64
   )] {
     // We call mmap/munmap in the remote process to alloc/free memory for our
@@ -119,7 +118,9 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
     // Allocate a page-sized buffer in the remote process that malloc_iterate
     // will populaate with metadata describing each heap entry it enumerates.
     let dataLen = sysconf(Int32(_SC_PAGESIZE))
-    var mmapArgs = [0, UInt64(dataLen), UInt64(PROT_READ | PROT_WRITE), UInt64(MAP_ANON | MAP_PRIVATE)]
+    var mmapArgs = [
+      0, UInt64(dataLen), UInt64(PROT_READ | PROT_WRITE), UInt64(MAP_ANON | MAP_PRIVATE),
+    ]
     let remoteDataAddr: UInt64 = try self.ptrace.callRemoteFunction(at: mmapAddr, with: mmapArgs)
     defer {
       let munmapArgs: [UInt64] = [remoteDataAddr, UInt64(dataLen)]
@@ -128,7 +129,8 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
 
     // Allocate and inialize a local buffer that will be used to copy metadata
     // to/from the target process.
-    let buffer = UnsafeMutableRawPointer.allocate(byteCount: dataLen, alignment: MemoryLayout<UInt64>.alignment)
+    let buffer = UnsafeMutableRawPointer.allocate(
+      byteCount: dataLen, alignment: MemoryLayout<UInt64>.alignment)
     defer { buffer.deallocate() }
     guard heap_iterate_metadata_init(buffer, dataLen) else {
       throw RemoteProcessError.heapIterationFailed
@@ -160,8 +162,8 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
     }
 
     var allocations: [(base: swift_addr_t, len: UInt64)] = []
-    let regionLen = endAddr - startAddr
-    let args = [startAddr, regionLen, remoteCodeAddr, remoteDataAddr]
+    let regionLen = region.endAddr - region.startAddr
+    let args = [region.startAddr, regionLen, remoteCodeAddr, remoteDataAddr]
     _ = try self.ptrace.callRemoteFunction(at: mallocIterateAddr, with: args) {
       // This callback is invoked when a SIGTRAP is encountered in the remote
       // process. In this context, this signal indicates there is no more room
@@ -180,6 +182,7 @@ internal final class AndroidRemoteProcess: LinuxRemoteProcess {
       regs.step(RegisterSet.trapInstructionSize)
 
       try self.ptrace.setRegSet(regSet: regs)
+      try self.ptrace.cont()
     }
 
     try self.process.readMem(remoteAddr: remoteDataAddr, localAddr: buffer, len: UInt(dataLen))

tools/swift-inspect/Sources/swift-inspect/Process.swift

@@ -178,9 +178,9 @@ internal func process(matching: String) -> ProcessIdentifier? {
     return nil
   }
 
-  let procfs_path = "/proc/\(processId)"
+  let procfsPath = "/proc/\(processId)"
   var isDirectory: Bool = false
-  guard FileManager.default.fileExists(atPath: procfs_path, isDirectory: &isDirectory)
+  guard FileManager.default.fileExists(atPath: procfsPath, isDirectory: &isDirectory)
         && isDirectory else {
     return nil
   }