structure D3DKMT_CREATE_DOORBELL (d3dkmthk.h)

Article
02/23/2024

Important

Certaines informations se rapportent à un produit de préversion qui peut être sensiblement modifié avant sa commercialisation. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

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

Membres

hHwQueue

[in] Handle UMD de l’objet de file d’attente matérielle créé lors d’un appel précédent à D3DKMTCreateHwQueue. Cet objet identifie la file d’attente matérielle pour laquelle une sonnette doit être affectée.

hRingBuffer

[in] Gérez l’UMD dans une allocation de mémoire tampon en anneau créée précédemment par l’UMD. L’allocation doit être visible par GPU et déjà résidente. Dxgkrnl transmet l’adresse virtuelle gpu et la taille de cette allocation à KMD dans un appel DxgkDdiCreateDoorbell correspondant. L’indicateur ResizeRingBufferOperation est un indicateur d’UMD à KMD indiquant qu’une sonnette 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 dans 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 comme zone de contrôle pour stocker les emplacements de pointeur en lecture/écriture de la mémoire tampon en anneau si nécessaire. L’allocation doit être visible par GPU et déjà résidente. Dxgkrnl transmet l’adresse virtuelle gpu et la taille de cette allocation à KMD dans un appel DxgkDdiCreateDoorbell correspondant.

Flags

[in/optional] Champ bit de valeurs D3DKMT_CREATE_DOORBELL_FLAGS spécifiant les indicateurs de création de sonnette.

PrivateDriverDataSize

[in] Taille des données du pilote privé vers laquelle pPrivateDriverData pointe, 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.

DoorbellCPUVirtualAddress

[out] Pointeur vers l’adresse virtuelle du processeur (à la fois en lecture/écriture) réservée par le système d’exploitation pour cette sonnette. UMD écrit une valeur spécifique à cette adresse, en « sonnant la porte » 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 sonnette, même si la sonnette physique sous-jacente est déconnectée. L’UMD doit toujours utiliser cette adresse pour écrire/lire dans cette sonnette.

DoorbellSecondaryCPUVirtualAddress

[out/optional] Pointeur vers une adresse virtuelle secondaire du processeur (à la fois en lecture/écriture) réservée par le système d’exploitation pour cette sonnette.

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

DoorbellStatusCPUVirtualAddress

[out] Pointeur vers l’adresse virtuelle du processeur de la sonnette status. La valeur à cette adresse indique à l’UMD si la sonnette affectée à cette file d’attente matérielle est actuellement connectée. Chaque fois que l’UMD envoie un nouveau travail à la file d’attente et sonne à la porte, il doit case activée cette valeur pour déterminer si l’anneau de sonnette a réussi. Si l’anneau a échoué, UMD doit appeler D3DKMTConnectDoorbell pour reconnecter la sonnette, puis réessayer d’envoyer le travail.

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

Valeur	Signification
D3DDDI_DOORBELL_STATUS_CONNECTED	La sonnette est connectée et prête à être soumise au travail.
D3DDDI_DOORBELL_STATUS_CONNECTED_NOTIFY	La sonnette est connectée ; toutefois, après chaque nouvelle soumission de travail et sonnerie de porte, l’UMD doit notifier KMD en appelant D3DKMTNotifyWorkSubmission.
D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY	La sonnette ne peut pas être connectée pour le moment, mais l’UMD doit réessayer de la connecter.
D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT	La sonnette n’est pas connectée et l’UMD ne peut pas utiliser cette file d’attente matérielle pour l’envoi de travaux. Cette défaillance implique généralement un scénario irrécupérable, tel qu’une réinitialisation GPU ou un arrêt de la carte.

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

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

En cas de retour réussi de DxgkDdiConnectDoorbell, le système d’exploitation écrit le status comme D3DDDI_DOORBELL_STATUS_CONNECTED.
Si le système d’exploitation déconnecte la sonnette 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 de KMD, puis écrit le status comme D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY.
Si le KMD souhaite déconnecter la sonnette pour une raison quelconque, il appelle le rappel DxgkDisconnectDoorbellCB pour informer le système d’exploitation. KMD fournit D3DDDI_DOORBELL_STATUS en tant que status, que le système d’exploitation écrit dans cette page status.
Dans les scénarios de perte ou d’arrêt du GPU, le système d’exploitation écrit D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT en tant que status.