struttura D3DKMT_CREATE_DOORBELL (d3dkmthk.h)

Articolo
02/06/2025

La struttura D3DKMT_CREATE_DOORBELL contiene parametri per D3DKMTCreateDoorbell.

Sintassi

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;

Membri

hHwQueue

[in] Handle UMD dell'oggetto coda hardware creato in una chiamata precedente a D3DKMTCreateHwQueue. Questo handle identifica la coda hardware a cui deve essere assegnato un campanello.

hRingBuffer

[in] Handle UMD per un'allocazione del buffer circolare che UMD creato in precedenza. L'allocazione deve essere visibile e già residente nella GPU. Dxgkrnl passa lungo l'indirizzo virtuale GPU (VA) e le dimensioni di questa allocazione al KMD in una chiamata DxgkDdiCreateDoorbell. Il flagResizeRingBufferOperationè un suggerimento da UMD a KMD che viene ricreato un campanello per questa coda hardware con un nuovo buffer circolare ridimensionato.

hRingBufferControl

[in/facoltativo] Handle UMD per un'allocazione del controllo del buffer circolare creato in precedenza da UMD. UMD e KMD possono usare questa allocazione come area di controllo per archiviare posizioni del puntatore di lettura/scrittura del buffer circolare, se necessario. L'allocazione deve essere visibile dalla GPU e già residente quando UMD chiama D3DKMTCreateDoorbell. Dxgkrnl passa lungo la GPU VA e le dimensioni di questa allocazione al KMD in una chiamata DxgkDdiCreateDoorbell.

Flags

[in/facoltativo] Campo di bit di D3DKMT_CREATE_DOORBELL_FLAGS valori che specificano i flag di creazione del campanello.

PrivateDriverDataSize

[in] Dimensioni dei dati del driver privato a cui pPrivateDriverData punta, in byte.

PrivateDriverData

[in/out] Puntatore a un buffer privato per il driver. Le dimensioni di questo buffer vengono specificate da PrivateDriverDataSize. La dimensione massima consentita del buffer è D3DDDI_DOORBELL_PRIVATEDATA_MAX_BYTES_WDDM3_1 byte.

DoorbellCPUVirtualAddress

[out] Puntatore al VA della CPU (sia di lettura/scrittura) riservato dal sistema operativo per questo campanello. UMD scriverà un valore specifico in questo indirizzo, in modo efficace "suonando il campanello" per notificare all'utilità di pianificazione GPU di un nuovo invio di lavoro nella coda hardware. Questo indirizzo rimane costante per tutta la durata del campanello, anche se il campanello fisico sottostante viene disconnesso. Il UMD deve sempre usare questo indirizzo per scrivere/leggere in questo campanello.

DoorbellSecondaryCPUVirtualAddress

[out/optional] Puntatore a un VA della CPU secondario (sia in lettura/scrittura) riservato dal sistema operativo per questo campanello.

Nell'hardware che implementa una posizione secondaria del campanello, UMD imposta il flagRequireSecondaryCpuVA. Per questi dispositivi, il sistema operativo riserva un altro VA CPU per questo campanello. Nel corso della durata del campanello, questo indirizzo rimarrà costante anche se il campanello fisico sottostante viene disconnesso.

DoorbellStatusCPUVirtualAddress

[out] Puntatore alla CPU VA dello stato del campanello. Il valore in questo indirizzo indica al UMD se il campanello assegnato a questa coda hardware è attualmente connesso. Ogni volta che il UMD invia nuovo lavoro alla coda e suona il campanello, deve controllare questo valore per determinare se l'anello del campanello è riuscito. Se l'anello non è riuscito, UMD deve chiamare D3DKMTConnectDoorbell per riconnettere il campanello e quindi provare a inviare nuovamente il lavoro.

Il sistema operativo alloca e scrive questa memoria di stato del campanello a 64 bit, la esegue il mapping nello spazio degli indirizzi del processo e assegna il relativo VA CPU in modalità utente all'UMD da cui leggere. Di conseguenza, UMD dovrebbe leggere il valore a 64 bit archiviato in questo indirizzo per ottenere lo stato del campanello. Il valore di questo indirizzo può essere uno dei valori di enumerazione D3DDDI_DOORBELL_STATUS.

Questo indirizzo rimane costante per tutta la durata del campanello, anche se il campanello fisico sottostante viene disconnesso. Il UMD deve usare sempre questo indirizzo per leggere lo stato del campanello.

Solo il sistema operativo scrive e aggiorna questa memoria di stato:

Al termine del ritorno da DxgkDdiConnectDoorbell, il sistema operativo scrive lo stato come D3DDDI_DOORBELL_STATUS_CONNECTED.
Se il sistema operativo disconnette il campanello come parte della sospensione della coda hardware o dell'alimentazione della GPU, chiama DxgkDdiDisconnectDoorbell e quindi scrive lo stato come D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY.
Se il KMD vuole disconnettere il campanello per qualsiasi motivo, chiama il DxgkDisconnectDoorbellCB callback per informare il sistema operativo. KmD fornisce D3DDDI_DOORBELL_STATUS come stato, che il sistema operativo scrive in questa pagina di stato.
Negli scenari di perdita o arresto della GPU, il sistema operativo scrive D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT come stato.

HwQueueProgressFenceLastQueuedValueCPUVirtualAddress

[out] CPU VA della posizione in cui UMD scriverà il valore limite di stato appena accodato ogni volta che viene aggiunto un nuovo buffer dei comandi al buffer circolare.

hDoorbell

[out] Handle di runtime per l'oggetto campanello appena creato.