Como escrever seu primeiro driver de cliente USB (KMDF)

Neste artigo, você usará o modelo de Driver do Modo Kernel para USB fornecido com o Microsoft Visual Studio para escrever um driver de cliente com base na KMDF (estrutura de driver de modo kernel) simples. Depois de criar e instalar o driver do cliente, você exibirá o driver do cliente no Gerenciador de Dispositivos e exibirá a saída do driver em um depurador.

Para obter uma explicação sobre o código-fonte gerado pelo modelo, consulte Noções básicas sobre o código do modelo KMDF para driver do cliente USB.

Pré-requisitos

Para desenvolver, depurar e instalar um driver de modo kernel, você precisa de dois computadores:

• Um computador host executando o Windows 7 ou uma versão posterior do sistema operacional Windows. O computador host é o ambiente de desenvolvimento, onde você escreve e depura o driver.
• Um computador de destino executando o Windows Vista ou uma versão posterior do Windows. O computador de destino tem o driver de modo kernel que você deseja depurar.

Antes de começar, certifique-se de que você atende aos seguintes requisitos:

Requisitos de software

• Seu computador host hospeda seu ambiente de desenvolvimento e tem o Visual Studio.
• Seu computador host tem o WDK (Windows Driver Kit) mais recente. O kit tem cabeçalhos, bibliotecas, ferramentas, documentação e as ferramentas de depuração necessárias para desenvolver, compilar e depurar um driver do cliente KMDF. Para obter a versão mais recente do WKD, consulte Baixar o Kit de Driver do Windows (WDK).
• Seu computador host tem a versão mais recente das ferramentas de depuração para Windows. Você pode obter a versão mais recente do WDK ou Baixar e instalar ferramentas de depuração para Windows.
• Seu computador de destino está executando o Windows Vista ou uma versão posterior do Windows.
• Os computadores host e de destino estão configurados para depuração de kernel. Para obter mais informações, consulte Configurando uma conexão de rede no Visual Studio.

Requisitos de hardware

Obtenha um dispositivo USB para o qual você escreverá o driver do cliente. Na maioria dos casos, você recebe um dispositivo USB e sua especificação de hardware. A especificação descreve os recursos do dispositivo e os comandos do fornecedor suportados. Use a especificação para determinar a funcionalidade do driver USB e as decisões de design relacionadas.

Se você não estiver familiarizado com o desenvolvimento de driver USB, use o kit de aprendizado OSR USB FX2 para estudar exemplos de USB incluídos no WDK. Você pode obter o kit de aprendizagem no OSR Online. Ele contém o dispositivo USB FX2 e todas as especificações de hardware necessárias para implementar um driver do cliente.

Você também pode obter dispositivos MUTT (Microsoft USB Test Tool). O hardware MUTT pode ser adquirido na JJG Technologies. O dispositivo não tem o firmware instalado. Para instalar o firmware, baixe o pacote de software deste site e execute o arquivo MUTTUtil.exe. Para obter mais informações, consulte a documentação incluída com o pacote.

Leitura recomendada

• Conceitos para todos os desenvolvedores de drivers
• Nós de dispositivo e pilhas de dispositivos
• Introdução a drivers no Windows
• Estrutura de driver do modo kernel
• Como desenvolver drivers com o Windows Driver Foundation escrito por Penny Orwick e Guy Smith. Para obter mais informações, consulte Como desenvolver drivers com o WDF.

Etapa 1: gerar o código do driver KMDF usando o modelo de driver USB do Visual Studio

Para obter instruções sobre como gerar código de driver KMDF, consulte as etapas em Como escrever um driver KMDF com base em um modelo.

Para código específico de USB, selecione as seguintes opções no Visual Studio:

1. Na caixa de diálogo Novo Projeto, na caixa de pesquisa na parte superior, digite USB.
2. No painel do meio, selecione Driver do Modo Kernel, USB (KMDF).
3. Selecione Avançar.
4. Digite um nome de projeto, escolha um local de gravação e selecione Criar.

As capturas de tela a seguir mostram a caixa de diálogo Novo Projeto para o modelo de Driver do Modo Kernel para USB.

Este artigo pressupõe que o nome do projeto do Visual Studio é "MyUSBDriver_". Ele contém os seguintes arquivos:

