D3DKMT_CREATE_DOORBELL 结构 (d3dkmthk.h)

项目
02/23/2024

重要

某些信息与预发行产品相关，该产品在商业发布之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

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;
} D3DKMT_CREATE_DOORBELL;

成员

hHwQueue

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

hRingBuffer

[in]UMD 先前创建的环形缓冲区分配的 UMD 句柄。分配必须是 GPU 可见且已驻留的。 Dxgkrnl 在相应的 DxgkDdiCreateDoorbell 调用中沿此分配的 GPU 虚拟地址和大小传递给 KMD。 ResizeRingBufferOperation 标志是从 UMD 到 KMD 的提示，指示正在为此硬件队列重新创建一个门铃，其中包含一个新的重设大小的环形缓冲区。

hRingBufferControl

[in/optional]以前由 UMD 创建的环形缓冲区控制分配的 UMD 句柄。如果需要，UMD 和 KMD 可以将此分配用作控制区域来存储环形缓冲区读/写指针位置。分配必须是 GPU 可见且已驻留的。 Dxgkrnl 在相应的 DxgkDdiCreateDoorbell 调用中沿此分配的 GPU 虚拟地址和大小传递给 KMD。

Flags

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

PrivateDriverDataSize

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

PrivateDriverData

[in/out]指向专用于驱动程序的缓冲区的指针。此缓冲区的大小由 PrivateDriverDataSize 指定。

DoorbellCPUVirtualAddress

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

DoorbellSecondaryCPUVirtualAddress

[out/optional]指向辅助 CPU 虚拟地址的指针 (OS 为此门铃保留读/写) 。

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

DoorbellStatusCPUVirtualAddress

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

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

值	含义
D3DDDI_DOORBELL_STATUS_CONNECTED	门铃已连接，可以提交工作。
D3DDDI_DOORBELL_STATUS_CONNECTED_NOTIFY	门铃已连接;但是，在每次提交新工作和门铃响铃后，UMD 应通过调用 D3DKMTNotifyWorkSubmission 来通知 KMD。
D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY	此时无法连接门铃，但 UMD 应重试进行连接。
D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT	门铃不会连接，UMD 无法将此硬件队列用于工作提交。此故障通常意味着不可恢复的方案，例如 GPU 重置或停止的适配器。

此地址在门铃的生存期内保持不变，即使基础物理门铃断开连接也是如此。 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作为状态。