Door de gebruiker geïnitieerde feedback - repromodus

Artikel
2025-03-17

Gebruiker-geïnitieerde feedback (UIF) repro-modus stelt het systeem in staat om meer gedetailleerde logboekregistratie te verzamelen terwijl de gebruiker de fout reproduceert. Net als bij de normale UIF-modus wordt dit ook bereikt door een nieuwe WMI-logboekregistratiesessie te maken met door IHV gedefinieerde ETW-providers. Nadat de repromodus is voltooid, worden de uitgebreide logboeken verzameld en naar Microsoft verzonden voor analyse. Er zijn IHV-extensiepunten voor het in- of uitschakelen van uitgebreide logbestanden van firmware. Repro-logboeken zijn bedoeld om gedetailleerder te zijn, zodat de reden waarom de klant een probleem ondervindt, kan worden opgespoord. Daarom is de logboekbestandsgrootte voor het logboek voor de repromodus ingesteld op een maximale grootte van 10 MB. De IHV moet gedetailleerdere instellingen gebruiken voor ETW-providervlaggen, niveau, en trefwoordwaarden.

Het huidige repromodusmodel voor UIF vereist dat Microsoft op de hoogte wordt gesteld van alle provider-GUID's, niveaus en vlaggen voordat de feedbacklogboeken van IHV worden opgenomen. Door de providers toe te voegen aan het register, zoals aangegeven in dit onderwerp, kan een IHV de logboeken testen op de juiste niveaus.

Door Microsoft geleverde WMI-sessie voor automatische logboekregistratie

Microsoft biedt een WMI-sessie voor automatische logboekregistratie zonder initiële ETW-providers. Wanneer de stuurprogramma's van de IHV zijn geïnstalleerd, moeten ze de vereiste registersleutels van de WMI-provider toevoegen onder de door Microsoft geleverde WMI-sessiesleutel voor automatische logboekregistratie. De IHV mag geen van de registerwaarden voor automatische logboekregistratie wijzigen. Alle ETW-provideropties zijn echter beschikbaar voor de IHV, inclusief het inschakelniveau, "match any", "match all", etc.

Belangrijk

De auto-logger is nooit ingeschakeld als auto-logger. Deze waarden worden gebruikt om de IHV-logregistratie voor de reproductiemodus te valideren zoals beschreven in De logboeken van de reproductiemodus testen. Daarnaast kunnen we gebruikers vragen deze logboeken handmatig in te dienen met behulp van het hulpprogramma netsh. De provider-GUIDs, niveaus en vlaggen moeten ook worden verzonden naar Microsoft, samen met een voorbeeld van de logboeken, zodat ze worden opgenomen in de UIF's van de repromodus (zie IHV-providers verzenden naar Microsoft.

De WMI-sessie voor automatische logboekregistratie wordt toegevoegd aan de HKLM-register hive met het volgende pad:

HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSessionRepro

Het resulterende ETL-logboekbestand bevindt zich hier:

%SystemDrive%\System32\LogFiles\WMI\WifiDriverIHVSessionRepro.etl

WIJZIGINGEN in IHV-stuurprogramma INF

IHP's moeten hun INF-stuurprogrammabestanden bijwerken om de volgende registersleutelwaarden toe te voegen, zodat ze tijdens de normale UIF-modus gedetailleerde IHV-logboeken kunnen verkrijgen. De volgende fragmenten bevatten een sjabloon voor het toevoegen van één ETW-provider aan de sessie voor automatische logboekregistratie. Een IHV kan zoveel providers toevoegen als ze passend zien. Bovendien zijn de inschakelen niveauwaarden IHV-specifiek per ETW-provider, dus ze hoeven niet noodzakelijkerwijs hetzelfde te zijn als de door Microsoft gedefinieerde waarden (TRACE_LEVEL_CRITICAL, TRACE_LEVEL_ERROR, enzovoort).

IHV ETW-providers toevoegen

In het volgende fragment ziet u hoe u IHV ETW-providers toevoegt in het INF-bestand:

HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\<IHVProviderGUID_1>,Enabled,%REG_DWORD%,1
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\<IHVProviderGUID_1>,,EnableLevel,%REG_DWORD%,<IHV_LogEnableLevelValue>
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\<IHVProviderGUID_1>,MatchAnyKeyword,%REG_QWORD%,<IHV_MatchAnyKewordValue>

