D3DKMT_CREATE_DOORBELL结构（d3dkmthk.h）

项目
02/06/2025

D3DKMT_CREATE_DOORBELL 结构包含 D3DKMTCreateDoorbell的参数。

语法

typedef struct _D3DKMT_CREATE_DOORBELL {
  D3DKMT_HANDLE                hHwQueue;
  D3DKMT_HANDLE                hRingBuffer;
  D3DKMT_HANDLE                hRingBufferControl;
  D3DKMT_CREATE_DOORBELL_FLAGS Flags;
  UINT                         PrivateDriverDataSize;
  VOID                         *PrivateDriverData;
  VOID                         *DoorbellCPUVirtualAddress;
  VOID                         *DoorbellSecondaryCPUVirtualAddress;
  VOID                         *DoorbellStatusCPUVirtualAddress;
  VOID                         *HwQueueProgressFenceLastQueuedValueCPUVirtualAddress;
  D3DKMT_HANDLE                hDoorbell;
} D3DKMT_CREATE_DOORBELL;

成员

hHwQueue

[in]在调用 D3DKMTCreateHwQueue之前创建的硬件队列对象的 UMD 句柄。此句柄标识需要为其分配门铃的硬件队列。

hRingBuffer

[in]UMD 的通道缓冲区分配，UMD 以前创建的。分配必须是 GPU 可见且已驻留的。 Dxgkrnl 将 GPU 虚拟地址（VA）和此分配的大小传递给 KMD，DxgkDdiCreateDoorbell 调用。 ResizeRingBufferOperation 标志是 UMD 到 KMD 的提示，提示为此硬件队列重新创建门铃，其中包含新的重设大小的环形缓冲区。

hRingBufferControl

[in/optional]UMD 对环缓冲区控制分配的 UMD 句柄以前由 UMD 创建。 UMD 和 KMD 可以使用此分配作为控制区域来存储环缓冲区读/写指针位置（如果需要）。当 UMD 调用 D3DKMTCreateDoorbell时，分配必须是 GPU 可见且已驻留。 Dxgkrnl 在相应的 DxgkDDdiCreateDoorbell 调用中沿 GPU VA 传递此分配的大小。

Flags

[in/optional]指定门铃创建标志的 D3DKMT_CREATE_DOORBELL_FLAGS 值的位字段。

PrivateDriverDataSize

[in]pPrivateDriverData 指向的专用驱动程序数据的大小（以字节为单位）。

PrivateDriverData

[in/out]指向专用于驱动程序的缓冲区的指针。此缓冲区的大小由 PrivateDriverDataSize指定。允许的最大缓冲区大小为D3DDDI_DOORBELL_PRIVATEDATA_MAX_BYTES_WDDM3_1字节。

DoorbellCPUVirtualAddress

[out]指向 OS 为此门铃保留的 CPU VA（两个读/写）的指针。 UMD 会将特定值写入此地址，从而有效地“敲响门铃”，以通知 GPU 计划程序在硬件队列上提交新的工作提交。即使基础物理门铃断开连接，此地址在门铃的生存期内保持不变。 UMD 应始终使用此地址来写入/读取此门铃。

DoorbellSecondaryCPUVirtualAddress

[out/optional]指向 OS 为此门铃保留的辅助 CPU VA（两个读/写）的指针。

在实现辅助门铃位置的硬件上，UMD 将设置 RequireSecondaryCpuVA 标志。对于此类设备，OS 将为此门铃保留另一个 CPU VA。在门铃的生存期内，即使基础物理门铃断开连接，此地址也会保持不变。

DoorbellStatusCPUVirtualAddress

[out]指向门铃状态的 CPU VA 的指针。此地址处的值指示 UMD 是否当前连接分配给此硬件队列的门铃。每次 UMD 向队列提交新工作并响起门铃时，都必须检查此值，以确定门铃环是否成功。如果通道失败，UMD 必须调用 D3DKMTConnectDoorbell 重新连接门铃，然后再次尝试提交工作。

OS 分配并写入此 64 位门铃状态内存，将其映射到进程的地址空间，并将其用户模式 CPU VA 提供给 UMD 进行读取。因此，UMD 应读取存储在此地址中的 64 位值以获取门铃状态。此地址的值可以是 D3DDDI_DOORBELL_STATUS 枚举值之一。

即使基础物理门铃断开连接，此地址在门铃的生存期内保持不变。 UMD 应始终使用此地址来读取门铃的状态。

仅 OS 写入并更新此状态内存：

从 DxgkDdiConnectDoorbell成功返回时，OS 会将状态写入为D3DDDI_DOORBELL_STATUS_CONNECTED。
如果 OS 在暂停硬件队列或关闭 GPU 时断开门铃的连接，它将调用 KMD 的 DxgkDdiDisconnectDoorbell，然后将状态写入为D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY。
如果 KMD 出于任何原因想要断开门铃的连接，它将调用 DxgkDisconnectDoorbellCB 回调来通知 OS。 KMD 提供D3DDDI_DOORBELL_STATUS作为 OS 写入此状态页的状态。
在 GPU 丢失或停止的情况下，OS 将D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT写入状态。

HwQueueProgressFenceLastQueuedValueCPUVirtualAddress

[out]UMD 每次将新的命令缓冲区追加到环形缓冲区时，UMD 将写入新排队的进度围栏值的位置的 CPU VA。

hDoorbell

[out]新创建的门铃对象的运行时句柄。