structure DXGK_DEBUG_REPORT_INTERFACE (dispmprt.h)

La structure DXGK_DEBUG_REPORT_INTERFACE contient des pointeurs vers des fonctions dans l’interface Rapport de débogage, qui est implémentée par le pilote de port d’affichage.

Syntaxe

typedef struct _DXGK_DEBUG_REPORT_INTERFACE {
  USHORT                    Size;
  USHORT                    Version;
  PVOID                     Context;
  PINTERFACE_REFERENCE      InterfaceReference;
  PINTERFACE_DEREFERENCE    InterfaceDereference;
  DXGK_DEBUG_REPORT_HANDLE( )(HANDLE DeviceHandle,ULONG ulCode,ULONG_PTR ulpArg1,ULONG_PTR ulpArg2,ULONG_PTR ulpArg3,ULONG_PTR ulpArg4) *DbgReportCreate;
  BOOLEAN( )(DXGK_DEBUG_REPORT_HANDLE hReport,PVOID pvData,ULONG ulDataSize)                  *DbgReportSecondaryData;
  VOID( )(DXGK_DEBUG_REPORT_HANDLE hReport)                     *DbgReportComplete;
} DXGK_DEBUG_REPORT_INTERFACE, *PDXGK_DEBUG_REPORT_INTERFACE;

Membres

Size

Taille, en octets, de cette structure.

Version

Numéro de version de l’interface Rapport de débogage. Les constantes de numéro de version sont définies dans Dispmprt.h (par exemple, DXGK_DEBUG_REPORT_INTERFACE_VERSION_1).

Context

Pointeur vers un contexte fourni par le pilote de port d’affichage.

InterfaceReference

Pointeur vers une fonction de référence d’interface implémentée par le pilote de port d’affichage.

InterfaceDereference

Pointeur vers une fonction de déréférencement d’interface implémentée par le pilote de port d’affichage.

DbgReportCreate

Crée un rapport d’erreurs initial.

Si votre pilote miniport d’affichage détecte une défaillance et s’en rétablit, vous pouvez créer un rapport d’erreurs qui peut être utilisé ultérieurement pour le débogage. Tout d’abord, appelez DbgReportCreate pour créer un rapport initial. Ajoutez ensuite des données au rapport en effectuant un ou plusieurs appels à DbgReportSecondaryData. Une fois que vous avez terminé d’ajouter des données au rapport, appelez DbgReportComplete.

La syntaxe de DbgReportComplete est la suivante.

// IRQL: PASSIVE_LEVEL
DXGK_DEBUG_REPORT_HANDLE (*DbgReportCreate)(
  _In_ HANDLE    DeviceHandle,
  _In_ ULONG     ulCode,
  _In_ ULONG_PTR ulpArg1,
  _In_ ULONG_PTR ulpArg2,
  _In_ ULONG_PTR ulpArg3,
  _In_ ULONG_PTR ulpArg4
);

• DeviceHandle est un handle d’un bloc de contexte associé à une carte d’affichage. Le pilote miniport d’affichage a créé cette poignée dans sa fonction DxgkDdiAddDevice* . Ce paramètre peut être NULL.

• ulCode est un code pour le rapport d’erreurs. Les codes suivants sont pris en charge :

  • THREAD_STUCK_IN_DEVICE_DRIVER
  • VIDEO_DRIVER_DEBUG_REPORT_REQUEST
  • VIDEO_TDR_FATAL_ERROR
  • VIDEO_TDR_SUCCESS

• ulpArg1 est le premier argument à ajouter au rapport. Le développeur du pilote miniport d’affichage détermine la valeur et la signification de ulpArg1.

• ulpArg2 est le deuxième argument à ajouter au rapport. Le développeur du pilote de miniport d’affichage détermine la valeur et la signification de ulpArg2.

• ulpArg3 est le troisième argument à ajouter au rapport. Le développeur du pilote miniport d’affichage détermine la valeur et la signification de ulpArg3.

• ulpArg4 est réservé.

DbgReportSecondaryData

