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）和此配置的大小傳遞至對應 DxgkDdiCreateDoorbell 呼叫中的 KMD。 ResizeRingBufferOperation 旗標是 UMD 到 KMD 的提示，指出此硬體佇列的門鈴會以新的重設大小通道緩衝區重新建立。

hRingBufferControl

[in/optional]UMD 緩衝區控制項配置的 UMD 句柄先前由 UMD 建立。 UMD 和 KMD 可以使用此配置作為控制區域，視需要儲存環形緩衝區讀取/寫入指標位置。當UMD呼叫 D3DKMTCreateDoorbell時，配置必須是 GPU 可見且已常駐。 Dxgkrnl 會在對應的 DxgkDdiCreateDoorbell 呼叫中，沿著 GPU VA 傳遞此配置的大小給 KMD。

Flags

[in/optional]指定門鈴建立旗標之 D3DKMT_CREATE_DOORBELL_FLAGS 值的位欄位。

PrivateDriverDataSize

[in]pPrivateDriverData 指向的私人驅動程序數據大小，以位元組為單位。

PrivateDriverData

[in/out]指向驅動程式私用之緩衝區的指標。這個緩衝區的大小是由 PrivateDriverDataSize所指定。允許的緩衝區大小上限為D3DDDI_DOORBELL_PRIVATEDATA_MAX_BYTES_WDDM3_1個字節。

DoorbellCPUVirtualAddress

[out]此門鈴作系統保留的CPU VA指標（兩者皆為讀取/寫入）。 UMD 會將特定值寫入此位址，有效地「響鈴」，以通知 GPU 排程器硬體佇列上的新工作提交。即使基礎實體門鈴中斷連線，這個位址在門鈴的存留期內仍然保持不變。 UMD 應該一律使用此位址來寫入/讀取此門鈴。

DoorbellSecondaryCPUVirtualAddress

[out/optional]作系統為此門鈴保留的次要 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。
如果作系統在暫停硬體佇列或關閉 GPU 時中斷門鈴的連線，則會呼叫 KMD 的 DxgkDdiDisconnectDoorbell，然後將狀態寫入為D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY。
如果 KMD 因故想要中斷門鈴的連線，它會呼叫 DxgkDisconnectDoorbellCB 回呼以通知 OS。 KMD 會提供D3DDDI_DOORBELL_STATUS作為作系統寫入此狀態頁面的狀態。
在 GPU 遺失或停止的情況下，OS 會將D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT寫入為狀態。

HwQueueProgressFenceLastQueuedValueCPUVirtualAddress

[out]UMD 會在每次將新的命令緩衝區附加至通道緩衝區時，寫入新佇列進度柵欄值的位置 CPU VA。

hDoorbell

[out]新建立之 Doorbell 物件的運行時間句柄。