D3DKMTConnectDoorbell function (d3dkmthk.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.
D3DKMTConnectDoorbell connects (or reconnects) a previously created doorbell to a hardware queue.
Syntax
NTSTATUS D3DKMTConnectDoorbell(
D3DKMT_CONNECT_DOORBELL *unnamedParam1
);
Parameters
unnamedParam1
[in] Pointer to a *D3DKMT_CONNECT_DOORBELL* structure that describes the doorbell to connect.
Return value
D3DKMTConnectDoorbell returns STATUS_SUCCESS when the OS successfully connects the doorbell to the hardware queue and UMD can use this doorbell for work submission. Typically this call should not fail; however, a failure code would be from GPU lost or stop kinds of irrecoverable scenarios.
Remarks
Each time the UMD submits new work to the hardware queue and rings the doorbell, it must read the DoorbellStatusCPUVirtualAddress to check whether the doorbell ring succeeded. On failure, UMD must call D3DKMTConnectDoorbell to reconnect the doorbell and then try the submission again.
A doorbell can be disconnected for several reasons:
- When a doorbell is created, the OS initializes it in a "disconnected" state, and only connects it when UMD calls D3DKMTConnectDoorbell for the first time.
- The doorbell was "victimized" on hardware that supports the dedicated doorbell model. That is, this hardware queue's physical doorbell was assigned to another hardware queue. This reassignment is likely because there are more hardware queues created on the GPU than physical doorbells.
- The doorbell was disconnected as a part of suspending the hardware queue or powering down the GPU.
When UMD calls D3DKMTConnectDoorbell to connect the doorbell assigned to a hardware queue, the OS makes a corresponding DxgkDdiConnectDoorbell call to KMD, so that the KMD can find a physical doorbell, assign it to this hardware queue, and make the required connections between the hardware queue, doorbell, GPU scheduler and so forth.
For more information, see User-mode work submission.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 11, version 24H2 (WDDM 3.2) |
| Header | d3dkmthk.h |