structure D3DKMT_CREATE_DOORBELL (d3dkmthk.h)

Article
02/06/2025

La structure D3DKMT_CREATE_DOORBELL contient des paramètres pour D3DKMTCreateDoorbell.

Syntaxe

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;

Membres

hHwQueue

[in] Handle UMD de l’objet de file d’attente matérielle créé dans un appel antérieur à D3DKMTCreateHwQueue. Cette poignée identifie la file d’attente matérielle pour laquelle une porte d’entrée doit être affectée.

hRingBuffer

[in] Handle UMD vers une allocation de mémoire tampon en anneau que UMD précédemment créée. L’allocation doit être visible par GPU et déjà résidente. Dxgkrnl passe l’adresse virtuelle GPU (VA) et la taille de cette allocation à KMD dans un appel DxgkDdiCreateDoorbell correspondant. L’indicateur ResizeRingBufferOperation est un indicateur de UMD à KMD indiquant qu’une porte d’entrée est recréée pour cette file d’attente matérielle avec une nouvelle mémoire tampon en anneau redimensionnée.

hRingBufferControl

[in/optional] Handle UMD vers une allocation de contrôle de mémoire tampon en anneau précédemment créée par UMD. UMD et KMD peuvent utiliser cette allocation en tant que zone de contrôle pour stocker les emplacements des pointeurs de lecture/écriture de mémoire tampon en anneau si nécessaire. L’allocation doit être visible par GPU et déjà résidente lorsque UMD appelle D3DKMTCreateDoorbell. Dxgkrnl passe le long de l’va gpu et de la taille de cette allocation à KMD dans un appel DxgkDdiCreateDoorbell correspondant.

Flags

[in/optional] Champ de bits de D3DKMT_CREATE_DOORBELL_FLAGS valeurs spécifiant les indicateurs de création de porte d’entrée.

PrivateDriverDataSize

[in] Taille des données de pilote privé qui pPrivateDriverData pointe vers, en octets.

PrivateDriverData

[in/out] Pointeur vers une mémoire tampon privée vers le pilote. La taille de cette mémoire tampon est spécifiée par PrivateDriverDataSize. La taille maximale de la mémoire tampon autorisée est D3DDDI_DOORBELL_PRIVATEDATA_MAX_BYTES_WDDM3_1 octets.

DoorbellCPUVirtualAddress

[out] Pointeur vers l’UC VA (en lecture/écriture) réservé par le système d’exploitation pour cette porte d’entrée. UMD écrit une valeur spécifique dans cette adresse, en effet « sonnant la porte d’entrée » pour informer le planificateur GPU d’une nouvelle soumission de travail sur la file d’attente matérielle. Cette adresse reste constante pendant toute la durée de vie de la porte d’entrée, même si la porte d’entrée physique sous-jacente est déconnectée. L’UMD doit toujours utiliser cette adresse pour écrire/lire dans cette porte d’entrée.

DoorbellSecondaryCPUVirtualAddress

[out/optional] Pointeur vers une unité virtuelle d’UC secondaire (en lecture/écriture) réservée par le système d’exploitation pour cette porte d’entrée.

Sur le matériel qui implémente un emplacement de porte d’entrée secondaire, l’UMD définit l’indicateur RequireSecondaryCpuVA. Pour ces appareils, le système d’exploitation réserve un autre processeur VA pour cette porte d’entrée. Au cours de la durée de vie de la porte d’entrée, cette adresse restera constante même si la porte d’entrée physique sous-jacente est déconnectée.

DoorbellStatusCPUVirtualAddress

[out] Pointeur vers l’UC VA de l’état doorbell. La valeur à cette adresse indique à l’UMD si la porte d’entrée affectée à cette file d’attente matérielle est actuellement connectée. Chaque fois que l’UMD envoie de nouvelles tâches à la file d’attente et sonne la porte d’entrée, elle doit vérifier cette valeur pour déterminer si l’anneau de porte a réussi. Si l’anneau a échoué, UMD doit appeler D3DKMTConnectDoorbell pour reconnecter la porte d’entrée, puis réessayer de soumettre le travail.

Le système d’exploitation alloue et écrit cette mémoire d’état de porte 64 bits, le mappe dans l’espace d’adressage du processus et donne à l’UMD son processeur en mode utilisateur à lire. Par conséquent, UMD doit lire la valeur 64 bits stockée dans cette adresse pour obtenir l’état de la porte d’entrée. La valeur de cette adresse peut être l’une des valeurs d’énumération D3DDDI_DOORBELL_STATUS.

Cette adresse reste constante pendant toute la durée de vie de la porte d’entrée, même si la porte d’entrée physique sous-jacente est déconnectée. L’UMD doit toujours utiliser cette adresse pour lire l’état de la porte d’entrée.

Seul le système d’exploitation écrit et met à jour cette mémoire d’état :

Lors du retour réussi de DxgkDdiConnectDoorbell, le système d’exploitation écrit l’état en tant que D3DDDI_DOORBELL_STATUS_CONNECTED.
Si le système d’exploitation déconnecte la porte d’entrée dans le cadre de la suspension de la file d’attente matérielle ou de la mise hors tension du GPU, il appelle le DxgkDdiDisconnectDoorbell, puis écrit l’état en tant que D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY.
Si le KMD souhaite déconnecter la porte d’entrée pour une raison quelconque, il appelle le DxgkDisconnectDoorbellCB rappel pour informer le système d’exploitation. KMD fournit D3DDDI_DOORBELL_STATUS comme état, que le système d’exploitation écrit dans cette page d’état.
Dans les scénarios de perte ou d’arrêt du GPU, le système d’exploitation écrit D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT comme état.

HwQueueProgressFenceLastQueuedValueCPUVirtualAddress

[out] PROCESSEUR VA de l’emplacement où l’UMD écrit la valeur de clôture de progression nouvellement mise en file d’attente chaque fois qu’une nouvelle mémoire tampon de commande est ajoutée à la mémoire tampon en anneau.

hDoorbell

[out] Handle d’exécution pour l’objet doorbell nouvellement créé.