Compartilhar via

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 KMDF (Kernel-Mode Driver Framework). Você começará com um modelo do Microsoft Visual Studio e, em seguida, implantará e instalará o driver em um computador separado.

Antes de continuar, você precisará seguir as etapas de instalação listadas em Baixar o WDK (Kit de Driver do Windows).

As Ferramentas de Depuração para Windows são incluídas quando você instala o WDK.

Criar e criar 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 intermediária e escolha Driver na lista suspensa à direita.

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

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

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

    Observação

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

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

  6. Marque 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. Veja-os na janela Gerenciador de Soluções. (Se a janela Gerenciador de Soluções não estiver visível, escolha Gerenciador de Soluções no menu Exibir.) 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 lugares 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 >> Gerais do Driver e observe que a Plataforma de Destino usa como padrão Universal .

  8. Para criar 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 do build inclui:

    >    Driver is 'Universal'.

    Depois de verificar se a solução foi criada com êxito, você pode fechar o Visual Studio.

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

    • KmdfDriver.sys – o arquivo de driver do 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 host e 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 depuração. Neste exemplo, usaremos 50000 como a porta e 1.2.3.4 como a chave.

    Em cenários reais de depuração de driver, é recomendável 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 Depurar Drivers – 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) o projeto KmdfDriver e escolha Propriedades.

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

  5. Marque 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 do 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 de páginas de propriedades do pacote kmdfdriver, mostrando a instalação do driver de implantação selecionada

    Observação

    Neste exercício, a ID de hardware não identifica uma parte real do hardware. Ele identifica um dispositivo imaginário que receberá um local na árvore de dispositivos como um filho do nó raiz. Para hardware real, não selecione Atualização de 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, acesse Arquivos de Driver do KmdfDriver > 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 alguns minutos.

    Quando você implanta um driver, os arquivos de driver são copiados para a pasta %Systemdrive%\drivertest\drivers no computador de teste. Se algo der errado durante a implantação, você poderá marcar para ver 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 %systemdrive%\drivertest\drivers.

    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:\Arquivos de Programas (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, em seguida, executando a ferramenta DevCon.

    1. Esta é a sintaxe geral para a ferramenta devcon que você usará para instalar o driver:

      devcon install <INF file><hardware ID>

      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 de driver e insira este comando:

      devcon install kmdfdriver.inf root\kmdfdriver

      Se você receber uma mensagem de erro sobre o devcon não ser reconhecido, tente adicionar o caminho à ferramenta devcon . Por exemplo, se você copiou 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 será exibida indicando que o driver de teste é um driver sem sinal. Selecione Instalar este driver de qualquer maneira para 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ê anexará um depurador remotamente do computador host.

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

    C:\Arquivos de Programas (x86)\Kits do Windows\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 pressione "enter".

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

    Importante

    Use o comando "ir" para permitir que o computador de destino seja executado novamente antes de sair do depurador ou se o computador de destino permanecerá sem resposta à entrada do mouse e do teclado porque ele ainda está falando com o depurador.

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

Para obter mais informações sobre depuração remota, consulte Depuração remota usando 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 para esses 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. 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).