DXGKDDI_CREATEDOORBELL callback function (d3dkmddi.h)

Important

Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

The OS calls KMD's DxgkDdiCreateDoorbell callback function to create a doorbell for a hardware queue.

Syntax

DXGKDDI_CREATEDOORBELL DxgkddiCreatedoorbell;

NTSTATUS DxgkddiCreatedoorbell(
  INOUT_PDXGKARG_CREATEDOORBELL pArgs
)
{...}

Parameters

pArgs

[in/out] Pointer to a DXGKARG_CREATEDOORBELL structure that describes the doorbell.

Return value

DxgkDdiCreateDoorbell returns STATUS_SUCCESS if KMD was able to successfully create its doorbell object for the specified hardware queue, and UMD can use this doorbell for work submission. Otherwise, it returns an appropriate NTSTATUS error code. UMD can't use the doorbell for work submission if KMD returns any failure code.

Remarks

When UMD calls D3DKMTCreateDoorbell to create a doorbell for a hardware queue, the OS makes a corresponding DxgkDdiCreateDoorbell call to KMD so that KMD can initialize its doorbell structures.

KMD's DxgkDdiCreateDoorbell function should only create and initialize its doorbell data structures. It should not assign a physical doorbell location to this doorbell object yet as that is done during a subsequent call to DxgkDdiConnectDoorbell. This lazy assignment ensures that a physical doorbell is not used up during hardware queue and doorbell creation, only to go wasted in the event that UMD never submits commands to it or starts submitting commands at a later time. In this way, physical doorbells are used only when actually required.

For more information, see User-mode work submission.

Requirements

Requirement Value
Minimum supported client Windows 11, version 24H2 (WDDM 3.2)
Header d3dkmddi.h
IRQL PASSIVE_LEVEL

See also

DXGKARG_CREATEDOORBELL

D3DKMTCreateDoorbell

DxgkDdiConnectDoorbell

DxgkDdiDestroyDoorbell