Como escrever seu primeiro driver de cliente USB (UMDF)

Neste artigo, você usará o modelo Driver de modo de usuário, USB (UMDF V2) fornecido com o Microsoft Visual Studio 2022 para escrever um driver de cliente baseado em estrutura de driver de modo de usuário (UMDF). 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.

UMDF (referido como a estrutura neste artigo) é baseado no modelo de objeto componente (COM). Cada objeto de estrutura deve implementar IUnknown e seus métodos, QueryInterface, AddRef e Release, por padrão. Os métodos AddRef e Release gerenciam o tempo de vida do objeto, portanto, o driver do cliente não precisa manter a contagem de referência. O método QueryInterface permite que o driver de cliente obtenha ponteiros de interface para outros objetos de estrutura no modelo de objeto WDF (Windows Driver Frameworks). Os objetos Framework executam tarefas de driver complicadas e interagem com o Windows. Certos objetos de estrutura expõem interfaces que permitem que um driver de cliente interaja com a estrutura.

Um driver de cliente baseado em UMDF é implementado como um servidor COM (DLL) em processo e C++ é a linguagem preferida para escrever um driver de cliente para um dispositivo USB. Normalmente, o driver do cliente implementa várias interfaces expostas pela estrutura. Este artigo refere-se a uma classe definida pelo cliente de driver que implementa interfaces de framework como uma classe de retorno de chamada. Depois que essas classes são instanciadas, os objetos de retorno de chamada resultantes são associados a objetos de estrutura específicos. Essa parceria dá ao motorista do cliente a oportunidade de responder a eventos relacionados ao dispositivo ou ao sistema relatados pela estrutura. Sempre que o Windows notifica o framework sobre determinados eventos, o framework invoca o callback do driver do cliente, se houver um disponível. Caso contrário, a estrutura prossegue com o processamento padrão do evento. O código do modelo define classes de retorno de chamada de driver, dispositivo e fila.

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

Antes de começar

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

• Um computador host executando o Windows 10 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 executando a versão do sistema operacional em que você deseja testar seu driver, por exemplo, Windows 11, versão 22H2. O computador de destino tem o controlador em modo de utilizador que você deseja depurar e um dos programas de depuração.

Em alguns casos, quando os computadores host e de destino estão executando a mesma versão do Windows, você pode ter apenas um computador executando o Windows 10 ou uma versão posterior do Windows. Este artigo pressupõe que você esteja usando dois computadores para desenvolver, depurar e instalar o driver do modo de usuário.

Antes de começar, certifique-se de que cumpre os seguintes requisitos:

Requisitos de software

• Seu computador host tem o Visual Studio 2022.

• O seu computador anfitrião tem o Kit de Driver do Windows (WDK) mais recente para Windows 11, versão 22H2.

  O kit inclui cabeçalhos, bibliotecas, ferramentas, documentação e as ferramentas de depuração necessárias para desenvolver, construir e depurar um driver de cliente USB. Você pode obter a versão mais recente do WDK em Como obter o 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.

• Se você estiver usando dois computadores, deverá configurar os computadores host e de destino para depuração no modo de usuário. Para obter mais informações, consulte Configuração da depuração User-Mode 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ê é novo no desenvolvimento de drivers USB, use o kit de aprendizado OSR USB FX2 para estudar amostras USB incluídas com o WDK. Ele contém o dispositivo USB FX2 e todas as especificações de hardware necessárias para implementar um driver de cliente.

Leitura recomendada

• Conceitos para todos os desenvolvedores de drivers
• Nós de dispositivo e pilhas de dispositivos
• Introdução aos drivers no Windows
• User-Mode Estrutura de Controladores
• Desenvolvimento de Drivers com a Windows Driver Foundation, escrito por Penny Orwick e Guy Smith. Para obter mais informações, consulte Desenvolvendo controladores com WDF.

Etapa 1: Gerar o código do driver

Para obter detalhes sobre como escrever código de driver UMDF, consulte Escrevendo um driver UMDF com base em um modelo.

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

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 de usuário, USB (UMDF V2).
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 driver USB User-Mode.

