DXGKDDI_RENDER fonction de rappel (d3dkmddi.h)

Article
02/06/2025

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

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 de commande et DMA. La fonction DxgkDdiCreateContext du pilote miniport d’affichage a précédemment renvoyé ce handle dans le membre hContext de la structure DXGKARG_CREATECONTEXT vers laquelle pointe le paramètre pCreateContext de DxgkDdiCreateCon text.

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 par un handle sur l’appareil. La fonction du pilote miniport d’affichage DxgkDdiCreateDevice a précédemment retourné le handle d’appareil dans le membre de la structure DXGKARG_CREATEDEVICE vers laquelle pointe le paramètre pCreateDevice de DxgkDdiCreateDev ice.

[in/out] pRender

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

Valeur de retour

DxgkDdiRender retourne l’une des valeurs suivantes :

Retourner le code	Description
STATUS_SUCCESS	La mémoire tampon de commande entière a été traduite.
STATUS_NO_MEMORY	DxgkDdiRender n’a pas pu allouer de mémoire nécessaire pour qu’elle se termine.
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 (autrement dit, 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 indiquant que le matériel graphique n’a pas pu prendre en charge.
STATUS_INVALID_PARAMETER	DxgkDdiRender a détecté des paramètres d’instruction que le matériel graphique n’a pas pu prendre en charge ; toutefois, le matériel graphique peut prendre en charge les instructions elles-mêmes. Le pilote n’est pas requis 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 sous-exécutées ou dépassées. Autrement dit, le pilote a reçu moins d’instructions ou de données que prévu. Le pilote n’est pas requis pour retourner ce code d’erreur. Au lieu de cela, il peut retourner STATUS_ILLEGAL_INSTRUCTION lorsqu’il détecte les données ou les instructions sous-exécution ou dépassement.
STATUS_INVALID_HANDLE	DxgkDdiRender a détecté un handle non valide dans la mémoire tampon de commande.
STATUS_GRAPHICS_DRIVER_MISMATCH	Le pilote miniport d’affichage n’est pas compatible avec le pilote d’affichage en mode utilisateur qui a lancé l’appel à DxgkDdiRender (autrement dit, soumis 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 DxgkDdiR ender du pilote de miniport d’affichage pour générer une mémoire tampon DMA à partir de la mémoire tampon de commande passée par le pilote d’affichage en mode utilisateur. Lorsque le pilote miniport d’affichage se traduit de la mémoire tampon de commande à la mémoire tampon DMA, le pilote doit également valider la mémoire tampon de commande pour s’assurer que la mémoire tampon de commande ne contient pas de commandes ou de commandes privilégiées qui peuvent être utilisées pour accéder à la mémoire qui n’appartient pas au processus. Outre la mémoire tampon DMA de sortie, le pilote miniport d’affichage doit également générer une liste d’emplacements de correctifs de sortie. Le gestionnaire de mémoire vidéo utilise cette liste pour fractionner et corriger correctement les mémoires tampons DMA.

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

Voici un exemple de la façon dont les pilotes miniport d’affichage doivent accéder à ces mémoires tampons à l’aide de __try et de __except logique. 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;
  }

Note

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

Le pilote miniport d’affichage n’est pas nécessaire pour 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, car le pilote d’affichage en mode utilisateur n’a pas fourni de liste d’emplacement corrective d’entrée, le pilote de 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’allocation que fournit le pilote d’affichage en mode utilisateur 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 D3DKMT_HANDLE typé fourni par le pilote d’affichage en mode utilisateur dans un handle spécifique à l’appareil, que la fonction d’affichage du pilote miniport DxgkDdiOpenAllocation fonction retourne. L’index de chaque allocation et l’état d’écriture de l’allocation (autrement dit, le paramètre de l’indicateur WriteOperation bit-field) reste constant pendant la conversion.

En plus du handle spécifique à l’appareil, le sous-système du noyau graphique DirectX fournit le pilote miniport d’affichage avec 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 SegmentId membre du Nième élément du pAllocationList membre de DXGKARG_RENDER sur zéro. Si le SegmentId membre du Nième élément de la liste d’allocation n’est pas défini sur zéro, le pilote de 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 pré-patcher lorsqu’il 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.

Note

Même si la fonction DxgkDdiRender du pilote fonction pré-patche la mémoire tampon DMA, le pilote doit toujours insérer toutes les références aux allocations dans la liste d’emplacements des correctifs de sortie spécifiée par le pPatchLocationListOut membre de DXGKARG_RENDER. 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 référence un handle NULL, puis utiliser un élément d’emplacement de correctif 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 miniport d’affichage traduit une mémoire tampon de commande en mémoire tampon DMA, le pilote d’affichage miniport 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 Using the Guaranteed Contract DMA Buffer Model), le pilote d’affichage en mode utilisateur doit garantir suffisamment de ressources pour la commande de traduction. Si suffisamment de ressources n’existent pas pour la traduction, le pilote miniport d’affichage doit rejeter la mémoire tampon DMA.
Le pilote d’affichage en mode utilisateur doit toujours fractionner des commandes qui peuvent se traduire par plus que la taille d’une seule mémoire tampon DMA, car la fonction du pilote de miniport d’affichage DxgkDdiRender 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 à partir de Windows 7 pour les adaptateurs d’affichage qui prennent en charge accélération matérielle GDI.