Enregistreur de traces en clair (IFR) pour la journalisation des traces

Article
06/15/2023

Inflight Trace Recorder (IFR) est une fonctionnalité de suivi qui permet à un fournisseur de traces, tel qu’un pilote en mode noyau ou un pilote UMDF, de créer un ensemble de mémoires tampons circulaires en mémoire où les derniers messages de journal sont conservés. Les messages du journal peuvent être affichés à l’aide d’un débogueur.

L’IFR est basée sur le suivi logiciel WPP. Le principal avantage d’IFR par rapport à WPP est qu’il est activé automatiquement et que vous n’avez pas besoin de démarrer des sessions de suivi à l’avance.

S’applique à :

Système d’exploitation minimum : Windows 8 pour les développeurs de pilotes KMDF et WDM
Système d’exploitation minimum : Windows 10 pour les développeurs de pilotes UMDF (2.15)

Comment activer l’enregistreur de traces en clair dans Visual Studio

Tout d’abord, suivez les étapes décrites dans Ajout du suivi logiciel WPP à un pilote Windows.

Ensuite, dans la page de propriétés du projet, sous Propriétés de configuration-WpP> Tracing-Function> and Macro Options-Enable> Inflight Trace Recorder, sélectionnez Oui.

Enfin, pour UMDF uniquement, il existe une étape supplémentaire : sous WpP Tracing-Function> et Macro Options-Preprocessor> Definitions, ajoutez WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Comment activer l’enregistreur de traces en clair à partir de la ligne de commande

Si vous modifiez manuellement le fichier .vcxproj, définissez les entrées suivantes :

Pour un pilote KMDF ou WDM :

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

Pour un pilote UMDF :

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

Guide pratique pour configurer les paramètres de l’enregistreur de traces inflight

Vous pouvez configurer l’IFR en définissant les entrées de Registre facultatives suivantes sous la clé de paramètre du pilote.

Utilisez les entrées de Registre suivantes :

LogPages : REG_DWORD

Définissez sur le nombre de pages à stocker le journal par défaut. La valeur par défaut est 1.

VerboseOn : REG_DWORD

Le paramètre par défaut zéro entraîne la journalisation des erreurs, des avertissements et des événements d’information par l’IFR. Définissez sur un pour ajouter une sortie détaillée au journal.

WppRecorder_UseTimeStamp : REG_DWORD (disponible à partir de la build WDK 22557)

Les pilotes définissent cette entrée sur un pour ajouter des horodatages aux entrées de journal qui sont ensuite visibles à l’aide de !rcdrkd.rcdrlogdump ou !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp : REG_DWORD (disponible à partir de la build WDK 22557)

Si vous souhaitez des horodatages plus précis, en plus de WppRecorder_UseTimeStamp, ajoutez WppRecorder_PreciseTimeStamp à l’aide de la même syntaxe que celle indiquée ci-dessus.

Exemples

Dans les exemples suivants, ajoutez les lignes entre les commentaires de début et de fin pour définir le nombre de pages de journal sur deux et activer les horodatages.

Pour un pilote en mode noyau :

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

Pour un pilote UMDF :

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

Comment envoyer des messages de trace au journal par défaut

Suivez les instructions fournies dans Ajout d’un suivi logiciel WPP à un pilote Windows. Par exemple :

Dans DriverEntry, appelez WPP_INIT_TRACING(DriverObject, RegistryPath).
Dans EvtDriverUnload, appelez WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Le pilote est maintenant libre d’appeler la fonction de trace en fonction des besoins. Par exemple : TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Pour plus d’informations, consultez WPP_INIT_TRACING et WPP_CLEANUP.

Comment envoyer des messages de trace à un journal personnalisé

Cela s’applique uniquement aux pilotes en mode noyau (KMDF ou WDM).

Pour la majorité des pilotes, le journal par défaut est suffisant. Toutefois, dans certains scénarios, il est utile d’avoir des mémoires tampons de journal distinctes pour des entités distinctes.

Par exemple, lors de l’écriture d’un pilote de bus, vous pouvez souhaiter que chaque appareil enfant dispose de sa propre mémoire tampon. Vous pouvez ensuite utiliser le débogueur pour vider uniquement le journal d’un appareil enfant spécifique.

Pour configurer des journaux personnalisés, le pilote doit inclure <WppRecorder.h>. Appelez ensuite les API suivantes :

WppRecorderLogCreate pour créer plusieurs mémoires tampons de journal
WppRecorderLogDelete avant d’appeler WPP_CLEANUP.
WppRecorderLogSetIdentifier pour définir un identificateur de chaîne pour un journal d’enregistreur donné (facultatif)
WppRecorderConfigure pour désactiver le journal par défaut (facultatif)

Le pilote doit également définir une nouvelle macro de trace qui prend le descripteur de journal comme premier paramètre. Pour obtenir un exemple, consultez l’exemple de pilote De grille-pain.

Comment ajouter des informations d’horodatage à un journal personnalisé

Si votre pilote appelle WppRecorderLogCreate pour créer des handles de journal supplémentaires, il est possible d’activer les horodatages pour certains handles de journal, mais pas pour d’autres.

Pour ce faire, vous devez ajouter une seule ligne au code de pilote pour chaque handle de journal qui doit utiliser des horodatages. Pour obtenir un exemple de code, consultez WppRecorderLogCreate.

Notes

Cette fonctionnalité est disponible à partir de la build WDK 22557. Pour plus d’informations sur le ciblage d’une version spécifique, consultez Génération de pilotes pour différentes versions de Windows.

Comment afficher les messages de trace dans le débogueur

Pour les pilotes KMDF et UMDF, utilisez !wdfkd.wdflogdump comme d’habitude . Il imprime à la fois le journal IFR du framework et le journal IFR du pilote.

Pour les pilotes WDM, utilisez !rcdrkd.rcdrloglist et !rcdrkd.rcdrlogdump.

Partager via