Arquivos	Descrição
Public.h	Fornece declarações comuns compartilhadas pelo driver do cliente e aplicativos de usuário que se comunicam com o dispositivo USB.
<Nome do projeto>.inf	Contém as informações necessárias para instalar o driver do cliente no computador de destino.
Trace.h	Declara funções de rastreamento e macros.
Driver.h; Driver.c	Declara e define pontos de entrada de driver e rotinas de retorno de chamada de evento.
Device.h; Device.c	Declara e define a rotina de retorno de chamada de evento para o evento prepare-hardware.
Queue.h; Queue.c	Declara e define uma rotina de retorno de chamada de evento para o evento gerado pelo objeto da fila da estrutura.

Etapa 2: modificar o arquivo INF para adicionar informações sobre seu dispositivo

Antes de criar o driver, você deve modificar o arquivo INF de modelo com informações sobre seu dispositivo, especificamente a cadeia de caracteres de ID de hardware.

No Gerenciador de Soluções, em Arquivos de Driver, clique duas vezes no arquivo INF.

No arquivo INF, é possível fornecer informações como o nome do fabricante e do provedor, a classe de configuração do dispositivo e assim por diante. Uma informação que você deve fornecer é o identificador de hardware do seu dispositivo.

Para fornecer a cadeia de caracteres de ID de hardware:

1. Anexe seu dispositivo USB ao computador host e deixe o Windows enumerar o dispositivo.

2. Abra o Gerenciador de Dispositivos e as propriedades do seu dispositivo.

3. Na guia Detalhes, selecione IDs de Hardware em Propriedade.

   A ID de hardware do dispositivo é exibida na caixa de listagem. Selecione e segure (ou clique com o botão direito do mouse) e copie a cadeia de caracteres de ID de hardware.

