[swift-inspect] full Android implementation including heap iteration

Author: andrurogerz

tools/swift-inspect/Package.swift

@@ -19,7 +19,8 @@ let package = Package(
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
                 .target(name: "SwiftInspectClient", condition: .when(platforms: [.windows])),
                 .target(name: "SwiftInspectClientInterface", condition: .when(platforms: [.windows])),
-                .target(name: "SwiftInspectLinux", condition: .when(platforms: [.linux])),
+                .target(name: "SwiftInspectLinux", condition: .when(platforms: [.linux, .android])),
+                .target(name: "AndroidCLib", condition: .when(platforms: [.android])),
             ],
             swiftSettings: [.unsafeFlags(["-parse-as-library"])]),
         .target(name: "SwiftInspectClient"),
@@ -32,6 +33,10 @@ let package = Package(
         .systemLibrary(
             name: "LinuxSystemHeaders",
             path: "Sources/SwiftInspectLinux/SystemHeaders"),
+        .target(
+            name: "AndroidCLib",
+            path: "Sources/AndroidCLib",
+            publicHeadersPath: "include"),
         .systemLibrary(
             name: "SwiftInspectClientInterface"),
         .testTarget(

tools/swift-inspect/README.md

@@ -32,6 +32,25 @@ In order to build on Windows with CMake, some additional parameters must be pass
 cmake -B out -G Ninja -S . -D ArgumentParser_DIR=... -D CMAKE_Swift_FLAGS="-Xcc -I%SDKROOT%\usr\include\swift\SwiftRemoteMirror"
 ~~~
 
+#### Android
+
+To cross-compile swift-inspect for Android, some additional parameters must be passed to the build tool to locate the toolchain and necessary libraries.
+
+~~~
+set ANDROID_ARCH=aarch64
+set ANDROID_API_LEVEL=29
+set ANDROID_NDK_ROOT=C:\Android\android-sdk\ndk\26.3.11579264
+set SWIFT_ANDROID_SDK_ROOT=C:\Users\Andrew\AppData\Local\Programs\Swift\Platforms\0.0.0\Android.platform\Developer\SDKs\Android.sdk
+swift build --triple %ANDROID_ARCH%-unknown-linux-android%ANDROID_API_LEVEL% `
+    --sdk %ANDROID_NDK_ROOT%\toolchains\llvm\prebuilt\windows-x86_64\sysroot `
+    -Xswiftc -sdk -Xswiftc %SWIFT_ANDROID_SDK_ROOT% `
+    -Xswiftc -sysroot -Xswiftc %ANDROID_NDK_ROOT%\toolchains\llvm\prebuilt\windows-x86_64\sysroot `
+    -Xswiftc -I -Xswiftc %SWIFT_ANDROID_SDK_ROOT%\usr\include `
+    -Xlinker -L%ANDROID_NDK_ROOT%\toolchains\llvm\prebuilt\windows-x86_64\lib\clang\17.0.2\lib\linux\%ANDROID_ARCH% `
+    -Xcc -I%SWIFT_ANDROID_SDK_ROOT%\usr\include\swift\SwiftRemoteMirror `
+    -Xlinker %SWIFT_ANDROID_SDK_ROOT%\usr\lib\swift\android\%ANDROID_ARCH%\libswiftRemoteMirror.so
+~~~
+
 ### Using
 
 The following inspection operations are available currently.

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

@@ -0,0 +1,77 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "heap.h"
+
+#if defined(__aarch64__) || defined(__ARM64__) || defined(_M_ARM64)
+#define DEBUG_BREAK() asm("brk #0x0; nop")
+#elif defined(_M_X64) || defined(__amd64__) || defined(__x86_64__) || defined(_M_AMD64)
+#define DEBUG_BREAK() asm("int3; nop")
+#else
+#error("only aarch64 and x86_64 are supported")
+#endif
+
+/* We allocate a buffer in the remote process that it populates with metadata
+ * describing each heap entry it enumerates. We then read the contents of the
+ * buffer, and individual heap entry contents, with process_vm_readv.
+ *
+ * The buffer is interpreted as an array of 8-byte pairs. The first pair
+ * contains metadata describing the buffer itself: max valid index (e.g. size of
+ * the buffer) and next index (e.g. write cursor/position). Each subsequent pair
+ * describes the address and length of a heap entry in the remote process.
+ *
+ * ------------
+ * | uint64_t | max valid index (e.g. sizeof(buffer) / sizeof(uint64_t))
+ * ------------
+ * | uint64_t | next free index (starts at 2)
+ * ------------
+ * | uint64_t | heap item 1 address
+ * ------------
+ * | uint64_t | heap item 1 size
+ * ------------
+ * | uint64_t | heap item 2 address
+ * ------------
+ * | uint64_t | heap item 2 size
+ * ------------
+ * | uint64_t | ...
+ * ------------
+ * | uint64_t | ...
+ * ------------
+ * | uint64_t | heap item N address
+ * ------------
+ * | uint64_t | heap item N size
+ * ------------
+ */
+
+// NOTE: this function cannot call any other functions and must only use
+// relative branches. We could inline assembly instead, but C is more reabable
+// and maintainable.
+static void remote_callback_start(unsigned long base, unsigned long size, void *arg) {
+  volatile uint64_t *data = (uint64_t*)arg;
+  while (data[HEAP_ITERATE_DATA_NEXT_FREE_IDX] >= data[HEAP_ITERATE_DATA_MAX_VALID_IDX]) {
+    DEBUG_BREAK();
+  }
+  data[data[HEAP_ITERATE_DATA_NEXT_FREE_IDX]++] = base;
+  data[data[HEAP_ITERATE_DATA_NEXT_FREE_IDX]++] = size;
+}
+
+// NOTE: this function is here to mark the end of remote_callback_start and is never
+// called.
+static void remote_callback_end() {}
+
+void* heap_callback_start() {
+  return (void*)remote_callback_start;
+}
+
+size_t heap_callback_len() {
+  return (size_t)(remote_callback_end - remote_callback_start);
+}

tools/swift-inspect/Sources/AndroidCLib/include/heap.h

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <unistd.h>
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#define HEAP_ITERATE_DATA_MAX_VALID_IDX 0
+#define HEAP_ITERATE_DATA_NEXT_FREE_IDX 1
+#define HEAP_ITERATE_DATA_HEADER_SIZE 2
+#define HEAP_ITERATE_DATA_ENTRY_SIZE  2
+
+typedef void (*heap_iterate_callback_t)(void* context, uint64_t base, uint64_t len);
+bool heap_iterate(pid_t pid, void* callback_context, heap_iterate_callback_t callback);
+
+void* heap_callback_start();
+size_t heap_callback_len();
+
+#if defined(__cplusplus)
+}
+#endif

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

@@ -0,0 +1,125 @@
+import Foundation
+import LinuxSystemHeaders
+
+public class PTrace {
+  enum Error: Swift.Error {
+    case PTraceFailure(_ command: Int32, pid: pid_t, errno: Int32 = get_errno())
+    case WaitFailure(pid: pid_t, errno: Int32 = get_errno())
+    case IllegalArgument(description: String)
+    case UnexpectedWaitStatus(pid: pid_t, status: Int32, sigInfo: siginfo_t? = nil)
+  }
+
+  let pid: pid_t
+
+  public init(process pid: pid_t) throws {
+    if ptrace_attach(pid) == -1 { throw Error.PTraceFailure(PTRACE_ATTACH, pid: pid) }
+
+    while true {
+      var status: Int32 = 0
+      let result = waitpid(pid, &status, 0)
+      if result == -1 {
+        if get_errno() == EINTR { continue }
+        throw Error.WaitFailure(pid: pid)
+      }
+
+      if result == pid && wIfStopped(status) { break }
+    }
+
+    self.pid = pid
+  }
+
+  deinit { ptrace_detach(self.pid) }
+
+  public func cont() throws {
+    if ptrace_continue(self.pid) == -1 { throw Error.PTraceFailure(PTRACE_CONT, pid: self.pid) }
+  }
+
+  public func getSigInfo() throws -> siginfo_t {
+    var sigInfo = siginfo_t()
+    if ptrace_getsiginfo(self.pid, &sigInfo) == -1 {
+      throw Error.PTraceFailure(PTRACE_GETSIGINFO, pid: self.pid)
+    }
+    return sigInfo
+  }
+
+  public func pokeData(addr: UInt64, value: UInt64) throws {
+    if ptrace_pokedata(self.pid, UInt(addr), UInt(value)) == -1 {
+      throw Error.PTraceFailure(PTRACE_POKEDATA, pid: self.pid)
+    }
+  }
+
+  public func getRegSet() throws -> RegisterSet {
+    var regSet = RegisterSet()
+    try withUnsafeMutableBytes(of: &regSet) {
+      var vec = iovec(iov_base: $0.baseAddress!, iov_len: MemoryLayout<RegisterSet>.size)
+      if ptrace_getregset(self.pid, NT_PRSTATUS, &vec) == -1 {
+        throw Error.PTraceFailure(PTRACE_GETREGSET, pid: self.pid)
+      }
+    }
+    return regSet
+  }
+
+  public func setRegSet(regSet: RegisterSet) throws {
+    var regSetCopy = regSet
+    try withUnsafeMutableBytes(of: &regSetCopy) {
+      var vec = iovec(iov_base: $0.baseAddress!, iov_len: MemoryLayout<RegisterSet>.size)
+      if ptrace_setregset(self.pid, NT_PRSTATUS, &vec) == -1 {
+        throw Error.PTraceFailure(PTRACE_SETREGSET, pid: self.pid)
+      }
+    }
+  }
+
+  public func callRemoteFunction(
+    at address: UInt64, with args: [UInt64] = [], onTrap callback: (() throws -> Void)? = nil
+  ) throws -> UInt64 {
+
+    guard args.count <= 6 else {
+      throw Error.IllegalArgument(description: "max of 6 arguments allowed")
+    }
+
+    let origRegs = try self.getRegSet()
+    defer { try? self.setRegSet(regSet: origRegs) }
+
+    // Set the return address to 0. This forces the function to return to 0 on
+    // completion, resulting in a SIGSEGV with address 0 which will interrupt
+    // the process and notify us (the tracer) via waitpid(). At that point, we
+    // will restore the original state and continue the process.
+    let returnAddr: UInt64 = 0
+
+    var newRegs = try origRegs.setupCall(self, to: address, with: args, returnTo: returnAddr)
+    try self.setRegSet(regSet: newRegs)
+    try self.cont()
+
+    var status: Int32 = 0
+    while true {
+      let result = waitpid(self.pid, &status, 0)
+      if result == -1 {
+        if get_errno() == EINTR { continue }
+        throw Error.WaitFailure(pid: self.pid)
+      }
+
+      if wIfExited(status) || wIfSignaled(status) {
+        throw Error.UnexpectedWaitStatus(pid: self.pid, status: status)
+      }
+
+      if wIfStopped(status) {
+        guard wStopSig(status) == SIGTRAP, let callback = callback else { break }
+
+        // give the caller the opportunity to handle SIGTRAP
+        try callback()
+        try self.cont()
+        continue
+      }
+    }
+
+    let sigInfo = try self.getSigInfo()
+    newRegs = try self.getRegSet()
+
+    guard wStopSig(status) == SIGSEGV, siginfo_si_addr(sigInfo) == nil else {
+      print("WSTOPSIG(status):\(wStopSig(status)), si_addr:\(siginfo_si_addr(sigInfo)!)")
+      throw Error.UnexpectedWaitStatus(pid: self.pid, status: status, sigInfo: sigInfo)
+    }
+
+    return UInt64(newRegs.returnValue())
+  }
+}

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

@@ -13,9 +13,25 @@
 import Foundation
 import LinuxSystemHeaders
 
+// The Android version of iovec defineds iov_len as __kernel_size_t, while the
+// standard Linux definition is size_t. This extension makes the difference
+// easier to deal with.
+public extension iovec {
+  init<T: BinaryInteger>(iov_base: UnsafeMutableRawPointer?, iov_len: T) {
+    self.init()
+    self.iov_base = iov_base
+    #if os(Android)
+      self.iov_len = __kernel_size_t(iov_len)
+    #else
+      self.iov_len = size_t(iov_len)
+    #endif
+  }
+}
+
 public class Process {
   public enum ProcessError: Error {
     case processVmReadFailure(pid: pid_t, address: UInt64, size: UInt64)
+    case processVmWriteFailure(pid: pid_t, address: UInt64, size: UInt64)
     case malformedString(address: UInt64)
   }
 
@@ -69,11 +85,12 @@ public class Process {
   // read an array of type T elements from the target process
   public func readArray<T>(address: UInt64, upToCount: UInt) throws -> [T] {
     guard upToCount > 0 else { return [] }
+
     let maxSize = upToCount * UInt(MemoryLayout<T>.stride)
     let array: [T] = Array(unsafeUninitializedCapacity: Int(upToCount)) { buffer, initCount in
-      var local = iovec(iov_base: buffer.baseAddress!, iov_len: Int(maxSize))
+      var local = iovec(iov_base: buffer.baseAddress!, iov_len: maxSize)
       var remote = iovec(
-        iov_base: UnsafeMutableRawPointer(bitPattern: UInt(address)), iov_len: Int(maxSize))
+        iov_base: UnsafeMutableRawPointer(bitPattern: UInt(address)), iov_len: maxSize)
       let bytesRead = process_vm_readv(self.pid, &local, 1, &remote, 1, 0)
       initCount = bytesRead / MemoryLayout<T>.stride
     }
@@ -84,4 +101,14 @@ public class Process {
 
     return array
   }
+
+  public func writeMem(remoteAddr: UInt64, localAddr: UnsafeRawPointer, len: UInt) throws {
+    var local = iovec(iov_base: UnsafeMutableRawPointer(mutating: localAddr), iov_len: len)
+    var remote = iovec(iov_base: UnsafeMutableRawPointer(bitPattern: UInt(remoteAddr)), iov_len: len)
+
+    let bytesWritten = process_vm_writev(self.pid, &local, 1, &remote, 1, 0)
+    guard bytesWritten == len else {
+      throw ProcessError.processVmWriteFailure(pid: self.pid, address: remoteAddr, size: UInt64(len))
+    }
+  }
 }