PsStep

Performs a single-step operation on the target core.

Syntax

PULSE_STATUS PsStep(
[in] PPS_ENGINE pEngine,
[in] uint8_t SuppressInterrupts
);

Parameters

PPS_ENGINE pEngine

An opaque handle to an engine created by the EngCreateEngine function.

uint8_t SuppressInterrupts

A boolean parameter controlling the interrupt suppression. If not 0, it blocks interrupt delivery during the single-step operation.

Return value

If the function succeeds, the return value is PULSE_STATUS_SUCCESS.

If it fails, it returns one of the PULSE_STATUS values. Possible return codes include, but are not limited to, the following:

PULSE_STATUS_INSUFFICIENT_RESOURCES 0xC0000002	One of the memory allocations failed during initialization.
PULSE_STATUS_READ_FAILED 0xC0000003	Transport communication failed during a read operation.
PULSE_STATUS_WRITE_FAILED 0xC0000004	Transport communication failed during a write operation.
PULSE_STATUS_TIMEOUT 0xC0000007	Might happen if Transport I/O timed out. No response was received from the debuggee within the request timeout period.
PULSE_STATUS_INVALID_PARAMETER 0xC0000010	The pEngine parameter is NULL.
PULSE_STATUS_INVALID_PACKET 0xC0000031	An invalid or unexpected packet was received in response.
PULSE_STATUS_DEVICE_CONNECTION_LOST 0xC0000308	The connection to the transport was lost. Try restarting the engine or the transport.

Remarks

Pending interrupts, such as clock timer interrupts, are delivered during the single-step operation by default. This may be confusing, as it can break the linear instruction flow. To maintain a linear flow, suppress the interrupts.

If you encounter a wait instruction like "hlt", "mwait" or similar, do NOT suppress interrupts - otherwise, the core will wait for an interrupt to wake up and may never resume execution. Since all other cores are blocked in the hypervisor, you may end up with a deadlocked system.