Utilisation de l’enregistreur de trace inflérateur (IFR) dans les pilotes KMDF et UMDF 2

Article
07/08/2024

À compter de Windows 10, vous pouvez générer votre pilote KMDF ou UMDF afin qu’il obtienne des informations de débogage de pilotes supplémentaires via le prétraitement de trace logicielle Windows. Cette fonctionnalité, appelée Inflight Trace Recorder (IFR), est disponible à partir de KMDF version 1.15 et UMDF version 2.15.

Inflight Trace Recorder est une extension du suivi logiciel WPP. Contrairement au suivi WPP, l’enregistreur de trace inflight continue de fonctionner sans consommateur de trace attaché. L’infrastructure écrit des messages dans une mémoire tampon circulaire, et votre pilote peut également ajouter ses propres messages. Chaque pilote a son propre journal, de sorte que plusieurs appareils associés à un pilote partagent un seul journal.

Si vous activez l’IFR dans votre binaire de pilote, l’IFR est présente et en cours d’exécution pendant la durée de vie de votre pilote. Vous n’avez pas besoin de démarrer une session de collecte de traces explicite.

Les journaux d’activité sont stockés en mémoire non paginable, de sorte qu’ils sont récupérables après un incident système. En outre, les journaux de l’enregistreur de trace Inflight sont inclus dans des fichiers minidump, sauf lorsque le pilote responsable est indéterminé ou si le blocage était un délai d’expiration de l’hôte.

Comment activer l’enregistreur de trace Inflight et envoyer des messages à partir de votre pilote

Dans Microsoft Visual Studio, procédez comme suit :
- Ouvrez les pages de propriétés de votre projet de pilote. Cliquez avec le bouton droit sur le projet de pilote dans Explorateur de solutions, puis sélectionnez Propriétés. Dans les pages de propriétés du pilote, sélectionnez Propriétés de configuration, puis Suivi Wpp. Dans le menu Général , définissez Le suivi WPP sur Oui.
- Accédez à Propriétés-Wpp> Tracing-Function> et Macro Options , puis choisissez Activer l’enregistreur WPP.
- Dans le même menu, définissez Scan Configuration Data sur le fichier contenant vos informations de trace, par exemple Trace.h.
Dans chaque fichier source qui appelle une macro WPP, ajoutez une directive #include qui identifie un fichier d’en-tête de message de trace (TMH). Le nom de fichier doit avoir un format de <driver-source-file-name.tmh>.

Par exemple, si votre pilote se compose de deux fichiers sources, appelés MyDriver1.c et MyDriver2.c, MyDriver1.c doit contenir :

#include « MyDriver1.tmh »

et MyDriver2.c doivent contenir :

#include « MyDriver2.tmh »

Lorsque vous générez votre pilote dans Visual Studio, le préprocesseur WPP génère le .fichiers tmh .

Définissez une macro WPP_CONTROL_GUIDS dans un fichier d’en-tête. Cette macro définit un GUID et des indicateurs de trace pour les messages de suivi de votre pilote.

L’exemple de pilote Osrusbfx2 définit un GUID de contrôle unique et sept indicateurs de trace dans le fichier d’en-tête Trace.h, comme illustré dans l’exemple suivant :

#define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \
  (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
  WPP_DEFINE_BIT(DBG_INIT)          /* bit  0 = 0x00000001 */ \
  WPP_DEFINE_BIT(DBG_PNP)           /* bit  1 = 0x00000002 */ \
  WPP_DEFINE_BIT(DBG_POWER)         /* bit  2 = 0x00000004 */ \
  WPP_DEFINE_BIT(DBG_WMI)           /* bit  3 = 0x00000008 */ \
  WPP_DEFINE_BIT(DBG_CREATE_CLOSE)  /* bit  4 = 0x00000010 */ \
  WPP_DEFINE_BIT(DBG_IOCTL)         /* bit  5 = 0x00000020 */ \
  WPP_DEFINE_BIT(DBG_WRITE)         /* bit  6 = 0x00000040 */ \
  WPP_DEFINE_BIT(DBG_READ)          /* bit  7 = 0x00000080 */ \
)

Dans cet exemple :

OsrUsbFxTraceGuid est le nom convivial du GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
Les indicateurs de trace sont utilisés pour différencier les messages de trace générés en tant que pilote gère différents types de requêtes d’E/S.

Votre pilote (KMDF et UMDF 2) doit appeler WPP_INIT_TRACING pour les pilotes en mode noyau avec l’objet de pilote et un chemin de Registre, généralement à partir de DriverEntry :
```
WPP_INIT_TRACING( DriverObject, RegistryPath );
```
Pour désactiver le suivi, les pilotes KMDF et UMDF 2 appellent WPP_CLEANUP pour les pilotes en mode noyau à partir d’EvtCleanupCallback ou EvtDriverUnload :
```
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
```
La macro WPP_CLEANUP prend un paramètre de type PDRIVER_OBJECT. Par conséquent, si driverEntry de votre pilote échoue, vous pouvez ignorer l’appel de WdfDriverWdmGetDriverObject et appeler à la place WPP_CLEANUP avec un pointeur vers l’objet de pilote WDM.

