Validação de Drivers do Windows

Artigo
04/24/2024

Use as ferramentas InfVerif, Driver Verifier Driver Isolation e ApiValidator para testar o pacote de driver quanto à conformidade com os requisitos de Drivers do Windows descritos em Introdução aos Drivers do Windows.

InfVerif

O InfVerif é uma ferramenta que valida a sintaxe INF e verifica se o INF está em conformidade com os requisitos e as restrições.

Use InfVerif com /w para verificar se um Driver do Windows:

Atende ao princípio declarativo (D) dos Princípios d Design do DCH
Está em conformidade com o requisito de isolamento do pacote de driver de Introdução aos Drivers do Windows

Para obter mais detalhes, consulte Execução do InfVerif da linha de comando.

O InfVerif valida os requisitos de isolamento de Driver com o argumento "/w", conforme mostrado aqui:

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

Se o InfVerif não relatar erros ao validar com /w, o INF atende ao requisito de Isolamento do Pacote de Driver dos Drivers do Windows.

Direcionamento de versões atuais e anteriores do Windows

Se o INF contiver a sintaxe introduzida em uma versão recente do Windows, como a Diretiva INF AddEventProvider, que está disponível a partir do Windows 10 versão 1809 e você também deseja direcionar versões anteriores do Windows, use decorações INF para marcar entradas INF específicas da versão. Para obter um código de exemplo mostrando como usar decorações de versão do sistema operacional, consulte Combinação de extensões de plataforma com versões de sistema operacional.

Os arquivos INF usando decorações de versão do sistema operacional podem falhar para InfVerif porque os requisitos de isolamento de driver podem não ter suprote nas versões anteriores do Windows. Para validar esse INF, você pode especificar a versão mínima do Windows em que as verificações de isolamento de driver devem ser aplicadas, usando o argumento "/wbuild". Por exemplo, um arquivo INF que usa a diretiva AddEventProvider pode usar o seguinte para aplicar somente verificações de isolamento de driver para o Windows 10 versão 1809 e posterior:

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

Verificações de isolamento de driver do verificador de driver

Para se qualificar como um Driver do Windows, um pacote de driver deve atender aos requisitos de Isolamento do Pacote de Driver . A partir do Windows 11, o Verificador de Driver (DV) pode monitorar binários do kernel para leituras e gravações do Registro que não são permitidas para pacotes de driver isolados.

Você pode exibir as violações como elas acontecem em um depurador de kernel ou pode configurar o DV para interromper o sistema e gerar um despejo de memória com detalhes quando ocorre uma violação. Você pode iniciar o desenvolvimento do driver com o primeiro método e, em seguida, alternar para o segundo à medida que o driver se aproxima da conclusão.

Para exibir as violações à medida que ocorrem, primeiro conecte um depurador de kernel e, em seguida, use os comandos a seguir. Depois que uma reinicialização tiver habilitado as configurações do DV, você poderá monitorar violações na saída do depurador do kernel.

Para habilitar as verificações de isolamento de driver em um único driver:

verifier /rc 33 36 /driver myDriver.sys

Para verificar mais de um driver, separe cada nome de driver com um espaço:

verifier /rc 33 36 /driver myDriver1.sys myDriver2.sys

Para configurar o DV para verificação de bugs quando ocorrer uma violação, use a seguinte sintaxe:

verifier /onecheck /rc 33 36 /driver myDriver1.sys

Você precisará reinicializar para habilitar as configurações de verificação. Para fazer isso da linha de comando, especifique:

shutdown /r /t 0

Aqui estão alguns exemplos de mensagens de erro:

Exemplo: ZwCreateKey fornece caminho absoluto completo:

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

Exemplo: ZwCreateKey fornece caminho relativo a um identificador que não é de uma API aprovada:

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

Considere executar testes de Fundamentos do Dispositivo com verificações de isolamento de driver DV habilitadas em seu driver para ajudar a detectar violações de isolamento de driver antecipadamente.

Drivers KMDF

Quando os drivers KMDF usam APIs WDF para acessar o Registro, como WdfRegistryCreateKey, WdfRegistryOpenKey, or WdfRegistryQueryValue, the registry access happens via wdf01000.sys instead of the KMDF driver binary directly. Para exibir violações causadas pelo binário do driver KMDF, habilite as verificações de isolamento de driver em wdf01000.sys além do binário do driver KMDF. Observe que, ao fazer isso, você verá violações de todos os drivers KMDF no sistema que estão usando o WDF para seus acessos ao Registro.

