mirror of
https://github.com/par274/sharpemu.git
synced 2026-08-01 23:49:44 +08:00
Add live debugger frontend and mutex stall recovery (#383)
This commit is contained in:
Spooks
@@ -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();
|
||||
}
|
||||
Reference in New Issue
Block a user