Partilhar via

Tutorial: Escrever um KMDF (driver Universal do Windows) com base em um modelo

  • Artigo

Este tópico descreve como escrever um driver universal do Windows usando o Kernel-Mode Driver Framework (KMDF). Você começará com um modelo do Microsoft Visual Studio e, em seguida, implantará e instalará seu driver em um computador separado.

Pré-requisitos

  • Siga as etapas para instalar do Windows Driver Kit (WDK). Ferramentas de Depuração para Windows são incluídas quando você instala o WDK.

  • Instale Visual Studio 2022. Ao instalar o Visual Studio 2022, selecione a carga de trabalho Desenvolvimento para Desktop com C++ e, em Componentes Individuais, adicione:

    • MSVC v143 – Bibliotecas com mitigação de Spectre do VS 2022 C++ ARM64/ARM64EC (mais recentes)
    • MSVC v143 – bibliotecas com mitigação de Spectre VS 2022 C++ x64/x86 (mais recente)
    • ATL do C++ para as mais recentes ferramentas de build v143 com Mitigações de Espectro (ARM64/ARM64EC)
    • ATL do C++ para as mais recentes ferramentas de build v143 com Mitigações de Espectro (x86 & x64)
    • C++ MFC for latest v143 build tools with Spectre Mitigations (ARM64/ARM64EC)
    • MFC do C++ para as mais recentes ferramentas de build v143 com Mitigações de Espectro (x86 & x64)
    • Windows Driver Kit

Criar e desenvolver um driver

  1. Abra o Microsoft Visual Studio. No menu Arquivo, escolha Novo > Projeto.

  2. Na caixa de diálogo Criar um novo projeto, selecione C++ na lista suspensa à esquerda, escolha Windows na lista suspensa no meio e escolha Driver na lista suspensa à direita.

  3. Selecione Kernel Mode Driver (KMDF) na lista de tipos de projeto. Selecione Avançar.

    Captura de tela da nova caixa de diálogo do projeto, mostrando o driver do modo kernel selecionado.

    Dica

    Se você não conseguir encontrar modelos de projeto de driver no Visual Studio, a extensão do WDK do Visual Studio não foi instalada corretamente. Para resolver isso, execute o Instalador do Visual Studio, selecione Modificar, adicione Kits de Driver do Windows na guia Componente Individual e selecione Modificar.

  4. Na caixa de diálogo Configurar o novo projeto, insira "KmdfDriver" no campo Nome do projeto.

    Nota

    Ao criar um novo driver KMDF ou UMDF, você deve selecionar um nome de driver com 32 caracteres ou menos. Esse limite de comprimento é definido em wdfglobals.h.  

  5. No campo Local, insira o diretório no qual você deseja criar o novo projeto.

  6. Verifique Colocar solução e projeto no mesmo diretório e selecione Criar.

    Captura de tela da caixa de diálogo de configuração do projeto.

    O Visual Studio cria um projeto e uma solução. Você pode vê-los na janela do Gerenciador de Soluções . (Se a janela do Gerenciador de Soluções não estiver visível, escolha do Gerenciador de Soluções no menu Exibição.) A solução tem um projeto de driver chamado KmdfDriver. Para ver o código-fonte do driver, abra qualquer um dos arquivos em Arquivos de Origem. Driver.c e Device.c são bons locais para começar.

    Captura de tela do gerenciador de soluções mostrando os arquivos no projeto do driver.

  7. Na janela Gerenciador de Soluções, selecione e segure (ou clique com o botão direito do mouse) KmdfDriver, e escolha Propriedades. Navegue até Propriedades de Configuração > Configurações de Driver > Geral e observe que Plataforma de Destino usa o padrão Universal.

  8. Para compilar o driver, escolha Compilar Solução no menu Compilar. O Microsoft Visual Studio exibe o progresso da compilação na janela Saída. (Se a janela Saída não estiver visível, escolha Saída no menu Exibir.)

    Verifique se a saída de build inclui:

    >    Driver is 'Universal'.

    Após verificar que a solução foi criada com êxito, você pode fechar o Visual Studio.

  9. Para ver o driver compilado, no Explorador de Arquivos, vá para sua pasta KmdfDriver e, em seguida, para x64\Debug\KmdfDriver. O diretório inclui os seguintes arquivos:

    • KmdfDriver.sys -- o arquivo de driver no modo kernel
    • KmdfDriver.inf – um arquivo de informações que o Windows usa quando você instala o driver

