Usando o Driver Verifier estático para localizar defeitos nos drivers do Windows

Artigo
07/03/2024

O Verificador de Driver Estático (SDV) usa um conjunto de regras de interface e um modelo do sistema operacional para determinar se o driver interage corretamente com o sistema operacional Windows. O SDV encontra defeitos no código do driver que podem apontar para possíveis bugs nos drivers.

O SDV pode analisar drivers de modo kernel que estão em conformidade com um dos seguintes modelos de driver: WDM, KMDF, NDIS ou Storport. Para obter mais informações, consulte Drivers com suporte e Determinando se o verificador de driver estático oferece suporte ao driver ou à biblioteca. Além disso, o SDV fornece suporte limitado (um conjunto de regras severamente restrito focado em erros gerais, como referências nulas) para drivers que não seguem os modelos de driver acima.

Importante

O SDV não é mais suportado e o SDV não está disponível nas versões WDK ou EWDK do Windows 24H2. Ele não está disponível em WDKs mais recentes que a compilação 26017 e não está incluído no Windows 24H2 RTM WDK. O SDV ainda pode ser usado baixando o Windows 11, versão 22H2 EWDK (lançado em 24 de outubro de 2023) com as ferramentas de compilação do Visual Studio 17.1.5 de Baixar o Kit de Driver do Windows (WDK). Recomenda-se apenas o uso do Enterprise WDK para executar o SDV. Usar versões mais antigas do WDK padrão em conjunto com versões recentes do Visual Studio não é recomendado, pois isso provavelmente resultará em falhas de análise.
No futuro, o CodeQL será a principal ferramenta de análise estática para drivers. O CodeQL fornece uma linguagem de consulta poderosa que trata o código como um banco de dados a ser consultado, simplificando a gravação de consultas para comportamentos, padrões e muito mais específicos. Para obter mais informações sobre como usar o CodeQL, consulte CodeQL e o teste de logotipo de ferramentas estáticas.

Preparando seu código-fonte

Use as etapas a seguir para preparar seu código para análise.

Declarar funções fornecidas pelo driver usando tipos de função

O SDV requer que as funções sejam declaradas usando declarações de tipo de função de função. Por exemplo, uma rotina DriverEntry deve ser declarada usando o tipo de função DRIVER_INITIALIZE:
```
DRIVER_INITIALIZE DriverEntry;
```
Após a declaração, você implementa (ou define) sua rotina de retorno de chamada da seguinte maneira:
```
/
// Driver initialization routine
//
NTSTATUS
  DriverEntry(
    _In_ struct _DRIVER_OBJECT  *DriverObject,
    _In_ PUNICODE_STRING  RegistryPath
    )
  {
      // Function body
  }
```
Cada modelo de driver suportado tem um conjunto de tipos de função para as funções de retorno de chamada do driver e rotinas de despacho. Esses tipos de função são declarados nos arquivos de cabeçalho WDK. Por exemplo, aqui está o protótipo de função para o tipo de função DRIVER_INITIALIZE como aparece em Wdm.h.
```
/
// Define driver initialization routine type.
//
_Function_class_(DRIVER_INITIALIZE)
_IRQL_requires_same_
typedef
NTSTATUS
DRIVER_INITIALIZE (
    _In_ struct _DRIVER_OBJECT *DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    );

typedef DRIVER_INITIALIZE *PDRIVER_INITIALIZE;
```
Como os tipos de função de função já estão definidos nos arquivos de cabeçalho do WDK, você só precisa declarar que suas funções de retorno de chamada são desse tipo. Nesse caso, você declara DriverEntry como sendo do tipo DRIVER_INITIALIZE. Para obter uma lista completa dos tipos de função para os modelos de driver, consulte Usando declarações de tipo de função de função.

Executar análise de código para C/C++

Para ajudá-lo a determinar se o código-fonte está preparado, execute a ferramenta de análise de código no Visual Studio. A ferramenta Análise de Código verifica se há declarações de tipo de função de função, que o SDV exige. A ferramenta Análise de Código pode ajudar a identificar quaisquer declarações de função que possam ter sido perdidas ou avisá-lo quando os parâmetros da definição de função não corresponderem aos do tipo de função de função.

Abra seu projeto de driver no Visual Studio.
No menu Compilar , clique em Executar Análise de Código na Solução.

Os resultados são exibidos na janela Análise de código . Corrija quaisquer declarações de função que você possa ter perdido. Você também pode configurar a ferramenta de análise de código para que ela seja executada sempre que você criar sua solução.

A tabela a seguir mostra alguns dos avisos que a ferramenta Análise de Código pode encontrar no código do driver. Para executar o Verificador de Driver Estático, seu driver precisa estar livre desses defeitos.

