Partilhar via

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

Este artigo descreve como escrever um driver universal para Windows usando Kernel-Mode Driver Framework (KMDF). Começas com um modelo Microsoft Visual Studio e depois implementas e instalas o driver num computador separado.

Pré-requisitos

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

  • Instale Visual Studio 2022. Ao instalar o Visual Studio 2022, selecione o Desenvolvimento de área de trabalho com C++ workload e, em seguida, em Componentes individuais, adicione:

    • MSVC v143 - VS 2022 C++ ARM64/ARM64EC bibliotecas mitigadas contra a vulnerabilidade Spectre (Mais recente)
    • MSVC v143 - VS 2022 C++ x64/x86 bibliotecas mitigadas contra Spectre (Mais recente)
    • C++ ATL para as mais recentes ferramentas de compilação v143 com Spectre Mitigations (ARM64/ARM64EC)
    • C++ ATL para as mais recentes ferramentas de compilação v143 com Spectre Mitigations (x86 & x64)
    • C++ MFC para as mais recentes ferramentas de compilação v143 com Spectre Mitigations (ARM64/ARM64EC)
    • C++ MFC para as mais recentes ferramentas de compilação v143 com mitigações do Spectre (x86 & x64)
    • Kit de Controladores do Windows

Criar e desenvolver um controlador

  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 no meio e escolha Driver na lista suspensa direita.

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

    Captura de tela da caixa de diálogo do novo 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 WDK Visual Studio não foi instalada corretamente. Para resolver este problema, inicie Visual Studio Installer, selecione Modificar, adicione Kits de Drivers do Windows na guia Componente Individual e selecione Modificar.

  4. Na caixa de diálogo Configurar o seu novo projeto, digite "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. Este 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.

    Visual Studio cria um projeto e uma solução. Você pode vê-los na janela Gerenciador de Soluções. (Se a janela do Explorador de Soluções não estiver visível, escolha Explorador de Soluções no menu Visualizar .) A solução tem um projeto de driver chamado KmdfDriver. Para ver o código-fonte do driver, abra qualquer um dos arquivos em Source Files. 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 de 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 define-se por padrão como Universal.

  8. Para construir o seu driver, escolha Build Solution no menu Build. O Microsoft Visual Studio exibe o progresso da compilação na janela Output. (Se a janela de Saída não estiver visível, escolha Saída no menu Visualizar .)

    Verifique se a saída da compilação inclui:

    >    Driver is 'Universal'.

    Quando verificares que a solução foi construída com sucesso, podes fechar o Visual Studio.

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

    • KmdfDriver.sys--o ficheiro do driver em modo kernel
    • KmdfDriver.inf — um ficheiro de informação que o Windows utiliza quando instala o driver

Instalar 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 mais informações sobre a depuração de drivers, consulte Ferramentas de depuração para Windows.

Até agora, usaste o Visual Studio para construir um driver no computador anfitrião. Agora você precisa configurar um computador de destino.

  1. Siga as instruções em Configurar um computador para implantação e teste de drivers (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. Usa-os mais tarde na fase de depuração. Neste exemplo, usamos 50000 como porta e 1.2.3.4 como chave.

    Em cenários reais de depuração de drivers, recomendamos o uso de uma chave gerada pelo KDNET. Para mais informações sobre como usar o KDNET para gerar uma chave aleatória, consulte o artigo Debug Drivers - Step by Step Lab (Sysvad Kernel Mode ).

  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 mantenha pressionado (ou clique com o botão direito do mouse) o projeto KmdfDriver e escolha Propriedades.

  4. Na janela KmdfDriver Package Property Pages, no painel esquerdo, vá para Propriedades de Configuração > Instalação de Drivers > Implantação.

  5. Verificar Remover versões anteriores do driver antes da implantação.

  6. Para Nome do Computador Remoto, selecione o nome do computador que configurou para testes e debugging. Neste exercício, usamos um computador chamado MyTestComputer.

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

    captura de ecrã da janela das páginas de propriedades do pacote kmdfdriver, com a instalação do driver de distribuição selecionado

    Observação

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

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

  8. No menu Build, escolha Implantar Solução. O Visual Studio copia automaticamente os arquivos necessários para instalar e executar o driver no computador de destino.

    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á 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.

Instale o controlador

Com o seu driver KMDF implementado no computador alvo, deve agora 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, procure na seguinte pasta:

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

    Copie a ferramenta DevCon para o computador remoto.

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

    1. Aqui está a sintaxe geral da ferramenta devcon que usas para instalar o driver:

      devcon instalar <ficheiro INF><ID de hardware>

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

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

      devcon instalar kmdfdriver.inf root\kmdfdriver

      Se receber uma mensagem de erro indicando que devcon não é reconhecido, tente adicionar o caminho da 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 instalar kmdfdriver.inf root\kmdfdriver

      Uma caixa de diálogo é exibida indicando que o driver de teste é um driver não assinado. Selecione Instalar este driver mesmo assim para continuar.

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

Depurar o driver

Agora que instalaste o driver KMDF no computador alvo, conecta um depurador remotamente a partir do computador host.

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

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

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

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

  3. No menu Depurar, escolha Interromper. O depurador no computador anfitrião interfere no computador de destino. Na janela Debugger Command, pode-se ver o prompt de comando de depuração do kernel: kd>.

  4. Neste ponto, podes experimentar com o depurador introduzindo comandos no prompt kd-> . Por exemplo, você pode tentar 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 Depurador no menu Depurar.

    Importante

    Certifica-te de que usas o comando "go" para deixar o computador alvo funcionar novamente antes de sair do depurador, caso contrário o computador alvo continua a não responder ao teu rato e teclado porque ainda está a falar com o depurador.

Para obter um guia passo a passo detalhado do processo de depuração do driver, consulte Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode).

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

Usando o Driver Module Framework (DMF)

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

DMF como uma estrutura permite a criação de objetos WDF chamados DMF Modules. O código para esses módulos DMF pode ser compartilhado entre diferentes drivers. Além disso, o DMF inclui uma biblioteca de módulos DMF que desenvolvemos para os nossos drivers e consideramos que poderiam trazer valor a outros desenvolvedores de drivers.

O DMF não substitui o WDF. DMF é uma segunda estrutura que é usada com WDF. O programador que usa DMF ainda usa o WDF e todas as suas primitivas para escrever drivers de dispositivos.

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

  • Last updated on