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

src/SharpEmu.CLI/Program.cs

@@ -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;

src/SharpEmu.CLI/SharpEmu.CLI.csproj

@@ -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>

src/SharpEmu.CLI/packages.lock.json

@@ -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": {