[The following is optional]
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\<IHVProviderGUID_1>,MatchAllKeyword,%REG_QWORD%,<IHV_MatchAllKewordValue>

[Strings]
REG_DWORD = 0x00010001
REG_QWORD = 0x000B0001

Voorbeeldwaarden

In dit voorbeeld ziet u een instelling op informatieniveau van WDI UE met alle trefwoorden:

HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\{21ba7b61-05f8-41f1-9048-c09493dcfe38},Enabled,%REG_DWORD%,1
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\{21ba7b61-05f8-41f1-9048-c09493dcfe38},,EnableLevel,%REG_DWORD%,0xFF
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\WifiDriverIHVSession\{21ba7b61-05f8-41f1-9048-c09493dcfe38},MatchAnyKeyword,%REG_QWORD%,0x000FFFFF

Standard EnableLevel values:
0x5 - Verbose
0x4 - Informational
0x3 - Warning
0x2 - Error
0x1 - Critical
0x0 – LogAlways

Callback van ETW-besturingselement

Een IHV kan zich registreren voor de callback van etw-besturingselementen in de bijbehorende ETW-logboekregistratiecode. Hierdoor kan de IHV worden gewaarschuwd wanneer ETW-providers worden ingeschakeld of uitgeschakeld, of wanneer een opnamecontrole wordt gestart. Hiermee kan de IHV uitgebreide firmware-logboeken in- of uitschakelen voor de repro-modus.

Notitie

Als de ETW-providers worden gedeeld tussen de normale modus en de repromodus, moet de IHV de door IHV gedefinieerde EnableLevel, gedefinieerd in het INF-bestand, uitschakelen om uitgebreide firmwarelogboeken te starten/stoppen.

ETW callbackfunctie

In het volgende fragment ziet u hoe u zich registreert voor de ETW-callback. Dit is alleen belangrijk als de IHV bij het begin en einde van de UIF-repromodus specifieke actie moet ondernemen (zoals het starten of stoppen van uitgebreide firmwarelogboekregistratie). Als er meerdere ETW-providers worden gebruikt, kunnen IHD's overwegen om slechts één callback te implementeren om firmwarelogboekregistratie te initiëren. Alle firmwarelogboekregistratie moet worden doorgestuurd naar de ETW-traceprovider van de IHV. De diagnostische hulpprogramma's voor UIF verzamelen alleen traceringen voor de ETW-provider van de IHV.

Er zijn twee manieren om de ETW-callback in te schakelen, afhankelijk van hoe u ETW-logboekregistratie hebt geïmplementeerd.

Gemanifesteerde ETW's met automatisch gegenereerde code via MC.exe. Zie Een instrumentatiemanifest schrijven voor meer informatie.
1. De header in het volgende fragment (etwtracingevents.h) is een automatisch gegenereerde ETW-gebeurtenisheader die is gemaakt via MC.exe. Er wordt aangenomen dat de ETW-gebeurtenissen al zijn gegenereerd, dus dit onderwerp richt zich niet op dit onderdeel.
2. MCGEN_PRIVATE_ENABLE_CALLBACK_V2 moet worden gedefinieerd voordat de automatisch gegenereerde ETW-header wordt opgenomen. Anders wordt de callback niet aangeroepen.
Registreren voor de ETW-callback via de EventRegister-API.
1. De ETW-callbackprovider moet worden doorgegeven aan de EventRegister functie bij het registreren van de traceringsprovider.

Dit fragment toont het prototype voor de callback-functie ETW.

#include <evntprov.h>
extern
VOID
EtwEventControlCallback(
    _In_ LPCGUID SourceId,
    _In_ ULONG ControlCode,
    _In_ UCHAR Level,
    _In_ ULONGLONG MatchAnyKeyword,
    _In_ ULONGLONG MatchAllKeyword,
    _In_opt_ PEVENT_FILTER_DESCRIPTOR FilterData,
    _Inout_opt_ PVOID CallbackContext
    );

De volgende code is alleen vereist als u automatisch gegenereerde ETW-gebeurtenissen hebt gebruikt met behulp van het hulpprogramma MC.exe.

#define MCGEN_PRIVATE_ENABLE_CALLBACK_V2 EtwEventControlCallback

