Partilhar via

Como escrever seu primeiro driver de cliente USB (KMDF)

Neste artigo, usará o modelo de driver USB Kernel-Mode fornecido com o Microsoft Visual Studio para escrever um driver de cliente simples baseado no KMDF (kernel-mode driver framework). Depois de criar e instalar o driver do cliente, você visualizará o driver do cliente no Gerenciador de dispositivos e visualizará 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 um driver de 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 é seu ambiente de desenvolvimento, onde você escreve e depura seu driver.
  • Um computador de destino que executa 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 cumpre os seguintes requisitos:

Requisitos de software

  • Seu computador host hospeda seu ambiente de desenvolvimento e tem o Visual Studio.
  • Seu computador host tem o Kit de Driver do Windows (WDK) mais recente. O kit inclui cabeçalhos, bibliotecas, ferramentas, documentação e as ferramentas de depuração necessárias para desenvolver, criar e depurar um driver KMDF. Para obter a versão mais recente do WDK, 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 pode Baixar e instalar as Ferramentas de Depuração para Windows.
  • O computador de destino está executando o Windows Vista ou uma versão posterior do Windows.
  • Os seus computadores de origem e de destino estão configurados para depuração do 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ê estará escrevendo 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ê é novo no desenvolvimento de drivers USB, use o kit de aprendizado OSR USB FX2 para estudar amostras USB incluídas com o WDK. Você pode obter o kit de aprendizagem de OSR Online. Ele contém o dispositivo USB FX2 e todas as especificações de hardware necessárias para implementar um driver de cliente.

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

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 Escrevendo 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 central, selecione Driver do modo kernel, USB (KMDF).
  3. Selecione Seguinte.
  4. Insira um nome de projeto, escolha um local de guardar e selecione Criar.

As capturas de ecrã seguintes mostram a caixa de diálogo Novo Projeto para o modelo de controlador USB Kernel-Mode.

Novas opções de projeto do Visual Studio.

Visual Studio novas opções de projeto segunda tela.

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

Ficheiros Descrição
Public.h Fornece declarações comuns compartilhadas pelo driver cliente e aplicativos de usuário que se comunicam com o dispositivo USB.
<Nome do projeto.inf> Contém 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 os pontos de entrada do driver e as rotinas de retorno de chamada para eventos.
Device.h; Device.c Declara e define a rotina de callback para o evento de preparação de hardware.
Queue.h; Queue.c Declara e define uma rotina de callback para o evento gerado pelo objeto de fila do framework.

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

Antes de criar o driver, você deve modificar o arquivo INF 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, você pode fornecer informações como o fabricante e o nome 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. Conecte o dispositivo USB ao computador host e deixe o Windows enumerar o dispositivo.

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

  3. Na guia Detalhes, selecione Ids de Hardware sob Propriedade.

    O ID de hardware do dispositivo é exibido 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 construir o seu driver:

  1. Abra o projeto ou solução de driver 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 Configuration Manager, selecione Ative Solution Configuration (por exemplo, Debug or Release) e Ative Solution Platform (por exemplo, Win32) que correspondem ao tipo de compilação em que você está interessado.
  4. No menu Build, selecione a opção Build Solution.

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

Etapa 4: Configurar um computador para testes e debugging

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 do kernel

O código do modelo contém várias mensagens de rastreamento (TraceEvents) que podem ajudá-lo a rastrear chamadas de função. Todas as funções no código-fonte contêm mensagens de rastreamento que marcam a entrada e 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 WPP está habilitado para seu projeto de driver, o arquivo de símbolo PDB criado durante o processo de compilação contém instruções de formatação de mensagem de rastreamento. Se configurar os computadores host e de destino para traçamento WPP, o seu driver pode enviar mensagens de traçamento para um ficheiro ou para o debugger.

Para configurar seu computador host para rastreamento WPP:

  1. Crie arquivos TMF (formato de mensagem de rastreamento) 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> pasta 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 do PDB. A opção -p especifica o local para os 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

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

    3. !wmitrace.searchpath +Localização <do ficheiro TMF>

      Adicione a localização dos arquivos TMF ao caminho de procura da extensão do depurador.

      A saída é semelhante ao seguinte:

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

Para configurar o computador de destino para o rastreamento do WPP:

  1. Certifique-se de que tem a ferramenta Tracelog no computador de destino. A ferramenta pode ser encontrada na <pasta install_folder>Windows Kits\8.0\Tools\<arch> do WDK. Para obter mais informações, consulte Sintaxe de 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 Visual Studio Professional 2019. Como outra opção, você pode digitar o seguinte comando e especificar o GUID em um arquivo .guid. O arquivo contém o GUID em formato de hífen:

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

    Você pode parar 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 , selecione e mantenha pressionado (ou clique com o botão direito do mouse) o *<nome> do projeto*Pacote e escolha Propriedades.
  2. No painel esquerdo, navegue até Configuration Properties > Driver Install > Deployment.
  3. Marque Habilitar implantação e marque Importar para o repositório de drivers.
  4. Em 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çãoou pressione F5 no teclado.

Observação

Não especifique o ID de hardware do seu dispositivo em Atualização de driver de ID de hardware. O ID do hardware deve ser especificado somente no arquivo de informações do driver (INF).

Para obter mais informações sobre como implantar o driver no sistema de destino no Visual Studio, consulte Implantando 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 você 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 este 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 Exemplos de PnPUtil.

  • Atualização do DevCon

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

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

Etapa 7: Exibir o driver no Gerenciador de dispositivos

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

    devmgmt

  2. Verifique se o Gestor de Dispositivos apresenta um nó para o seguinte elemento:

    Amostras

    MyUSBDriver_Device

Etapa 8: Exibir a saída no depurador

O Visual Studio primeiro exibe o progresso na janela Saída . Em seguida, abre a janela Imediata do Depurador. Verifique se as mensagens de rastreio aparecem no depurador no computador host. A saída deve ter esta aparência, 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