4. Substitua USB\VID_vvvv&PID_pppp na linha a seguir pela cadeia de caracteres de ID de hardware.

   [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Etapa 3: criar o código do driver do cliente USB

Para criar seu driver:

1. Abra o projeto de driver ou uma solução no Visual Studio
2. Selecione e segure (ou clique com o botão direito do mouse) a solução no Gerenciador de Soluções e selecione Gerenciador de Configurações.
3. No Gerenciador de Configurações, selecione a Configuração da Solução Ativa (por exemplo, Depurar ou Liberar) e a Plataforma de Solução Ativa (por exemplo, Win32) que corresponde ao tipo de build em que você está interessado.
4. No menu Compilar, selecione Compilar Solução.

Para obter mais informações, consulte Como criar um Driver.

Etapa 4: configurar um computador para teste e depuração

Para testar e depurar um driver, execute o depurador no computador host e o driver no computador de destino. Até agora, você usou o Visual Studio no computador host para criar um driver. Em seguida, você precisa configurar um computador de destino. Para configurar um computador de destino, siga as instruções em Provisionar um computador para implantação e teste de driver.

Etapa 5: habilitar o rastreamento para depuração de kernel

O código do modelo contém várias mensagens de rastreamento (TraceEvents) que podem ajudar você a rastrear chamadas de função. Todas as funções no código-fonte contêm mensagens de rastreamento que marcam a entrada e a saída de uma rotina. Para erros, a mensagem de rastreamento contém o código de erro e uma cadeia de caracteres significativa. Como o rastreamento de WPP está habilitado para seu projeto de driver, o arquivo de símbolo PDB criado durante o processo de build contém instruções de formatação de mensagem de rastreamento. Se você configurar os computadores host e de destino para rastreamento WPP, o driver poderá enviar mensagens de rastreamento para um arquivo ou para o depurador.

Para configurar seu computador host para rastreamento de WPP:

1. Crie arquivos de formato de mensagem de rastreamento (TMF) extraindo instruções de formatação de mensagem de rastreamento do arquivo de símbolo PDB.

   Você pode usar Tracepdb.exe para criar arquivos TMF. A ferramenta está localizada na <pasta de instalação>Windows Kits\10.0\bin\<architecture> do WDK. O comando a seguir cria arquivos TMF para o projeto de driver.

   tracepdb -f <PDBFiles> -p <TMFDirectory>

   A opção -f especifica o local e o nome do arquivo de símbolo PDB. A opção -p especifica o local dos arquivos TMF criados pelo Tracepdb. Para obter mais informações, consulte Comandos Tracepdb.

   No local especificado, você verá três arquivos (um por arquivo .c no projeto). Eles recebem nomes de arquivo GUID.

2. No depurador, digite os seguintes comandos:

   1. .load Wmitrace

      Carrega a extensão Wmitrace.dll.

   2. .chain

      Verifica se a extensão do depurador está carregada.

   3. !wmitrace.searchpath +<Local do arquivo TMF>

      Adiciona o local dos arquivos TMF ao caminho de pesquisa da extensão do depurador.

      A saída será semelhante a esta:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Para configurar seu computador de destino para rastreamento de WPP:

1. Verifique se você tem a ferramenta Tracelog no computador de destino. A ferramenta está localizada em <install_folder>Windows Kits\8.0\Tools\<arch> do WDK. Para obter mais informações, consulte Sintaxe do comando Tracelog.

2. Abra uma Janela de Comando e execute como administrador.

3. Digite o seguinte comando:

   tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

   O comando inicia uma sessão de rastreamento chamada MyTrace.

   O argumento guid especifica o GUID do provedor de rastreamento, que é o driver do cliente. Você pode obter o GUID de Trace.h no projeto do Visual Studio Professional 2019. Como outra opção, você pode digitar o comando a seguir e especificar o GUID em um arquivo .guid. O arquivo contém o GUID no formato de hífen:

   tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

   Você pode interromper a sessão de rastreamento digitando o seguinte comando:

   tracelog -stop MyTrace

Etapa 6: implantar o driver no computador de destino

1. Na janela Gerenciador de Soluções mantenha selecionado (ou clique com o botão direito do mouse) o projeto de pacote, o *<nome do projeto>*Pacote e escolha Propriedades.
2. No painel esquerdo, navegue até Propriedades de Configuração > Instalação do Driver > Implantação.
3. Marque Habilitar implantação e marque Importar para o repositório de drivers.
4. Para Nome do Computador Remoto, especifique o nome do computador de destino.
5. Selecione Instalar e verificar.
6. Selecione Ok.
7. No menu Depurar, escolha Iniciar Depuração ou pressione F5 no teclado.

Observação

Não especifique a ID de hardware do seu dispositivo em Atualização de driver de ID de hardware. A ID de hardware deve ser especificada apenas no arquivo INF de informações do driver.

Para obter mais informações sobre como implantar o driver no sistema de destino no Visual Studio, consulte Como implantar um driver em um computador de teste.

Você também pode instalar manualmente o driver no computador de destino usando o Gerenciador de Dispositivos. Se quiser instalar o driver a partir de um prompt de comando, estes utilitários estão disponíveis:

• PnPUtil

  Esta ferramenta vem com o Windows. Está em Windows\System32. Você pode usar esse utilitário para adicionar o driver ao repositório de drivers.

  C:\>pnputil /a m:\MyDriver_.inf
  Microsoft PnP Utility
  
  Processing inf : MyDriver_.inf
  Driver package added successfully.
  Published name : oem22.inf
  

  Para obter mais informações, consulte PnPUtil Examples.

• DevCon Update

  Essa ferramenta vem com o WDK. Você pode usá-la para instalar e atualizar drivers.

  devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6
  

Etapa 7: visualizar o driver no Gerenciador de dispositivos

1. Digite o seguinte comando para abrir o Gerenciador de Dispositivos:

   devmgmt
   

2. Verifique se o Gerenciador de dispositivos mostra um nó para o seguinte nó:

   Amostras

   MyUSBDriver_Device

Etapa 8: exibir a saída no depurador

O Visual Studio primeiro exibe o andamento na janela Saída. Em seguida, ele abre a Janela Imediata do Depurador. Verifique se as mensagens de rastreamento aparecem no depurador no computador host. A saída deve ser semelhante a esta, onde "MyUSBDriver_" é o nome do módulo de driver:

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit

Tópicos relacionados

• Noções básicas sobre o código do modelo KMDF para um driver do cliente USB
• Introdução ao desenvolvimento do driver de cliente USB