DXGKDDI_RENDER fonction de rappel (d3dkmddi.h)

Article
08/07/2023

La fonction DxgkDdiRender génère une mémoire tampon d’accès direct à la mémoire (DMA) à partir de la mémoire tampon de commandes transmise par le pilote d’affichage en mode utilisateur.

Syntaxe

DXGKDDI_RENDER DxgkddiRender;

NTSTATUS DxgkddiRender(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRender
)
{...}

Paramètres

[in] hContext

Handle vers le contexte de l’appareil pour les mémoires tampons DMA et de commande. La fonction DxgkDdiCreateContext du pilote miniport d’affichage a précédemment retourné ce handle dans le membre hContext de la structure DXGKARG_CREATECONTEXT vers laquelle pointe le paramètre pCreateContext de DxgkDdiCreateContext .

Si le pilote ne prend pas en charge la création de contexte, le sous-système du noyau graphique Microsoft DirectX remplace le handle dans le contexte par un handle pour l’appareil. La fonction DxgkDdiCreateDevice du pilote miniport d’affichage a précédemment retourné le handle de périphérique dans le membre hDevice de la structure DXGKARG_CREATEDEVICE vers laquelle pointe le paramètre pCreateDevice de DxgkDdiCreateDevice .

[in/out] pRender

Pointeur vers une structure de DXGKARG_RENDER qui contient des informations sur les mémoires tampons DMA et de commande.

Valeur retournée

DxgkDdiRender retourne l’une des valeurs suivantes :

Code de retour	Description
STATUS_SUCCESS	La mémoire tampon de commande entière a été traduite.
STATUS_NO_MEMORY	DxgkDdiRender n’a pas pu allouer la mémoire nécessaire à sa fin.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	La mémoire tampon DMA actuelle est épuisée.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender a détecté des instructions non privilégiées (c’est-à-dire des instructions qui accèdent à la mémoire au-delà du privilège du processus actuel de l’unité de traitement centrale [UC]).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender a détecté des instructions que le matériel graphique ne pouvait pas prendre en charge.
STATUS_INVALID_PARAMETER	DxgkDdiRender a détecté des paramètres d’instruction que le matériel graphique ne pouvait pas prendre en charge ; toutefois, le matériel graphique peut prendre en charge les instructions proprement dites. Le pilote n’est pas nécessaire pour retourner ce code d’erreur. Au lieu de cela, il peut retourner STATUS_ILLEGAL_INSTRUCTION lorsqu’il détecte des paramètres d’instruction non pris en charge.
STATUS_INVALID_USER_BUFFER	DxgkDdiRender a détecté des données ou des instructions en cours d’exécution ou de dépassement. Autrement dit, le pilote a reçu moins ou plus d’instructions ou de données que prévu. Le pilote n’est pas nécessaire pour retourner ce code d’erreur. Au lieu de cela, il peut retourner STATUS_ILLEGAL_INSTRUCTION lorsqu’il détecte des données ou des instructions en cours d’exécution ou de dépassement.
STATUS_INVALID_HANDLE	DxgkDdiRender a détecté un handle non valide dans la mémoire tampon de commandes.
STATUS_GRAPHICS_DRIVER_MISMATCH	Le pilote de miniport d’affichage n’est pas compatible avec le pilote d’affichage en mode utilisateur qui a lancé l’appel à DxgkDdiRender (autrement dit, a envoyé la mémoire tampon de commande).
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Le pilote de miniport d’affichage a détecté une erreur dans le flux DMA. Le périphérique de contexte graphique est placé dans un état perdu si le pilote retourne ce code d’erreur.

Remarques

Le sous-système du noyau graphique DirectX appelle la fonction DxgkDdiRender du pilote de miniport d’affichage pour générer une mémoire tampon DMA à partir de la mémoire tampon de commandes passée par le pilote d’affichage en mode utilisateur. Lorsque le pilote de miniport d’affichage se traduit de la mémoire tampon de commandes en mémoire tampon DMA, le pilote doit également valider la mémoire tampon de commandes pour s’assurer que la mémoire tampon de commandes ne contient pas de commandes privilégiées ou de commandes pouvant être utilisées pour accéder à la mémoire qui n’appartient pas au processus. En plus de la mémoire tampon DMA de sortie, le pilote de miniport d’affichage doit également générer une liste d’emplacements des correctifs de sortie. Le gestionnaire de mémoire vidéo utilise cette liste pour fractionner et corriger les mémoires tampons DMA de manière appropriée.

La mémoire tampon de commande pCommand et la liste d’emplacement de correctif d’entrée pPatchLocationListIn générées par le pilote d’affichage en mode utilisateur sont allouées à partir de l’espace d’adressage du mode utilisateur et sont passées au pilote miniport d’affichage sans être affecté. Le pilote miniport d’affichage doit utiliser __try/__except du code sur tout accès à la mémoire tampon et à la liste, et doit valider le contenu de la mémoire tampon et de la liste avant de copier le contenu dans les mémoires tampons de noyau respectives (autrement dit, avant de copier le contenu du membre pCommand vers le membre pDmaBuffer et le contenu du membre pPatchLocationListIn vers le membre pPatchLocationListOut , qui sont tous membres de la structure DXGKARG_RENDER vers laquelle pointe le paramètre pRender ).

