DXGKDDI_CREATEDOORBELL callback function (d3dkmddi.h)

Article
02/22/2024

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.

Requirements

Requirement	Value
Minimum supported client	WIN11_FUTURE
Header	d3dkmddi.h
IRQL	PASSIVE_LEVEL