Convalida dei driver di Windows

Articolo
08/14/2024

Usa gli strumenti InfVerif, Driver Verifier Driver Isolation Checks e ApiValidator per testare la conformità del pacchetto driver ai requisiti dei driver di Windows descritti in Introduzione allo sviluppo di driver Windows.

InfVerif

InfVerif è uno strumento che convalida la sintassi INF e verifica che INF sia conforme ai requisiti e alle restrizioni.

Usare InfVerif con /w per verificare che un driver di Windows:

Soddisfa il principio dichiarativo (D) dei principi di progettazione DCH
Conforme al requisito di isolamento del pacchetto driver di Introduzione allo sviluppo di driver Windows

Per altri dettagli, vedere Esecuzione di InfVerif dalla riga di comando.

InfVerif convalida i requisiti di isolamento driver con l'argomento '/w', come illustrato di seguito:

infverif.exe /w <INF file> [<INF file>]

Se InfVerif non segnala errori durante la convalida con /w, INF soddisfa il requisito di isolamento dei pacchetti driver di Windows.

Destinazione delle versioni correnti e precedenti di Windows

Se l'INF contiene la sintassi introdotta in una versione recente di Windows, ad esempio la direttiva INF AddEventProvider disponibile a partire da Windows 10 versione 1809 e vuoi anche usare le versioni precedenti di Windows, usa le decorazioni INF per contrassegnare le voci INF specifiche della versione. Per il codice di esempio che illustra come usare le decorazioni della versione del sistema operativo, vedere Combinazione di estensioni della piattaforma con le versioni del sistema operativo.

I file INF che usano decorazioni della versione del sistema operativo potrebbero non riuscire InfVerif perché i requisiti di isolamento del driver potrebbero non essere supportati nelle versioni precedenti di Windows. Per convalidare tale INF, è possibile specificare la versione minima di Windows in cui devono essere applicati i controlli di isolamento del driver, usando l'argomento '/wbuild'. Ad esempio, un file INF che usa la direttiva AddEventProvider potrebbe usare quanto segue per applicare solo i controlli di isolamento driver a Windows 10 versione 1809 e successive:

infverif.exe /w /wbuild NTAMD64.10.0.0.17763 <INF file> [<INF file>]

Controlli di isolamento driver di verifica driver

Per qualificarsi come driver di Windows, un pacchetto driver deve soddisfare i requisiti di isolamento del pacchetto driver. A partire da Windows 11, Driver Verifier (DV) può monitorare i file binari del kernel per le letture e le scritture del registro e del file system non consentite per i pacchetti driver isolati.

È possibile visualizzare le violazioni man mano che si verificano in un debugger del kernel, è possibile esaminare le violazioni segnalate nel registro eventi di sistema oppure configurare DV per arrestare il sistema e generare un dump della memoria con i dettagli quando si verifica una violazione. È possibile avviare lo sviluppo di driver con i primi e i secondi metodi, quindi passare al secondo quando il driver si avvicina al completamento.

Per abilitare i controlli di isolamento del driver in modo che vengano segnalati tramite il debugger del kernel e il registro eventi di sistema, ma non controllare il sistema:

verifier /rc 33 36 /driver myDriver.sys [myDriver2.sys ...]

Per configurare DV in controllo di bug quando si verifica una violazione dell'isolamento del driver, usare la sintassi seguente:

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.sys ...]

Indipendentemente dal metodo di monitoraggio scelto, è necessario riavviare per abilitare le impostazioni di verifica. Per eseguire questa operazione dalla riga di comando, specificare:

shutdown /r /t 0

Ecco alcuni esempi di messaggi di errore, come illustrato nel debugger del kernel:

Esempio: ZwCreateKey fornisce il percorso assoluto completo:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should not use absolute paths. Detected creation of unisolated registry key \Registry\Machine\SYSTEM

Esempio: ZwCreateKey fornisce il percorso relativo a un handle che non proviene da un'API approvata:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should only use key handles returned from WDF or WDM APIs. Detected creation of unisolated registry key \REGISTRY\MACHINE\SYSTEM\SomeKeyThatShouldNotExist

Prendere in considerazione l'esecuzione di test Di base del dispositivo con controlli di isolamento del driver DV abilitati sul driver per rilevare le violazioni dell'isolamento del driver in anticipo.

Nota

DV non vuole inondare gli utenti con un diluvio di report della stessa violazione, quindi ha un meccanismo di limitazione in cui può limitare la segnalazione di ogni errore univoco. A partire da Windows 11 24H2, per assicurarsi di visualizzare il set completo di violazioni dell'isolamento del driver per qualsiasi esecuzione specificata di un test o di una serie di test, è possibile richiedere la limitazione per le violazioni di isolamento driver da reimpostare usando:

verifier /dif 33 /action 1

