mirror of
https://github.com/par274/sharpemu.git
synced 2026-07-25 20:28:48 +08:00
Spooks
50 lines
2.2 KiB
C#
50 lines
2.2 KiB
C#
// 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);
|
|
}
|