#include "etwtracingEvents.h" // Generated from manifest - This must come 
                              // after MCGEN_PRIVATE_ENABLE_CALLBACK_V2 is                   
                              // defined

De parameter ControlCode van de ETW-callback geeft aan wanneer de provider is ingeschakeld of uitgeschakeld. De waarden worden gedefinieerd in <evntrace.h> en hebben de volgende waarden:

#define EVENT_CONTROL_CODE_DISABLE_PROVIDER 0
#define EVENT_CONTROL_CODE_ENABLE_PROVIDER  1
#define EVENT_CONTROL_CODE_CAPTURE_STATE    2

Codering voor Gebeurteniscontrole: PROVIDER INSCHAKELEN

Met deze vlag wordt de ETW-provider ingeschakeld en wordt aangegeven dat de UIF-repromodussessie is gestart. Dit moet worden gebruikt om uitgebreide firmwarelogboekregistratie en/of pakketregistratie te initiëren.

EVENEMENT_CONTROLECODE_UITSCHAKELEN_LEVERANCIER

Met deze vlag wordt de ETW-provider uitgeschakeld en wordt aangegeven dat de UIF-repromodussessie is beëindigd. De implementatie van IHV moet op dit moment firmwarelogboeken leegmaken en opnieuw instellen als de parameter Niveau overeenkomt met het niveau van de door IHV opgegeven UIF-repromodus in het INF-bestand (0xFF in het voorbeeld van de volgende sectie).

EVENT_CONTROL_CODE_TOESTAND_OPNEMEN

Met deze vlag wordt aangevraagd dat de provider de statusgegevens registreert. Dit wordt over het algemeen aangeroepen om de logboeken in het geheugen naar de schijf te spoelen. De implementatie van de IHV moet op dit moment de firmwarelogboeken leegmaken en opnieuw instellen als de parameter Niveau overeenkomt met het door de IHV opgegeven niveau voor de UIF-repro-modus in het INF-bestand (0xFF in het voorbeeld uit de volgende sectie).

Voorbeeldcode

Hier volgt een voorbeeld van een ETW-callback-implementatie die als sjabloon kan worden gebruikt om uitgebreide stuurprogramma- en firmwarelogboekregistratie in te schakelen voor scenario's voor repromodus UIF.

Notitie

IHDs moeten alle in behandeling zijnde firmwarelogboeken leegmaken voor zowel de EVENT_CONTROL_CODE_CAPTURE_STATE als EVENT_CONTROL_CODE_DISABLE_PROVIDER controlecodes.

Nadat de EVENT_CONTROL_CODE_CAPTURE_STATE is aangeroepen, roept het diagnostische hulpprogramma UIF de ETW-callback nog twee keer aan met de EVENT_CONTROL_CODE_ENABLE_PROVIDER besturingscode. Om te voorkomen dat de firmwarelogboekregistratie opnieuw wordt ingeschakeld, verschuift de toestandsmachine van de status ReproModeStateCaptured naar de status ReproModeStateFinal voordat hij terugkeert naar de status ReproModeStateNotStarted. De EVENT_CONTROL_CODE_DISABLE_PROVIDER besturingscode wordt alleen gebruikt om de provider uit te schakelen. Dit maakt geen deel uit van het UIF-proces, maar moet nog steeds worden gehonoreerd.

IHD's moeten de IHV_ETW_REPRO_MODE_LEVEL waarde in het volgende voorbeeld wijzigen zodat deze overeenkomt met het niveau van de repromodus dat is ingesteld in het INF-bestand.

#define IHV_ETW_REPRO_MODE_LEVEL 0xFF // This value must match the repro mode              
                                      // EnableLevel INF value

typedef enum _EtwReproModeState
{
    ReproModeStateNotStarted = 0,
    ReproModeStateStarted,
    ReproModeStateCaptured,
    ReproModeStateFinal
} EtwReproModeState;
 
static EtwReproModeState g_eReproModeLoggingEnabled = ReproModeStateNotStarted; 

