mirror of
https://github.com/par274/sharpemu.git
synced 2026-09-06 08:43:06 +08:00
Add live debugger frontend and mutex stall recovery (#383)
This commit is contained in:
Spooks
@@ -262,6 +262,32 @@ internal static partial class Program
|
||||
return 2;
|
||||
}
|
||||
|
||||
if (!TryGetDebugServerOptions(args, out var debugServerEnabled, out var debugServerOptions, out var debugServerError))
|
||||
{
|
||||
Log.Error($"Invalid --debug-server endpoint: {debugServerError}");
|
||||
return 1;
|
||||
}
|
||||
|
||||
SharpEmu.Debugger.DebuggerServerHost? debugHost = null;
|
||||
if (debugServerEnabled)
|
||||
{
|
||||
debugHost = new SharpEmu.Debugger.DebuggerServerHost(debugServerOptions);
|
||||
try
|
||||
{
|
||||
debugHost.Start();
|
||||
Log.Info($"Live debug server listening on {debugHost.Endpoint}. Attach with SharpEmu.DebugClient.");
|
||||
// With StopAtEntry, the guest parks at its first frame until a
|
||||
// client connects and continues.
|
||||
runtimeOptions = runtimeOptions with { DebugHook = debugHost.Hook };
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Log.Error("Failed to start the debug server.", ex);
|
||||
debugHost.DisposeAsync().AsTask().GetAwaiter().GetResult();
|
||||
return 6;
|
||||
}
|
||||
}
|
||||
|
||||
Console.Error.WriteLine("[DEBUG] Creating runtime...");
|
||||
|
||||
try
|
||||
@@ -335,6 +361,12 @@ internal static partial class Program
|
||||
}
|
||||
finally
|
||||
{
|
||||
if (debugHost is not null)
|
||||
{
|
||||
debugHost.NotifyRunCompleted();
|
||||
debugHost.DisposeAsync().AsTask().GetAwaiter().GetResult();
|
||||
}
|
||||
|
||||
HostSessionControl.SetEmbeddedHostSurface(0);
|
||||
if (hostSurface is not null)
|
||||
{
|
||||
@@ -998,8 +1030,45 @@ internal static partial class Program
|
||||
|
||||
private static void PrintUsage()
|
||||
{
|
||||
Log.Info("Usage: SharpEmu.CLI [--strict] [--trace-imports[=N]] [--cpu-engine=<native>] [--log-level=<level>] [--log-file[=<path>]] <path-to-eboot.bin>");
|
||||
Log.Info("Usage: SharpEmu.CLI [--strict] [--trace-imports[=N]] [--cpu-engine=<native>] [--log-level=<level>] [--log-file[=<path>]] [--debug-server[=host:port]] <path-to-eboot.bin>");
|
||||
Log.Info(@"Example: SharpEmu.CLI --cpu-engine=native --trace-imports=64 --log-level=debug --log-file ""E:\Games\...\eboot.bin""");
|
||||
Log.Info("Debug server: --debug-server starts a live debug listener (default 127.0.0.1:5714); connect with SharpEmu.DebugClient.");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Detects the <c>--debug-server</c> flag and parses its optional
|
||||
/// <c>host:port</c> endpoint. Returns false only when the flag is present but
|
||||
/// its endpoint is malformed, so the caller can abort with a clear error.
|
||||
/// </summary>
|
||||
private static bool TryGetDebugServerOptions(
|
||||
string[] args,
|
||||
out bool enabled,
|
||||
out SharpEmu.Debugger.Server.DebuggerServerOptions options,
|
||||
out string error)
|
||||
{
|
||||
enabled = false;
|
||||
options = new SharpEmu.Debugger.Server.DebuggerServerOptions();
|
||||
error = string.Empty;
|
||||
foreach (var argument in args)
|
||||
{
|
||||
if (string.Equals(argument, "--debug-server", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
enabled = true;
|
||||
continue;
|
||||
}
|
||||
|
||||
const string prefix = "--debug-server=";
|
||||
if (argument.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
enabled = true;
|
||||
if (!SharpEmu.Debugger.Server.DebuggerServerOptions.TryParseEndpoint(argument[prefix.Length..], out options, out error))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static bool TryParseArguments(
|
||||
@@ -1033,6 +1102,15 @@ internal static partial class Program
|
||||
continue;
|
||||
}
|
||||
|
||||
// The debug-server endpoint is parsed separately (see
|
||||
// TryGetDebugServerOptions); accept the flag here so it is not
|
||||
// rejected as an unknown option or mistaken for the eboot path.
|
||||
if (string.Equals(argument, "--debug-server", StringComparison.OrdinalIgnoreCase) ||
|
||||
argument.StartsWith("--debug-server=", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (string.Equals(argument, "--trace-imports", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
importTraceLimit = DefaultImportTraceLimit;
|
||||
|
||||
@@ -7,6 +7,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\SharpEmu.Core\SharpEmu.Core.csproj" />
|
||||
<ProjectReference Include="..\SharpEmu.Debugger\SharpEmu.Debugger.csproj" />
|
||||
<ProjectReference Include="..\SharpEmu.GUI\SharpEmu.GUI.csproj" />
|
||||
<ProjectReference Include="..\SharpEmu.Logging\SharpEmu.Logging.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
@@ -216,9 +216,17 @@
|
||||
"type": "Project",
|
||||
"dependencies": {
|
||||
"Iced": "[1.21.0, )",
|
||||
"SharpEmu.HLE": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.Libs": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.Logging": "[0.0.2-beta.2, )"
|
||||
"SharpEmu.HLE": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.Libs": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.Logging": "[0.0.2-beta.3, )"
|
||||
}
|
||||
},
|
||||
"sharpemu.debugger": {
|
||||
"type": "Project",
|
||||
"dependencies": {
|
||||
"SharpEmu.Core": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.HLE": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.Logging": "[0.0.2-beta.3, )"
|
||||
}
|
||||
},
|
||||
"sharpemu.gui": {
|
||||
@@ -228,24 +236,24 @@
|
||||
"Avalonia.Desktop": "[11.3.18, )",
|
||||
"Avalonia.Fonts.Inter": "[11.3.18, )",
|
||||
"Avalonia.Themes.Fluent": "[11.3.18, )",
|
||||
"SharpEmu.Core": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.Libs": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.Logging": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.Core": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.Libs": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.Logging": "[0.0.2-beta.3, )",
|
||||
"Tmds.DBus.Protocol": "[0.21.3, )"
|
||||
}
|
||||
},
|
||||
"sharpemu.hle": {
|
||||
"type": "Project",
|
||||
"dependencies": {
|
||||
"SharpEmu.Logging": "[0.0.2-beta.2, )"
|
||||
"SharpEmu.Logging": "[0.0.2-beta.3, )"
|
||||
}
|
||||
},
|
||||
"sharpemu.libs": {
|
||||
"type": "Project",
|
||||
"dependencies": {
|
||||
"SharpEmu.HLE": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.ShaderCompiler": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.ShaderCompiler.Vulkan": "[0.0.2-beta.2, )",
|
||||
"SharpEmu.HLE": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.ShaderCompiler": "[0.0.2-beta.3, )",
|
||||
"SharpEmu.ShaderCompiler.Vulkan": "[0.0.2-beta.3, )",
|
||||
"Silk.NET.Input": "[2.23.0, )",
|
||||
"Silk.NET.Vulkan": "[2.23.0, )",
|
||||
"Silk.NET.Vulkan.Extensions.EXT": "[2.23.0, )",
|
||||
@@ -259,13 +267,13 @@
|
||||
"sharpemu.shadercompiler": {
|
||||
"type": "Project",
|
||||
"dependencies": {
|
||||
"SharpEmu.HLE": "[0.0.2-beta.2, )"
|
||||
"SharpEmu.HLE": "[0.0.2-beta.3, )"
|
||||
}
|
||||
},
|
||||
"sharpemu.shadercompiler.vulkan": {
|
||||
"type": "Project",
|
||||
"dependencies": {
|
||||
"SharpEmu.ShaderCompiler": "[0.0.2-beta.2, )"
|
||||
"SharpEmu.ShaderCompiler": "[0.0.2-beta.3, )"
|
||||
}
|
||||
},
|
||||
"Avalonia": {
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
|
||||
using System.Buffers.Binary;
|
||||
using System.Text;
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Core.Cpu.Native;
|
||||
using SharpEmu.Core.Loader;
|
||||
using SharpEmu.Core.Memory;
|
||||
@@ -272,7 +273,23 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
|
||||
entryFrameDiagnostic,
|
||||
Environment.NewLine,
|
||||
"CpuEngine: native-only");
|
||||
// Frame boundaries an attached debugger observes; null hook = a branch.
|
||||
var debugHook = executionOptions.DebugHook;
|
||||
var debugFrame = debugHook is null
|
||||
? null
|
||||
: new CpuContextDebugFrame(
|
||||
frameKind == EntryFrameKind.ProcessEntry
|
||||
? CpuDebugFrameKind.ProcessEntry
|
||||
: CpuDebugFrameKind.ModuleInitializer,
|
||||
entryPoint,
|
||||
processImageName,
|
||||
context,
|
||||
effectiveImportStubs);
|
||||
debugHook?.OnFrameEnter(debugFrame!);
|
||||
|
||||
_nativeCpuBackend ??= new DirectExecutionBackend(_moduleManager);
|
||||
// Let backend stall reports reference the same frame as entry.
|
||||
(_nativeCpuBackend as DirectExecutionBackend)?.SetActiveDebugFrame(debugFrame);
|
||||
if (_nativeCpuBackend.TryExecute(
|
||||
context,
|
||||
entryPoint,
|
||||
@@ -282,6 +299,7 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
|
||||
executionOptions,
|
||||
out var nativeResult))
|
||||
{
|
||||
debugHook?.OnFrameExit(debugFrame!, nativeResult);
|
||||
LastSessionSummary = new CpuSessionSummary(
|
||||
nativeResult,
|
||||
nativeResult == OrbisGen2Result.ORBIS_GEN2_OK
|
||||
@@ -296,6 +314,8 @@ public sealed class CpuDispatcher : ICpuDispatcher, IDisposable
|
||||
return nativeResult;
|
||||
}
|
||||
|
||||
debugHook?.OnFrameExit(debugFrame!, OrbisGen2Result.ORBIS_GEN2_ERROR_NOT_IMPLEMENTED);
|
||||
|
||||
var backendName = string.IsNullOrWhiteSpace(_nativeCpuBackend.BackendName)
|
||||
? "native-backend"
|
||||
: _nativeCpuBackend.BackendName;
|
||||
|
||||
@@ -1,15 +1,26 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
|
||||
namespace SharpEmu.Core.Cpu;
|
||||
|
||||
public readonly struct CpuExecutionOptions
|
||||
{
|
||||
public bool EnableDisasmDiagnostics { get; init; }
|
||||
|
||||
|
||||
public CpuExecutionEngine CpuEngine { get; init; }
|
||||
|
||||
public bool StrictDynlibResolution { get; init; }
|
||||
|
||||
public int ImportTraceLimit { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// An optional debugger attached to this execution session. When set, the
|
||||
/// dispatcher notifies it at each frame boundary via
|
||||
/// <see cref="ICpuDebugHook.OnFrameEnter"/> / <see cref="ICpuDebugHook.OnFrameExit"/>.
|
||||
/// Null when no debugger is attached, which is the default and imposes no
|
||||
/// runtime cost.
|
||||
/// </summary>
|
||||
public ICpuDebugHook? DebugHook { get; init; }
|
||||
}
|
||||
|
||||
@@ -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>
|
||||
/// Adapts a live <see cref="CpuContext"/> to <see cref="ICpuDebugFrame"/>. The
|
||||
/// dispatcher creates one of these around the guest context it is about to run
|
||||
/// and passes it to the attached <see cref="ICpuDebugHook"/>; every accessor
|
||||
/// forwards directly to the underlying context.
|
||||
/// </summary>
|
||||
internal sealed class CpuContextDebugFrame : ICpuDebugFrame
|
||||
{
|
||||
private readonly CpuContext _context;
|
||||
|
||||
internal CpuContextDebugFrame(
|
||||
CpuDebugFrameKind kind,
|
||||
ulong entryPoint,
|
||||
string label,
|
||||
CpuContext context,
|
||||
IReadOnlyDictionary<ulong, string> importStubs)
|
||||
{
|
||||
Kind = kind;
|
||||
EntryPoint = entryPoint;
|
||||
Label = label ?? string.Empty;
|
||||
_context = context ?? throw new ArgumentNullException(nameof(context));
|
||||
ImportStubs = importStubs ?? new Dictionary<ulong, string>();
|
||||
}
|
||||
|
||||
public CpuDebugFrameKind Kind { get; }
|
||||
|
||||
public Generation Generation => _context.TargetGeneration;
|
||||
|
||||
public ulong EntryPoint { get; }
|
||||
|
||||
public string Label { get; }
|
||||
|
||||
public ICpuMemory Memory => _context.Memory;
|
||||
|
||||
public ulong GetRegister(CpuRegister register) => _context[register];
|
||||
|
||||
public void SetRegister(CpuRegister register, ulong value) => _context[register] = value;
|
||||
|
||||
public ulong Rip
|
||||
{
|
||||
get => _context.Rip;
|
||||
set => _context.Rip = value;
|
||||
}
|
||||
|
||||
public ulong Rflags
|
||||
{
|
||||
get => _context.Rflags;
|
||||
set => _context.Rflags = value;
|
||||
}
|
||||
|
||||
public ulong FsBase => _context.FsBase;
|
||||
|
||||
public ulong GsBase => _context.GsBase;
|
||||
|
||||
public void GetXmm(int registerIndex, out ulong low, out ulong high)
|
||||
=> _context.GetXmmRegister(registerIndex, out low, out high);
|
||||
|
||||
public IReadOnlyDictionary<ulong, string> ImportStubs { get; }
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Core.Cpu.Debugging;
|
||||
|
||||
/// <summary>
|
||||
/// Identifies the kind of guest entry frame a debugger is observing. The
|
||||
/// dispatcher enters a fresh frame for the process entry point and for every
|
||||
/// module initializer, so the debug layer can label stops accordingly.
|
||||
/// </summary>
|
||||
public enum CpuDebugFrameKind
|
||||
{
|
||||
/// <summary>The guest process entry point (<c>eboot.bin</c> start).</summary>
|
||||
ProcessEntry,
|
||||
|
||||
/// <summary>A module DT_INIT / initializer routine.</summary>
|
||||
ModuleInitializer,
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Core.Cpu.Debugging;
|
||||
|
||||
/// <summary>The kind of execution stall the backend detected.</summary>
|
||||
public enum CpuStallKind
|
||||
{
|
||||
/// <summary>
|
||||
/// The guest is repeatedly re-dispatching the same import with no forward
|
||||
/// progress — most commonly a spin on a mutex lock/unlock pair.
|
||||
/// </summary>
|
||||
ImportLoop,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Details of a detected stall handed to <see cref="ICpuDebugHook.OnStall"/>.
|
||||
/// Reported from the emulation thread at the point the backend recognises the
|
||||
/// livelock, before it forces the guest out of the loop.
|
||||
/// </summary>
|
||||
public readonly struct CpuStallInfo
|
||||
{
|
||||
public CpuStallInfo(
|
||||
CpuStallKind kind,
|
||||
string? nid,
|
||||
ulong instructionPointer,
|
||||
long dispatchIndex,
|
||||
ulong argument0,
|
||||
ulong argument1,
|
||||
string detail,
|
||||
string? libraryName = null,
|
||||
string? functionName = null)
|
||||
{
|
||||
Kind = kind;
|
||||
Nid = nid;
|
||||
InstructionPointer = instructionPointer;
|
||||
DispatchIndex = dispatchIndex;
|
||||
Argument0 = argument0;
|
||||
Argument1 = argument1;
|
||||
Detail = detail ?? string.Empty;
|
||||
LibraryName = libraryName;
|
||||
FunctionName = functionName;
|
||||
}
|
||||
|
||||
public CpuStallKind Kind { get; }
|
||||
|
||||
/// <summary>The NID of the import being spun on, when known.</summary>
|
||||
public string? Nid { get; }
|
||||
|
||||
/// <summary>The guest return address of the looping import dispatch.</summary>
|
||||
public ulong InstructionPointer { get; }
|
||||
|
||||
/// <summary>The import dispatch counter at detection time.</summary>
|
||||
public long DispatchIndex { get; }
|
||||
|
||||
/// <summary>The first two guest ABI arguments at stall detection.</summary>
|
||||
public ulong Argument0 { get; }
|
||||
|
||||
public ulong Argument1 { get; }
|
||||
|
||||
/// <summary>The resolved HLE export, when the NID is registered.</summary>
|
||||
public string? LibraryName { get; }
|
||||
|
||||
public string? FunctionName { get; }
|
||||
|
||||
public bool IsResolved => !string.IsNullOrWhiteSpace(FunctionName);
|
||||
|
||||
/// <summary>A human-readable one-line summary of the stall.</summary>
|
||||
public string Detail { get; }
|
||||
}
|
||||
@@ -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; }
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.HLE;
|
||||
|
||||
namespace SharpEmu.Core.Cpu.Debugging;
|
||||
|
||||
/// <summary>
|
||||
/// The seam the CPU dispatcher uses to notify an attached debugger when guest
|
||||
/// execution crosses a frame boundary. Implemented outside of Core (for
|
||||
/// example by <c>SharpEmu.Debugger</c>) and supplied through
|
||||
/// <see cref="CpuExecutionOptions.DebugHook"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This is intentionally coarse-grained: it exposes the entry and exit of each
|
||||
/// dispatched frame rather than per-instruction stepping. Per-instruction
|
||||
/// control requires cooperation from the native execution backend and is layered
|
||||
/// on top of this seam as the backend gains support; keeping the dispatcher-level
|
||||
/// contract stable lets the debugger infrastructure exist independently of that
|
||||
/// work. Implementations must be thread-safe: frames may be dispatched from the
|
||||
/// dedicated emulation thread while a debug server services clients on its own
|
||||
/// threads.
|
||||
/// </remarks>
|
||||
public interface ICpuDebugHook
|
||||
{
|
||||
/// <summary>
|
||||
/// Invoked immediately before the native backend begins executing a frame.
|
||||
/// The debugger may inspect or mutate <paramref name="frame"/> and may block
|
||||
/// the calling thread (for example, to honour a pause request) before
|
||||
/// returning to allow execution to proceed.
|
||||
/// </summary>
|
||||
void OnFrameEnter(ICpuDebugFrame frame);
|
||||
|
||||
/// <summary>
|
||||
/// Invoked after a frame completes, whether it returned to the host or
|
||||
/// terminated with an error. <paramref name="frame"/> reflects the final
|
||||
/// guest state.
|
||||
/// </summary>
|
||||
void OnFrameExit(ICpuDebugFrame frame, OrbisGen2Result result);
|
||||
|
||||
/// <summary>
|
||||
/// Invoked from the emulation thread when the backend detects an execution
|
||||
/// stall (for example a mutex spin loop) in the running frame, before it
|
||||
/// forces the guest out of the loop. As with <see cref="OnFrameEnter"/>, the
|
||||
/// implementation may inspect <paramref name="frame"/> and block to honour a
|
||||
/// break before returning to let the backend proceed.
|
||||
/// </summary>
|
||||
void OnStall(ICpuDebugFrame frame, CpuStallInfo info);
|
||||
}
|
||||
@@ -10,6 +10,7 @@ using System.Runtime.InteropServices;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using System.Threading;
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Core.Cpu;
|
||||
using SharpEmu.HLE;
|
||||
using SharpEmu.Libs.Kernel;
|
||||
@@ -316,11 +317,15 @@ public sealed partial class DirectExecutionBackend
|
||||
}
|
||||
if (!isGuestWorker &&
|
||||
!ActiveForcedGuestExit &&
|
||||
ShouldForceGuestExitOnImportLoop(in importStubEntry, num7, num, value, value2) &&
|
||||
TryForceGuestExitToHostStub(argPackPtr, num, num7, importStubEntry.Nid))
|
||||
ShouldForceGuestExitOnImportLoop(in importStubEntry, num7, num, value, value2))
|
||||
{
|
||||
cpuContext[CpuRegister.Rax] = 1uL;
|
||||
return 1uL;
|
||||
// Break before the forced exit so the loop state is still live.
|
||||
NotifyDebuggerStall(CpuStallKind.ImportLoop, in importStubEntry, num7, num, value, value2);
|
||||
if (TryForceGuestExitToHostStub(argPackPtr, num, num7, importStubEntry.Nid))
|
||||
{
|
||||
cpuContext[CpuRegister.Rax] = 1uL;
|
||||
return 1uL;
|
||||
}
|
||||
}
|
||||
bool flag0 = importStubEntry.SuppressStrlenTrace;
|
||||
bool flag = num7 >= 2156221920u && num7 <= 2156225024u;
|
||||
|
||||
@@ -9,6 +9,7 @@ using System.Linq;
|
||||
using System.Runtime.InteropServices;
|
||||
using System.Threading;
|
||||
using SharpEmu.Core.Cpu;
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Core.Loader;
|
||||
using SharpEmu.Core.Memory;
|
||||
using SharpEmu.HLE;
|
||||
@@ -235,6 +236,11 @@ public sealed unsafe partial class DirectExecutionBackend : INativeCpuBackend, I
|
||||
|
||||
private CpuContext? _cpuContext;
|
||||
|
||||
// Debugger seam; both null when no debugger is attached.
|
||||
private ICpuDebugHook? _debugHook;
|
||||
|
||||
private ICpuDebugFrame? _activeDebugFrame;
|
||||
|
||||
[ThreadStatic]
|
||||
private static DirectExecutionBackend? _activeExecutionBackend;
|
||||
|
||||
@@ -890,6 +896,49 @@ public sealed unsafe partial class DirectExecutionBackend : INativeCpuBackend, I
|
||||
|
||||
private bool HasActiveExecutionThread => ReferenceEquals(_activeExecutionBackend, this);
|
||||
|
||||
/// <summary>
|
||||
/// Binds the debug frame view the dispatcher created for the frame about to
|
||||
/// run, so stall notifications reference the same frame the debugger saw at
|
||||
/// entry. Set to null when no debugger is attached.
|
||||
/// </summary>
|
||||
internal void SetActiveDebugFrame(ICpuDebugFrame? frame) => _activeDebugFrame = frame;
|
||||
|
||||
/// <summary>
|
||||
/// Notifies an attached debugger of a detected execution stall. No-op when no
|
||||
/// debugger is attached or no frame is bound. The debugger may block here to
|
||||
/// present a break before the backend forces the guest out of the loop.
|
||||
/// </summary>
|
||||
private void NotifyDebuggerStall(
|
||||
CpuStallKind kind,
|
||||
in ImportStubEntry import,
|
||||
ulong instructionPointer,
|
||||
long dispatchIndex,
|
||||
ulong argument0,
|
||||
ulong argument1)
|
||||
{
|
||||
var hook = _debugHook;
|
||||
var frame = _activeDebugFrame;
|
||||
if (hook is null || frame is null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var export = import.Export;
|
||||
var exportDescription = export is null ? "unresolved" : $"{export.LibraryName}:{export.Name}";
|
||||
var detail = $"kind={kind}, nid={import.Nid}, export={exportDescription}, dispatch#{dispatchIndex}, " +
|
||||
$"rip=0x{instructionPointer:X16}, arg0=0x{argument0:X16}, arg1=0x{argument1:X16}";
|
||||
hook.OnStall(frame, new CpuStallInfo(
|
||||
kind,
|
||||
import.Nid,
|
||||
instructionPointer,
|
||||
dispatchIndex,
|
||||
argument0,
|
||||
argument1,
|
||||
detail,
|
||||
export?.LibraryName,
|
||||
export?.Name));
|
||||
}
|
||||
|
||||
private CpuContext? ActiveCpuContext => HasActiveExecutionThread ? _activeCpuContext : _cpuContext;
|
||||
|
||||
private ulong ActiveEntryReturnSentinelRip
|
||||
@@ -1051,6 +1100,7 @@ public sealed unsafe partial class DirectExecutionBackend : INativeCpuBackend, I
|
||||
Console.Error.WriteLine(_moduleManager.TryGetExport("L-Q3LEjIbgA", out ExportedFunction export2) ? ("[LOADER][INFO] ExportCheck map_direct: " + export2.LibraryName + ":" + export2.Name) : "[LOADER][INFO] ExportCheck map_direct: MISSING");
|
||||
_entryPoint = entryPoint;
|
||||
_cpuContext = context;
|
||||
_debugHook = executionOptions.DebugHook;
|
||||
_returnFallbackTarget = context[CpuRegister.Rsi];
|
||||
Volatile.Write(ref _globalFallbackTarget, _returnFallbackTarget);
|
||||
Volatile.Write(ref _globalUnresolvedReturnStub, (ulong)_unresolvedReturnStub);
|
||||
|
||||
@@ -68,6 +68,7 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
|
||||
CpuEngine = cpuExecutionOptions.CpuEngine,
|
||||
StrictDynlibResolution = cpuExecutionOptions.StrictDynlibResolution,
|
||||
ImportTraceLimit = Math.Max(0, cpuExecutionOptions.ImportTraceLimit),
|
||||
DebugHook = cpuExecutionOptions.DebugHook,
|
||||
};
|
||||
_fileSystem = fileSystem ?? new PhysicalFileSystem();
|
||||
}
|
||||
@@ -79,6 +80,7 @@ public sealed class SharpEmuRuntime : ISharpEmuRuntime
|
||||
CpuEngine = options.CpuEngine,
|
||||
StrictDynlibResolution = options.StrictDynlibResolution,
|
||||
ImportTraceLimit = Math.Max(0, options.ImportTraceLimit),
|
||||
DebugHook = options.DebugHook,
|
||||
};
|
||||
var moduleManager = new ModuleManager();
|
||||
// The compile-time generated registry (SharpEmu.SourceGenerators) is the sole
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
namespace SharpEmu.Core.Runtime;
|
||||
|
||||
using SharpEmu.Core.Cpu;
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
|
||||
public readonly struct SharpEmuRuntimeOptions
|
||||
{
|
||||
@@ -12,4 +13,11 @@ public readonly struct SharpEmuRuntimeOptions
|
||||
public bool StrictDynlibResolution { get; init; }
|
||||
|
||||
public int ImportTraceLimit { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// An optional debugger to attach to guest execution. Flows through to
|
||||
/// <see cref="CpuExecutionOptions.DebugHook"/>. Null (the default) runs with
|
||||
/// no debugger attached.
|
||||
/// </summary>
|
||||
public ICpuDebugHook? DebugHook { get; init; }
|
||||
}
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net;
|
||||
|
||||
namespace SharpEmu.DebugClient;
|
||||
|
||||
/// <summary>
|
||||
/// Parses the <c>host:port</c> the client connects to. Mirrors the server's
|
||||
/// defaults (loopback, port 5714) so a bare invocation attaches to a local
|
||||
/// emulator with no arguments.
|
||||
/// </summary>
|
||||
internal static class ClientEndpoint
|
||||
{
|
||||
public const int DefaultPort = 5714;
|
||||
|
||||
public static bool TryParse(string? text, out string host, out int port, out string error)
|
||||
{
|
||||
host = "127.0.0.1";
|
||||
port = DefaultPort;
|
||||
error = string.Empty;
|
||||
if (string.IsNullOrWhiteSpace(text))
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
var value = text.Trim();
|
||||
var separator = value.LastIndexOf(':');
|
||||
if (separator >= 0)
|
||||
{
|
||||
var portText = value[(separator + 1)..];
|
||||
if (portText.Length > 0 && (!int.TryParse(portText, out port) || port is <= 0 or > 65535))
|
||||
{
|
||||
error = $"Invalid port '{portText}'.";
|
||||
return false;
|
||||
}
|
||||
|
||||
value = value[..separator];
|
||||
}
|
||||
|
||||
if (!string.IsNullOrWhiteSpace(value))
|
||||
{
|
||||
host = string.Equals(value, "localhost", StringComparison.OrdinalIgnoreCase) ? "127.0.0.1" : value;
|
||||
}
|
||||
|
||||
if (!IPAddress.TryParse(host, out _) && !Uri.CheckHostName(host).Equals(UriHostNameType.Dns))
|
||||
{
|
||||
error = $"Invalid host '{host}'.";
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,160 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Text.Json;
|
||||
|
||||
namespace SharpEmu.DebugClient;
|
||||
|
||||
/// <summary>
|
||||
/// Turns a friendly REPL line (<c>mem 0x1000 64</c>) into the JSON request the
|
||||
/// server understands. Local-only verbs (help, quit) are reported back to the
|
||||
/// caller instead of producing a request.
|
||||
/// </summary>
|
||||
internal static class CommandTranslator
|
||||
{
|
||||
public enum ActionKind
|
||||
{
|
||||
SendRequest,
|
||||
ShowHelp,
|
||||
Quit,
|
||||
Ignore,
|
||||
Error,
|
||||
}
|
||||
|
||||
public readonly record struct Result(ActionKind Kind, string? Payload = null, string? Error = null);
|
||||
|
||||
public static Result Translate(string line)
|
||||
{
|
||||
var trimmed = line.Trim();
|
||||
if (trimmed.Length == 0)
|
||||
{
|
||||
return new Result(ActionKind.Ignore);
|
||||
}
|
||||
|
||||
var parts = trimmed.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);
|
||||
var verb = parts[0].ToLowerInvariant();
|
||||
switch (verb)
|
||||
{
|
||||
case "help" or "?":
|
||||
return new Result(ActionKind.ShowHelp);
|
||||
case "quit" or "exit" or "q":
|
||||
return new Result(ActionKind.Quit);
|
||||
case "raw":
|
||||
var json = trimmed[verb.Length..].Trim();
|
||||
return json.Length == 0
|
||||
? Error("raw requires a JSON object argument.")
|
||||
: Send(json);
|
||||
|
||||
case "ping":
|
||||
return Request("ping");
|
||||
case "status" or "info":
|
||||
return Request("status");
|
||||
case "state":
|
||||
return Request("state");
|
||||
case "regs" or "registers":
|
||||
return Request("registers");
|
||||
case "continue" or "cont" or "c":
|
||||
return Request("continue");
|
||||
case "step" or "s":
|
||||
return Request("step");
|
||||
case "pause" or "p":
|
||||
return Request("pause");
|
||||
case "bp" or "breakpoints" or "bl":
|
||||
return Request("list-breakpoints");
|
||||
|
||||
case "setreg":
|
||||
return parts.Length >= 3
|
||||
? Request("set-register", ("register", parts[1]), ("value", parts[2]))
|
||||
: Error("Usage: setreg <register> <value>");
|
||||
case "mem" or "read":
|
||||
return parts.Length >= 3
|
||||
? Request("read-memory", ("address", parts[1]), ("length", parts[2]))
|
||||
: Error("Usage: mem <address> <length>");
|
||||
case "write":
|
||||
return parts.Length >= 3
|
||||
? Request("write-memory", ("address", parts[1]), ("bytes", parts[2]))
|
||||
: Error("Usage: write <address> <hex-bytes>");
|
||||
case "break" or "b":
|
||||
if (parts.Length < 2)
|
||||
{
|
||||
return Error("Usage: break <address> [kind] [length]");
|
||||
}
|
||||
|
||||
var breakArgs = new List<(string, string)> { ("address", parts[1]) };
|
||||
if (parts.Length >= 3)
|
||||
{
|
||||
breakArgs.Add(("kind", parts[2]));
|
||||
}
|
||||
|
||||
if (parts.Length >= 4)
|
||||
{
|
||||
breakArgs.Add(("length", parts[3]));
|
||||
}
|
||||
|
||||
return Request("add-breakpoint", breakArgs.ToArray());
|
||||
case "del" or "rm" or "delete":
|
||||
return parts.Length >= 2
|
||||
? Request("remove-breakpoint", ("id", parts[1]))
|
||||
: Error("Usage: del <id>");
|
||||
case "enable":
|
||||
return parts.Length >= 2
|
||||
? Request("enable-breakpoint", ("id", parts[1]), ("enabled", "true"))
|
||||
: Error("Usage: enable <id>");
|
||||
case "disable":
|
||||
return parts.Length >= 2
|
||||
? RequestWithBool("enable-breakpoint", ("id", parts[1]), enabledName: "enabled", enabled: false)
|
||||
: Error("Usage: disable <id>");
|
||||
|
||||
default:
|
||||
return Error($"Unknown command '{verb}'. Type 'help' for the command list.");
|
||||
}
|
||||
}
|
||||
|
||||
private static Result Request(string command, params (string Name, string Value)[] args)
|
||||
{
|
||||
var payload = new Dictionary<string, object?> { ["command"] = command };
|
||||
foreach (var (name, value) in args)
|
||||
{
|
||||
payload[name] = value;
|
||||
}
|
||||
|
||||
return Send(JsonSerializer.Serialize(payload));
|
||||
}
|
||||
|
||||
private static Result RequestWithBool(string command, (string Name, string Value) idArg, string enabledName, bool enabled)
|
||||
{
|
||||
var payload = new Dictionary<string, object?>
|
||||
{
|
||||
["command"] = command,
|
||||
[idArg.Name] = idArg.Value,
|
||||
[enabledName] = enabled,
|
||||
};
|
||||
return Send(JsonSerializer.Serialize(payload));
|
||||
}
|
||||
|
||||
private static Result Send(string json) => new(ActionKind.SendRequest, json);
|
||||
|
||||
private static Result Error(string message) => new(ActionKind.Error, Error: message);
|
||||
|
||||
public const string HelpText = """
|
||||
SharpEmu debug client commands:
|
||||
status | info Show target state and last stop
|
||||
state Show run state only
|
||||
regs | registers Dump integer registers (paused only)
|
||||
setreg <reg> <value> Set a register (rip/rflags/gp, paused only)
|
||||
mem <addr> <len> Read guest memory as hex (paused only)
|
||||
write <addr> <hex> Write guest memory from hex (paused only)
|
||||
break <addr> [kind] [len] Add a breakpoint (kind: execute/readwatch/writewatch/accesswatch)
|
||||
bp | breakpoints List breakpoints
|
||||
del <id> Remove a breakpoint
|
||||
enable <id> / disable <id> Toggle a breakpoint
|
||||
continue | c Resume the target
|
||||
step | s Resume and stop at the next frame
|
||||
pause Ask a running target to stop
|
||||
ping Round-trip check
|
||||
raw <json> Send a literal JSON request
|
||||
help | ? Show this help
|
||||
quit | exit Disconnect and exit
|
||||
Addresses and values accept decimal or 0x-prefixed hex.
|
||||
""";
|
||||
}
|
||||
@@ -0,0 +1,153 @@
|
||||
<!--
|
||||
Copyright (C) 2026 SharpEmu Emulator Project
|
||||
SPDX-License-Identifier: GPL-2.0-or-later
|
||||
-->
|
||||
|
||||
# SharpEmu.DebugClient
|
||||
|
||||
A small, standalone command-line client that connects to the SharpEmu
|
||||
emulator's **live debug server** and drives it interactively. It ships as its
|
||||
own executable (`SharpEmu.DebugClient`) and takes no dependency on the emulator
|
||||
assemblies — it speaks the server's line-delimited JSON protocol directly over
|
||||
TCP, so you can also drive the server from `nc`, a script, or your own tool.
|
||||
|
||||
> **Status:** infrastructure. The transport, protocol, session model, and
|
||||
> breakpoint store are in place. Stops are delivered at **frame boundaries**
|
||||
> (process entry and each module initializer); per-instruction stepping and data
|
||||
> watchpoints are part of the surface and become live as the CPU backend grows
|
||||
> the corresponding hooks. See [`docs/debugger-server.md`](../../docs/debugger-server.md)
|
||||
> for the architecture and protocol reference.
|
||||
|
||||
## How it fits together
|
||||
|
||||
```
|
||||
+-------------------------+ TCP (JSON lines) +----------------------+
|
||||
| SharpEmu (emulator) | <------------------------------> | SharpEmu.DebugClient |
|
||||
| --debug-server | | (this executable) |
|
||||
| | | |
|
||||
| DebuggerServerHost | | REPL / --exec |
|
||||
| +- DebuggerServer | frame boundaries via ICpuDebugHook| |
|
||||
| +- DebuggerSession <-+------ CPU dispatcher ------------ | |
|
||||
+-------------------------+ +----------------------+
|
||||
```
|
||||
|
||||
The emulator is the **server**; this client is a separate process that connects
|
||||
to it and issues commands. The two never share memory — everything crosses the
|
||||
socket as JSON.
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
dotnet build src/SharpEmu.DebugClient/SharpEmu.DebugClient.csproj
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
1. Launch the emulator with the debug server enabled. It listens on
|
||||
`127.0.0.1:5714` by default and, with stop-at-entry on, parks the guest at
|
||||
its first frame until you continue:
|
||||
|
||||
```bash
|
||||
SharpEmu --debug-server "/path/to/game/eboot.bin"
|
||||
# or choose an endpoint:
|
||||
SharpEmu --debug-server=127.0.0.1:5714 "/path/to/game/eboot.bin"
|
||||
```
|
||||
|
||||
2. In another terminal, attach the client:
|
||||
|
||||
```bash
|
||||
SharpEmu.DebugClient # defaults to 127.0.0.1:5714
|
||||
SharpEmu.DebugClient 127.0.0.1:5714 # explicit endpoint
|
||||
```
|
||||
|
||||
3. Drive the target:
|
||||
|
||||
```
|
||||
status
|
||||
regs
|
||||
break 0x00000008801234a0
|
||||
continue
|
||||
mem 0x00000008802000000 64
|
||||
```
|
||||
|
||||
## Invocation
|
||||
|
||||
```
|
||||
SharpEmu.DebugClient [host:port] [--exec "<command>"]... [--quiet]
|
||||
```
|
||||
|
||||
| Option | Meaning |
|
||||
| ------------- | ------------------------------------------------------------- |
|
||||
| `host:port` | Server endpoint. Default `127.0.0.1:5714`. `localhost` is fine. |
|
||||
| `--exec, -e` | Run one command non-interactively, then exit. Repeatable. |
|
||||
| `--quiet` | Suppress the connection banner. |
|
||||
| `--help, -h` | Show usage and the command list. |
|
||||
|
||||
Non-interactive example (scriptable):
|
||||
|
||||
```bash
|
||||
SharpEmu.DebugClient --exec "break 0x8801234a0" --exec "continue"
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
Addresses and values accept decimal or `0x`-prefixed hex. Register and memory
|
||||
commands only succeed while the target is **paused**.
|
||||
|
||||
| Command | Server verb | Description |
|
||||
| ------- | ----------- | ----------- |
|
||||
| `status` \| `info` | `status` | Target state plus the last stop. |
|
||||
| `state` | `state` | Run state only (`Running`/`Paused`/…). |
|
||||
| `regs` \| `registers` | `registers` | Dump the integer registers. |
|
||||
| `setreg <reg> <value>` | `set-register` | Set `rip`, `rflags`, or a GP register. |
|
||||
| `mem <addr> <len>` \| `read <addr> <len>` | `read-memory` | Read guest memory as hex. |
|
||||
| `write <addr> <hex>` | `write-memory` | Write guest memory from a hex string. |
|
||||
| `break <addr> [kind] [len]` \| `b …` | `add-breakpoint` | Add a breakpoint. `kind`: `execute` (default), `readwatch`, `writewatch`, `accesswatch`. |
|
||||
| `bp` \| `breakpoints` | `list-breakpoints` | List breakpoints. |
|
||||
| `del <id>` \| `rm <id>` | `remove-breakpoint` | Remove a breakpoint. |
|
||||
| `enable <id>` / `disable <id>` | `enable-breakpoint` | Toggle a breakpoint. |
|
||||
| `continue` \| `c` | `continue` | Resume a paused target. |
|
||||
| `step` \| `s` | `step` | Resume and stop at the next frame boundary. |
|
||||
| `pause` | `pause` | Ask a running target to stop at the next boundary. |
|
||||
| `ping` | `ping` | Round-trip liveness check. |
|
||||
| `raw <json>` | *(passthrough)* | Send a literal JSON request. |
|
||||
| `help` \| `?` | — | Show the command list (local). |
|
||||
| `quit` \| `exit` | — | Disconnect and exit (local). |
|
||||
|
||||
## Output
|
||||
|
||||
The client prints two kinds of lines as they arrive:
|
||||
|
||||
- `reply>` — the response to a command you sent (`ok`, plus `data` or `error`).
|
||||
- `event>` — an unsolicited notification: `hello` on connect, `stopped` when the
|
||||
target hits a breakpoint / entry / step / pause, `resumed` on continue, and
|
||||
`terminated` when the run ends.
|
||||
|
||||
Because replies and events share one stream, the client prints everything it
|
||||
receives rather than pairing replies to requests — a `stopped` event may arrive
|
||||
between your command and its reply.
|
||||
|
||||
## Protocol (for building your own client)
|
||||
|
||||
One JSON object per line, UTF-8, `\n`-terminated, in both directions.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{"command":"read-memory","address":"0x8802000000","length":64}
|
||||
```
|
||||
|
||||
Reply:
|
||||
|
||||
```json
|
||||
{"ok":true,"command":"read-memory","data":{"address":"0x0000000880200000","length":64,"bytes":"48894C24.."}}
|
||||
```
|
||||
|
||||
Event:
|
||||
|
||||
```json
|
||||
{"event":"stopped","reason":"Breakpoint","address":"0x00000008801234A0","frameKind":"ProcessEntry","frameLabel":"eboot.bin","registers":{ ... }}
|
||||
```
|
||||
|
||||
The full verb list and payload fields live in
|
||||
[`docs/debugger-server.md`](../../docs/debugger-server.md).
|
||||
@@ -0,0 +1,120 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net.Sockets;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
|
||||
namespace SharpEmu.DebugClient;
|
||||
|
||||
/// <summary>
|
||||
/// A thin TCP wrapper around the server's line-delimited JSON protocol: it
|
||||
/// writes request lines and runs a background loop that prints incoming
|
||||
/// responses and events as they arrive. Because the stream interleaves replies
|
||||
/// with asynchronous stop/resume events, a single reader printing everything is
|
||||
/// simpler and more robust than correlating request/response pairs.
|
||||
/// </summary>
|
||||
internal sealed class DebugClientConnection : IAsyncDisposable
|
||||
{
|
||||
private static readonly UTF8Encoding Utf8NoBom = new(encoderShouldEmitUTF8Identifier: false);
|
||||
private static readonly JsonSerializerOptions PrettyOptions = new() { WriteIndented = true };
|
||||
|
||||
private readonly TcpClient _client;
|
||||
private readonly StreamReader _reader;
|
||||
private readonly StreamWriter _writer;
|
||||
private readonly SemaphoreSlim _writeLock = new(1, 1);
|
||||
|
||||
private DebugClientConnection(TcpClient client, NetworkStream stream)
|
||||
{
|
||||
_client = client;
|
||||
_reader = new StreamReader(stream, Utf8NoBom);
|
||||
_writer = new StreamWriter(stream, Utf8NoBom) { AutoFlush = false };
|
||||
}
|
||||
|
||||
public static async Task<DebugClientConnection> ConnectAsync(string host, int port, CancellationToken cancellationToken)
|
||||
{
|
||||
var client = new TcpClient();
|
||||
await client.ConnectAsync(host, port, cancellationToken).ConfigureAwait(false);
|
||||
return new DebugClientConnection(client, client.GetStream());
|
||||
}
|
||||
|
||||
/// <summary>Continuously prints incoming lines until the stream closes.</summary>
|
||||
public async Task ReceiveLoopAsync(CancellationToken cancellationToken)
|
||||
{
|
||||
try
|
||||
{
|
||||
while (!cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
var line = await _reader.ReadLineAsync(cancellationToken).ConfigureAwait(false);
|
||||
if (line is null)
|
||||
{
|
||||
Console.WriteLine();
|
||||
Console.WriteLine("[connection closed by server]");
|
||||
return;
|
||||
}
|
||||
|
||||
Print(line);
|
||||
}
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
}
|
||||
catch (IOException)
|
||||
{
|
||||
Console.WriteLine();
|
||||
Console.WriteLine("[connection lost]");
|
||||
}
|
||||
}
|
||||
|
||||
public async Task SendAsync(string json, CancellationToken cancellationToken)
|
||||
{
|
||||
await _writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
await _writer.WriteLineAsync(json.AsMemory(), cancellationToken).ConfigureAwait(false);
|
||||
await _writer.FlushAsync(cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
finally
|
||||
{
|
||||
_writeLock.Release();
|
||||
}
|
||||
}
|
||||
|
||||
private static void Print(string line)
|
||||
{
|
||||
try
|
||||
{
|
||||
using var document = JsonDocument.Parse(line);
|
||||
var root = document.RootElement;
|
||||
var isEvent = root.TryGetProperty("event", out _);
|
||||
var prefix = isEvent ? "event>" : "reply>";
|
||||
var pretty = JsonSerializer.Serialize(root, PrettyOptions);
|
||||
Console.WriteLine();
|
||||
Console.WriteLine($"{prefix}\n{pretty}");
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
Console.WriteLine();
|
||||
Console.WriteLine(line);
|
||||
}
|
||||
}
|
||||
|
||||
public async ValueTask DisposeAsync()
|
||||
{
|
||||
try
|
||||
{
|
||||
await _writer.FlushAsync().ConfigureAwait(false);
|
||||
}
|
||||
catch (IOException)
|
||||
{
|
||||
}
|
||||
catch (ObjectDisposedException)
|
||||
{
|
||||
}
|
||||
|
||||
_writeLock.Dispose();
|
||||
_reader.Dispose();
|
||||
await _writer.DisposeAsync().ConfigureAwait(false);
|
||||
_client.Dispose();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,193 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net.Sockets;
|
||||
using SharpEmu.DebugClient;
|
||||
|
||||
return await ClientProgram.RunAsync(args).ConfigureAwait(false);
|
||||
|
||||
internal static class ClientProgram
|
||||
{
|
||||
public static async Task<int> RunAsync(string[] args)
|
||||
{
|
||||
if (args.Any(a => a is "--help" or "-h"))
|
||||
{
|
||||
PrintUsage();
|
||||
return 0;
|
||||
}
|
||||
|
||||
string? endpointArg = null;
|
||||
var execCommands = new List<string>();
|
||||
var quiet = false;
|
||||
for (var i = 0; i < args.Length; i++)
|
||||
{
|
||||
var arg = args[i];
|
||||
if (string.Equals(arg, "--exec", StringComparison.OrdinalIgnoreCase) || string.Equals(arg, "-e", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
if (i + 1 >= args.Length)
|
||||
{
|
||||
Console.Error.WriteLine("--exec requires a command argument.");
|
||||
return 2;
|
||||
}
|
||||
|
||||
execCommands.Add(args[++i]);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (string.Equals(arg, "--quiet", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
quiet = true;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (arg.StartsWith('-'))
|
||||
{
|
||||
Console.Error.WriteLine($"Unknown option '{arg}'.");
|
||||
PrintUsage();
|
||||
return 2;
|
||||
}
|
||||
|
||||
endpointArg ??= arg;
|
||||
}
|
||||
|
||||
if (!ClientEndpoint.TryParse(endpointArg, out var host, out var port, out var endpointError))
|
||||
{
|
||||
Console.Error.WriteLine(endpointError);
|
||||
return 2;
|
||||
}
|
||||
|
||||
using var shutdown = new CancellationTokenSource();
|
||||
Console.CancelKeyPress += (_, eventArgs) =>
|
||||
{
|
||||
eventArgs.Cancel = true;
|
||||
shutdown.Cancel();
|
||||
};
|
||||
|
||||
DebugClientConnection connection;
|
||||
try
|
||||
{
|
||||
connection = await DebugClientConnection.ConnectAsync(host, port, shutdown.Token).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex) when (ex is SocketException or OperationCanceledException)
|
||||
{
|
||||
Console.Error.WriteLine($"Could not connect to {host}:{port}: {ex.Message}");
|
||||
Console.Error.WriteLine("Start the emulator with --debug-server first.");
|
||||
return 3;
|
||||
}
|
||||
|
||||
await using (connection)
|
||||
{
|
||||
var receiveTask = connection.ReceiveLoopAsync(shutdown.Token);
|
||||
|
||||
if (execCommands.Count > 0)
|
||||
{
|
||||
await RunOneShotAsync(connection, execCommands, shutdown.Token).ConfigureAwait(false);
|
||||
}
|
||||
else
|
||||
{
|
||||
if (!quiet)
|
||||
{
|
||||
Console.WriteLine($"Connected to SharpEmu debug server at {host}:{port}.");
|
||||
Console.WriteLine("Type 'help' for commands, 'quit' to exit.");
|
||||
}
|
||||
|
||||
await RunReplAsync(connection, shutdown).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
shutdown.Cancel();
|
||||
try
|
||||
{
|
||||
await receiveTask.ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
}
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private static async Task RunOneShotAsync(
|
||||
DebugClientConnection connection,
|
||||
IReadOnlyList<string> commands,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
foreach (var command in commands)
|
||||
{
|
||||
var result = CommandTranslator.Translate(command);
|
||||
switch (result.Kind)
|
||||
{
|
||||
case CommandTranslator.ActionKind.SendRequest:
|
||||
await connection.SendAsync(result.Payload!, cancellationToken).ConfigureAwait(false);
|
||||
break;
|
||||
case CommandTranslator.ActionKind.Error:
|
||||
Console.Error.WriteLine(result.Error);
|
||||
break;
|
||||
case CommandTranslator.ActionKind.ShowHelp:
|
||||
Console.WriteLine(CommandTranslator.HelpText);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Give the server a moment to answer before the client exits.
|
||||
try
|
||||
{
|
||||
await Task.Delay(TimeSpan.FromMilliseconds(500), cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
}
|
||||
}
|
||||
|
||||
private static async Task RunReplAsync(DebugClientConnection connection, CancellationTokenSource shutdown)
|
||||
{
|
||||
while (!shutdown.IsCancellationRequested)
|
||||
{
|
||||
var line = await Console.In.ReadLineAsync(shutdown.Token).ConfigureAwait(false);
|
||||
if (line is null)
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
var result = CommandTranslator.Translate(line);
|
||||
switch (result.Kind)
|
||||
{
|
||||
case CommandTranslator.ActionKind.Quit:
|
||||
return;
|
||||
case CommandTranslator.ActionKind.ShowHelp:
|
||||
Console.WriteLine(CommandTranslator.HelpText);
|
||||
break;
|
||||
case CommandTranslator.ActionKind.Error:
|
||||
Console.Error.WriteLine(result.Error);
|
||||
break;
|
||||
case CommandTranslator.ActionKind.Ignore:
|
||||
break;
|
||||
case CommandTranslator.ActionKind.SendRequest:
|
||||
try
|
||||
{
|
||||
await connection.SendAsync(result.Payload!, shutdown.Token).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or ObjectDisposedException)
|
||||
{
|
||||
Console.Error.WriteLine("Send failed; the connection is closed.");
|
||||
return;
|
||||
}
|
||||
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private static void PrintUsage()
|
||||
{
|
||||
Console.WriteLine("SharpEmu.DebugClient — live debugger client for the SharpEmu debug server.");
|
||||
Console.WriteLine();
|
||||
Console.WriteLine("Usage: SharpEmu.DebugClient [host:port] [--exec \"<command>\"]... [--quiet]");
|
||||
Console.WriteLine(" host:port Server endpoint (default 127.0.0.1:5714).");
|
||||
Console.WriteLine(" --exec, -e Run a command non-interactively (repeatable), then exit.");
|
||||
Console.WriteLine(" --quiet Suppress the connection banner.");
|
||||
Console.WriteLine(" --help, -h Show this help.");
|
||||
Console.WriteLine();
|
||||
Console.WriteLine(CommandTranslator.HelpText);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
<!--
|
||||
Copyright (C) 2026 SharpEmu Emulator Project
|
||||
SPDX-License-Identifier: GPL-2.0-or-later
|
||||
-->
|
||||
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<PropertyGroup>
|
||||
<!-- A small, standalone console tool: it speaks the debug server's
|
||||
line-delimited JSON protocol directly over TCP and takes no dependency
|
||||
on the emulator assemblies, so it builds and ships independently. -->
|
||||
<OutputType>Exe</OutputType>
|
||||
<AssemblyName>SharpEmu.DebugClient</AssemblyName>
|
||||
<RootNamespace>SharpEmu.DebugClient</RootNamespace>
|
||||
<NoWarn>$(NoWarn);1591</NoWarn>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
@@ -0,0 +1,48 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Breakpoints;
|
||||
|
||||
/// <summary>
|
||||
/// A single breakpoint or watchpoint. Instances are immutable; the owning
|
||||
/// <see cref="BreakpointStore"/> replaces an entry to change its enabled state.
|
||||
/// </summary>
|
||||
public sealed class Breakpoint
|
||||
{
|
||||
public Breakpoint(int id, BreakpointKind kind, ulong address, ulong length = 1, bool enabled = true)
|
||||
{
|
||||
if (length == 0)
|
||||
{
|
||||
throw new ArgumentOutOfRangeException(nameof(length), "Breakpoint length must be at least one byte.");
|
||||
}
|
||||
|
||||
Id = id;
|
||||
Kind = kind;
|
||||
Address = address;
|
||||
Length = length;
|
||||
Enabled = enabled;
|
||||
}
|
||||
|
||||
/// <summary>The store-assigned identifier used by clients to reference it.</summary>
|
||||
public int Id { get; }
|
||||
|
||||
public BreakpointKind Kind { get; }
|
||||
|
||||
/// <summary>The first guest address the breakpoint covers.</summary>
|
||||
public ulong Address { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The number of bytes the breakpoint covers. Always one for
|
||||
/// <see cref="BreakpointKind.Execute"/>; the watch kinds may span a range.
|
||||
/// </summary>
|
||||
public ulong Length { get; }
|
||||
|
||||
public bool Enabled { get; }
|
||||
|
||||
/// <summary>True when <paramref name="address"/> falls within this breakpoint.</summary>
|
||||
public bool Covers(ulong address) => address >= Address && address < Address + Length;
|
||||
|
||||
/// <summary>Returns a copy with a different enabled state.</summary>
|
||||
public Breakpoint WithEnabled(bool enabled)
|
||||
=> enabled == Enabled ? this : new Breakpoint(Id, Kind, Address, Length, enabled);
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Breakpoints;
|
||||
|
||||
/// <summary>
|
||||
/// The kind of stop a breakpoint requests. Execution breakpoints are honoured
|
||||
/// at the frame-boundary seam that exists today; the data-watch kinds are part
|
||||
/// of the surface so client protocols and tooling can be built against them,
|
||||
/// and are armed once the execution backend can report the corresponding
|
||||
/// accesses.
|
||||
/// </summary>
|
||||
public enum BreakpointKind
|
||||
{
|
||||
/// <summary>Stop when the instruction pointer reaches the address.</summary>
|
||||
Execute,
|
||||
|
||||
/// <summary>Stop when the guest reads from the address range.</summary>
|
||||
ReadWatch,
|
||||
|
||||
/// <summary>Stop when the guest writes to the address range.</summary>
|
||||
WriteWatch,
|
||||
|
||||
/// <summary>Stop when the guest reads from or writes to the address range.</summary>
|
||||
AccessWatch,
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Breakpoints;
|
||||
|
||||
/// <summary>
|
||||
/// A thread-safe registry of breakpoints. The debug server mutates it from
|
||||
/// client-servicing threads while the emulation thread queries it at frame
|
||||
/// boundaries, so every operation takes the same lock.
|
||||
/// </summary>
|
||||
public sealed class BreakpointStore
|
||||
{
|
||||
private readonly object _sync = new();
|
||||
private readonly Dictionary<int, Breakpoint> _breakpoints = new();
|
||||
private int _nextId = 1;
|
||||
|
||||
/// <summary>Adds a breakpoint and returns the created entry with its id.</summary>
|
||||
public Breakpoint Add(BreakpointKind kind, ulong address, ulong length = 1)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
var effectiveLength = kind == BreakpointKind.Execute ? 1UL : Math.Max(1UL, length);
|
||||
var breakpoint = new Breakpoint(_nextId++, kind, address, effectiveLength);
|
||||
_breakpoints[breakpoint.Id] = breakpoint;
|
||||
return breakpoint;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Removes a breakpoint by id. Returns false when it did not exist.</summary>
|
||||
public bool Remove(int id)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
return _breakpoints.Remove(id);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Enables or disables a breakpoint by id.</summary>
|
||||
public bool SetEnabled(int id, bool enabled)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (!_breakpoints.TryGetValue(id, out var breakpoint))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
_breakpoints[id] = breakpoint.WithEnabled(enabled);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Removes every breakpoint.</summary>
|
||||
public void Clear()
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
_breakpoints.Clear();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Returns a point-in-time copy of all breakpoints.</summary>
|
||||
public IReadOnlyList<Breakpoint> Snapshot()
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
return _breakpoints.Values.ToArray();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Finds the first enabled execution breakpoint covering <paramref name="address"/>,
|
||||
/// or null when none applies.
|
||||
/// </summary>
|
||||
public Breakpoint? FindExecuteHit(ulong address)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
foreach (var breakpoint in _breakpoints.Values)
|
||||
{
|
||||
if (breakpoint.Enabled && breakpoint.Kind == BreakpointKind.Execute && breakpoint.Covers(address))
|
||||
{
|
||||
return breakpoint;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.HLE;
|
||||
|
||||
namespace SharpEmu.Debugger;
|
||||
|
||||
/// <summary>
|
||||
/// An immutable snapshot of the guest integer register state at a stop. XMM/YMM
|
||||
/// state is intentionally omitted here and read on demand through the target to
|
||||
/// keep the common register-dump path cheap.
|
||||
/// </summary>
|
||||
public readonly struct DebugRegisterFile
|
||||
{
|
||||
private readonly ulong[] _generalPurpose;
|
||||
|
||||
public DebugRegisterFile(
|
||||
ulong[] generalPurpose,
|
||||
ulong rip,
|
||||
ulong rflags,
|
||||
ulong fsBase,
|
||||
ulong gsBase)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(generalPurpose);
|
||||
if (generalPurpose.Length != 16)
|
||||
{
|
||||
throw new ArgumentException("Expected 16 general-purpose registers.", nameof(generalPurpose));
|
||||
}
|
||||
|
||||
_generalPurpose = generalPurpose;
|
||||
Rip = rip;
|
||||
Rflags = rflags;
|
||||
FsBase = fsBase;
|
||||
GsBase = gsBase;
|
||||
}
|
||||
|
||||
public ulong Rip { get; }
|
||||
|
||||
public ulong Rflags { get; }
|
||||
|
||||
public ulong FsBase { get; }
|
||||
|
||||
public ulong GsBase { get; }
|
||||
|
||||
/// <summary>Reads a register by identifier.</summary>
|
||||
public ulong this[DebugRegisterId id] => id switch
|
||||
{
|
||||
DebugRegisterId.Rip => Rip,
|
||||
DebugRegisterId.Rflags => Rflags,
|
||||
DebugRegisterId.FsBase => FsBase,
|
||||
DebugRegisterId.GsBase => GsBase,
|
||||
_ when id.IsGeneralPurpose() => _generalPurpose[(int)id],
|
||||
_ => throw new ArgumentOutOfRangeException(nameof(id), id, null),
|
||||
};
|
||||
|
||||
/// <summary>Reads a general-purpose register.</summary>
|
||||
public ulong this[CpuRegister register] => _generalPurpose[(int)register];
|
||||
|
||||
/// <summary>Captures the integer register state of a live debug frame.</summary>
|
||||
public static DebugRegisterFile Capture(ICpuDebugFrame frame)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(frame);
|
||||
|
||||
var gpr = new ulong[16];
|
||||
for (var i = 0; i < gpr.Length; i++)
|
||||
{
|
||||
gpr[i] = frame.GetRegister((CpuRegister)i);
|
||||
}
|
||||
|
||||
return new DebugRegisterFile(gpr, frame.Rip, frame.Rflags, frame.FsBase, frame.GsBase);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.HLE;
|
||||
|
||||
namespace SharpEmu.Debugger;
|
||||
|
||||
/// <summary>
|
||||
/// The registers a debugger can name. The first sixteen values line up with
|
||||
/// <see cref="CpuRegister"/> so a general-purpose register can be converted
|
||||
/// between the two enums by casting; the remaining values cover the special
|
||||
/// registers a debug frame exposes.
|
||||
/// </summary>
|
||||
public enum DebugRegisterId
|
||||
{
|
||||
Rax = 0,
|
||||
Rcx = 1,
|
||||
Rdx = 2,
|
||||
Rbx = 3,
|
||||
Rsp = 4,
|
||||
Rbp = 5,
|
||||
Rsi = 6,
|
||||
Rdi = 7,
|
||||
R8 = 8,
|
||||
R9 = 9,
|
||||
R10 = 10,
|
||||
R11 = 11,
|
||||
R12 = 12,
|
||||
R13 = 13,
|
||||
R14 = 14,
|
||||
R15 = 15,
|
||||
|
||||
Rip = 16,
|
||||
Rflags = 17,
|
||||
FsBase = 18,
|
||||
GsBase = 19,
|
||||
}
|
||||
|
||||
/// <summary>Helpers for mapping between debug and CPU register identifiers.</summary>
|
||||
public static class DebugRegisterIdExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// True when the identifier names one of the sixteen general-purpose
|
||||
/// registers and can be cast to <see cref="CpuRegister"/>.
|
||||
/// </summary>
|
||||
public static bool IsGeneralPurpose(this DebugRegisterId id)
|
||||
=> id is >= DebugRegisterId.Rax and <= DebugRegisterId.R15;
|
||||
|
||||
/// <summary>
|
||||
/// Converts a general-purpose identifier to its <see cref="CpuRegister"/>.
|
||||
/// Throws when <paramref name="id"/> is a special register.
|
||||
/// </summary>
|
||||
public static CpuRegister ToCpuRegister(this DebugRegisterId id)
|
||||
{
|
||||
if (!id.IsGeneralPurpose())
|
||||
{
|
||||
throw new ArgumentOutOfRangeException(nameof(id), id, "Not a general-purpose register.");
|
||||
}
|
||||
|
||||
return (CpuRegister)(int)id;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net;
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Debugger.Server;
|
||||
using SharpEmu.Debugger.Session;
|
||||
|
||||
namespace SharpEmu.Debugger;
|
||||
|
||||
/// <summary>
|
||||
/// One-call wiring of the live debugger: it owns a <see cref="DebuggerSession"/>
|
||||
/// and a <see cref="DebuggerServer"/>, exposes the <see cref="Hook"/> to attach
|
||||
/// to <c>SharpEmuRuntimeOptions.DebugHook</c>, and starts/stops the network
|
||||
/// front-end. A host constructs one, hands <see cref="Hook"/> to the runtime,
|
||||
/// calls <see cref="Start"/>, and calls <see cref="NotifyRunCompleted"/> once the
|
||||
/// runtime returns.
|
||||
/// </summary>
|
||||
public sealed class DebuggerServerHost : IAsyncDisposable
|
||||
{
|
||||
private readonly DebuggerSession _session;
|
||||
private readonly DebuggerServer _server;
|
||||
|
||||
public DebuggerServerHost(
|
||||
DebuggerServerOptions? serverOptions = null,
|
||||
DebuggerSessionOptions? sessionOptions = null)
|
||||
{
|
||||
_session = new DebuggerSession(sessionOptions);
|
||||
_server = new DebuggerServer(_session, serverOptions);
|
||||
}
|
||||
|
||||
/// <summary>The session driving the target.</summary>
|
||||
public IDebuggerSession Session => _session;
|
||||
|
||||
/// <summary>
|
||||
/// The dispatcher hook to hand to the runtime so guest frames route through
|
||||
/// the debugger.
|
||||
/// </summary>
|
||||
public ICpuDebugHook Hook => _session.Hook;
|
||||
|
||||
/// <summary>The endpoint the server bound to, or null before <see cref="Start"/>.</summary>
|
||||
public IPEndPoint? Endpoint => _server.Endpoint;
|
||||
|
||||
/// <summary>Begins accepting debugger clients.</summary>
|
||||
public void Start() => _server.Start();
|
||||
|
||||
/// <summary>
|
||||
/// Releases a parked emulation thread and marks the target terminated. Call
|
||||
/// after the runtime's run returns so any attached client is notified and the
|
||||
/// guest thread is never left blocked in the debugger.
|
||||
/// </summary>
|
||||
public void NotifyRunCompleted() => _session.NotifyTerminated();
|
||||
|
||||
public async ValueTask DisposeAsync()
|
||||
{
|
||||
_session.NotifyTerminated();
|
||||
await _server.DisposeAsync().ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,340 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.Debugger.Breakpoints;
|
||||
using SharpEmu.Debugger.Session;
|
||||
using SharpEmu.HLE;
|
||||
|
||||
namespace SharpEmu.Debugger.Protocol;
|
||||
|
||||
/// <summary>
|
||||
/// Translates parsed <see cref="DebugRequest"/> verbs into operations on an
|
||||
/// <see cref="IDebuggerSession"/> and packages the outcome as a
|
||||
/// <see cref="DebugResponse"/>. This is the single place command semantics live,
|
||||
/// so it is shared by every connection and independent of the wire format.
|
||||
/// </summary>
|
||||
public sealed class DebugCommandDispatcher
|
||||
{
|
||||
private readonly IDebuggerSession _session;
|
||||
|
||||
public DebugCommandDispatcher(IDebuggerSession session)
|
||||
{
|
||||
_session = session ?? throw new ArgumentNullException(nameof(session));
|
||||
}
|
||||
|
||||
public DebugResponse Dispatch(DebugRequest request)
|
||||
{
|
||||
return request.Command switch
|
||||
{
|
||||
JsonLineDebugProtocol.ParseErrorCommand => ParseError(request),
|
||||
"ping" => DebugResponse.Success(request.Command),
|
||||
"status" or "info" => Status(request),
|
||||
"state" => DebugResponse.Success(request.Command, new Dictionary<string, object?>
|
||||
{
|
||||
["state"] = _session.State.ToString(),
|
||||
}),
|
||||
"registers" or "regs" => Registers(request),
|
||||
"set-register" or "set-reg" => SetRegister(request),
|
||||
"read-memory" or "read-mem" => ReadMemory(request),
|
||||
"write-memory" or "write-mem" => WriteMemory(request),
|
||||
"list-breakpoints" or "breakpoints" => ListBreakpoints(request),
|
||||
"add-breakpoint" or "break" => AddBreakpoint(request),
|
||||
"remove-breakpoint" or "delete-breakpoint" => RemoveBreakpoint(request),
|
||||
"enable-breakpoint" => EnableBreakpoint(request),
|
||||
"continue" or "cont" or "c" => Simple(request, _session.Continue(), "Target is not paused."),
|
||||
"step" or "s" => Simple(request, _session.StepFrame(), "Target is not paused."),
|
||||
"pause" => Pause(request),
|
||||
_ => DebugResponse.Failure(request.Command, $"Unknown command '{request.Command}'."),
|
||||
};
|
||||
}
|
||||
|
||||
private static DebugResponse ParseError(DebugRequest request)
|
||||
{
|
||||
var message = request.TryGetString("message", out var text) ? text : "Malformed request.";
|
||||
return DebugResponse.Failure(request.Command, message);
|
||||
}
|
||||
|
||||
private DebugResponse Status(DebugRequest request)
|
||||
{
|
||||
var data = new Dictionary<string, object?>
|
||||
{
|
||||
["state"] = _session.State.ToString(),
|
||||
["breakpoints"] = _session.Breakpoints.Snapshot().Count,
|
||||
};
|
||||
|
||||
if (_session.LastStop is { } stop)
|
||||
{
|
||||
data["lastStop"] = DescribeStop(stop);
|
||||
}
|
||||
|
||||
return DebugResponse.Success(request.Command, data);
|
||||
}
|
||||
|
||||
private DebugResponse Registers(DebugRequest request)
|
||||
{
|
||||
if (!_session.TryGetRegisters(out var registers))
|
||||
{
|
||||
return NotPaused(request);
|
||||
}
|
||||
|
||||
return DebugResponse.Success(request.Command, new Dictionary<string, object?>
|
||||
{
|
||||
["registers"] = DescribeRegisters(registers),
|
||||
});
|
||||
}
|
||||
|
||||
private DebugResponse SetRegister(DebugRequest request)
|
||||
{
|
||||
if (!request.TryGetString("register", out var name) || !TryParseRegister(name, out var id))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected a valid 'register' name.");
|
||||
}
|
||||
|
||||
if (!request.TryGetUInt64("value", out var value))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected a 'value'.");
|
||||
}
|
||||
|
||||
return _session.TrySetRegister(id, value)
|
||||
? DebugResponse.Success(request.Command)
|
||||
: DebugResponse.Failure(request.Command, "Register is not writable or target is not paused.");
|
||||
}
|
||||
|
||||
private DebugResponse ReadMemory(DebugRequest request)
|
||||
{
|
||||
if (!request.TryGetUInt64("address", out var address))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected an 'address'.");
|
||||
}
|
||||
|
||||
if (!request.TryGetInt32("length", out var length) || length <= 0 || length > MaxMemoryChunk)
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, $"Expected a 'length' between 1 and {MaxMemoryChunk}.");
|
||||
}
|
||||
|
||||
var buffer = new byte[length];
|
||||
if (!_session.TryReadMemory(address, buffer))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Memory is unreadable or target is not paused.");
|
||||
}
|
||||
|
||||
return DebugResponse.Success(request.Command, new Dictionary<string, object?>
|
||||
{
|
||||
["address"] = FormatAddress(address),
|
||||
["length"] = length,
|
||||
["bytes"] = Convert.ToHexString(buffer),
|
||||
});
|
||||
}
|
||||
|
||||
private DebugResponse WriteMemory(DebugRequest request)
|
||||
{
|
||||
if (!request.TryGetUInt64("address", out var address))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected an 'address'.");
|
||||
}
|
||||
|
||||
if (!request.TryGetString("bytes", out var hex) || hex.Length == 0 || (hex.Length & 1) != 0)
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected 'bytes' as an even-length hex string.");
|
||||
}
|
||||
|
||||
byte[] data;
|
||||
try
|
||||
{
|
||||
data = Convert.FromHexString(hex);
|
||||
}
|
||||
catch (FormatException)
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "'bytes' is not valid hex.");
|
||||
}
|
||||
|
||||
if (data.Length > MaxMemoryChunk)
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, $"Cannot write more than {MaxMemoryChunk} bytes at once.");
|
||||
}
|
||||
|
||||
return _session.TryWriteMemory(address, data)
|
||||
? DebugResponse.Success(request.Command, new Dictionary<string, object?> { ["written"] = data.Length })
|
||||
: DebugResponse.Failure(request.Command, "Memory is unwritable or target is not paused.");
|
||||
}
|
||||
|
||||
private DebugResponse ListBreakpoints(DebugRequest request)
|
||||
{
|
||||
var breakpoints = _session.Breakpoints.Snapshot()
|
||||
.OrderBy(breakpoint => breakpoint.Id)
|
||||
.Select(DescribeBreakpoint)
|
||||
.ToArray();
|
||||
|
||||
return DebugResponse.Success(request.Command, new Dictionary<string, object?>
|
||||
{
|
||||
["breakpoints"] = breakpoints,
|
||||
});
|
||||
}
|
||||
|
||||
private DebugResponse AddBreakpoint(DebugRequest request)
|
||||
{
|
||||
if (!request.TryGetUInt64("address", out var address))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected an 'address'.");
|
||||
}
|
||||
|
||||
var kind = BreakpointKind.Execute;
|
||||
if (request.TryGetString("kind", out var kindText) && !TryParseBreakpointKind(kindText, out kind))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, $"Unknown breakpoint kind '{kindText}'.");
|
||||
}
|
||||
|
||||
var length = 1UL;
|
||||
if (request.TryGetUInt64("length", out var requestedLength) && requestedLength > 0)
|
||||
{
|
||||
length = requestedLength;
|
||||
}
|
||||
|
||||
var breakpoint = _session.Breakpoints.Add(kind, address, length);
|
||||
return DebugResponse.Success(request.Command, new Dictionary<string, object?>
|
||||
{
|
||||
["breakpoint"] = DescribeBreakpoint(breakpoint),
|
||||
});
|
||||
}
|
||||
|
||||
private DebugResponse RemoveBreakpoint(DebugRequest request)
|
||||
{
|
||||
if (!request.TryGetInt32("id", out var id))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected an 'id'.");
|
||||
}
|
||||
|
||||
return _session.Breakpoints.Remove(id)
|
||||
? DebugResponse.Success(request.Command)
|
||||
: DebugResponse.Failure(request.Command, $"No breakpoint with id {id}.");
|
||||
}
|
||||
|
||||
private DebugResponse EnableBreakpoint(DebugRequest request)
|
||||
{
|
||||
if (!request.TryGetInt32("id", out var id))
|
||||
{
|
||||
return DebugResponse.Failure(request.Command, "Expected an 'id'.");
|
||||
}
|
||||
|
||||
var enabled = !request.TryGetBool("enabled", out var requested) || requested;
|
||||
return _session.Breakpoints.SetEnabled(id, enabled)
|
||||
? DebugResponse.Success(request.Command)
|
||||
: DebugResponse.Failure(request.Command, $"No breakpoint with id {id}.");
|
||||
}
|
||||
|
||||
private DebugResponse Pause(DebugRequest request)
|
||||
{
|
||||
_session.RequestPause();
|
||||
return DebugResponse.Success(request.Command);
|
||||
}
|
||||
|
||||
private static DebugResponse Simple(DebugRequest request, bool succeeded, string failureMessage)
|
||||
=> succeeded ? DebugResponse.Success(request.Command) : DebugResponse.Failure(request.Command, failureMessage);
|
||||
|
||||
private static DebugResponse NotPaused(DebugRequest request)
|
||||
=> DebugResponse.Failure(request.Command, "Target is not paused.");
|
||||
|
||||
internal static IReadOnlyDictionary<string, object?> DescribeStop(DebugStopEvent stop)
|
||||
{
|
||||
var data = new Dictionary<string, object?>
|
||||
{
|
||||
["reason"] = stop.Reason.ToString(),
|
||||
["address"] = FormatAddress(stop.Address),
|
||||
["frameKind"] = stop.FrameKind.ToString(),
|
||||
["frameLabel"] = stop.FrameLabel,
|
||||
["registers"] = DescribeRegisters(stop.Registers),
|
||||
};
|
||||
|
||||
if (stop.Breakpoint is { } breakpoint)
|
||||
{
|
||||
data["breakpoint"] = DescribeBreakpoint(breakpoint);
|
||||
}
|
||||
|
||||
if (stop.Result is { } result)
|
||||
{
|
||||
data["result"] = result.ToString();
|
||||
}
|
||||
|
||||
if (stop.Detail is { } detail)
|
||||
{
|
||||
data["detail"] = detail;
|
||||
}
|
||||
|
||||
if (stop.OpcodeBytes is { } opcodeBytes)
|
||||
{
|
||||
data["opcodeBytes"] = opcodeBytes;
|
||||
}
|
||||
|
||||
if (stop.StallInfo is { } stall)
|
||||
{
|
||||
data["stall"] = new Dictionary<string, object?>
|
||||
{
|
||||
["kind"] = stall.Kind.ToString(),
|
||||
["nid"] = stall.Nid,
|
||||
["instructionPointer"] = FormatAddress(stall.InstructionPointer),
|
||||
["dispatchIndex"] = stall.DispatchIndex,
|
||||
["argument0"] = FormatAddress(stall.Argument0),
|
||||
["argument1"] = FormatAddress(stall.Argument1),
|
||||
["resolved"] = stall.IsResolved,
|
||||
["library"] = stall.LibraryName,
|
||||
["function"] = stall.FunctionName,
|
||||
};
|
||||
}
|
||||
|
||||
return data;
|
||||
}
|
||||
|
||||
private static IReadOnlyDictionary<string, object?> DescribeRegisters(DebugRegisterFile registers)
|
||||
{
|
||||
var result = new Dictionary<string, object?>(20);
|
||||
for (var i = 0; i < 16; i++)
|
||||
{
|
||||
result[((CpuRegister)i).ToString().ToLowerInvariant()] = FormatAddress(registers[(CpuRegister)i]);
|
||||
}
|
||||
|
||||
result["rip"] = FormatAddress(registers.Rip);
|
||||
result["rflags"] = FormatAddress(registers.Rflags);
|
||||
result["fs_base"] = FormatAddress(registers.FsBase);
|
||||
result["gs_base"] = FormatAddress(registers.GsBase);
|
||||
return result;
|
||||
}
|
||||
|
||||
private static IReadOnlyDictionary<string, object?> DescribeBreakpoint(Breakpoint breakpoint)
|
||||
=> new Dictionary<string, object?>
|
||||
{
|
||||
["id"] = breakpoint.Id,
|
||||
["kind"] = breakpoint.Kind.ToString(),
|
||||
["address"] = FormatAddress(breakpoint.Address),
|
||||
["length"] = breakpoint.Length,
|
||||
["enabled"] = breakpoint.Enabled,
|
||||
};
|
||||
|
||||
private static string FormatAddress(ulong value) => $"0x{value:X16}";
|
||||
|
||||
private static bool TryParseRegister(string name, out DebugRegisterId id)
|
||||
{
|
||||
var normalized = name.Trim().ToLowerInvariant();
|
||||
switch (normalized)
|
||||
{
|
||||
case "rip":
|
||||
id = DebugRegisterId.Rip;
|
||||
return true;
|
||||
case "rflags":
|
||||
id = DebugRegisterId.Rflags;
|
||||
return true;
|
||||
case "fs_base" or "fsbase":
|
||||
id = DebugRegisterId.FsBase;
|
||||
return true;
|
||||
case "gs_base" or "gsbase":
|
||||
id = DebugRegisterId.GsBase;
|
||||
return true;
|
||||
}
|
||||
|
||||
return Enum.TryParse(normalized, ignoreCase: true, out id) && Enum.IsDefined(id);
|
||||
}
|
||||
|
||||
private static bool TryParseBreakpointKind(string text, out BreakpointKind kind)
|
||||
=> Enum.TryParse(text.Trim(), ignoreCase: true, out kind) && Enum.IsDefined(kind);
|
||||
|
||||
private const int MaxMemoryChunk = 64 * 1024;
|
||||
}
|
||||
@@ -0,0 +1,152 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Globalization;
|
||||
using System.Text.Json;
|
||||
|
||||
namespace SharpEmu.Debugger.Protocol;
|
||||
|
||||
/// <summary>
|
||||
/// A parsed client request: a <see cref="Command"/> verb plus a bag of named
|
||||
/// arguments backed by the original JSON. Numeric arguments accept either JSON
|
||||
/// numbers or <c>"0x"</c>-prefixed hex strings so addresses read naturally on
|
||||
/// the wire.
|
||||
/// </summary>
|
||||
public sealed class DebugRequest
|
||||
{
|
||||
private readonly JsonElement _root;
|
||||
|
||||
private DebugRequest(string command, JsonElement root)
|
||||
{
|
||||
Command = command;
|
||||
_root = root;
|
||||
}
|
||||
|
||||
/// <summary>The lower-cased command verb.</summary>
|
||||
public string Command { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Parses a single JSON object into a request. Returns false when the text is
|
||||
/// not a JSON object or is missing a string <c>command</c> field.
|
||||
/// </summary>
|
||||
public static bool TryParse(string json, out DebugRequest request, out string error)
|
||||
{
|
||||
request = null!;
|
||||
error = string.Empty;
|
||||
try
|
||||
{
|
||||
using var document = JsonDocument.Parse(json);
|
||||
var root = document.RootElement.Clone();
|
||||
if (root.ValueKind != JsonValueKind.Object)
|
||||
{
|
||||
error = "Request must be a JSON object.";
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!root.TryGetProperty("command", out var commandElement) ||
|
||||
commandElement.ValueKind != JsonValueKind.String)
|
||||
{
|
||||
error = "Request is missing a string 'command'.";
|
||||
return false;
|
||||
}
|
||||
|
||||
var command = commandElement.GetString() ?? string.Empty;
|
||||
request = new DebugRequest(command.Trim().ToLowerInvariant(), root);
|
||||
return true;
|
||||
}
|
||||
catch (JsonException ex)
|
||||
{
|
||||
error = $"Malformed JSON: {ex.Message}";
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
public bool TryGetString(string name, out string value)
|
||||
{
|
||||
if (_root.TryGetProperty(name, out var element) && element.ValueKind == JsonValueKind.String)
|
||||
{
|
||||
value = element.GetString() ?? string.Empty;
|
||||
return true;
|
||||
}
|
||||
|
||||
value = string.Empty;
|
||||
return false;
|
||||
}
|
||||
|
||||
public bool TryGetUInt64(string name, out ulong value)
|
||||
{
|
||||
value = 0;
|
||||
if (!_root.TryGetProperty(name, out var element))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
switch (element.ValueKind)
|
||||
{
|
||||
case JsonValueKind.Number:
|
||||
return element.TryGetUInt64(out value);
|
||||
case JsonValueKind.String:
|
||||
return TryParseNumber(element.GetString(), out value);
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
public bool TryGetInt32(string name, out int value)
|
||||
{
|
||||
value = 0;
|
||||
if (!_root.TryGetProperty(name, out var element))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
switch (element.ValueKind)
|
||||
{
|
||||
case JsonValueKind.Number:
|
||||
return element.TryGetInt32(out value);
|
||||
case JsonValueKind.String when TryParseNumber(element.GetString(), out var parsed) && parsed <= int.MaxValue:
|
||||
value = (int)parsed;
|
||||
return true;
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
public bool TryGetBool(string name, out bool value)
|
||||
{
|
||||
value = false;
|
||||
if (!_root.TryGetProperty(name, out var element))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
switch (element.ValueKind)
|
||||
{
|
||||
case JsonValueKind.True:
|
||||
value = true;
|
||||
return true;
|
||||
case JsonValueKind.False:
|
||||
value = false;
|
||||
return true;
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private static bool TryParseNumber(string? text, out ulong value)
|
||||
{
|
||||
value = 0;
|
||||
if (string.IsNullOrWhiteSpace(text))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
text = text.Trim();
|
||||
if (text.StartsWith("0x", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return ulong.TryParse(text.AsSpan(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out value);
|
||||
}
|
||||
|
||||
return ulong.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out value);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Protocol;
|
||||
|
||||
/// <summary>
|
||||
/// The reply to a <see cref="DebugRequest"/>: either success with an optional
|
||||
/// data payload, or a failure with a human-readable message.
|
||||
/// </summary>
|
||||
public sealed class DebugResponse
|
||||
{
|
||||
private DebugResponse(bool ok, string? command, IReadOnlyDictionary<string, object?>? data, string? error)
|
||||
{
|
||||
Ok = ok;
|
||||
Command = command;
|
||||
Data = data;
|
||||
Error = error;
|
||||
}
|
||||
|
||||
public bool Ok { get; }
|
||||
|
||||
/// <summary>Echoes the command the reply answers, when known.</summary>
|
||||
public string? Command { get; }
|
||||
|
||||
public IReadOnlyDictionary<string, object?>? Data { get; }
|
||||
|
||||
public string? Error { get; }
|
||||
|
||||
public static DebugResponse Success(string command, IReadOnlyDictionary<string, object?>? data = null)
|
||||
=> new(ok: true, command, data, error: null);
|
||||
|
||||
public static DebugResponse Failure(string command, string error)
|
||||
=> new(ok: false, command, data: null, error);
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Protocol;
|
||||
|
||||
/// <summary>
|
||||
/// Frames debugger traffic on a connection. A protocol turns bytes into
|
||||
/// <see cref="DebugRequest"/> objects and serialises <see cref="DebugResponse"/>
|
||||
/// replies plus asynchronous events (stops, resumes, termination) back to the
|
||||
/// client. Swapping the implementation (line-delimited JSON today, a GDB remote
|
||||
/// serial stub later) leaves the session and server untouched.
|
||||
/// </summary>
|
||||
public interface IDebugProtocol
|
||||
{
|
||||
/// <summary>A short protocol name reported in the handshake.</summary>
|
||||
string Name { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Reads the next request, or null at end of stream. Parse failures are
|
||||
/// surfaced as a request with a reserved error command rather than throwing.
|
||||
/// </summary>
|
||||
Task<DebugRequest?> ReadRequestAsync(TextReader reader, CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>Writes a reply to a request.</summary>
|
||||
Task WriteResponseAsync(TextWriter writer, DebugResponse response, CancellationToken cancellationToken);
|
||||
|
||||
/// <summary>Writes an unsolicited event (for example a stop notification).</summary>
|
||||
Task WriteEventAsync(
|
||||
TextWriter writer,
|
||||
string eventName,
|
||||
IReadOnlyDictionary<string, object?> data,
|
||||
CancellationToken cancellationToken);
|
||||
}
|
||||
@@ -0,0 +1,112 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Text.Json;
|
||||
|
||||
namespace SharpEmu.Debugger.Protocol;
|
||||
|
||||
/// <summary>
|
||||
/// A newline-delimited JSON protocol: one JSON object per line in each
|
||||
/// direction. Requests carry a <c>command</c>; replies carry <c>ok</c> plus
|
||||
/// <c>data</c>/<c>error</c>; events carry an <c>event</c> name. It is trivial to
|
||||
/// drive from a socket, <c>nc</c>, or a small script, which suits bring-up and
|
||||
/// tooling while a richer protocol is layered on later.
|
||||
/// </summary>
|
||||
public sealed class JsonLineDebugProtocol : IDebugProtocol
|
||||
{
|
||||
/// <summary>The command assigned to a request that failed to parse.</summary>
|
||||
public const string ParseErrorCommand = "$parse-error";
|
||||
|
||||
private static readonly JsonSerializerOptions SerializerOptions = new()
|
||||
{
|
||||
WriteIndented = false,
|
||||
};
|
||||
|
||||
public string Name => "json-lines/1";
|
||||
|
||||
public async Task<DebugRequest?> ReadRequestAsync(TextReader reader, CancellationToken cancellationToken)
|
||||
{
|
||||
while (true)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
var line = await reader.ReadLineAsync(cancellationToken).ConfigureAwait(false);
|
||||
if (line is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(line))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (DebugRequest.TryParse(line, out var request, out var error))
|
||||
{
|
||||
return request;
|
||||
}
|
||||
|
||||
// Surface the parse failure as a synthetic request so the connection
|
||||
// loop can reply with an error rather than dropping the client.
|
||||
var envelope = $"{{\"command\":\"{ParseErrorCommand}\",\"message\":{JsonSerializer.Serialize(error)}}}";
|
||||
if (DebugRequest.TryParse(envelope, out var errorRequest, out _))
|
||||
{
|
||||
return errorRequest;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public async Task WriteResponseAsync(TextWriter writer, DebugResponse response, CancellationToken cancellationToken)
|
||||
{
|
||||
var payload = new Dictionary<string, object?>
|
||||
{
|
||||
["ok"] = response.Ok,
|
||||
};
|
||||
|
||||
if (response.Command is not null)
|
||||
{
|
||||
payload["command"] = response.Command;
|
||||
}
|
||||
|
||||
if (response.Data is not null)
|
||||
{
|
||||
payload["data"] = response.Data;
|
||||
}
|
||||
|
||||
if (response.Error is not null)
|
||||
{
|
||||
payload["error"] = response.Error;
|
||||
}
|
||||
|
||||
await WriteLineAsync(writer, payload, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
public async Task WriteEventAsync(
|
||||
TextWriter writer,
|
||||
string eventName,
|
||||
IReadOnlyDictionary<string, object?> data,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
var payload = new Dictionary<string, object?>(data.Count + 1)
|
||||
{
|
||||
["event"] = eventName,
|
||||
};
|
||||
|
||||
foreach (var (key, value) in data)
|
||||
{
|
||||
payload[key] = value;
|
||||
}
|
||||
|
||||
await WriteLineAsync(writer, payload, cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static async Task WriteLineAsync(
|
||||
TextWriter writer,
|
||||
IReadOnlyDictionary<string, object?> payload,
|
||||
CancellationToken cancellationToken)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
var json = JsonSerializer.Serialize(payload, SerializerOptions);
|
||||
await writer.WriteLineAsync(json.AsMemory(), cancellationToken).ConfigureAwait(false);
|
||||
await writer.FlushAsync(cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,158 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net.Sockets;
|
||||
using System.Text;
|
||||
using SharpEmu.Debugger.Protocol;
|
||||
using SharpEmu.Debugger.Session;
|
||||
using SharpEmu.Logging;
|
||||
|
||||
namespace SharpEmu.Debugger.Server;
|
||||
|
||||
/// <summary>
|
||||
/// Services a single connected client: reads requests, dispatches them against
|
||||
/// the shared session, and pushes session lifecycle events. Writes from the
|
||||
/// request loop and from event callbacks are serialised through one lock so the
|
||||
/// two never interleave a half-written line.
|
||||
/// </summary>
|
||||
internal sealed class DebuggerClientConnection : IAsyncDisposable
|
||||
{
|
||||
private static readonly SharpEmuLogger Log = SharpEmuLog.For("SharpEmu.Debugger");
|
||||
private static readonly UTF8Encoding Utf8NoBom = new(encoderShouldEmitUTF8Identifier: false);
|
||||
|
||||
private readonly TcpClient _client;
|
||||
private readonly IDebuggerSession _session;
|
||||
private readonly IDebugProtocol _protocol;
|
||||
private readonly DebugCommandDispatcher _dispatcher;
|
||||
private readonly SemaphoreSlim _writeLock = new(1, 1);
|
||||
|
||||
private TextWriter? _writer;
|
||||
private CancellationToken _cancellationToken;
|
||||
|
||||
public DebuggerClientConnection(TcpClient client, IDebuggerSession session, IDebugProtocol protocol)
|
||||
{
|
||||
_client = client;
|
||||
_session = session;
|
||||
_protocol = protocol;
|
||||
_dispatcher = new DebugCommandDispatcher(session);
|
||||
}
|
||||
|
||||
public async Task RunAsync(CancellationToken cancellationToken)
|
||||
{
|
||||
_cancellationToken = cancellationToken;
|
||||
var endpoint = _client.Client.RemoteEndPoint?.ToString() ?? "unknown";
|
||||
Log.Info($"Debugger client connected: {endpoint}");
|
||||
|
||||
using var stream = _client.GetStream();
|
||||
using var reader = new StreamReader(stream, Utf8NoBom);
|
||||
await using var writer = new StreamWriter(stream, Utf8NoBom) { AutoFlush = false };
|
||||
_writer = writer;
|
||||
|
||||
_session.Stopped += OnStopped;
|
||||
_session.Resumed += OnResumed;
|
||||
_session.Terminated += OnTerminated;
|
||||
try
|
||||
{
|
||||
await SendEventAsync("hello", new Dictionary<string, object?>
|
||||
{
|
||||
["protocol"] = _protocol.Name,
|
||||
["state"] = _session.State.ToString(),
|
||||
}).ConfigureAwait(false);
|
||||
|
||||
while (!cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
var request = await _protocol.ReadRequestAsync(reader, cancellationToken).ConfigureAwait(false);
|
||||
if (request is null)
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
var response = _dispatcher.Dispatch(request);
|
||||
await WriteResponseAsync(response).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
// Server shutting down.
|
||||
}
|
||||
catch (IOException)
|
||||
{
|
||||
// Client dropped the connection.
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Log.Warn($"Debugger client error ({endpoint}): {ex.Message}");
|
||||
}
|
||||
finally
|
||||
{
|
||||
_session.Stopped -= OnStopped;
|
||||
_session.Resumed -= OnResumed;
|
||||
_session.Terminated -= OnTerminated;
|
||||
_writer = null;
|
||||
Log.Info($"Debugger client disconnected: {endpoint}");
|
||||
}
|
||||
}
|
||||
|
||||
private void OnStopped(object? sender, DebugStopEvent stop)
|
||||
=> _ = SendEventAsync("stopped", DebugCommandDispatcher.DescribeStop(stop));
|
||||
|
||||
private void OnResumed(object? sender, EventArgs e)
|
||||
=> _ = SendEventAsync("resumed", EmptyData);
|
||||
|
||||
private void OnTerminated(object? sender, EventArgs e)
|
||||
=> _ = SendEventAsync("terminated", EmptyData);
|
||||
|
||||
private async Task WriteResponseAsync(DebugResponse response)
|
||||
{
|
||||
var writer = _writer;
|
||||
if (writer is null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
await _writeLock.WaitAsync(_cancellationToken).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
await _protocol.WriteResponseAsync(writer, response, _cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
finally
|
||||
{
|
||||
_writeLock.Release();
|
||||
}
|
||||
}
|
||||
|
||||
private async Task SendEventAsync(string name, IReadOnlyDictionary<string, object?> data)
|
||||
{
|
||||
var writer = _writer;
|
||||
if (writer is null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
await _writeLock.WaitAsync(_cancellationToken).ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
await _protocol.WriteEventAsync(writer, name, data, _cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
finally
|
||||
{
|
||||
_writeLock.Release();
|
||||
}
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or OperationCanceledException or ObjectDisposedException)
|
||||
{
|
||||
// The client went away between the event firing and the write.
|
||||
}
|
||||
}
|
||||
|
||||
public ValueTask DisposeAsync()
|
||||
{
|
||||
_writeLock.Dispose();
|
||||
_client.Dispose();
|
||||
return ValueTask.CompletedTask;
|
||||
}
|
||||
|
||||
private static readonly IReadOnlyDictionary<string, object?> EmptyData = new Dictionary<string, object?>();
|
||||
}
|
||||
@@ -0,0 +1,136 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Collections.Concurrent;
|
||||
using System.Net;
|
||||
using System.Net.Sockets;
|
||||
using SharpEmu.Debugger.Protocol;
|
||||
using SharpEmu.Debugger.Session;
|
||||
using SharpEmu.Logging;
|
||||
|
||||
namespace SharpEmu.Debugger.Server;
|
||||
|
||||
/// <summary>
|
||||
/// A TCP server that exposes an <see cref="IDebuggerSession"/> to remote
|
||||
/// clients over a pluggable <see cref="IDebugProtocol"/>. Every connection sees
|
||||
/// the same session, so multiple clients (for example a UI and a scripted
|
||||
/// probe) observe a consistent view of the target.
|
||||
/// </summary>
|
||||
public sealed class DebuggerServer : IDebuggerServer
|
||||
{
|
||||
private static readonly SharpEmuLogger Log = SharpEmuLog.For("SharpEmu.Debugger");
|
||||
|
||||
private readonly IDebuggerSession _session;
|
||||
private readonly DebuggerServerOptions _options;
|
||||
private readonly Func<IDebugProtocol> _protocolFactory;
|
||||
private readonly ConcurrentDictionary<DebuggerClientConnection, Task> _connections = new();
|
||||
private readonly CancellationTokenSource _shutdown = new();
|
||||
|
||||
private TcpListener? _listener;
|
||||
private Task? _acceptLoop;
|
||||
|
||||
public DebuggerServer(
|
||||
IDebuggerSession session,
|
||||
DebuggerServerOptions? options = null,
|
||||
Func<IDebugProtocol>? protocolFactory = null)
|
||||
{
|
||||
_session = session ?? throw new ArgumentNullException(nameof(session));
|
||||
_options = options ?? new DebuggerServerOptions();
|
||||
_protocolFactory = protocolFactory ?? (static () => new JsonLineDebugProtocol());
|
||||
}
|
||||
|
||||
public bool IsListening => _listener is not null;
|
||||
|
||||
public IPEndPoint? Endpoint { get; private set; }
|
||||
|
||||
public void Start()
|
||||
{
|
||||
if (_listener is not null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
var listener = new TcpListener(_options.BindAddress, _options.Port);
|
||||
listener.Start(_options.MaxClients);
|
||||
_listener = listener;
|
||||
Endpoint = (IPEndPoint?)listener.LocalEndpoint;
|
||||
Log.Info($"Debug server listening on {Endpoint} (protocol {_protocolFactory().Name})");
|
||||
_acceptLoop = Task.Run(() => AcceptLoopAsync(listener, _shutdown.Token));
|
||||
}
|
||||
|
||||
private async Task AcceptLoopAsync(TcpListener listener, CancellationToken cancellationToken)
|
||||
{
|
||||
while (!cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
TcpClient client;
|
||||
try
|
||||
{
|
||||
client = await listener.AcceptTcpClientAsync(cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
break;
|
||||
}
|
||||
catch (SocketException) when (cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
break;
|
||||
}
|
||||
catch (ObjectDisposedException)
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
var connection = new DebuggerClientConnection(client, _session, _protocolFactory());
|
||||
var task = Task.Run(() => ServeAsync(connection, cancellationToken), cancellationToken);
|
||||
_connections[connection] = task;
|
||||
}
|
||||
}
|
||||
|
||||
private async Task ServeAsync(DebuggerClientConnection connection, CancellationToken cancellationToken)
|
||||
{
|
||||
try
|
||||
{
|
||||
await connection.RunAsync(cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
finally
|
||||
{
|
||||
_connections.TryRemove(connection, out _);
|
||||
await connection.DisposeAsync().ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
|
||||
public async Task StopAsync()
|
||||
{
|
||||
if (_listener is null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
await _shutdown.CancelAsync().ConfigureAwait(false);
|
||||
_listener.Stop();
|
||||
_listener = null;
|
||||
|
||||
try
|
||||
{
|
||||
if (_acceptLoop is not null)
|
||||
{
|
||||
await _acceptLoop.ConfigureAwait(false);
|
||||
}
|
||||
|
||||
await Task.WhenAll(_connections.Values).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex) when (ex is OperationCanceledException or SocketException or ObjectDisposedException)
|
||||
{
|
||||
// Expected while tearing connections down.
|
||||
}
|
||||
|
||||
_connections.Clear();
|
||||
Log.Info("Debug server stopped.");
|
||||
}
|
||||
|
||||
public async ValueTask DisposeAsync()
|
||||
{
|
||||
await StopAsync().ConfigureAwait(false);
|
||||
_shutdown.Dispose();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net;
|
||||
|
||||
namespace SharpEmu.Debugger.Server;
|
||||
|
||||
/// <summary>Network configuration for a <see cref="DebuggerServer"/>.</summary>
|
||||
public sealed class DebuggerServerOptions
|
||||
{
|
||||
/// <summary>The default TCP port the debug server listens on.</summary>
|
||||
public const int DefaultPort = 5714;
|
||||
|
||||
/// <summary>
|
||||
/// The address to bind. Defaults to loopback so the debug surface is not
|
||||
/// exposed off-box; a caller must opt in to a routable address explicitly.
|
||||
/// </summary>
|
||||
public IPAddress BindAddress { get; init; } = IPAddress.Loopback;
|
||||
|
||||
/// <summary>The TCP port to listen on.</summary>
|
||||
public int Port { get; init; } = DefaultPort;
|
||||
|
||||
/// <summary>
|
||||
/// The maximum number of simultaneous client connections. Additional
|
||||
/// connections wait in the accept backlog.
|
||||
/// </summary>
|
||||
public int MaxClients { get; init; } = 4;
|
||||
|
||||
/// <summary>
|
||||
/// Parses a <c>host:port</c>, bare <c>port</c>, or bare host into options.
|
||||
/// Returns false when the text cannot be interpreted.
|
||||
/// </summary>
|
||||
public static bool TryParseEndpoint(string? text, out DebuggerServerOptions options, out string error)
|
||||
{
|
||||
options = new DebuggerServerOptions();
|
||||
error = string.Empty;
|
||||
if (string.IsNullOrWhiteSpace(text))
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
var value = text.Trim();
|
||||
var host = value;
|
||||
var port = DefaultPort;
|
||||
|
||||
var separator = value.LastIndexOf(':');
|
||||
if (separator >= 0)
|
||||
{
|
||||
var portText = value[(separator + 1)..];
|
||||
if (portText.Length > 0)
|
||||
{
|
||||
if (!int.TryParse(portText, out port) || port is <= 0 or > 65535)
|
||||
{
|
||||
error = $"Invalid port '{portText}'.";
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
host = value[..separator];
|
||||
}
|
||||
|
||||
var address = IPAddress.Loopback;
|
||||
if (!string.IsNullOrWhiteSpace(host) &&
|
||||
!string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) &&
|
||||
!IPAddress.TryParse(host, out address!))
|
||||
{
|
||||
error = $"Invalid bind address '{host}'.";
|
||||
return false;
|
||||
}
|
||||
|
||||
options = new DebuggerServerOptions
|
||||
{
|
||||
BindAddress = address ?? IPAddress.Loopback,
|
||||
Port = port,
|
||||
};
|
||||
return true;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using System.Net;
|
||||
|
||||
namespace SharpEmu.Debugger.Server;
|
||||
|
||||
/// <summary>
|
||||
/// A network front-end that exposes a debugger session to remote clients.
|
||||
/// </summary>
|
||||
public interface IDebuggerServer : IAsyncDisposable
|
||||
{
|
||||
/// <summary>True once the listener is accepting connections.</summary>
|
||||
bool IsListening { get; }
|
||||
|
||||
/// <summary>The endpoint the server is bound to, or null before start.</summary>
|
||||
IPEndPoint? Endpoint { get; }
|
||||
|
||||
/// <summary>Binds and begins accepting client connections.</summary>
|
||||
void Start();
|
||||
|
||||
/// <summary>Stops accepting connections and closes active clients.</summary>
|
||||
Task StopAsync();
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Debugger.Breakpoints;
|
||||
using SharpEmu.HLE;
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>
|
||||
/// Describes a stop delivered to debugger clients: why the target stopped,
|
||||
/// where, and the register snapshot at that point.
|
||||
/// </summary>
|
||||
public sealed class DebugStopEvent
|
||||
{
|
||||
public DebugStopEvent(
|
||||
DebugStopReason reason,
|
||||
DebugRegisterFile registers,
|
||||
CpuDebugFrameKind frameKind,
|
||||
string frameLabel,
|
||||
Breakpoint? breakpoint = null,
|
||||
OrbisGen2Result? result = null,
|
||||
string? detail = null,
|
||||
string? opcodeBytes = null,
|
||||
CpuStallInfo? stallInfo = null)
|
||||
{
|
||||
Reason = reason;
|
||||
Registers = registers;
|
||||
FrameKind = frameKind;
|
||||
FrameLabel = frameLabel ?? string.Empty;
|
||||
Breakpoint = breakpoint;
|
||||
Result = result;
|
||||
Detail = detail;
|
||||
OpcodeBytes = opcodeBytes;
|
||||
StallInfo = stallInfo;
|
||||
}
|
||||
|
||||
public DebugStopReason Reason { get; }
|
||||
|
||||
/// <summary>The instruction pointer where the target stopped.</summary>
|
||||
public ulong Address => Registers.Rip;
|
||||
|
||||
public DebugRegisterFile Registers { get; }
|
||||
|
||||
public CpuDebugFrameKind FrameKind { get; }
|
||||
|
||||
public string FrameLabel { get; }
|
||||
|
||||
/// <summary>The breakpoint responsible for the stop, when applicable.</summary>
|
||||
public Breakpoint? Breakpoint { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The frame result for a <see cref="DebugStopReason.Fault"/> stop; null for
|
||||
/// non-fault stops.
|
||||
/// </summary>
|
||||
public OrbisGen2Result? Result { get; }
|
||||
|
||||
/// <summary>A human-readable summary of a fault, when applicable.</summary>
|
||||
public string? Detail { get; }
|
||||
|
||||
/// <summary>
|
||||
/// A hex preview of the bytes at <see cref="Address"/> (the faulting
|
||||
/// instruction), when the stop is a fault and the bytes were readable.
|
||||
/// </summary>
|
||||
public string? OpcodeBytes { get; }
|
||||
|
||||
/// <summary>Structured backend evidence for a stall stop.</summary>
|
||||
public CpuStallInfo? StallInfo { get; }
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>Why the target stopped and handed control to the debugger.</summary>
|
||||
public enum DebugStopReason
|
||||
{
|
||||
/// <summary>Stopped at the configured entry point before running any frame.</summary>
|
||||
EntryPoint,
|
||||
|
||||
/// <summary>An execution breakpoint was hit.</summary>
|
||||
Breakpoint,
|
||||
|
||||
/// <summary>A data watchpoint was hit.</summary>
|
||||
Watchpoint,
|
||||
|
||||
/// <summary>A single-step (frame step) request completed.</summary>
|
||||
Step,
|
||||
|
||||
/// <summary>A client-requested pause took effect.</summary>
|
||||
Pause,
|
||||
|
||||
/// <summary>The guest raised a fault or trap.</summary>
|
||||
Fault,
|
||||
|
||||
/// <summary>
|
||||
/// The backend detected an execution stall (for example a mutex spin loop /
|
||||
/// livelock) with no forward progress.
|
||||
/// </summary>
|
||||
Stall,
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>The execution state of a debugged target as seen by the debugger.</summary>
|
||||
public enum DebuggerRunState
|
||||
{
|
||||
/// <summary>No guest frame has entered the debugger yet.</summary>
|
||||
Detached,
|
||||
|
||||
/// <summary>The guest is executing and cannot be inspected safely.</summary>
|
||||
Running,
|
||||
|
||||
/// <summary>
|
||||
/// The guest is parked at a frame boundary. Registers and memory can be
|
||||
/// read and written, and breakpoints can be edited.
|
||||
/// </summary>
|
||||
Paused,
|
||||
|
||||
/// <summary>The guest has finished; no further frames will run.</summary>
|
||||
Terminated,
|
||||
}
|
||||
@@ -0,0 +1,425 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Debugger.Breakpoints;
|
||||
using SharpEmu.HLE;
|
||||
using SharpEmu.Logging;
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>
|
||||
/// The default <see cref="IDebuggerSession"/>. It plugs into the CPU dispatcher
|
||||
/// as an <see cref="ICpuDebugHook"/>: when a frame boundary warrants a stop it
|
||||
/// parks the emulation thread inside <see cref="ICpuDebugHook.OnFrameEnter"/>
|
||||
/// while a debug client inspects and edits state, then releases it on
|
||||
/// continue/step.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Pausing works by blocking the emulation thread on <see cref="_resumeGate"/>
|
||||
/// from within the hook call. Because that thread is the one that owns the guest
|
||||
/// context, register and memory accessors are safe to serve from other threads
|
||||
/// only while it is parked — which is exactly the <see cref="DebuggerRunState.Paused"/>
|
||||
/// window the accessors gate on.
|
||||
/// </remarks>
|
||||
public sealed class DebuggerSession : IDebuggerSession, ICpuDebugHook
|
||||
{
|
||||
private static readonly SharpEmuLogger Log = SharpEmuLog.For("SharpEmu.Debugger");
|
||||
|
||||
private readonly object _sync = new();
|
||||
private readonly ManualResetEventSlim _resumeGate = new(initialState: false);
|
||||
private readonly DebuggerSessionOptions _options;
|
||||
|
||||
private ICpuDebugFrame? _currentFrame;
|
||||
private DebuggerRunState _state = DebuggerRunState.Detached;
|
||||
private DebugStopEvent? _lastStop;
|
||||
private bool _seenFirstFrame;
|
||||
private bool _pausePending;
|
||||
private bool _stepPending;
|
||||
|
||||
public DebuggerSession(DebuggerSessionOptions? options = null)
|
||||
{
|
||||
_options = options ?? new DebuggerSessionOptions();
|
||||
Breakpoints = new BreakpointStore();
|
||||
}
|
||||
|
||||
public BreakpointStore Breakpoints { get; }
|
||||
|
||||
public ICpuDebugHook Hook => this;
|
||||
|
||||
public event EventHandler<DebugStopEvent>? Stopped;
|
||||
|
||||
public event EventHandler? Resumed;
|
||||
|
||||
public event EventHandler? Terminated;
|
||||
|
||||
public DebuggerRunState State
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
return _state;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public DebugStopEvent? LastStop
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
return _lastStop;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void ICpuDebugHook.OnFrameEnter(ICpuDebugFrame frame)
|
||||
{
|
||||
DebugStopEvent? stop;
|
||||
lock (_sync)
|
||||
{
|
||||
_currentFrame = frame;
|
||||
var firstFrame = !_seenFirstFrame;
|
||||
_seenFirstFrame = true;
|
||||
|
||||
var reason = ResolveStopReason(frame, firstFrame, out var breakpoint);
|
||||
if (reason is null)
|
||||
{
|
||||
_state = DebuggerRunState.Running;
|
||||
return;
|
||||
}
|
||||
|
||||
_state = DebuggerRunState.Paused;
|
||||
_lastStop = new DebugStopEvent(
|
||||
reason.Value,
|
||||
DebugRegisterFile.Capture(frame),
|
||||
frame.Kind,
|
||||
frame.Label,
|
||||
breakpoint);
|
||||
stop = _lastStop;
|
||||
_resumeGate.Reset();
|
||||
}
|
||||
|
||||
Log.Debug($"Debugger stop: {stop!.Reason} at 0x{stop.Address:X16} ({stop.FrameLabel})");
|
||||
Stopped?.Invoke(this, stop);
|
||||
|
||||
// Park the emulation thread until a client resumes the target. The frame
|
||||
// stays live and inspectable for the whole wait.
|
||||
_resumeGate.Wait();
|
||||
|
||||
lock (_sync)
|
||||
{
|
||||
if (_state != DebuggerRunState.Terminated)
|
||||
{
|
||||
_state = DebuggerRunState.Running;
|
||||
}
|
||||
}
|
||||
|
||||
Resumed?.Invoke(this, EventArgs.Empty);
|
||||
}
|
||||
|
||||
void ICpuDebugHook.OnFrameExit(ICpuDebugFrame frame, OrbisGen2Result result)
|
||||
{
|
||||
DebugStopEvent? stop = null;
|
||||
lock (_sync)
|
||||
{
|
||||
if (_options.BreakOnFault &&
|
||||
result != OrbisGen2Result.ORBIS_GEN2_OK &&
|
||||
_state != DebuggerRunState.Terminated)
|
||||
{
|
||||
// Parking here keeps the post-fault frame inspectable.
|
||||
_currentFrame = frame;
|
||||
_state = DebuggerRunState.Paused;
|
||||
_lastStop = BuildFaultStop(frame, result);
|
||||
stop = _lastStop;
|
||||
_resumeGate.Reset();
|
||||
}
|
||||
}
|
||||
|
||||
if (stop is not null)
|
||||
{
|
||||
Log.Debug($"Debugger fault stop: {stop.Result} at 0x{stop.Address:X16} ({stop.FrameLabel})");
|
||||
Stopped?.Invoke(this, stop);
|
||||
_resumeGate.Wait();
|
||||
Resumed?.Invoke(this, EventArgs.Empty);
|
||||
}
|
||||
|
||||
lock (_sync)
|
||||
{
|
||||
if (ReferenceEquals(_currentFrame, frame))
|
||||
{
|
||||
_currentFrame = null;
|
||||
}
|
||||
|
||||
if (_state != DebuggerRunState.Terminated)
|
||||
{
|
||||
_state = DebuggerRunState.Running;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void ICpuDebugHook.OnStall(ICpuDebugFrame frame, CpuStallInfo info)
|
||||
{
|
||||
if (!_options.BreakOnStall)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
DebugStopEvent? stop = null;
|
||||
lock (_sync)
|
||||
{
|
||||
if (_state == DebuggerRunState.Terminated)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
_currentFrame = frame;
|
||||
_state = DebuggerRunState.Paused;
|
||||
_lastStop = new DebugStopEvent(
|
||||
DebugStopReason.Stall,
|
||||
DebugRegisterFile.Capture(frame),
|
||||
frame.Kind,
|
||||
frame.Label,
|
||||
breakpoint: null,
|
||||
result: null,
|
||||
detail: info.Detail,
|
||||
opcodeBytes: ReadOpcodePreview(frame, info.InstructionPointer, 16),
|
||||
stallInfo: info);
|
||||
stop = _lastStop;
|
||||
_resumeGate.Reset();
|
||||
}
|
||||
|
||||
Log.Debug($"Debugger stall stop: {info.Kind} nid={info.Nid} at 0x{info.InstructionPointer:X16}");
|
||||
Stopped?.Invoke(this, stop);
|
||||
_resumeGate.Wait();
|
||||
|
||||
lock (_sync)
|
||||
{
|
||||
if (ReferenceEquals(_currentFrame, frame))
|
||||
{
|
||||
_currentFrame = null;
|
||||
}
|
||||
|
||||
if (_state != DebuggerRunState.Terminated)
|
||||
{
|
||||
_state = DebuggerRunState.Running;
|
||||
}
|
||||
}
|
||||
|
||||
Resumed?.Invoke(this, EventArgs.Empty);
|
||||
}
|
||||
|
||||
private static DebugStopEvent BuildFaultStop(ICpuDebugFrame frame, OrbisGen2Result result)
|
||||
{
|
||||
var opcodeBytes = ReadOpcodePreview(frame, frame.Rip, 16);
|
||||
var detail = $"result={result}";
|
||||
if (opcodeBytes is not null)
|
||||
{
|
||||
detail += $", bytes={opcodeBytes}";
|
||||
}
|
||||
|
||||
return new DebugStopEvent(
|
||||
DebugStopReason.Fault,
|
||||
DebugRegisterFile.Capture(frame),
|
||||
frame.Kind,
|
||||
frame.Label,
|
||||
breakpoint: null,
|
||||
result: result,
|
||||
detail: detail,
|
||||
opcodeBytes: opcodeBytes);
|
||||
}
|
||||
|
||||
private static string? ReadOpcodePreview(ICpuDebugFrame frame, ulong address, int maxBytes)
|
||||
{
|
||||
Span<byte> buffer = stackalloc byte[maxBytes];
|
||||
var count = 0;
|
||||
for (; count < maxBytes; count++)
|
||||
{
|
||||
if (!frame.Memory.TryRead(address + (ulong)count, buffer.Slice(count, 1)))
|
||||
{
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return count == 0 ? null : Convert.ToHexString(buffer[..count]);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Signals that the whole guest run has finished. Releases any parked
|
||||
/// emulation thread and moves the session to
|
||||
/// <see cref="DebuggerRunState.Terminated"/>.
|
||||
/// </summary>
|
||||
public void NotifyTerminated()
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
_state = DebuggerRunState.Terminated;
|
||||
_currentFrame = null;
|
||||
}
|
||||
|
||||
_resumeGate.Set();
|
||||
Terminated?.Invoke(this, EventArgs.Empty);
|
||||
}
|
||||
|
||||
private DebugStopReason? ResolveStopReason(ICpuDebugFrame frame, bool firstFrame, out Breakpoint? breakpoint)
|
||||
{
|
||||
breakpoint = null;
|
||||
if (_pausePending)
|
||||
{
|
||||
_pausePending = false;
|
||||
return DebugStopReason.Pause;
|
||||
}
|
||||
|
||||
if (_stepPending)
|
||||
{
|
||||
_stepPending = false;
|
||||
return DebugStopReason.Step;
|
||||
}
|
||||
|
||||
var hit = Breakpoints.FindExecuteHit(frame.EntryPoint);
|
||||
if (hit is not null)
|
||||
{
|
||||
breakpoint = hit;
|
||||
return DebugStopReason.Breakpoint;
|
||||
}
|
||||
|
||||
if (_options.StopAtEntry && firstFrame)
|
||||
{
|
||||
return DebugStopReason.EntryPoint;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
public bool TryGetRegisters(out DebugRegisterFile registers)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (!IsPausedWithFrame(out var frame))
|
||||
{
|
||||
registers = default;
|
||||
return false;
|
||||
}
|
||||
|
||||
registers = DebugRegisterFile.Capture(frame);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
public bool TrySetRegister(DebugRegisterId id, ulong value)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (!IsPausedWithFrame(out var frame))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
if (id.IsGeneralPurpose())
|
||||
{
|
||||
frame.SetRegister(id.ToCpuRegister(), value);
|
||||
return true;
|
||||
}
|
||||
|
||||
switch (id)
|
||||
{
|
||||
case DebugRegisterId.Rip:
|
||||
frame.Rip = value;
|
||||
return true;
|
||||
case DebugRegisterId.Rflags:
|
||||
frame.Rflags = value;
|
||||
return true;
|
||||
default:
|
||||
// FS/GS bases are owned by the TLS setup and are read-only here.
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public bool TryReadMemory(ulong address, Span<byte> destination)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
return IsPausedWithFrame(out var frame) && frame.Memory.TryRead(address, destination);
|
||||
}
|
||||
}
|
||||
|
||||
public bool TryWriteMemory(ulong address, ReadOnlySpan<byte> source)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
return IsPausedWithFrame(out var frame) && frame.Memory.TryWrite(address, source);
|
||||
}
|
||||
}
|
||||
|
||||
public bool TryReadXmm(int registerIndex, out ulong low, out ulong high)
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (!IsPausedWithFrame(out var frame) || (uint)registerIndex >= 16)
|
||||
{
|
||||
low = 0;
|
||||
high = 0;
|
||||
return false;
|
||||
}
|
||||
|
||||
frame.GetXmm(registerIndex, out low, out high);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
public bool Continue()
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (_state != DebuggerRunState.Paused)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
_resumeGate.Set();
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
public bool StepFrame()
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (_state != DebuggerRunState.Paused)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
_stepPending = true;
|
||||
_resumeGate.Set();
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
public void RequestPause()
|
||||
{
|
||||
lock (_sync)
|
||||
{
|
||||
if (_state == DebuggerRunState.Running)
|
||||
{
|
||||
_pausePending = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private bool IsPausedWithFrame(out ICpuDebugFrame frame)
|
||||
{
|
||||
// Callers must hold _sync.
|
||||
if (_state == DebuggerRunState.Paused && _currentFrame is not null)
|
||||
{
|
||||
frame = _currentFrame;
|
||||
return true;
|
||||
}
|
||||
|
||||
frame = null!;
|
||||
return false;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>Configuration for a <see cref="DebuggerSession"/>.</summary>
|
||||
public sealed class DebuggerSessionOptions
|
||||
{
|
||||
/// <summary>
|
||||
/// When true, the session pauses at the first frame it observes so a client
|
||||
/// can attach breakpoints before the guest runs. Defaults to true, matching
|
||||
/// the "stop at entry" behaviour most debuggers expose.
|
||||
/// </summary>
|
||||
public bool StopAtEntry { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// When true, the session pauses when a frame ends with a non-OK result (a
|
||||
/// CPU trap, memory fault, or unimplemented path) so a client can inspect the
|
||||
/// post-fault register/memory state before the frame is torn down. Defaults
|
||||
/// to true. The stop reports <see cref="DebugStopReason.Fault"/>.
|
||||
/// </summary>
|
||||
public bool BreakOnFault { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// When true, the session pauses when the backend detects an execution stall
|
||||
/// (a mutex spin loop / livelock) before the guest is forced out of the loop,
|
||||
/// so a client can inspect the stalled state. Defaults to true. The stop
|
||||
/// reports <see cref="DebugStopReason.Stall"/>.
|
||||
/// </summary>
|
||||
public bool BreakOnStall { get; init; } = true;
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>
|
||||
/// The inspection and control surface a debugger front-end (for example a
|
||||
/// network server) drives. Register and memory accessors succeed only while the
|
||||
/// target is <see cref="DebuggerRunState.Paused"/>; they return <c>false</c>
|
||||
/// otherwise so callers never read torn state from a running guest.
|
||||
/// </summary>
|
||||
public interface IDebugTarget
|
||||
{
|
||||
/// <summary>The current execution state.</summary>
|
||||
DebuggerRunState State { get; }
|
||||
|
||||
/// <summary>The most recent stop, or null if the target has not stopped yet.</summary>
|
||||
DebugStopEvent? LastStop { get; }
|
||||
|
||||
/// <summary>Reads the integer register file. Fails unless paused.</summary>
|
||||
bool TryGetRegisters(out DebugRegisterFile registers);
|
||||
|
||||
/// <summary>Writes a single register. Fails unless paused.</summary>
|
||||
bool TrySetRegister(DebugRegisterId id, ulong value);
|
||||
|
||||
/// <summary>Reads guest memory into <paramref name="destination"/>. Fails unless paused.</summary>
|
||||
bool TryReadMemory(ulong address, Span<byte> destination);
|
||||
|
||||
/// <summary>Writes guest memory from <paramref name="source"/>. Fails unless paused.</summary>
|
||||
bool TryWriteMemory(ulong address, ReadOnlySpan<byte> source);
|
||||
|
||||
/// <summary>Reads a 128-bit XMM register. Fails unless paused.</summary>
|
||||
bool TryReadXmm(int registerIndex, out ulong low, out ulong high);
|
||||
|
||||
/// <summary>
|
||||
/// Resumes a paused target. Returns false when the target was not paused.
|
||||
/// </summary>
|
||||
bool Continue();
|
||||
|
||||
/// <summary>
|
||||
/// Resumes a paused target and stops again at the next frame boundary.
|
||||
/// Returns false when the target was not paused.
|
||||
/// </summary>
|
||||
bool StepFrame();
|
||||
|
||||
/// <summary>
|
||||
/// Requests that a running target stop at the next frame boundary. Has no
|
||||
/// effect if the target is already paused or terminated.
|
||||
/// </summary>
|
||||
void RequestPause();
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
// Copyright (C) 2026 SharpEmu Emulator Project
|
||||
// SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
using SharpEmu.Core.Cpu.Debugging;
|
||||
using SharpEmu.Debugger.Breakpoints;
|
||||
|
||||
namespace SharpEmu.Debugger.Session;
|
||||
|
||||
/// <summary>
|
||||
/// The debugger's coordination point. It bridges the CPU dispatcher seam
|
||||
/// (<see cref="Hook"/>) to the inspection surface (<see cref="IDebugTarget"/>),
|
||||
/// owns breakpoint state, and raises lifecycle events that a server relays to
|
||||
/// connected clients.
|
||||
/// </summary>
|
||||
public interface IDebuggerSession : IDebugTarget
|
||||
{
|
||||
/// <summary>The breakpoints armed for this session.</summary>
|
||||
BreakpointStore Breakpoints { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The dispatcher-facing hook. Assign this to
|
||||
/// <c>SharpEmuRuntimeOptions.DebugHook</c> so guest frames are routed through
|
||||
/// the session.
|
||||
/// </summary>
|
||||
ICpuDebugHook Hook { get; }
|
||||
|
||||
/// <summary>Raised on the emulation thread each time the target stops.</summary>
|
||||
event EventHandler<DebugStopEvent>? Stopped;
|
||||
|
||||
/// <summary>Raised when a paused target resumes.</summary>
|
||||
event EventHandler? Resumed;
|
||||
|
||||
/// <summary>Raised once the target has terminated.</summary>
|
||||
event EventHandler? Terminated;
|
||||
|
||||
/// <summary>
|
||||
/// Signals that the guest run has finished. Releases any parked emulation
|
||||
/// thread and transitions the session to
|
||||
/// <see cref="DebuggerRunState.Terminated"/>. Hosts call this after the
|
||||
/// runtime returns.
|
||||
/// </summary>
|
||||
void NotifyTerminated();
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
<!--
|
||||
Copyright (C) 2026 SharpEmu Emulator Project
|
||||
SPDX-License-Identifier: GPL-2.0-or-later
|
||||
-->
|
||||
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\SharpEmu.Core\SharpEmu.Core.csproj" />
|
||||
<ProjectReference Include="..\SharpEmu.HLE\SharpEmu.HLE.csproj" />
|
||||
<ProjectReference Include="..\SharpEmu.Logging\SharpEmu.Logging.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
<PropertyGroup>
|
||||
<NoWarn>$(NoWarn);1591</NoWarn>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
@@ -676,10 +676,15 @@ public static class KernelPthreadCompatExports
|
||||
return (int)OrbisGen2Result.ORBIS_GEN2_ERROR_BUSY;
|
||||
}
|
||||
|
||||
// FreeBSD maps NORMAL to checked non-recursive behavior:
|
||||
// self-lock is an error, never implicit recursion.
|
||||
TracePthreadMutex(ctx, "lock", mutexAddress, resolvedAddress, state, currentThreadId, (int)OrbisGen2Result.ORBIS_GEN2_ERROR_DEADLOCK);
|
||||
return (int)OrbisGen2Result.ORBIS_GEN2_ERROR_DEADLOCK;
|
||||
// Several Gen5 runtimes layer their own owner/count bookkeeping
|
||||
// over a NORMAL or ADAPTIVE kernel mutex. Returning EDEADLK here
|
||||
// leaves that guest bookkeeping out of sync with the HLE owner and
|
||||
// turns the wrapper into a permanent lock/unlock retry loop. Keep
|
||||
// the compatibility recursion used by the original implementation;
|
||||
// ERRORCHECK mutexes still take the strict EDEADLK path below.
|
||||
state.RecursionCount++;
|
||||
TracePthreadMutex(ctx, "lock", mutexAddress, resolvedAddress, state, currentThreadId, (int)OrbisGen2Result.ORBIS_GEN2_OK);
|
||||
return (int)OrbisGen2Result.ORBIS_GEN2_OK;
|
||||
}
|
||||
else
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user