structure VIDEO_PORT_DEBUG_REPORT_INTERFACE (video.h)

  • Article

La structure VIDEO_PORT_DEBUG_REPORT_INTERFACE contient des pointeurs vers les fonctions Rapport de débogage, qui sont implémentées par le pilote de port vidéo.

Syntaxe

typedef struct _VIDEO_PORT_DEBUG_REPORT_INTERFACE
{
    IN USHORT                  Size;
    IN USHORT                  Version;
    OUT PVOID                  Context;
    OUT PINTERFACE_REFERENCE   InterfaceReference;
    OUT PINTERFACE_DEREFERENCE InterfaceDereference;

    OUT
    PVIDEO_DEBUG_REPORT
    (*DbgReportCreate)(
        IN PVOID HwDeviceExtension,
        IN ULONG ulCode,
        IN ULONG_PTR ulpArg1,
        IN ULONG_PTR ulpArg2,
        IN ULONG_PTR ulpArg3,
        IN ULONG_PTR ulpArg4
        );

    OUT
    BOOLEAN
    (*DbgReportSecondaryData)(
        IN OUT PVIDEO_DEBUG_REPORT pReport,
        IN PVOID pvData,
        IN ULONG ulDataSize
        );

    OUT
    VOID
    (*DbgReportComplete)(
        IN OUT PVIDEO_DEBUG_REPORT pReport
        );
} VIDEO_PORT_DEBUG_REPORT_INTERFACE, *PVIDEO_PORT_DEBUG_REPORT_INTERFACE;

Membres

Size

Spécifie la taille, en octets, de cette structure.

Version

Spécifie la version de l’interface retournée par le pilote de port vidéo. Actuellement, la seule version prise en charge est VIDEO_PORT_DEBUG_REPORT_INTERFACE_VERSION_1.

Context

Pointeur vers un contexte fourni par le pilote de port vidéo.

InterfaceReference

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

InterfaceDereference

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

OUT (IN PVOID HwDeviceExtension,IN ULONG ulCode,IN ULONG_PTR ulpArg1,IN ULONG_PTR ulpArg2,IN ULONG_PTR ulpArg3,IN ULONG_PTR ulpArg4) PVIDEO_DEBUG_REPORT( *DbgReportCreate unnamedParam1)

OUT (IN OUT PVIDEO_DEBUG_REPORT pReport,IN PVOID pvData,IN ULONG ulDataSize) BOOLEAN( *DbgReportSecondaryData unnamedParam1)

OUT (IN OUT PVIDEO_DEBUG_REPORT pReport) VOID( *DbgReportComplete unnamedParam1)

Remarques

Le pilote de miniport vidéo fournit les membres Size et Version de cette structure, puis appelle VideoPortQueryServices, qui initialise ses membres restants.

Si votre pilote de miniport vidéo 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 en appelant les membres de la fonction de rappel de VIDEO_PORT_DEBUG_REPORT_INTERFACE comme suit :

  1. Tout d’abord, appelez DbgReportCreate pour créer un rapport initial.
  2. Ajoutez ensuite des données au rapport en effectuant un ou plusieurs appels à DbgReportSecondaryData.
  3. Une fois que vous avez terminé d’ajouter des données au rapport, appelez DbgReportComplete.

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 de ulpArg4 est 5, cela signifie que quatre rapports d’erreurs précédents ont été générés par le pilote de 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.

La structure VIDEO_DEBUG_REPORT retournée par DbgReportCreate et transmise par la suite à DbgReportSecondaryData et DbgReportComplete est opaque. N’essayez pas d’accéder directement à ses membres.

Les sections suivantes décrivent ces fonctions de rappel en détail. Ces rappels doivent être appelés à l’adresse IRQL = PASSIVE_LEVEL.

DbgReportCreate

DbgReportCreate crée un rapport d’erreurs initial. Il 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. DbgReportCreate retourne un pointeur vers une structure de VIDEO_DEBUG_REPORT opaque qui représente un handle vers le rapport de débogage nouvellement créé.

DbgReportCréer des paramètres

  • HwDeviceHandle [in] 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 [in] Code du rapport d’erreurs. Les codes suivants sont pris en charge : THREAD_STUCK_IN_DEVICE_DRIVER VIDEO_DRIVER_DEBUG_REPORT_REQUEST, VIDEO_TDR_FATAL_ERROR et VIDEO_TDR_SUCCESS.
  • ulpArg1 [in] Premier argument à ajouter au rapport. Le développeur du pilote miniport d’affichage détermine la valeur et la signification de ulpArg1.
  • ulpArg2 [in] 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 [in] Troisième argument à ajouter au rapport. Le développeur du pilote miniport d’affichage détermine la valeur et la signification de ulpArg3.
  • ulpArg4 [in] Réservé à l’utilisation du système.

DbgReportSecondaryData

La fonction DbgReportSecondaryData ajoute des données à un rapport d’erreurs initial créé précédemment par DbgReportCreate. Si DbgReportSecondaryData réussit, elle retourne TRUE. Sinon, il retourne FALSE.

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.

Une fois que vous avez terminé d’ajouter des données au rapport, fermez le rapport en appelant DbgReportComplete. 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é.

Paramètres DbgReportSecondaryData

  • hReport [in, out] 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 [in] Pointeur vers une mémoire tampon qui contient les données à ajouter au rapport.
  • ulDataSize [in] 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

La fonction DbgReportComplete ferme un rapport d’erreurs et libère toutes les ressources associées au rapport.

DbgReportComplete 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 de la possibilité de charger un rapport d’erreurs sur Microsoft.

Paramètres DbgReportComplete

  • hReport Pointeur vers une structure VIDEO_DEBUG_REPORT qui contient un handle vers le rapport d’erreurs à fermer. Le pilote miniport d’affichage a précédemment obtenu ce handle en appelant DbgReportCreate.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP SP2
Serveur minimal pris en charge Windows Server 2003 SP1
En-tête video.h (inclure Video.h)

Voir aussi

INTERFACE

VideoPortQueryServices