Análise de código para aviso C/C++	Descrição
C28101	O módulo Drivers inferiu que a função atual é uma <função do tipo> função
C28022	As classes de função desta função não coincidem com as classes de função no typedef utilizado para defini-las.
C28023	A função que está sendo atribuída ou passada deve ter uma anotação _Function_class para pelo menos uma das classes
C28024	O ponteiro de função que está sendo atribuído é anotado com a classe de função que não está contida nas classes de função.
C28169	A função> de despacho <não tem nenhuma anotação _Dispatch_type_
C28208	A assinatura da função não corresponde às declarações de função

Executando o verificador de driver estático

Abra o arquivo de projeto de driver (.vcxProj) no Visual Studio. No menu Driver, clique em Iniciar Driver Verifier estático….

Isso abre o aplicativo Verificador de Driver Estático, onde você pode controlar, configurar e agendar quando o Verificador de Driver Estático executa uma análise.
Se o driver incluir uma biblioteca, clique na guia Bibliotecas e clique em Adicionar biblioteca para adicionar a biblioteca.

Navegue até o diretório do código-fonte da biblioteca e selecione o arquivo de projeto (.vcxProj). Adicione todas as bibliotecas que seu driver inclui. As bibliotecas devem ser adicionadas antes que o SDV analise seu driver. Quando você inicia uma análise do driver, o SDV também analisa as bibliotecas que não foram processadas. Depois que uma biblioteca é processada, ela é armazenada no cache SDV global. Para obter mais informações, consulte Processamento de biblioteca no verificador de driver estático
Verifique as definições de configuração do Verificador de Driver Estático. Clique na guia Configurar .

Configuração do projeto A Configuração do projeto mostra as definições de configuração e plataforma que você selecionou no Visual Studio.

Recursos Na maioria dos casos, você pode usar as configurações padrão. Se o SDV relatar Tempo Limite, GiveUp ou Spaceout, você pode tentar ajustar essas configurações. Para obter mais informações, consulte Recomendações para solução de problemas do verificador de driver estático.

Agendar Selecione uma hora de início para o início da verificação. A configuração padrão é iniciar a análise imediatamente após clicar em Iniciar na guia Principal . Dependendo do tamanho do driver e sua complexidade, a análise estática pode levar muito tempo para ser executada. Você pode agendar a análise para começar quando for mais conveniente para você; por exemplo, no final do dia.

Observação

Certifique-se de verificar o plano de gerenciamento de energia do computador para garantir que o computador não entrará em estado de suspensão durante a análise.
Clique na guia Regras para selecionar quais regras de uso da API de driver devem ser verificadas ao iniciar a análise.

O Verificador de Driver Estático detecta o tipo de driver que você está analisando (WDF, WDM, NDIS ou Storport) e seleciona o conjunto padrão de regras para o tipo de driver. Se esta for a primeira vez que você estiver executando o SDV no driver, você deverá executar o conjunto de regras padrão.

Para obter informações sobre as regras, consulte Regras de conformidade DDI.
Inicie a análise estática. Clique na guia Principal e clique em Iniciar. Quando você clica em Iniciar, uma mensagem é exibida para informar que a análise estática está agendada e que a análise pode levar muito tempo para ser executada. Clique em OK para continuar. A análise começa no horário agendado.

Visualizando e analisando os resultados

À medida que a análise estática prossegue, o SDV informa o status da análise. Quando a análise é concluída, SDV relata os resultados e estatísticas. Se o driver não atender a uma regra de uso de API, o resultado será relatado como um defeito.

Se algum problema for encontrado, o SDV os exibirá nas páginas Avisos e Erros . A página Propriedades do Driver exibe os resultados dos testes para determinadas propriedades do driver. Os testes de propriedades do driver são usados para identificar os recursos do driver para qualificar ainda mais a análise. Você pode usar os resultados das Propriedades do Driver para confirmar as propriedades esperadas e os recursos suportados do seu driver.

Para exibir defeitos específicos no Relatório do Verificador de Driver Estático, clique em Defeito no painel Resultados. Isso abre o Visualizador de Rastreamento, que exibe um rastreamento do caminho de código para a violação de regra. Para obter mais informações, consulte Interpretando resultados do verificador de driver estático.

Observação

O Verificador de Driver Estático retém os resultados e as configurações da análise. Para limpar os resultados, clique em Limpar.

Solução de problemas de resultados do verificador de driver estático

Se o SDV informar que nenhum defeito foi encontrado, verifique a guia Principal para garantir que os pontos de entrada sejam detectados. Se o driver não declarar funções usando os tipos de função de função, o SDV não poderá analisar e localizar defeitos no código do driver. Para obter mais informações, consulte Usando declarações de tipo de função de função.

Se o SDV relatar tempos limite ou não retornar resultados úteis, talvez seja necessário alterar algumas opções de configuração do SDV. Para obter mais informações sobre como solucionar problemas de SDV, consulte Recomendações para solução de problemas do verificador de driver estático.

Determinando se o Verificador de Driver Estático oferece suporte ao driver ou biblioteca

Usando declarações de tipo de função

Regras do verificador de driver estático

Ferramenta de análise de código