Se non si esegue questa operazione prima di eseguire un test, è possibile che non vengano visualizzate determinate violazioni durante l'esecuzione dei test se tali violazioni si sono già verificate prima dell'avvio del test.

Conformità WHCP

Attualmente, il programma WHCP (Windows Hardware Compatibility Program) non impone l'isolamento completo del pacchetto driver. Tuttavia, a partire da Windows 11 24H2, il programma WHCP inizia a includere i requisiti correlati all'isolamento dei driver. Per abilitare lo stesso livello di convalida dell'isolamento dei pacchetti driver usato da Hardware Lab Kit (HLK) come parte dell'applicazione dei requisiti WHCP, usare la sintassi seguente:

Verifier /dif 33 /33 whcp /driver myDriver.sys [myDriver2.sys ...]

Quando si usa questa sintassi, verranno comunque segnalate tutte le violazioni di isolamento del driver, ma quelle non attualmente applicate per HLK verranno segnalate come avvisi anziché errori. Quelli elencati come avvisi non causeranno errori HLK e non causeranno il controllo bug del sistema se si abilitano i controlli di isolamento del driver con /onecheck per generare un controllo errori quando si verifica una violazione.

Quando si visualizzano eventi con un debugger del kernel, quelli considerati errori verranno preceduti DRIVER_ISOLATION_VIOLATION da , mentre quelli che sono avvisi saranno preceduti da DRIVER_ISOLATION_WARNING.

Quando si visualizzano gli eventi nel registro eventi di sistema, gli eventi con un ErrorLevel attributo 0 vengono considerati errori ed eventi con un altro ErrorLevel valore non vengono considerati errori. Per altre informazioni, vedere la sezione "Visualizzazione delle violazioni nel registro eventi di sistema" di seguito.

Visualizzazione delle violazioni nel registro eventi di sistema

Le violazioni del driver vengono segnalate nel registro eventi di sistema dal provider Microsoft-Windows-Kernel-XDV e con un ID evento "4". In Windows 11 24H2 e versioni successive, gli eventi conterranno un ErrorLevel valore. Gli eventi con un ErrorLevel valore pari a 0 vengono considerati errori in base alla modalità di isolamento del driver attiva (conformità completa dell'isolamento del driver rispetto alla conformità dell'isolamento WHCP) quando è stata generata la violazione. Gli eventi con altri ErrorLevel valori non sono considerati errori. Ad esempio, un evento con questi attributi verrebbe considerato un errore:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should not use absolute paths. Detected opening of unisolated registry key \Registry\Machine\System\CurrentControlSet\Services\ExampleDriver\Parameters
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0x0

Sebbene un evento con questi attributi non venga considerato un errore:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should only use key handles returned from WDF or WDM APIs. Detected querying of value under unisolated registry key \REGISTRY\MACHINE\SYSTEM\ControlSet001\Control
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0xf4240