Este artigo pressupõe que o nome do projeto é MyUSBDriver_UMDF_. Ele contém os seguintes arquivos:

Etapa 2: adicionar informações sobre seu dispositivo

Antes de criar o driver, você deve adicionar informações sobre seu dispositivo, especificamente o ID de hardware. Para fornecer o ID do hardware:

1. Na janela Gerenciador de Soluções , clique com o botão direito do mouse em MyUSBDriver_UMDF_ e escolha Propriedades.
2. Na janela MyUSBDriver_UMDF_ Property Pages , vá para Configuration Properties > Driver Install > Deployment, conforme mostrado aqui.
3. Verifique Remover versões anteriores do driver antes de implantação.
4. Para Nome do Dispositivo de Destino, selecione o nome do computador que você configurou para teste e depuração.
5. Selecione Atualização de Driver por ID de Hardwaree insira o ID de Hardware para o seu driver. Neste exercício, o ID de hardware é Root\MyUSBDriver_UMDF_. Selecione OK.

Todos os drivers de cliente USB baseados em UMDF exigem dois drivers fornecidos pela Microsoft, o refletor e o WinUSB.

• Refletor: Se o driver for carregado com sucesso, o refletor será carregado como o driver mais alto na pilha do modo kernel. O refletor deve ser o driver superior na pilha do modo kernel. Para atender a esse requisito, o arquivo INF do modelo especifica o refletor como um serviço e o WinUSB como um driver de filtro inferior no INF:

  [MyDevice_Install.NT.Services]
  AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall  ; flag 0x2 sets this as the service for the device
  AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall  ; this service is installed because its a filter.
  

• WinUSB: O pacote de instalação deve conter co-instaladores para Winusb.sys, pois, para o driver do cliente, o WinUSB é a porta de entrada para a pilha de drivers USB em modo kernel. Outro componente que é carregado é uma DLL de modo de usuário, chamada WinUsb.dll, no processo de host do driver do cliente (Wudfhost.exe). Winusb.dll expõe funções WinUSB que simplificam o processo de comunicação entre o driver do cliente e WinUSB.

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 2022.
2. Clique com o botão direito do rato na solução no Solution Explorer e selecione Configuration Manager.
3. No Configuration Manager, selecione sua Configuração de Solução Ativa (por exemplo, Depuração ou Versão) e sua Plataforma de Solução Ativa (por exemplo, x64) que correspondam ao tipo de compilação em que você está interessado.
4. Verifique se o GUID da interface do dispositivo está correto durante todo o projeto.
   • O GUID da interface do dispositivo é definido em Trace.h e é referenciado no ficheiro MyUSBDriverUMDFCreateDevice em Device.c. Quando você cria seu projeto com o nome MyUSBDriver_UMDF_, o Visual Studio 2022 define o GUID da interface do dispositivo com o nome GUID_DEVINTERFACE_MyUSBDriver_UMDF_ , mas chama WdfDeviceCreateDeviceInterface com o parâmetro &GUID_DEVINTERFACE_MyUSBDriverUMDFincorreto. Substitua o parâmetro incorreto pelo nome definido em Trace.h para garantir que o driver seja compilado corretamente.
5. 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: Ativar 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 o computador host para o rastreio de 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\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.

   Há três arquivos no local especificado, um por arquivo de código C no projeto. Eles recebem nomes de arquivo GUID.

2. No depurador, digite os seguintes comandos:

   .load Wmitrace
   .chain
   !wmitrace.searchpath + <TMF file location>
   

Estes comandos:

• Carregue extensão Wmitrace.dll.
• Verifica se a extensão do depurador está carregada.
• Adiciona a localização dos arquivos TMF ao caminho de pesquisa 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 rastreamento WPP

1. Certifique-se de que tem a ferramenta Tracelog no computador de destino. A ferramenta está localizada na <pasta de instalação install_folder>Windows Kits\10\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 2022. 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 , clique com o botão direito do mouse no nome do projeto (MyUSBDriver_UMDF_) e escolha Propriedades.
2. No painel esquerdo, navegue até Configuration Properties > Driver Install > Deployment.
3. Em Nome do dispositivo de destino, especifique o nome do computador de destino.
4. Selecione #B0 Instalar/Reinstalar e verifique #A1 .
5. Selecione OK.
6. No menu Depurar, escolha Iniciar Depuraçãoou pressione F5 no teclado.

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 mostra o seguinte nó.

   Dispositivo USB

   MyUSBDriver_UMDF_Device