Ajoute des données à un rapport d’erreurs initial créé précédemment par DbgReportCreate.

Appelez DbgReportSecondaryData pour ajouter des données à un rapport initial créé par un appel précédent à DbgReportCreate. Vous pouvez appeler DbgReportSecondaryData plusieurs fois, mais à chaque appel, les données écrites dans le rapport remplacent les données écrites par l’appel précédent. Les étapes suivantes fournissent une bonne stratégie pour l’ajout incrémentiel de données au rapport.

1. Obtenez les données les plus sécurisées à collecter.
2. Appelez DbgReportSecondaryData pour écrire ces données dans le rapport.
3. Obtenez des données qui sont plus risquées à collecter.
4. Appelez DbgReportSecondaryData pour écrire les données sécurisées d’origine ainsi que les données à risque nouvellement collectées dans le rapport. Vous devez inclure à la fois les données sécurisées et les données à risque dans cet appel, car les données écrites par cet appel remplacent les données écrites par le premier appel à DbgReportSecondaryData.
5. Continuez à appeler DbgReportSecondaryData, en améliorant les données à chaque fois, jusqu’à ce que vous n’ayez plus de données à ajouter.
6. Une fois que vous avez terminé d’ajouter des données au rapport, fermez le rapport en appelant DbgReportComplete. Le rapport est stocké dans un fichier et envoyé à Microsoft lorsque l’ordinateur est redémarré.
7. Si l’ordinateur cesse de répondre avant d’appeler DbgReportComplete, les données ajoutées au rapport par le dernier appel réussi à DbgReportSecondaryData sont enregistrées, puis envoyées à Microsoft lorsque l’ordinateur est redémarré.

BOOLEAN (*DbgReportSecondaryData)(
  _Inout_ DXGK_DEBUG_REPORT_HANDLE hReport,
  _In_    PVOID                    pvData,
  _In_    ULONG                    ulDataSize
);

• hReport est un handle du rapport d’erreurs auquel les données seront ajoutées. Le pilote miniport d’affichage a précédemment obtenu ce handle en appelant DbgReportCreate.

• pvData est un pointeur vers une mémoire tampon qui contient les données à ajouter au rapport.

• ulDataSize est la taille, en octets, des données à ajouter au rapport. La valeur de ce paramètre doit être inférieure ou égale à DXGK_DEBUG_REPORT_MAX_SIZE.

DbgReportComplete

Ferme un rapport d’erreurs et libère toutes les ressources associées au rapport.

DbgReportCreate crée une entrée dans le journal des événements système et affiche une boîte de dialogue qui informe l’utilisateur de l’échec et offre la possibilité de charger un rapport d’erreurs sur Microsoft.

Le rapport d’erreurs est enregistré dans un fichier et planifié pour être envoyé à Microsoft lorsque l’ordinateur est redémarré. Le rapport d’erreurs contient un code d’erreur et quatre arguments. Le code d’erreur et les trois premiers arguments sont fournis par l’appelant de DbgReportCreate. Le quatrième argument du rapport est fourni par le système d’exploitation et indique le nombre de rapports générés depuis le démarrage de l’ordinateur. Par exemple, si la valeur du quatrième argument est 5, cela signifie que quatre rapports d’erreurs précédents ont été générés par le pilote miniport d’affichage depuis le dernier démarrage de l’ordinateur. Seul le cinquième rapport est enregistré, car chaque rapport remplace le précédent.

// IRQL: PASSIVE_LEVEL
VOID DbgReportComplete(
   IN OUT DXGK_DEBUG_REPORT_HANDLE hReport
);

• hReport est un handle du rapport d’erreurs qui doit être fermé. Le pilote miniport d’affichage a précédemment obtenu ce handle en appelant DbgReportCreate.

IRQL : PASSIVE_LEVEL

Remarques

Le pilote miniport d’affichage fournit les membres Size et Version de cette structure, puis appelle DxgkCbQueryServices*, qui remplit les membres restants de cette structure.

Configuration requise