VOID
EtwEventControlCallback(
    _In_ LPCGUID SourceId,
    _In_ ULONG ControlCode,
    _In_ UCHAR Level,
    _In_ ULONGLONG MatchAnyKeyword,
    _In_ ULONGLONG MatchAllKeyword,
    _In_opt_ PEVENT_FILTER_DESCRIPTOR FilterData,
    _Inout_opt_ PVOID CallbackContext
    )
{
    UNREFERENCED_PARAMETER(SourceId);
    UNREFERENCED_PARAMETER(MatchAnyKeyword);
    UNREFERENCED_PARAMETER(MatchAllKeyword);
    UNREFERENCED_PARAMETER(FilterData);
    UNREFERENCED_PARAMETER(CallbackContext);

    switch(ControlCode)
    {
        case EVENT_CONTROL_CODE_ENABLE_PROVIDER:
            if (Level == IHV_ETW_REPRO_MODE_LEVEL)
            {
                switch(g_eReproModeLoggingEnabled)
                {
                    case ReproModeStateNotStarted:
                        //
                        // Enable verbose Firmware logs.
                        //
                        g_eReproModeLoggingEnabled = ReproModeStateStarted;
                        break;

                    case ReproModeStateCaptured:
                        //
                        // The diagnostic tools will invoke the callback after
                        // the capture with EVENT_CONTROL_CODE_ENABLE_PROVIDER
                        // twice. 
                        //
                        g_eReproModeLoggingEnabled = ReproModeStateFinal;
                        break;

                    case ReproModeStateFinal:
                        //
                        // The state machine is now complete, reset the state.
                        //
                        g_eReproModeLoggingEnabled = ReproModeStateNotStarted;
                        break;

                    case ReproModeStateStarted:
                    default:
                        break;
                }
            }
            break;  

        case EVENT_CONTROL_CODE_DISABLE_PROVIDER:
            if (g_eReproModeLoggingEnabled == ReproModeStateStarted) 
            {
                // 
                // Merge verbose firmware logs into ETW log (if not done already).
                // Disable verbose firmware logs
                // 
                g_eReproModeLoggingEnabled = ReproModeStateNotStarted;
            }
            break;

        case EVENT_CONTROL_CODE_CAPTURE_STATE:
            if (Level == IHV_ETW_REPRO_MODE_LEVEL &&
                g_eReproModeLoggingEnabled == ReproModeStateStarted)
            {
                // 
                // Merge verbose firmware logs into ETW log (if not done already).
                // Disable verbose firmware logs
                // 
                g_eReproModeLoggingEnabled = ReproModeStateCaptured;
            }
            break;  
    }
}

De logboeken van de repromodus testen

Als u de logboeken van de IHV-repromodus wilt testen, kunnen de volgende opdrachten worden gebruikt om het vastleggen te starten en te stoppen.

Notitie

Het resulterende ETL-bestand bevat enkele os-logboeken.

netsh wlan IHV startlogging
netsh wlan IHV stoplogging

Deze opdrachten worden ook door klanten gebruikt om handmatig logboeken van een apparaat te verzamelen.

IHV-providers aanmelden bij Microsoft

De laatste stap voor IHD's voor het indienen van door de gebruiker geïnitieerde feedback in de repromodus is om contact op te nemen met Microsoft en de aangevraagde provider-GUID's, niveaus en vlaggen op te geven, samen met voorbeeldlogboekgegevens voor controle. Zodra de logboekregistratie is goedgekeurd, worden de providers toegevoegd aan het door de gebruiker geïnitieerde feedbacksysteem.

Notitie

Wijzigingen in de GUID's, niveaus of vlaggen van de provider na verzending hebben geen invloed op de UIF-logboeken.

Gebruikersgeïnitieerde feedback met logging van IHV-traces

door de gebruiker geïnitieerde feedback - normale modus

Delen via

Door de gebruiker geïnitieerde feedback - repromodus

Door Microsoft geleverde WMI-sessie voor automatische logboekregistratie

WIJZIGINGEN in IHV-stuurprogramma INF

IHV ETW-providers toevoegen

Voorbeeldwaarden

Callback van ETW-besturingselement

ETW callbackfunctie

Codering voor Gebeurteniscontrole: PROVIDER INSCHAKELEN

EVENEMENT_CONTROLECODE_UITSCHAKELEN_LEVERANCIER

EVENT_CONTROL_CODE_TOESTAND_OPNEMEN

Voorbeeldcode

De logboeken van de repromodus testen

IHV-providers aanmelden bij Microsoft

Verwante koppelingen

Feedback

Aanvullende resources