Etapa 8: Exibir a saída no depurador

Verifique se as mensagens de rastreamento aparecem na janela imediata do depurador no computador host.

O resultado deve ser semelhante ao seguinte:

[0]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::OnPrepareHardware Entry
[0]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::OnPrepareHardware Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::CreateInstanceAndInitialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Initialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Initialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::CreateInstanceAndInitialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Configure Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::CreateInstanceAndInitialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::Initialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::Initialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::CreateInstanceAndInitialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Configure Exit

Observações

Vamos dar uma olhada em como a estrutura e o driver do cliente trabalham juntos para interagir com o Windows e lidar com solicitações enviadas para o dispositivo USB. Esta ilustração mostra os módulos carregados no sistema para um driver de cliente UMDF -based USB.

O objetivo de cada módulo é descrito aqui:

• Aplicativo — um processo de modo de usuário que emite solicitações de E/S para se comunicar com o dispositivo USB.
• Gerenciador de E/S — um componente do Windows que cria pacotes de solicitação de E/S (IRPs) para representar as solicitações de aplicativos recebidas e os encaminha para a parte superior da pilha de dispositivos do modo kernel para o dispositivo de destino.
• Refletor — um driver de modo kernel fornecido pela Microsoft instalado na parte superior da pilha de dispositivos do modo kernel (WUDFRd.sys). O refletor redireciona IRPs recebidos do gestor de E/S para o processo anfitrião do driver do cliente. Ao receber a solicitação, a estrutura e o driver do cliente lidam com a solicitação.
• Host process — o processo no qual o driver de modo de usuário é executado (Wudfhost.exe). Ele também hospeda a estrutura e o dispatcher de E/S.
• Driver do cliente — o driver de função de modo de usuário para o dispositivo USB.
• UMDF — o módulo de estrutura que lida com a maioria das interações com o Windows em nome do driver do cliente. Ele expõe as interfaces de driver de dispositivo (DDIs) de modo de usuário que o driver de cliente pode usar para executar tarefas comuns de driver.
• Dispatcher — mecanismo que é executado no processo do host; Determina como encaminhar uma solicitação para o modo kernel depois que ela foi processada pelos drivers do modo de usuário e atingiu a parte inferior da pilha do modo de usuário. Na ilustração, o dispatcher encaminha a solicitação para a DLL de modo de usuário, Winusb.dll.
• Winusb.dll — uma DLL de modo de usuário fornecida pela Microsoft que expõe funções WinUSB que simplificam o processo de comunicação entre o driver do cliente e WinUSB (Winusb.sys, carregado no modo kernel).
• Winusb.sys — um driver fornecido pela Microsoft que é exigido por todos os drivers de cliente UMDF para dispositivos USB. O driver deve ser instalado em baixo do refletor e serve como a porta de entrada para a pilha de drivers USB em modo núcleo. Para obter mais informações, consulte Introdução ao WinUSB para desenvolvedores.
• Pilha de drivers USB — um conjunto de drivers, fornecidos pela Microsoft, que lidam com a comunicação em nível de protocolo com o dispositivo USB. Para obter mais informações, consulte Drivers USB do lado do host no Windows.

Sempre que um aplicativo faz uma solicitação para a pilha de drivers USB, o gerenciador de E/S do Windows envia a solicitação para o refletor, que a direciona para o driver do cliente no modo de usuário. O driver do cliente lida com a solicitação chamando métodos UMDF específicos, que chamam internamente as funções WinUSB para enviar a solicitação para o WinUSB. Ao receber a solicitação, o WinUSB processa a solicitação ou a encaminha para a camada de drivers USB.

Tópicos relacionados

• Noções básicas sobre o código de modelo UMDF para driver de cliente USB
• Como ativar a suspensão seletiva USB e o despertar do sistema no driver UMDF para um dispositivo USB
• Introdução ao desenvolvimento de drivers de cliente USB