GDB RP: support qWasmCallStack and debugger breakpoints

.github/workflows/main.yml

@@ -137,19 +137,21 @@ jobs:
             wasi-swift-sdk-checksum: "b64dfad9e1c9ccdf06f35cf9b1a00317e000df0c0de0b3eb9f49d6db0fcba4d9"
             test-args: "--traits WasmDebuggingSupport --enable-code-coverage"
             build-dev-dashboard: true
-          - swift: "swiftlang/swift:nightly-main-noble"
-            development-toolchain-download: "https://download.swift.org/development/ubuntu2404/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a-ubuntu24.04.tar.gz"
-            wasi-swift-sdk-download: "https://download.swift.org/development/wasm-sdk/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm.artifactbundle.tar.gz"
-            wasi-swift-sdk-id: swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm
-            wasi-swift-sdk-checksum: "b64dfad9e1c9ccdf06f35cf9b1a00317e000df0c0de0b3eb9f49d6db0fcba4d9"
-            test-args: "--traits WasmDebuggingSupport -Xswiftc -DWASMKIT_CI_TOOLCHAIN_NIGHTLY"
-          - swift: "swiftlang/swift:nightly-main-noble"
-            development-toolchain-download: "https://download.swift.org/development/ubuntu2404/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a-ubuntu24.04.tar.gz"
-            wasi-swift-sdk-download: "https://download.swift.org/development/wasm-sdk/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm.artifactbundle.tar.gz"
-            wasi-swift-sdk-id: swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm
-            wasi-swift-sdk-checksum: "b64dfad9e1c9ccdf06f35cf9b1a00317e000df0c0de0b3eb9f49d6db0fcba4d9"
-            test-args: "--traits WasmDebuggingSupport -Xswiftc -DWASMKIT_CI_TOOLCHAIN_NIGHTLY --build-system swiftbuild"
-            label: " --build-system swiftbuild"
+            # Disabled until a toolchain containing https://github.com/swiftlang/swift/commit/b219d4089c922ceb8b700424236ca97f6087a9a1
+            # is tagged.
+          # - swift: "swiftlang/swift:nightly-main-noble"
+          #   development-toolchain-download: "https://download.swift.org/development/ubuntu2404/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a-ubuntu24.04.tar.gz"
+          #   wasi-swift-sdk-download: "https://download.swift.org/development/wasm-sdk/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm.artifactbundle.tar.gz"
+          #   wasi-swift-sdk-id: swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm
+          #   wasi-swift-sdk-checksum: "b64dfad9e1c9ccdf06f35cf9b1a00317e000df0c0de0b3eb9f49d6db0fcba4d9"
+          #   test-args: "--traits WasmDebuggingSupport -Xswiftc -DWASMKIT_CI_TOOLCHAIN_NIGHTLY"
+#           - swift: "swiftlang/swift:nightly-main-noble"
+#             development-toolchain-download: "https://download.swift.org/development/ubuntu2404/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a-ubuntu24.04.tar.gz"
+#             wasi-swift-sdk-download: "https://download.swift.org/development/wasm-sdk/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a/swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm.artifactbundle.tar.gz"
+#             wasi-swift-sdk-id: swift-DEVELOPMENT-SNAPSHOT-2025-10-02-a_wasm
+#             wasi-swift-sdk-checksum: "b64dfad9e1c9ccdf06f35cf9b1a00317e000df0c0de0b3eb9f49d6db0fcba4d9"
+#             test-args: "--traits WasmDebuggingSupport -Xswiftc -DWASMKIT_CI_TOOLCHAIN_NIGHTLY --build-system swiftbuild"
+#             label: " --build-system swiftbuild"
 
     runs-on: ubuntu-24.04
     name: "build-linux (${{ matrix.swift }}${{ matrix.label }})"

Package@swift-6.1.swift