Se si usa l'applicazione Visualizzatore eventi per visualizzare il registro eventi di sistema, è possibile filtrare la visualizzazione del log usando il menu a destra dell'applicazione facendo clic su "Filtra log corrente". Nella finestra di dialogo visualizzata, se si passa alla scheda XML e si modifica manualmente la query, è possibile usare questa query per filtrare il registro eventi di sistema in modo da visualizzare solo violazioni DV che devono essere considerate un errore:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Se si desidera filtrare la visualizzazione del registro eventi in tutte le violazioni DV che devono essere considerate un errore dopo un determinato periodo di tempo (ad esempio, dopo l'avvio di un passaggio di test), è possibile eseguire le operazioni seguenti:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime&gt;='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

In alternativa, se si preferisce un file XML che è possibile caricare fino a visualizzare, è possibile usare wevtutil per generare un codice XML di questo tipo in base alle stesse query:

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime>='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

Driver KMDF

Quando i driver KMDF usano API WDF per accedere al Registro di sistema, ad esempio WdfRegistryCreateKey, WdfRegistryOpenKey o WdfRegistryQueryValue, l'accesso al Registro di sistema avviene tramite wdf01000.sys anziché direttamente il file binario del driver KMDF. Per visualizzare le violazioni causate dal file binario del driver KMDF, abilitare i controlli di isolamento del driver su wdf01000.sys oltre al file binario del driver KMDF. Si noti che, quando si esegue questa operazione, verranno visualizzate violazioni da tutti i driver KMDF nel sistema che usano WDF per gli accessi al Registro di sistema.

ApiValidator

Lo strumento ApiValidator verifica che le API che la chiamata ai file binari siano valide per un driver windows. Lo strumento restituisce un errore se i file binari chiamano un'API esterna al set di API valide per i driver di Windows. Questo strumento fa parte di WDK per Windows 10.

ApiValidator convalida che un driver supporti il livello API, uno dei requisiti per i driver di Windows. Per un elenco completo dei requisiti, vedere Introduzione allo sviluppo di driver Windows.

Esecuzione di ApiValidator in Visual Studio

Se la proprietà Piattaforma di destinazione del progetto driver è impostata su Windows Driver, Visual Studio esegue Automaticamente ApiValidator come passaggio di post-compilazione.

Per visualizzare tutti i messaggi visualizzati da ApiValidator, passare a Strumenti-Opzioni-Progetti>> e Soluzioni-Compila> ed esegui e impostare dettagli di output di compilazione del progetto MSBuild su Dettagliato. Quando si compila dalla riga di comando, aggiungere l'opzione /v:detailed o /v:diag al comando di compilazione per aumentare il livello di dettaglio.

Per l'esempio di driver umdf2_fx2, gli errori di convalida dell'API hanno un aspetto simile al seguente:

Warning  1   warning : API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 2   warning : API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 3   warning : API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 4   warning : API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 5   warning : API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.  C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 6   warning : API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 7   warning : API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 8   warning : API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 9   warning : API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Error   10  error MSB3721: The command ""C:\Program Files (x86)\Windows Kits\10\bin\x64\ApiValidator.exe" -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug\\" -SupportedApiXmlFiles:"C:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x86\UniversalDDIs.xml" -ApiExtractorExePath:"C:\Program Files (x86)\Windows Kits\10\bin\x64"" exited with code -1.    C:\Program Files (x86)\Windows Kits\10\build\WindowsDriver.common.targets   1531    5   osrusbfx2um

Correzione degli errori di convalida

Se è stato passato un progetto di driver UMDF desktop legacy a Windows Driver, verificare di includere le librerie corrette durante la compilazione dei file binari. Selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) sul progetto e scegliere le proprietà. Passare a Linker-Input>. Le dipendenze aggiuntive devono contenere:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
Per esaminare altre opzioni del linker per la destinazione degli SKU OneCore, vedere Compilazione per OneCore.
Rimuovere o sostituire le chiamate API che non sono consentite una alla volta ed eseguire di nuovo lo strumento fino a quando non sono presenti errori.
In alcuni casi, è possibile sostituire queste chiamate con DDI alternative elencate nelle pagine di riferimento per l'DDI solo desktop. Potrebbe essere necessario codificare una soluzione alternativa se non è presente una sostituzione appropriata. Se necessario, scrivere un nuovo driver windows a partire dai modelli di driver in WDK.

Se vengono visualizzati errori come il seguente, vedere le indicazioni in Compilazione per OneCore.

ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSEnumerateSessionsW' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSFreeMemory' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: NOT all binaries are Universal

Esecuzione di ApiValidator dal prompt dei comandi

È anche possibile eseguire Apivalidator.exe dal prompt dei comandi. Nell'installazione di WDK passare a C:\Programmi (x86)\Windows Kits\10\bin<arch> e C:\Programmi (x86)\Windows Kits\10\build\universalDDIs<arch>.

Note importanti:

ApiValidator richiede i file seguenti: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll e UniversalDDIs.xml.
Il UniversalDDIs.xml deve corrispondere all'architettura binaria da convalidare, ad esempio per un driver x64 usare il UniversalDDI.xml x64
ApiValidator testa solo un'architettura alla volta
Per altre informazioni, vedere Problemi noti di ApiValidator di seguito

Usare la sintassi seguente:

Apivalidator.exe -DriverPackagePath: <driver folder path> -SupportedApiXmlFiles: (path to XML files containing supported APIs for Windows drivers)

Ad esempio, per verificare le API chiamate dall'esempio Di attività in WDK, compilare prima l'esempio in Visual Studio. Aprire quindi un prompt dei comandi e passare alla directory contenente lo strumento, ad esempio C:\Program Files (x86\Windows Kits\10\bin\x64. Immettere il comando seguente:

apivalidator.exe -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2\_fx2\Debug" -SupportedApiXmlFiles:"c:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x64\UniversalDDIs.xml"

Il comando produce l'output seguente:

ApiValidator.exe: Warning: API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API.

ApiValidator.exe Driver located at C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug is NOT a Universal Driver

Risoluzione dei problemi di ApiValidator

Se ApiValidator.exe restituisce un errore di formato non corretto, ad esempio il seguente:

Error      1              error : AitStatic output file has incorrect format or analysis run on incorrect file types.     C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe            osrusbfx2um

Usare questa soluzione alternativa:

Aprire Proprietà progetto, passare a Generale e rinominare Directory di output nel modo seguente:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
Ricompila la soluzione.

Problemi noti di ApiValidator

ApiValidator non viene eseguito su Arm64 perché AitStatic non funziona su Arm64.
I file binari arm64 possono essere testati in computer x64, ma non in un computer x86.
ApiValidator può essere eseguito su x86 per testare i file binari x86 e i file binari arm.
ApiValidator può essere eseguito su x64 per testare i file binari x86, x64, Arm e Arm64.

Condividi tramite