Implantar o driver

Normalmente, quando você testa e depura um driver, o depurador e o driver são executados em computadores separados. O computador que executa o depurador é chamado de computador hoste o computador que executa o driver é chamado de computador de destino. O computador de destino também é chamado de computador de teste. Para obter mais informações sobre drivers de depuração, consulte Ferramentas de Depuração para Windows.

Até agora, você usou o Visual Studio para criar um driver no computador host. Agora você precisa configurar um computador de destino.

  1. Siga as instruções em Provisionar um computador para implantação e teste de driver (WDK 10).

    Dica

    Ao seguir as etapas para provisionar o computador de destino automaticamente usando um cabo de rede, anote a porta e a chave. Você os usará posteriormente na etapa de debugging. Neste exemplo, usaremos 50000 como porta e 1.2.3.4 como a chave.

    Em cenários reais de depuração de driver, recomendamos usar uma chave gerada por KDNET. Para obter mais informações sobre como usar o KDNET para gerar uma chave aleatória, consulte o tópico Drivers de Depuração – Laboratório Passo a Passo (Modo Kernel do Sysvad).

  2. No computador host, abra sua solução no Visual Studio. Você pode clicar duas vezes no arquivo de solução, KmdfDriver.sln, na pasta KmdfDriver.

  3. Na janela Gerenciador de Soluções, selecione e segure (ou clique com o botão direito do mouse) no projeto KmdfDriver e escolha Propriedades.

  4. Na janela Páginas de Propriedades do Pacote KmdfDriver, no painel esquerdo, vá para Propriedades de Configuração > Instalação do Driver > Implantação.

  5. Marque a caixa Remover versões anteriores do driver antes da implantação.

  6. Para Nome do Computador Remoto, selecione o nome do computador que você configurou para teste e depuração. Neste exercício, usamos um computador chamado MyTestComputer.

  7. Selecione Atualização de driver de ID de hardware e insira a ID de hardware do driver. Neste exercício, a ID de hardware é Root\KmdfDriver. Selecione OK.

    captura de tela da janela Páginas de Propriedades do Pacote kmdfddriver, mostrando a instalação do driver de implantação selecionada

    Nota

    Neste exercício, a ID de hardware não identifica uma parte real do hardware. Ela identifica um dispositivo imaginário que receberá um lugar na árvore de dispositivos como filho do nó raiz. Para hardware real, não selecione a opção Atualização do Driver de ID de Hardware; em vez disso, selecione Instalar e Verificar. Você verá a ID de hardware no arquivo INF (informações do driver). Na janela Gerenciador de Soluções, vá para KmdfDriver Arquivos de Driver > e clique duas vezes em KmdfDriver.inf. A ID de hardware está localizada em [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. No menu Compilar, escolha Implantar Solução. O Visual Studio copia automaticamente os arquivos necessários para instalar e executar o driver no computador de destino. Isso pode levar um minuto ou dois.

    Quando você implanta um driver, os arquivos de driver são copiados para a pasta \drivertest\drivers do %Systemdrive%no computador de teste. Se algo der errado durante a implantação, você poderá verificar se os arquivos são copiados para o computador de teste. Verifique se os arquivos .inf, .cat, test cert e .sys e quaisquer outros arquivos necessários estão presentes na pasta \drivertest\drivers do %systemdrive%.

    Para obter mais informações sobre como implantar drivers, consulte Implantando um driver em um computador de teste.

Instalar o driver

Com o driver KMDF implantado no computador de destino, agora você instalará o driver. Quando você provisionou anteriormente o computador de destino com o Visual Studio usando a opção automática, o Visual Studio configurou o computador de destino para executar drivers assinados de teste como parte do processo de provisionamento. Agora você só precisa instalar o driver usando a ferramenta DevCon.

  1. No computador host, navegue até a pasta Ferramentas na instalação do WDK e localize a ferramenta DevCon. Por exemplo, examine a seguinte pasta:

    C:\Program Files (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Copie a ferramenta DevCon para seu computador remoto.

  2. No computador de destino, instale o driver navegando até a pasta que contém os arquivos de driver e executando a ferramenta DevCon.

    1. Aqui está a sintaxe geral da ferramenta de desenvolvimento que você usará para instalar o driver:

      instalar devcon <arquivo INF><ID de hardware>

      O arquivo INF necessário para instalar esse driver é KmdfDriver.inf. O arquivo INF contém a ID de hardware para instalar o binário do driver, KmdfDriver.sys. Lembre-se de que a ID de hardware, localizada no arquivo INF, é Root\KmdfDriver.

    2. Abra uma janela do Prompt de Comando como Administrador. Navegue até a pasta do pacote do driver e, em seguida, insira este comando:

      instalar devcon kmdfdriver.inf root\kmdfdriver

      Se você obtiver uma mensagem de erro sobre devcon não reconhecida, tente adicionar o caminho para a ferramenta devcon. Por exemplo, se você copiá-la para uma pasta no computador de destino chamada C:\Tools, tente usar o seguinte comando:

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Uma caixa de diálogo aparecerá indicando que o driver de teste é um driver não assinado. Selecione Instalar esse driver de qualquer maneira continuar.

      captura de tela do aviso de instalação do driver.

Depurar o driver

Agora que instalou o driver KMDF no computador de destino, você conectará um depurador remotamente do computador host.

  1. No computador host, abra uma janela do Prompt de Comando como Administrador. Mude para o diretório WinDbg.exe. Usaremos a versão x64 do WinDbg.exe do Windows Driver Kit (WDK) que foi instalada como parte da instalação do kit do Windows. Este é o caminho padrão para WinDbg.exe:

    C:\Arquivos de Programas (x86)\Windows Kits\10\Depuradores\x64

  2. Inicie o WinDbg para se conectar a uma sessão de depuração de kernel no computador de destino usando o comando a seguir. O valor da porta e da chave deve ser o mesmo que você usou para provisionar o computador de destino. Usaremos 50000 para a porta e 1.2.3.4 para a chave, os valores que usamos durante a etapa de implantação. O sinalizador k indica que esta é uma sessão de depuração de kernel.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. No menu Depurar, escolha Interromper. O depurador no computador host invadirá o computador de destino. Na janela Comando do Depurador, você pode ver o prompt de comando de depuração do kernel: kd>.

  4. Neste ponto, você pode experimentar o depurador inserindo comandos no prompt kd>. Por exemplo, você pode experimentar estes comandos:

  5. Para permitir que o computador de destino seja executado novamente, escolha Ir no menu Depurar ou pressione "g" e "enter".

  6. Para interromper a sessão de depuração, escolha Desanexar Debuggee do menu Depurar.

    Importante

    Certifique-se de usar o comando "go" para permitir que o computador de destino volte a funcionar antes de sair do depurador, ou o computador de destino permanecerá sem resposta à entrada do mouse e teclado, pois ainda estará se comunicando com o depurador.

Para obter um passo a passo detalhado do processo de depuração do driver, consulte Depuração de Drivers Universais - Laboratório Passo a Passo (Echo Kernel-Mode).

Para obter mais informações sobre depuração remota, consulte Depuração Remota usando o WinDbg.

Usando o DMF (Driver Module Framework)

O DMF (Driver Module Framework) é uma extensão do WDF que permite funcionalidade extra para um desenvolvedor de driver do WDF. Ele ajuda os desenvolvedores a escrever qualquer tipo de driver WDF melhor e mais rápido.

O DMF como uma estrutura permite a criação de objetos WDF chamados Módulos DMF. O código desses módulos DMF pode ser compartilhado entre drivers diferentes. Além disso, o DMF agrupa uma biblioteca de módulos DMF que desenvolvemos para nossos drivers e achamos que forneceria valor para outros desenvolvedores de driver.

O DMF não substitui o WDF. O DMF é uma segunda estrutura usada com o WDF. O desenvolvedor que aproveita o DMF ainda usa o WDF e todos os seus primitivos para gravar drivers de dispositivo.

Para obter mais informações, consulte DMF (Driver Module Framework).