@@ -21,7 +21,7 @@ let package = Package(
     ],
     traits: [
         .default(enabledTraits: []),
-        "WasmDebuggingSupport"
+        "WasmDebuggingSupport",
     ],
     targets: [
         .executableTarget(
@@ -123,7 +123,8 @@ let package = Package(
         .target(name: "WITExtractor"),
         .testTarget(name: "WITExtractorTests", dependencies: ["WITExtractor", "WIT"]),
 
-        .target(name: "GDBRemoteProtocol",
+        .target(
+            name: "GDBRemoteProtocol",
             dependencies: [
                 .product(name: "Logging", package: "swift-log"),
                 .product(name: "NIOCore", package: "swift-nio"),

Sources/GDBRemoteProtocol/GDBHostCommand.swift

@@ -38,6 +38,7 @@ package struct GDBHostCommand: Equatable {
         case readMemoryBinaryData
         case readMemory
         case wasmCallStack
+        case threadStopInfo
 
         case generalRegisters
 
@@ -97,6 +98,7 @@ package struct GDBHostCommand: Equatable {
     ///   - arguments: raw arguments that immediately follow kind of the command.
     package init(kindString: String, arguments: String) throws(GDBHostCommandDecoder.Error) {
         let registerInfoPrefix = "qRegisterInfo"
+        let threadStopInfoPrefix = "qThreadStopInfo"
 
         if kindString.starts(with: "x") {
             self.kind = .readMemoryBinaryData
@@ -109,6 +111,14 @@ package struct GDBHostCommand: Equatable {
         } else if kindString.starts(with: registerInfoPrefix) {
             self.kind = .registerInfo
 
+            guard arguments.isEmpty else {
+                throw GDBHostCommandDecoder.Error.unexpectedArgumentsValue
+            }
+            self.arguments = String(kindString.dropFirst(registerInfoPrefix.count))
+            return
+        } else if kindString.starts(with: threadStopInfoPrefix) {
+            self.kind = .threadStopInfo
+
             guard arguments.isEmpty else {
                 throw GDBHostCommandDecoder.Error.unexpectedArgumentsValue
             }

Sources/GDBRemoteProtocol/GDBTargetResponseEncoder.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 import Foundation
+import Logging
 import NIOCore
 
 extension String {
@@ -27,7 +28,12 @@ extension String {
 package class GDBTargetResponseEncoder: MessageToByteEncoder {
     private var isNoAckModeActive = false
 
-    package init() {}
+    private let logger: Logger
+
+    package init(logger: Logger) {
+        self.logger = logger
+    }
+
     package func encode(data: GDBTargetResponse, out: inout ByteBuffer) {
         if !isNoAckModeActive {
             out.writeInteger(UInt8(ascii: "+"))
@@ -51,8 +57,9 @@ package class GDBTargetResponseEncoder: MessageToByteEncoder {
             out.writeString(str.appendedChecksum)
 
         case .hexEncodedBinary(let binary):
-            let hexDump = ByteBuffer(bytes: binary).hexDump(format: .compact)
-            out.writeString(hexDump.appendedChecksum)
+            let hexDumpResponse = ByteBuffer(bytes: binary).hexDump(format: .compact).appendedChecksum
+            self.logger.trace("GDBTargetResponseEncoder encoded a response", metadata: ["RawResponse": .string(hexDumpResponse)])
+            out.writeString(hexDumpResponse)
 
         case .empty:
             out.writeString("".appendedChecksum)

Sources/WAT/Encoder.swift

@@ -158,6 +158,7 @@ extension TableType: WasmEncodable {
 struct ElementExprCollector: AnyInstructionVisitor {
     typealias Output = Void
 
+    var binaryOffset: Int = 0
     var isAllRefFunc: Bool = true
     var instructions: [Instruction] = []
 
@@ -443,6 +444,7 @@ extension WatParser.DataSegmentDecl {
 }
 
 struct ExpressionEncoder: BinaryInstructionEncoder {
+    var binaryOffset: Int = 0
     var encoder = Encoder()
     var hasDataSegmentInstruction: Bool = false
 

Sources/WAT/Parser/WastParser.swift

@@ -54,6 +54,7 @@ struct WastParser {
     }
 
     struct ConstExpressionCollector: WastConstInstructionVisitor {
+        var binaryOffset: Int = 0
         let addValue: (Value) -> Void
 
         mutating func visitI32Const(value: Int32) throws { addValue(.i32(UInt32(bitPattern: value))) }

Sources/WasmKit/CMakeLists.txt

@@ -11,6 +11,7 @@ add_wasmkit_library(WasmKit
   Component/CanonicalCall.swift
   Component/CanonicalOptions.swift
   Component/ComponentTypes.swift
+  Execution/DebuggerInstructionMapping.swift
   Execution/Instructions/Control.swift
   Execution/Instructions/Instruction.swift
   Execution/Instructions/Table.swift

Sources/WasmKit/Execution/Debugger.swift

@@ -0,0 +1,201 @@
+#if WasmDebuggingSupport
+    /// User-facing debugger state driven by a debugger host. This implementation has no knowledge of the exact
+    /// debugger protocol, which allows any protocol implementation or direct API users to be layered on top if needed.
+    package struct Debugger: ~Copyable {
+        package enum Error: Swift.Error, @unchecked Sendable {
+            case entrypointFunctionNotFound
+            case unknownCurrentFunctionForResumedBreakpoint(UnsafeMutablePointer<UInt64>)
+            case noInstructionMappingAvailable(Int)
+            case noReverseInstructionMappingAvailable(UnsafeMutablePointer<UInt64>)
+        }
+
+        private let valueStack: Sp
+        private var execution: Execution
+        private let store: Store
+
+        /// Parsed in-memory representation of a Wasm module instantiated for debugging.
+        private let module: Module
+
+        /// Instance of parsed Wasm ``module``.
+        private let instance: Instance
+
+        /// Reference to the entrypoint function of the currently debugged module, for use in ``stopAtEntrypoint``.
+        /// Currently assumed to be the WASI command `_start` entrypoint.
+        private let entrypointFunction: Function
+
+        /// Threading model of the Wasm engine configuration, cached for a potentially hot path.
+        private let threadingModel: EngineConfiguration.ThreadingModel
+
+        private(set) var breakpoints = [Int: CodeSlot]()
+
+        private var currentBreakpoint: (iseq: Execution.Breakpoint, wasmPc: Int)?
+
+        private var pc = Pc.allocate(capacity: 1)
+
+        /// Initializes a new debugger state instance.
+        /// - Parameters:
+        ///   - module: Wasm module to instantiate.
+        ///   - store: Store that instantiates the module.
+        ///   - imports: Imports required by `module` for instantiation.
+        package init(module: Module, store: Store, imports: Imports) throws {
+            let limit = store.engine.configuration.stackSize / MemoryLayout<StackSlot>.stride
+            let instance = try module.instantiate(store: store, imports: imports, isDebuggable: true)
+
+            guard case .function(let entrypointFunction) = instance.exports["_start"] else {
+                throw Error.entrypointFunctionNotFound
+            }
+
+            self.instance = instance
+            self.module = module
+            self.entrypointFunction = entrypointFunction
+            self.valueStack = UnsafeMutablePointer<StackSlot>.allocate(capacity: limit)
+            self.store = store
+            self.execution = Execution(store: StoreRef(store), stackEnd: valueStack.advanced(by: limit))
+            self.threadingModel = store.engine.configuration.threadingModel
+            self.pc.pointee = Instruction.endOfExecution.headSlot(threadingModel: threadingModel)
+        }
+
+        /// Sets a breakpoint at the first instruction in the entrypoint function of the module instantiated by
+        /// this debugger.
+        package mutating func stopAtEntrypoint() throws {
+            try self.enableBreakpoint(address: self.originalAddress(function: entrypointFunction))
+        }
+
+        /// Finds a Wasm address for the first instruction in a given function.
+        /// - Parameter function: the Wasm function to find the first Wasm instruction address for.
+        /// - Returns: byte offset of the first Wasm instruction of given function in the module it was parsed from.
+        private func originalAddress(function: Function) throws -> Int {
+            precondition(function.handle.isWasm)
+
+            switch function.handle.wasm.code {
+            case .debuggable(let wasm, _):
+                return wasm.originalAddress
+            case .uncompiled:
+                try function.handle.wasm.ensureCompiled(store: StoreRef(self.store))
+                return try self.originalAddress(function: function)
+            case .compiled:
+                fatalError()
+            }
+        }
+
+        /// Enables a breakpoint at a given Wasm address.
+        /// - Parameter address: byte offset of the Wasm instruction that will be replaced with a breakpoint. If no
+        /// direct internal bytecode matching instruction is found, the next closest internal bytecode instruction
+        /// is replaced with a breakpoint. The original instruction to be restored is preserved in debugger state
+        /// represented by `self`.
+        /// See also ``Debugger/disableBreakpoint(address:)``.
+        package mutating func enableBreakpoint(address: Int) throws(Error) {
+            guard self.breakpoints[address] == nil else {
+                return
+            }
+
+            guard let (iseq, wasm) = try self.instance.handle.instructionMapping.findIseq(forWasmAddress: address) else {
+                throw Error.noInstructionMappingAvailable(address)
+            }
+
+            self.breakpoints[wasm] = iseq.pointee
+            iseq.pointee = Instruction.breakpoint.headSlot(threadingModel: self.threadingModel)
+        }
+
+        /// Disables a breakpoint at a given Wasm address. If no breakpoint at a given address was previously set with
+        /// `self.enableBreakpoint(address:), this function immediately returns.
+        /// - Parameter address: byte offset of the Wasm instruction that was replaced with a breakpoint. The original
+        /// instruction is restored from debugger state and replaces the breakpoint instruction.
+        /// See also ``Debugger/enableBreakpoint(address:)``.
+        package mutating func disableBreakpoint(address: Int) throws(Error) {
+            guard let oldCodeSlot = self.breakpoints[address] else {
+                return
+            }
+
+            guard let (iseq, wasm) = try self.instance.handle.instructionMapping.findIseq(forWasmAddress: address) else {
+                throw Error.noInstructionMappingAvailable(address)
+            }
+
+            self.breakpoints[wasm] = nil
+            iseq.pointee = oldCodeSlot
+        }
+
+        /// Resumes the module instantiated by the debugger stopped at a breakpoint. The breakpoint is disabled
+        /// and execution is resumed until the next breakpoint is triggered or all remaining instructions are
+        /// executed. If the module is not stopped at a breakpoint, this function returns immediately.
+        /// - Returns: `[Value]` result of `entrypointFunction` if current instance ran to completion,
+        /// `nil` if it stopped at a breakpoint.
+        package mutating func run() throws -> [Value]? {
+            do {
+                if let currentBreakpoint {
+                    // Remove the breakpoint before resuming
+                    try self.disableBreakpoint(address: currentBreakpoint.wasmPc)
+                    self.execution.resetError()
+
+                    var sp = currentBreakpoint.iseq.sp
+                    var pc = currentBreakpoint.iseq.pc
+                    var md: Md = nil
+                    var ms: Ms = 0
+
+                    guard let currentFunction = sp.currentFunction else {
+                        throw Error.unknownCurrentFunctionForResumedBreakpoint(sp)
+                    }
+
+                    Execution.CurrentMemory.mayUpdateCurrentInstance(
+                        instance: currentFunction.instance,
+                        from: self.instance.handle,
+                        md: &md,
+                        ms: &ms
+                    )
+
+                    do {
+                        switch self.threadingModel {
+                        case .direct:
+                            try self.execution.runDirectThreaded(sp: sp, pc: pc, md: md, ms: ms)
+                        case .token:
+                            try self.execution.runTokenThreaded(sp: &sp, pc: &pc, md: &md, ms: &ms)
+                        }
+                    } catch is Execution.EndOfExecution {
+                    }
+
+                    let type = self.store.engine.funcTypeInterner.resolve(currentFunction.type)
+                    return type.results.enumerated().map { (i, type) in
+                        sp[VReg(i)].cast(to: type)
+                    }
+                } else {
+                    return try self.execution.executeWasm(
+                        threadingModel: self.threadingModel,
+                        function: self.entrypointFunction.handle,
+                        type: self.entrypointFunction.type,
+                        arguments: [],
+                        sp: self.valueStack,
+                        pc: self.pc
+                    )
+                }
+            } catch let breakpoint as Execution.Breakpoint {
+                let pc = breakpoint.pc
+                guard let wasmPc = self.instance.handle.instructionMapping.findWasm(forIseqAddress: pc) else {
+                    throw Error.noReverseInstructionMappingAvailable(pc)
+                }
+
+                self.currentBreakpoint = (breakpoint, wasmPc)
+                return nil
+            }
+        }
+
+        /// Array of addresses in the Wasm binary of executed instructions on the call stack.
+        package var currentCallStack: [Int] {
+            guard let currentBreakpoint else {
+                return []
+            }
+
+            var result = Execution.captureBacktrace(sp: currentBreakpoint.iseq.sp, store: self.store).symbols.compactMap {
+                return self.instance.handle.instructionMapping.findWasm(forIseqAddress: $0.address)
+            }
+            result.append(currentBreakpoint.wasmPc)
+
+            return result
+        }
+
+        deinit {
+            self.valueStack.deallocate()
+            self.pc.deallocate()
+        }
+    }
+
+#endif