Partilhar via

Usando o verificador de driver estático para encontrar defeitos nos drivers do Windows

Static Driver Verifier (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. 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 Suportados e Determinando se o Verificador de Drivers Estático suporta o seu driver ou biblioteca. Além disso, o SDV fornece suporte limitado (um conjunto de regras severamente restrito focado em erros gerais, como desreferê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 do 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 em Baixar o Kit de Driver do Windows (WDK). Somente o uso do Enterprise WDK para executar SDV é recomendado. O uso de 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 ferramenta principal de análise estática para controladores. O CodeQL fornece uma linguagem de consulta poderosa que trata o código como um banco de dados a ser consultado, simplificando a escrita 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.

  1. 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 papel 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 papéis 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 do 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;

    Dado que os tipos de funções de função já estão definidos nos ficheiros de cabeçalho do WDK, só precisa de declarar as suas funções de retorno de chamada para que sejam desse tipo. Nesse caso, você declara DriverEntry para ser 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.

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

    Para ajudá-lo a determinar se o código-fonte está preparado, execute a ferramenta 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, que o SDV exige. A ferramenta de análise de código pode ajudar a identificar quaisquer declarações de função que possam ter sido esquecidas ou avisá-lo quando os parâmetros da definição de função não corresponderem aos do tipo de parâmetro 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 todas as declarações de função que você possa ter perdido. Você também pode configurar a ferramenta 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 nesta função não correspondem à(s) classe(s) de função no typedef usado para defini-la.
    C28023 A função que está sendo atribuída ou aprovada 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 na lista de classes de função.
    C28169 A função de despacho <function> não tem nenhuma _Dispatch_type_ anotação
    C28208 A assinatura da função não corresponde às declarações de função

Executando o Verificador de Driver Estático

  1. Abra o arquivo de projeto de driver (.vcxProj) no Visual Studio. No menu Driver, clique em Iniciar Verificador de Driver 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.

  2. 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 o 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 controladores estático

  3. Verifique as definições de configuração para o Verificador de Driver estático. Clique na guia Configurar .

    Configuração do Projeto A Configuração do Projeto mostra a configuração e as configurações de 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.

    Horário 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 querer 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 entre em estado de suspensão durante a análise.

  4. Clique na guia Regras para selecionar quais regras de uso da API do driver devem ser verificadas ao iniciar a análise.

    O Verificador de Driver Estático deteta o tipo de driver que você está analisando (WDF, WDM, NDIS ou Storport) e seleciona o conjunto padrão de regras para seu tipo de driver. Se esta é a primeira vez que você está executando SDV em seu driver, você deve executar o conjunto de regras padrão.

    Para obter informações sobre as regras, consulte Regras de conformidade DDI.

  5. 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 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 estiver concluída, a SDV reporta os resultados e as estatísticas. Se o driver não satisfizer uma regra de uso da API, o resultado será relatado como um defeito.

Se algum problema for encontrado, o SDV exibirá aqueles nas páginas Avisos e Erros . A página Propriedades do driver mostra os resultados dos testes para propriedades específicas do driver. Os testes das propriedades do condutor são usados para identificar as características do condutor e 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 no Defeito no painel Resultados . Isso abre o Visualizador de Rastreamento, que exibe um rastreamento do caminho do código para a violação da regra. Para obter mais informações, consulte Interpretando resultados do verificador de driver estático.

Observação

O Static Driver Verifier 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 detetados. Se o driver não declarar funções usando os tipos de função de função, SDV será incapaz de analisar e encontrar defeitos no código do driver. Para obter mais informações, consulte Usando declarações de tipo 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.

Determinar se o Verificador de Driver Estático suporta seu driver ou biblioteca

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

Regras do Verificador de Driver Estático

Ferramenta de análise de código