Voici un exemple de la façon dont les pilotes de miniport d’affichage doivent accéder à ces mémoires tampons à l’aide __try de la logique et __except . AllocationListIn pointe vers la mémoire tampon en mode utilisateur.

__try
  {
    for (Index = 0; Index < AllocationListInSize; AllocationTable++, 
           AllocationListIn++, AllocationListOut++, Index++) 
    {
      D3DKMT_HANDLE AllocationHandle = AllocationListIn->hAllocation;
      . . .
    }
  }
__except(EXCEPTION_EXECUTE_HANDLER)
  {
    Status = STATUS_INVALID_PARAMETER;
    SAMPLE_LOG_ERROR(
  "Exception occurred accessing user-mode allocation list. Returning Status=0x%I64x",
      Status);
    goto cleanup;
  }

Notes

L’accès aux mémoires tampons du noyau ne nécessite pas de protection contre le try/except code.

Le pilote de miniport d’affichage n’est pas obligé d’utiliser les informations fournies par le pilote d’affichage en mode utilisateur si la recréation des informations est plus optimale. Par exemple, si pPatchLocationListIn est vide parce que le pilote d’affichage en mode utilisateur n’a pas fourni de liste d’emplacement de correctif d’entrée, le pilote miniport d’affichage peut générer le contenu de pPatchLocationListOut en fonction du contenu de la mémoire tampon de commandes à la place.

La liste d’allocations que le pilote d’affichage en mode utilisateur fournit est validée, copiée et convertie en liste d’allocation en mode noyau pendant la transition du noyau. Le sous-système du noyau graphique DirectX convertit chaque élément D3DDDI_ALLOCATIONLIST en élément DXGK_ALLOCATIONLIST en convertissant le handle de type D3DKMT_HANDLE fourni par le pilote d’affichage en mode utilisateur en handle spécifique au périphérique, que la fonction DxgkDdiOpenAllocation du pilote d’affichage du miniport d’affichage retourne. L’index de chaque allocation et la status d’écriture de l’allocation (autrement dit, le paramètre de l’indicateur de champ de bits WriteOperation) restent constants pendant la conversion.

En plus du handle spécifique au périphérique, le sous-système du noyau graphique DirectX fournit au pilote miniport d’affichage la dernière adresse de segment GPU connue pour chaque allocation. Si l’index d’allocation N est actuellement paginé, le sous-système du noyau graphique DirectX définit le membre SegmentId du Nième élément du membre pAllocationList de DXGKARG_RENDER sur zéro. Si le membre SegmentId du Nième élément de la liste d’allocation n’est pas défini sur zéro, le pilote miniport d’affichage doit pré-corriger la mémoire tampon DMA générée avec les informations d’adresse de segment fournies. Le pilote doit effectuer un correctif préalable lorsque cela est demandé, car le sous-système du noyau graphique DirectX peut ne pas appeler la fonction DxgkDdiPatch sur une mémoire tampon DMA que le pilote doit avoir correctement pré-corrigée.

Notes

Même si la fonction DxgkDdiRender du pilote pré-corrige la mémoire tampon DMA, le pilote doit toujours insérer toutes les références aux allocations dans la liste des emplacements de correctifs de sortie que le membre pPatchLocationListOut de DXGKARG_RENDER spécifie. Cette liste doit contenir toutes les références, car les adresses des allocations peuvent changer avant que la mémoire tampon DMA soit envoyée au GPU ; Par conséquent, le sous-système du noyau graphique DirectX appelle la fonction DxgkDdiPatch pour remodèler la mémoire tampon DMA.

Pour dissocier une allocation, le pilote de miniport d’affichage peut spécifier un élément dans la liste d’allocation qui fait référence à un handle NULL , puis peut utiliser un élément patch-location qui fait référence à cette allocation NULL . En règle générale, le pilote doit utiliser le premier élément de la liste d’allocation (élément 0) comme élément NULL .

Lorsque le pilote de miniport d’affichage traduit une mémoire tampon de commandes en mémoire tampon DMA, le pilote de miniport d’affichage et le pilote d’affichage en mode utilisateur doivent effectuer les actions suivantes pour les situations suivantes :

En mode DMA de contrat garanti (pour plus d’informations, consultez Utilisation du modèle de mémoire tampon DMA de contrat garanti), le pilote d’affichage en mode utilisateur doit garantir suffisamment de ressources pour la commande de traduction. S’il n’existe pas suffisamment de ressources pour la traduction, le pilote de miniport d’affichage doit rejeter la mémoire tampon DMA.
Le pilote d’affichage en mode utilisateur doit toujours fractionner les commandes qui peuvent se traduire par une taille supérieure à la taille d’une mémoire tampon DMA unique, car la fonction DxgkDdiRender du pilote miniport d’affichage ne peut pas gérer une seule commande supérieure à la taille de la mémoire tampon DMA et qui ne peut pas être fractionnée.

DxgkDdiRender doit être rendu paginable.

La prise en charge de la fonction DxgkDdiRenderKm a été ajoutée à compter de Windows 7 pour les cartes graphiques qui prennent en charge l’accélération matérielle GDI.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows Vista
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	d3dkmddi.h
IRQL	PASSIVE_LEVEL