Gestion des erreurs

Les fonctions Direct3D version 10 qu’un pilote d’affichage en mode utilisateur implémente ont généralement VOID pour un type de paramètre de retour. La principale exception à cette règle est la fonction CalcPrivateObjTypeSize-type (par exemple, la fonction CalcPrivateResourceSize ). Ce type de fonction retourne un type de paramètre SIZE_T qui indique la taille de la région de mémoire dont le pilote a besoin pour créer le type d’objet particulier via la fonction CreateObjType-type (par exemple , CreateResource(D3D10)).

Le retour de VOID empêche le pilote d’affichage en mode utilisateur de notifier le runtime Direct3D des erreurs de manière conventionnelle (c’est-à-dire par le biais d’un paramètre de retour de fonction du pilote d’affichage en mode utilisateur). Au lieu de cela, le pilote d’affichage en mode utilisateur doit utiliser la fonction de rappel pfnSetErrorCb du runtime Direct3D pour transmettre ces informations au runtime. Le runtime fournit un pointeur vers son pfnSetErrorCb dans la structure D3D10DDI_CORELAYER_DEVICECALLBACKS vers laquelle pointe le membre pUMCallbacks de la structure D3D10DDIARG_CREATEDEVICE dans un appel à la fonction CreateDevice(D3D10).

La page de référence de chaque fonction de pilote d’affichage en mode utilisateur spécifie les erreurs que la fonction peut transmettre par un appel à pfnSetErrorCb. Cela signifie que si le pilote d’affichage en mode utilisateur appelle pfnSetErrorCb avec un code d’erreur qui n’est pas autorisé pour la fonction de pilote d’affichage en mode utilisateur actuelle, le runtime détermine que la condition d’erreur est critique et agit de manière appropriée. Étant donné que le runtime agit de manière appropriée pendant pfnSetErrorCb, vous ne devez pas vous attendre à pouvoir inverser les effets de l’appel de pfnSetErrorCb( E_FAIL ) en appelant quelque chose comme pfnSetErrorCb( S_OK ). En fait, le runtime détermine que S_OK est tout aussi non valide ou critique que E_FAIL. Le concept de code de retour S_OK équivaut à la fonction de pilote d’affichage en mode utilisateur qui n’appelle pas du tout pfnSetErrorCb .

Si le runtime Direct3D détermine qu’une condition d’erreur est critique, il prend d’abord des mesures en journalisant l’erreur avec Dr. Watson, le débogueur post-mortem (juste-à-temps) par défaut. Le runtime perd alors l’appareil volontairement, émulant ainsi le scénario de réception du code d’erreur D3DDDIERR_DEVICEREMOVED. En obligeant le pilote à appeler la fonction de rappel pfnSetErrorCb , les chances sont beaucoup plus grandes que chaque erreur sortant du pilote aura une pile d’appels utile associée. Le fait d’avoir une pile d’appels associée à une erreur permet un diagnostic rapide et des journaux Dr. Watson précis.

Vous devez utiliser pfnSetErrorCb dans votre code de pilote quand un problème se produit dans votre pilote, même si le renvoi d’un code d’erreur que le runtime n’autorise pas pour la fonction de pilote particulière est déterminé par le runtime en tant que bogue ou problème de pilote. Il serait encore pire pour le pilote d’affichage en mode utilisateur d’absorber les erreurs critiques et de continuer. Le pilote d’affichage en mode utilisateur doit appeler pfnSetErrorCb le plus près possible du point de détection des erreurs afin de fournir une pile d’appels utile pour le débogage post-mortem.

Le tableau suivant répertorie les catégories d’erreurs que le runtime Direct3D autorise à partir de fonctions de pilote particulières.

Catégorie d’erreur	Signification
NoErrors	Le pilote ne doit rencontrer aucune erreur, y compris D3DDDIERR_DEVICEREMOVED. Le runtime détermine que tout appel à pfnSetErrorCb est critique.
AllowDeviceRemoved	Le pilote ne doit rencontrer aucune erreur, à l’exception de D3DDDIERR_DEVICEREMOVED. Le runtime détermine que tout appel à pfnSetErrorCb qui ne passe pas D3DDDIERR_DEVICEREMOVED est critique. Le pilote n’est pas tenu de retourner DEVICEREMOVED si l’appareil a été supprimé. Toutefois, le runtime permet au pilote de retourner DEVICEREMOVED, au cas où DEVICEREMOVED interfère avec la fonction du pilote, ce qui ne devrait généralement pas se produire.
AllowOutOfMemory	Le pilote peut éventuellement manquer de mémoire. Par conséquent, le pilote peut passer E_OUTOFMEMORY et D3DDDIERR_DEVICEREMOVED via pfnSetErrorCb. Le runtime détermine que tous les autres codes d’erreur sont critiques.
AllowCounterCreationErrors	Le pilote peut éventuellement manquer de mémoire. Le pilote peut également ne pas pouvoir créer de compteurs en raison de la nature exclusive des compteurs. Par conséquent, le pilote peut passer E_OUTOFMEMORY, DXGI_DDI_ERR_NONEXCLUSIVE et D3DDDIERR_DEVICEREMOVED via pfnSetErrorCb. Le runtime détermine que tous les autres codes d’erreur sont critiques.
AllowMapErrors	Le pilote doit case activée pour la contention de ressources. Par conséquent, le pilote peut passer DXGI_DDI_ERR_WASSTILLDRAWING via pfnSetErrorCb si l’indicateur D3D10_DDI_MAP_FLAG_DONOTWAIT a été passé dans la fonction ResourceMap du pilote. Le pilote peut également passer D3DDDIERR_DEVICEREMOVED via pfnSetErrorCb. Le runtime détermine que tous les autres codes d’erreur sont critiques.
AllowGetDataErrors	Le pilote doit case activée pour l’exécution de la requête. Par conséquent, le pilote peut passer DXGI_DDI_ERR_WASSTILLDRAWING via pfnSetErrorCb si la requête n’est pas encore terminée. Le pilote peut également passer D3DDDIERR_DEVICEREMOVED via pfnSetErrorCb. Le runtime détermine que tous les autres codes d’erreur sont critiques.
AllowWKCheckCounterErrors	La fonction CheckCounter du pilote doit indiquer si elle prend en charge des compteurs définis par le runtime. Par conséquent, le pilote peut passer DXGI_DDI_ERR_UNSUPPORTED via pfnSetErrorCb. Le runtime détermine que tous les autres codes d’erreur sont critiques. Le pilote ne peut pas retourner D3DDDIERR_DEVICEREMOVED pour une fonction de type case activée.
AllowDDCheckCounterErrors	Le pilote doit valider l’identificateur de compteur dépendant du périphérique (ID de compteur) pour s’assurer que l’ID du compteur se trouve dans la plage et qu’il y a suffisamment d’espace pour copier chaque chaîne de compteur dans la mémoire tampon fournie. Le pilote peut passer E_INVALIDARG via pfnSetErrorCb, lorsque les paramètres sont incorrects de cette façon. Le pilote ne peut pas retourner D3DDDIERR_DEVICEREMOVED pour une fonction de type case activée.