Portabilidade de um driver do UMDF 1 para o UMDF 2
Este tópico descreve como portar um driver do UMDF (User-Mode Driver Framework) 1 para o UMDF 2. Você pode começar com um driver UMDF 1 que usa arquivos Sources/Dirs (não um projeto do Visual Studio) ou pode converter um driver UMDF 1 contido em um projeto do Visual Studio. O resultado será um projeto de driver UMDF 2 no Visual Studio. Os drivers UMDF 2 são executados em Windows 10 para edições desktop (Home, Pro, Enterprise e Education) e Windows 10 Mobile.
O exemplo de driver echo é um exemplo de um driver que foi portado de UMDF 1 para UMDF 2.
Introdução
Para iniciar, abra um novo projeto de driver no Visual Studio. Selecione o modelo Driver do Visual C++->Windows> WDF-User> Mode Driver (UMDF 2). O Visual Studio abre um modelo parcialmente preenchido que inclui stubs para as funções de retorno de chamada que seu driver deve implementar. Esse novo projeto de driver será a base do driver UMDF 2. Use o exemplo de Eco UMDF 2 como um guia para o tipo de código que você deve introduzir.
Em seguida, examine o código do driver UMDF 1 existente e determine os mapeamentos de objetos. Cada objeto COM no UMDF 1 tem um objeto WDF correspondente no UMDF 2. Por exemplo, a interface IWDFDevice é mapeada para o objeto de dispositivo WDF, que é representado por um identificador WDFDEVICE. Quase todos os métodos de interface fornecidos pela estrutura no UMDF 1 têm métodos correspondentes no UMDF 2. Por exemplo, IWDFDevice::GetDefaultIoQueue mapeia para WdfDeviceGetDefaultQueue.
Da mesma forma, as funções de retorno de chamada fornecidas pelo driver têm equivalentes nas duas versões. No UMDF 1, a convenção de nomenclatura para interfaces fornecidas pelo driver (exceto para IDriverEntry) é IObjectCallbackXxx, enquanto no UMDF 2 a convenção de nomenclatura para rotinas fornecidas pelo driver é EvtObjectXxx. Por exemplo, o método de retorno de chamada IDriverEntry::OnDeviceAdd é mapeado para EvtDriverDeviceAdd.
Seu driver implementa funções de retorno de chamada no UMDF 1 e 2, mas a maneira como o driver fornece ponteiros para seus retornos de chamada é diferente. No UMDF 1, o driver implementa métodos de retorno de chamada como membros de interfaces fornecidas pelo driver. O driver registra essas interfaces com a estrutura quando cria objetos de estrutura, por exemplo, chamando IWDFDriver::CreateDevice.
No UMDF 2, o driver fornece ponteiros para funções de retorno de chamada fornecidas pelo driver em estruturas de configuração, como WDF_DRIVER_CONFIG e WDF_IO_QUEUE_CONFIG.
Gerenciando o tempo de vida do objeto
Os drivers que usam UMDF 1 devem implementar a contagem de referência para determinar quando é seguro excluir objetos. Como a estrutura rastreia referências de objeto em nome do driver, um driver UMDF 2 não precisa contar referências.
No UMDF 2, cada objeto de estrutura tem um objeto pai padrão. Quando um objeto pai é excluído, a estrutura exclui objetos filho associados. Quando o driver chama um método de criação de objeto, como WdfDeviceCreate, ele pode aceitar o pai padrão ou pode especificar um pai personalizado em uma estrutura WDF_OBJECT_ATTRIBUTES . Para obter uma lista de objetos de estrutura e seus objetos pai padrão, consulte Resumo de objetos de estrutura.
Inicialização do driver
Um driver UMDF 1 implementa a interface IDriverEntry . Em seu método de retorno de chamada IDriverEntry::OnDeviceAdd , o driver normalmente:
- Cria e inicializa uma instância do objeto de retorno de chamada do dispositivo.
- Cria o novo objeto de dispositivo de estrutura chamando IWDFDriver::CreateDevice.
- Configura as filas do dispositivo e seus objetos de retorno de chamada correspondentes.
- Cria uma instância de uma classe de interface de dispositivo chamando IWDFDevice::CreateDeviceInterface.
Um driver UMDF 2 implementa DriverEntry e EvtDriverDeviceAdd. Em sua rotina DriverEntry , um driver UMDF 2 normalmente chama WDF_DRIVER_CONFIG_INIT para inicializar a estrutura de WDF_DRIVER_CONFIG do driver. Em seguida, ele passa essa estrutura para WdfDriverCreate.
Em sua função EvtDriverDeviceAdd , o driver pode fazer algumas das seguintes ações:
- Preencha a estrutura WDFDEVICE_INIT , que fornece informações usadas para criar o objeto do dispositivo. Para obter mais informações sobre como usar WDFDEVICE_INIT, consulte Criando um objeto de dispositivo de estrutura.
- Configure a área de contexto do objeto de dispositivo. Para obter informações sobre como alocar e acessar o espaço de contexto para objetos de estrutura, consulte Espaço de Contexto de Objeto da Estrutura.
- Crie o objeto do dispositivo.
- Especifique manipuladores de solicitação para o objeto de dispositivo.
- Criar filas de E/S.
- Criar interfaces de dispositivo.
- Defina a política ociosa do dispositivo e as configurações de ativação, se o objeto do dispositivo possuir a política de energia.
- Crie objetos de interrupção, se o hardware der suporte a interrupções.
Instalando o driver
Quando você cria um novo projeto de driver no Visual Studio, o novo projeto contém um arquivo .inx. Quando você compila o driver, o Visual Studio compila o arquivo .inx em um arquivo INF que pode ser usado como parte de um pacote de driver.
Embora um arquivo INF para um driver UMDF 1 precise incluir uma ID de classe de driver, um DriverCLSID não é necessário em um arquivo INF para um driver UMDF 2.
Além disso, embora um driver UMDF 1 precise referenciar o co-instalador em seu arquivo INF, nenhuma referência de constaller é necessária em um arquivo INF UMDF 2. Embora uma referência de coinstaller possa aparecer em um arquivo INF para um driver UMDF 2, uma não é necessária.
Armazenando o contexto do dispositivo
No UMDF 1, o driver geralmente armazena o contexto do dispositivo em um objeto de retorno de chamada criado pelo driver, por exemplo, especificando membros privados da classe de objeto de retorno de chamada do dispositivo. Como alternativa, um driver UMDF 1 pode chamar o método IWDFObject::AssignContext para registrar o contexto em um objeto de estrutura.
No UMDF 2, a estrutura aloca espaço de contexto com base na estrutura de WDF_OBJECT_ATTRIBUTES opcional que o driver fornece quando chama um método de criação de objeto. Depois de chamar o método create de um objeto, um driver pode chamar WdfObjectAllocateContext uma ou mais vezes para alocar espaço de contexto adicional a um objeto específico. Para obter as etapas que um driver UMDF 2 deve usar para definir uma estrutura de contexto e um método acessador, consulte Espaço de Contexto de Objeto da Estrutura.
Depurando seu driver
Para depurar um driver UMDF 2, você usará extensões no Wdfkd.dll em vez de Wudfext.dll. Para obter mais informações sobre extensões no Wudfext.dll, consulte Resumo das Extensões do Depurador no Wdfkd.dll.
No UMDF 2, você também pode obter informações adicionais de depuração de driver por meio do INflight Trace Recorder (IFR), conforme descrito em Usando o Gravador de Rastreamento de Simulação em Drivers KMDF e UMDF 2. Além disso, você pode usar o próprio IFR ( Gravador de Voo ) da estrutura. Consulte Usando o Agente de Eventos da Estrutura.