Étant donné que les pilotes UMDF utilisent les signatures en mode noyau de ces macros pour initialiser et nettoyer le suivi, les appels sont identiques pour KMDF et UMDF.
Utilisez la macro DoTraceMessage ou une version personnalisée de la macro, dans votre pilote pour créer des messages de trace.

L’exemple suivant montre comment le pilote Osrusbfx2 utilise sa fonction TraceEvents dans une partie du code consacrée à la gestion des demandes de lecture :
```
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
    TraceEvents(TRACE_LEVEL_ERROR,
                DBG_READ,
                "Transfer exceeds %d\n",
                TEST_BOARD_TRANSFER_BUFFER_SIZE);

    status = STATUS_INVALID_PARAMETER;
}
```
L’appel à TraceEvents génère un message de trace si le contrôleur de trace active le niveau TRACE_LEVEL_ERROR et l’indicateur de trace DBG_READ. Le message inclut la valeur de la constante définie par le pilote TEST_BOARD_TRANSFER_BUFFER_SIZE.
Pour modifier la taille de la mémoire tampon circulaire utilisée par le journal des pilotes, modifiez la valeur de Registre LogPages à l’emplacement de Registre suivant :

Pour UMDF :

SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf

Pour KMDF :

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\<YourDriver>\Parameters\Wdf

Il s’agit d’une valeur de type REG_DWORD qui contient la taille de la mémoire tampon du journal allouée, dans les pages. Les valeurs valides sont comprises entre 0x1 et 0x10.

Pour un pilote KMDF

Chargez les commandes RCDRKD en tapant .load rcdrkd.dll dans le débogueur.
Utilisez l’extension !wdfkd.wdfldr pour afficher des informations sur le pilote actuellement lié dynamiquement aux frameworks WDF (Windows Driver Frameworks).
Utilisez !rcdrkd.rcdrlogdump et !rcdrkd.rcdrcrashdump pour afficher les messages que le pilote fournit.
Utilisez !wdfkd.wdflogdump ou !wdfkd.wdfcrashdump pour voir les messages que le framework fournit.

Débogage en direct d’un pilote UMDF

Utilisez l’extension !wdfkd.wdfldr pour afficher des informations sur les pilotes actuellement liés dynamiquement à WDF. Recherchez votre pilote en mode utilisateur. Entrez le processus hôte associé.
Tapez !wdfkd.wdflogdump <YourDriverName.dll<>Indicateur> , où< l’indicateur> est :
- 0x1 – Journaux d’activité du framework et du pilote fusionnés
- 0x2 – Journaux des pilotes
- 0x3 – Journaux d’activité framework
S’il n’existe aucun journal de pilote pour le pilote spécifié, l’extension affiche uniquement le journal de l’infrastructure.

Affichage des journaux de l’enregistreur de trace inflécheur après un incident de pilote UMDF

Dans WinDbg, sélectionnez File-Open> Crash Dump et spécifiez le fichier minidump que vous souhaitez déboguer.
Tapez !wdfkd.wdfcrashdump <YourDriverName.dll><ID de processus de l’option> hôte><du pilote, où <Option> est :
- 0x1 – Journaux d’activité du framework et du pilote fusionnés
- 0x2 – Journaux des pilotes
- 0x3 – Journaux d’activité framework
Si vous ne spécifiez pas de pilote, !wdfcrashdump affiche des informations pour tous les pilotes. Si vous ne spécifiez pas de processus hôte et qu’il n’y en a qu’un seul, l’extension utilise le processus hôte unique. Si vous ne spécifiez pas de processus hôte et qu’il en existe plusieurs, l’extension répertorie les processus hôtes actifs.

Si les informations de journal stockées dans le minidump ne correspondent pas au nom entré, le minidump ne contient pas les journaux du pilote.

Si vous n’avez pas de débogueur connecté, vous pouvez toujours accéder aux journaux du pilote et de l’infrastructure. Pour en savoir plus, consultez Vidéo : accès aux journaux IFR du pilote sans débogueur.

Pour plus d’informations sur l’ajout de messages de suivi à votre pilote, consultez Ajout de macros WPP à un pilote.

Comment activer le débogage d’un pilote UMDF

Extensions RCDRKD

Utilisation de l’enregistreur d’événements de l’infrastructure

Utilisation du suivi logiciel WPP dans les pilotes UMDF

Partager via

Utilisation de l’enregistreur de trace inflérateur (IFR) dans les pilotes KMDF et UMDF 2

Commentaires

Ressources supplémentaires

Partager via

Utilisation de l’enregistreur de trace inflérateur (IFR) dans les pilotes KMDF et UMDF 2

Articles connexes

Commentaires

Ressources supplémentaires