ApiValidator

A ferramenta ApiValidator verifica se as APIs que seus binários chamam são válidas para um driver do Windows. A ferramenta retornará um erro se os binários chamarem uma API que está fora do conjunto de APIs válidas para Drivers do Windows. Esta ferramenta faz parte do WDK para Windows 10.

O ApiValidator valida que um driver oferece suporte a Camadas de API, um dos requisitos para Drivers do Windows. Para obter uma lista completa de requisitos, consulte Introdução aos Drivers do Windows.

Execução de ApiValidator no Visual Studio

Se a propriedade Target Platform do seu projeto de driver estiver definida como Driver do Windows, o Visual Studio executará o ApiValidator automaticamente como uma etapa pós-compilação.

Para exibir todas as mensagens exibidas pelo ApiValidator, navegue até Ferramentas->Opções->Projetos e Soluções->Compilar e Executar e defina o detalhamento de saída da compilação do projeto MSBuild como Detalhado. Ao criar da linha de comando, adicione a opção /v:detailed ou /v:diag ao comando build para aumentar o detalhamento.

Para o exemplo de driver umdf2_fx2, os erros de validação de API têm a seguinte aparência:

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

Correção de erros de validação

Se você alternou um projeto de driver UMDF de área de trabalho herdado para o Driver do Windows, verifique se está incluindo as bibliotecas corretas ao criar seus binários. Selecione e segure (ou clique com o botão direito do mouse) o projeto e escolha propriedades. Navegue até Vinculador->Entrada. As Dependências Adicionais devem conter:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
Para revisar outras opções de vinculador para segmentar SKUs OneCore, consulte Criação para OneCore.
Remova ou substitua chamadas de API que não são permitidas uma de cada vez e execute novamente a ferramenta até que não haja erros.
Em alguns casos, você pode substituir essas chamadas por DDIs alternativas listadas nas páginas de referência para o DDI somente para desktop. Talvez seja necessário codificar uma solução alternativa se não houver uma substituição adequada. Se precisar, escreva um novo Driver do Windows dos modelos de driver no WDK.

Se você vir erros como os seguintes, consulte as diretrizes em Criação para 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

Execução de ApiValidator do Prompt de Comando

Você também pode executar Apivalidator.exe no prompt de comando. Na instalação do WDK, navegue até C:\Arquivos de Programas (x86)\Windows Kits\10\bin<arch> e C:\Arquivos de Programas (x86)\Windows Kits\10\build\universalDDIs<arch>.

Observações importantes:

ApiValidator requer os seguintes arquivos: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll e UniversalDDIs.xml.
O UniversalDDIs.xml deve corresponder à arquitetura binária que está sendo validada, por exemplo, para um driver x64 use o x64 UniversalDDI.xml
O ApiValidator testa apenas uma arquitetura de cada vez
Consulte Problemas conhecidos do ApiValidator abaixo para obter informações adicionais

Use a seguinte sintaxe:

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

Por exemplo, para verificar as APIs chamadas pelo exemplo Atividade no WDK, primeiro compile o exemplo no Visual Studio. Em seguida, abra um prompt de comando e navegue até o diretório que contém a ferramenta, por exemplo C:\Program Files (x86\Windows Kits\10\bin\x64. Insira o seguinte comando:

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"

O comando gera a seguinte saída:

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

Solução de problemas do ApiValidator

Se ApiValidator.exe gerar um erro de formato incorreto, como o seguinte:

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

Use esta solução alternativa:

Abra as propriedades do Projeto, navegue até Geral e renomeie o Diretório de Saída para o seguinte:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
Recrie a solução.

Problemas conhecidos do ApiValidator

O ApiValidator não é executado no Arm64 porque AitStatic não funciona no Arm64.
Os binários do Arm64 podem ser testados em computadores x64, mas não em um computador x86.
O ApiValidator pode ser executado em x86 para testar binários x86 e binários Arm.
O ApiValidator pode ser executado em x64 para testar binários x86, x64, Arm e Arm64.