DXGKDDI_PREEMPTCOMMAND callback function (d3dkmddi.h)

Article
05/26/2023

The DxgkDdiPreemptCommand function preempts a direct memory access (DMA) buffer that was previously submitted to and currently queued in the hardware command execution unit.

Syntax

DXGKDDI_PREEMPTCOMMAND DxgkddiPreemptcommand;

NTSTATUS DxgkddiPreemptcommand(
  [in] IN_CONST_HANDLE hAdapter,
  [in] IN_CONST_PDXGKARG_PREEMPTCOMMAND pPreemptCommand
)
{...}

Parameters

[in] hAdapter

A handle to a context block that is associated with a display adapter. The display miniport driver previously provided this handle to the Microsoft DirectX graphics kernel subsystem in the MiniportDeviceContext output parameter of the DxgkDdiAddDevice function.

[in] pPreemptCommand

A pointer to a DXGKARG_PREEMPTCOMMAND structure that describes the command that is used to preempt a DMA buffer previously submitted to the hardware command execution unit.

Return value

Returns STATUS_SUCCESS upon successful completion. If the driver instead returns an error code, the operating system causes a system bugcheck to occur. For more information, see the following Remarks section.

Remarks

If the driver determines that the hardware is already finished processing all of the submitted DMA buffers--and that the hardware informed the graphics processing unit (GPU) scheduler about the completions--when its DxgkDdiPreemptCommand function is called to preempt the DMA buffers, the driver should perform the following operations instead of submitting the preempt fence that is identified by the PreemptionFenceId member of DXGKARG_PREEMPTCOMMAND to the hardware:

Raise IRQL to interrupt level. For example, the driver can call the DxgkCbSynchronizeExecution function to synchronize with its DxgkDdiInterruptRoutine function.
Inform the GPU scheduler about the preemption information. The driver can either call the DxgkCbNotifyInterrupt function directly or call its DxgkDdiInterruptRoutine function (for example, if the driver must perform other updates as well).
Note that the GPU scheduler handles instances where the hardware has stopped responding because of Timeout Detection and Recovery (TDR) work.

If the driver returns an error code, the Microsoft DirectX graphics kernel subsystem causes a system bugcheck to occur. In a crash dump file, the error is noted by the message BugCheck 0x119, which has the following four parameters.

0x2
The NTSTATUS error code returned from the failed driver call
A pointer to the DXGKARG_PREEMPTCOMMAND structure
A pointer to an internal scheduler data structure

DxgkDdiPreemptCommand should be made nonpageable because it runs at IRQL = DISPATCH_LEVEL

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Target Platform	Desktop
Header	d3dkmddi.h
IRQL	DISPATCH_LEVEL