Add live debugger frontend and mutex stall recovery (#383)

src/SharpEmu.Core/Cpu/Debugging/ICpuDebugFrame.cs

@@ -0,0 +1,66 @@
+// Copyright (C) 2026 SharpEmu Emulator Project
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+using SharpEmu.HLE;
+
+namespace SharpEmu.Core.Cpu.Debugging;
+
+/// <summary>
+/// A live view of the guest CPU state at a dispatch boundary, handed to an
+/// <see cref="ICpuDebugHook"/> so a debugger can read and mutate registers and
+/// guest memory without taking a dependency on the concrete
+/// <c>CpuContext</c>/<c>CpuDispatcher</c> types.
+/// </summary>
+/// <remarks>
+/// The frame instance is only valid for the duration of the hook call that
+/// receives it (between <see cref="ICpuDebugHook.OnFrameEnter"/> and the
+/// matching <see cref="ICpuDebugHook.OnFrameExit"/>). Reads and writes are
+/// forwarded straight to the underlying guest context, so mutations made from
+/// a hook are observed by the CPU backend when it resumes the frame.
+/// </remarks>
+public interface ICpuDebugFrame
+{
+    /// <summary>The kind of frame being executed.</summary>
+    CpuDebugFrameKind Kind { get; }
+
+    /// <summary>The guest ABI generation this frame targets.</summary>
+    Generation Generation { get; }
+
+    /// <summary>The guest virtual address the frame begins executing at.</summary>
+    ulong EntryPoint { get; }
+
+    /// <summary>
+    /// A human-readable label for the frame (process image name or module name).
+    /// </summary>
+    string Label { get; }
+
+    /// <summary>Guest-addressable memory for this frame.</summary>
+    ICpuMemory Memory { get; }
+
+    /// <summary>Reads a general-purpose register.</summary>
+    ulong GetRegister(CpuRegister register);
+
+    /// <summary>Overwrites a general-purpose register.</summary>
+    void SetRegister(CpuRegister register, ulong value);
+
+    /// <summary>The instruction pointer.</summary>
+    ulong Rip { get; set; }
+
+    /// <summary>The flags register.</summary>
+    ulong Rflags { get; set; }
+
+    /// <summary>The FS segment base (guest TLS pointer).</summary>
+    ulong FsBase { get; }
+
+    /// <summary>The GS segment base.</summary>
+    ulong GsBase { get; }
+
+    /// <summary>Reads the 128-bit value of an XMM register.</summary>
+    void GetXmm(int registerIndex, out ulong low, out ulong high);
+
+    /// <summary>
+    /// The import stubs (guest address to NID) resolved for this frame, so a
+    /// debugger can annotate calls into HLE exports.
+    /// </summary>
+    IReadOnlyDictionary<ulong, string> ImportStubs { get; }
+}