DXGKCB_EXCLUDE_ADAPTER_ACCESS callback function (dispmprt.h)

Article
10/21/2021

The DxgkCbExcludeAdapterAccess function prevents all access to the display adapter and calls a provided DxgkProtectedCallback callback routine while in this protected state.

Syntax

DXGKCB_EXCLUDE_ADAPTER_ACCESS DxgkcbExcludeAdapterAccess;

NTSTATUS DxgkcbExcludeAdapterAccess(
  [in] HANDLE DeviceHandle,
  [in] ULONG Attributes,
  [in] DXGKDDI_PROTECTED_CALLBACK DxgkProtectedCallback,
  [in] PVOID ProtectedCallbackContext
)
{...}

Parameters

[in] DeviceHandle

A handle that represents a display adapter. The display miniport driver obtained this handle in the DeviceHandle member of the DXGKRNL_INTERFACE structure that was passed to DxgkDdiStartDevice.

[in] Attributes

A value that specifies video memory operations. This parameter can be any combination of the following bit flag values, except that DXGK_EXCLUDE_EVICT_ALL and DXGK_EXCLUDE_CALL_SYNCHRONOUS are mutually exclusive. These values are defined in Dispmprt.h.

DXGK_EXCLUDE_EVICT_ALL

All video memory in the adapter is copied to system memory; this is an expensive operation. If the Attributes parameter is not set to this value, access to locked surfaces in system memory is suspended.

DXGK_EXCLUDE_CALL_SYNCHRONOUS

Executes the protected DxgkProtectedCallback driver callback routine in the same thread context as the caller. The caller must be calling from a second level or third level synchronized DDI call. Otherwise the DxgkCbExcludeAdapterAccess function will fail.

DXGK_EXCLUDE_BRIDGE_ACCESS

Protects access to the PCI Express (PCIe) root port when the driver needs to access the root port configuration space. Set the Attributes parameter to this value before calling DxgkCbReadDeviceSpace or DxgkCbWriteDeviceSpace functions with the DataType parameter set to DXGK_WHICHSPACE_BRIDGE.

[in] DxgkProtectedCallback

The callback routine to be called back when all access to the adapter has been halted.

[in] ProtectedCallbackContext

A pointer to the value to pass to the ProtectedCallbackContext parameter of the DxgkProtectedCallback callback routine.

Return value

DxgkCbExcludeAdapterAccess returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

Application requests will be blocked until this function returns. While in this protective state, the provided DxgkProtectedCallback callback routine is called at IRQL = PASSIVE_LEVEL.

DxgkCbExcludeAdapterAccess acquires exclusive adapter access in order to prevent graphics-related I/O operations to the display adapter and all links. This effectively idles the GPU for the entire duration of the call.

This function also prevents all PCI configuration space access to the PCI Express (PCIe) root port if DXGK_EXCLUDE_BRIDGE_ACCESS is specified in the Attributes parameter.

The driver should not block continued execution of the calling thread by waiting for the DxgkProtectedCallback callback routine to return. For example, the driver could schedule an asynchronous worker thread to handle the callback routine.

An exception to this blocking of application requests occurs when the user-mode display driver has set the UseAlternateVA bit-field flag in the Flags member of the D3DDDICB_LOCKFLAGS structure in a call to the pfnLockCb function. DxgkCbExcludeAdapterAccess does not block this type of allocation lock, and the CPU can access the display adapter while the protected callback routine is executing.

Note If UseAlternateVA has been set in a call to pfnLockCb, the display miniport driver should not call DxgkCbExcludeAdapterAccess.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Desktop
Header	dispmprt.h (include Dispmprt.h)
IRQL	PASSIVE_LEVEL