Drivers de cliente HID de teclado e mouse

Este artigo descreve drivers de cliente HID de teclado e mouse. Teclados e mouses representam o primeiro conjunto de clientes HID que foram padronizados nas tabelas de uso HID e implementados em sistemas operacionais Windows.

Os drivers de cliente HID de teclado e mouse são implementados na forma de drivers de mapeador HID. Um driver de mapeador HID é um driver de filtro WDM de modo kernel que fornece uma interface bidirecional para solicitações de E/S entre um driver de classe não-HID e o driver de classe HID. O driver do mapeador mapeia as solicitações de E/S e os protocolos de dados de um para o outro.

O Windows fornece drivers de mapeador HID fornecidos pelo sistema para teclado HID e dispositivos de mouses HID.

Arquitetura e visão geral

A figura a seguir ilustra as pilhas de drivers fornecidas pelo sistema para dispositivos USB de teclado, mouse e touchpad.

A figura mostra os seguintes componentes:

• KBDHID.sys: Driver de mapeador de cliente HID para teclados. Converte os usos do HID em códigos de verificação para fazer interface com o driver de classe de teclado existente.
• MOUHID.sys: Driver de mapeador de cliente HID para mouses/touchpads. Converte os usos do HID em comandos do mouse (X/Y, botões, roda) para fazer interface com o driver de classe de teclado existente.
• KBDCLASS.sys: O driver de classe de teclado fornece funcionalidade para todos os teclados e teclados no sistema de forma segura.
• MOUCLASS.sys: O driver de classe de mouse fornece funcionalidade para todos os mouses e touchpads no sistema. O driver suporta dispositivos apontadores absolutos e relativos. MOUCLASS.sys não é o driver do Windows para telas sensíveis ao toque.
• HIDCLASS.sys: O driver da classe HID. O driver HID Class é a cola entre KBDHID.sys e MOUHID.sys clientes HID e vários transportes, como USB, Bluetooth e assim por diante.

O sistema cria a pilha de drivers da seguinte maneira:

• A pilha de transporte cria um objeto de dispositivo físico (PDO) para cada dispositivo HID conectado e carrega o driver de transporte HID apropriado, que por sua vez carrega o driver de classe HID.
• O driver de classe HID cria um PDO para cada TLC de teclado ou mouse. Dispositivos HID complexos (mais de um TLC) são expostos como vários PDOs criados pelo driver de classe HID. Por exemplo, um teclado com um mouse integrado pode ter uma coleção para os controles de teclado padrão e uma coleção diferente para o mouse.
• Os drivers de mapeador de cliente HID do teclado ou mouse são carregados no FDO apropriado.
• Os drivers do mapeador HID criam FDOs para teclado e mouse e carregam os drivers de classe.

Observações importantes

• Os drivers do fornecedor não são necessários para teclados e mouses compatíveis com os Usos HID e coleções de nível superior suportados.
• Os fornecedores opcionalmente fornecem drivers de filtro na pilha HID para alterar/aprimorar a funcionalidade desses TLC específicos.
• Os fornecedores devem criar TLCs separados e específicos do fornecedor para trocar dados proprietários entre seu cliente HID e o dispositivo. Evite usar drivers de filtro, a menos que seja crítico.
• O sistema abre todas as coleções de teclado e mouse para uso exclusivo.
• O sistema impede a desativação/ativação de um teclado.
• O sistema fornece suporte para rodas horizontais/verticais com recursos de rolagem suave.

Orientação do Motorista

A Microsoft fornece esta orientação para IHVs que gravam drivers:

1. Os desenvolvedores de drivers têm permissão para adicionar mais drivers na forma de um driver de filtro ou um novo driver cliente HID.

   1. Drivers de filtro: os desenvolvedores de drivers devem garantir que seu driver de valor agregado seja um driver de filtro e não substitua (ou seja usado no lugar de) drivers HID existentes do Windows na pilha de entrada.

      • Os drivers de filtro são permitidos nestes cenários:
        • Como um filtro superior para kbdhid/mouhid
        • Como um filtro superior para kbdclass/mouclass
      • Os drivers de filtro não são recomendados como um filtro entre os minidrivers de transporte HIDCLASS e HID

   2. Drivers de função: Como alternativa, os fornecedores podem criar um driver de função (em vez de um driver de filtro), mas apenas para PDOs HID específicos do fornecedor (com um serviço de modo de usuário, se necessário).

      Os drivers de função são permitidos nestes cenários:

      • Carregue apenas no hardware do fornecedor específico

   3. Drivers de transporte: a equipe do Windows não recomenda a criação de mais minidrivers de transporte HID que são complexos de escrever e manter. Se um parceiro estiver criando um novo minidriver de transporte HID, especialmente em sistemas SoC, recomendamos uma revisão arquitetônica detalhada para entender o raciocínio e garantir que o driver seja desenvolvido corretamente.

2. Os desenvolvedores de drivers devem usar estruturas de driver (KMDF ou UMDF) e não confiar no WDM para seus drivers de filtro.

3. Os desenvolvedores de drivers devem reduzir o número de transições de usuário do kernel entre seu serviço e a pilha de drivers.

4. Os desenvolvedores de drivers devem garantir a capacidade de ativar o sistema por meio da funcionalidade do teclado e do touchpad (ajustável pelo usuário final (gerenciador de dispositivos) ou pelo fabricante do PC). Além disso, em sistemas SoC, esses dispositivos devem ser capazes de se despertar de um estado de menor potência enquanto o sistema está em um estado S0 em funcionamento.

5. Os desenvolvedores de drivers devem garantir que seu hardware seja gerenciado de forma eficiente.

   • O dispositivo pode entrar em seu estado de energia mais baixo quando o dispositivo está ocioso.
   • O dispositivo está no estado de menor consumo de energia quando o sistema está em um estado de baixa energia (por exemplo, em espera (S3) ou em modo de espera conectado).

Layout do teclado

Um layout de teclado descreve completamente as características de entrada de um teclado para o Microsoft Windows 2000 e versões posteriores. Por exemplo, um layout de teclado especifica o idioma, o tipo e a versão do teclado, modificadores, códigos de verificação e assim por diante.

Consulte estes recursos para obter informações sobre layouts de teclado:

• Arquivo de cabeçalho do teclado, kdb.h, no Windows Driver Development Kit (DDK), que documenta informações gerais sobre layouts de teclado.

• Exemplos de layouts de teclado.

Para visualizar o layout de um teclado específico, consulte Layouts de teclado do Windows.

Para obter mais detalhes sobre o layout do teclado, visite Painel de Controle\Relógio, Idioma e Região\Idioma.

Botões e rodas suportados em mouses

A tabela a seguir identifica os recursos com suporte em diferentes versões de cliente do sistema operacional Windows.

Ativando botões 4-5 e roda em mouses PS/2

O método usado pelo Windows para ativar o novo modo de quatro e cinco botões e roda é uma extensão do método usado para ativar o terceiro botão e a roda em mouses compatíveis com IntelliMouse:

• O mouse é definido para o modo de roda de três botões definindo a taxa de relatório para 200 relatórios por segundo, depois para 100 relatórios por segundo e, em seguida, para 80 relatórios por segundo. Em seguida, leia o ID do mouse. O mouse deve relatar um ID de 3 quando essa sequência for concluída.

• O mouse é então definido para o modo de roda de cinco botões definindo a taxa de relatório para 200 relatórios por segundo, depois para 200 relatórios por segundo novamente e, em seguida, para 80 relatórios por segundo. Em seguida, leia o ID do mouse. Uma vez que a sequência é concluída, um mouse de roda de cinco botões deve relatar um ID de 4 (enquanto um mouse de roda de três botões compatível com IntelliMouse ainda relataria um ID de 3).

Este método é aplicável apenas a camundongos PS/2, não a camundongos HID. Os ratos HID devem relatar usos precisos em seu descritor de relatório.

Formato de pacote de dados de mouse compatível com PS/2 padrão (dois botões)

Formato de pacote de dados de mouse compatível com PS/2 padrão (três botões + roda vertical)

Formato de pacote de dados de mouse compatível com PS/2 padrão (cinco botões + roda vertical)

Dispositivos que não exigem drivers de fornecedor

Os drivers do fornecedor não são necessários para os seguintes dispositivos:

• Dispositivos que estão em conformidade com o Padrão HID.
• Dispositivos de porta de teclado, mouse ou jogo operados pelos drivers não HIDClass fornecidos pelo sistema.

Kbfiltr exemplo

Kbfiltr é usado com Kbdclass, o driver de classe do sistema para dispositivos de teclado e I8042prt, o driver de função para um teclado estilo PS/2. Kbfiltr demonstra como filtrar solicitações de E/S e como adicionar rotinas de retorno de chamada que modificam a operação de Kbdclass e I8042prt.

Para obter mais informações sobre a operação Kbfiltr, consulte:

• O arquivo de cabeçalho WDK ntddkbd.h .

• O código-fonte Kbfiltr de exemplo.

Kbfiltr códigos de controle de E/S

As IOCTLs a seguir são usadas pelo Kbfiltr.

IOCTL_INTERNAL_I8042_HOOK_KEYBOARD

O IOCTL_INTERNAL_I8042_HOOK_KEYBOARD pedido:

• Adiciona uma rotina de retorno de chamada de inicialização à rotina de inicialização do teclado I8042prt.
• Adiciona uma rotina de retorno de chamada ISR ao ISR do teclado I8042prt.

A inicialização e os retornos de chamada ISR são opcionais e são fornecidos por um driver de filtro de nível superior para um dispositivo de teclado estilo PS/2.

Depois que o I8042prt recebe uma solicitação de IOCTL_INTERNAL_KEYBOARD_CONNECT, ele envia uma solicitação de IOCTL_INTERNAL_I8042_HOOK_KEYBOARD síncrona para a parte superior da pilha de dispositivos de teclado.

Depois que o Kbfiltr recebe a solicitação do teclado de gancho, o Kbfiltr filtra a solicitação da seguinte maneira:

• Salva as informações de nível superior passadas para Kbfiltr, que inclui o contexto de um objeto de dispositivo de nível superior, um ponteiro para um retorno de chamada de inicialização e um ponteiro para um retorno de chamada ISR.
• Substitui as informações de nível superior por suas próprias.
• Salva o contexto de I8042prt e ponteiros para retornos de chamada que o retorno de chamada ISR Kbfiltr pode usar.

IOCTL_INTERNAL_KEYBOARD_CONNECT

A solicitação IOCTL_INTERNAL_KEYBOARD_CONNECT conecta o serviço Kbdclass ao dispositivo de teclado. Kbdclass envia essa solicitação para baixo a pilha de dispositivos de teclado antes de abrir o dispositivo de teclado.

Depois que o Kbfiltr recebeu a solicitação de conexão do teclado, o Kbfiltr filtra a solicitação de conexão da seguinte maneira:

• Salva uma cópia da estrutura CONNECT_DATA (Kbdclass) do Kbdclass que é passada para o driver de filtro pelo Kbdclass.
• Substitui suas próprias informações de conexão pelas informações de conexão do driver de classe.
• Envia a solicitação de IOCTL_INTERNAL_KEYBOARD_CONNECT para baixo da pilha de dispositivos.

Se a solicitação não for bem-sucedida, o Kbfiltr concluirá a solicitação com um status de erro apropriado.

Kbfiltr fornece um modelo para uma rotina de retorno de chamada de serviço de filtro que pode complementar a operação de KeyboardClassServiceCallback, a rotina de retorno de chamada de serviço de classe Kbdclass. O retorno de chamada do serviço de filtro pode filtrar os dados de entrada que são transferidos do buffer de entrada do dispositivo para a fila de dados de classe.

IOCTL_INTERNAL_KEYBOARD_DISCONNECT

A solicitação de IOCTL_INTERNAL_KEYBOARD_DISCONNECT é concluída com um status de STATUS_NOT_IMPLEMENTED. O gerenciador Plug and Play pode adicionar ou remover um teclado Plug and Play.

Para todas as outras solicitações de controle de dispositivo, o Kbfiltr ignora a pilha IRP atual e envia a solicitação para baixo da pilha de dispositivos sem processamento adicional.

Rotinas de retorno de chamada implementadas pelo Kbfiltr

Kbfiltr implementa as seguintes rotinas de retorno de chamada.

KbFilter_InitializationRoutine

Visualizar PI8042_KEYBOARD_INITIALIZATION_ROUTINE

O KbFilter_InitializationRoutine não é necessário se a inicialização padrão I8042prt de um teclado for suficiente.

I8042prt chama KbFilter_InitializationRoutine quando ele inicializa o teclado. A inicialização padrão do teclado inclui as seguintes operações:

• Redefinir o teclado
• Definir a taxa e o atraso typematic
• ajustar os diodos emissores de luz (LED)

/*
Parameters
DeviceObject [in]
Pointer to the device object that is the context for this callback.

SynchFuncContext [in]
Pointer to the context for the routines pointed to by ReadPort and Writeport.

ReadPort [in]
Pointer to the system-supplied PI8042_SYNCH_READ_PORT callback that reads from the port.

WritePort [in]
Pointer to the system-supplied PI8042_SYNCH_WRITE_PORT callback that writes to the port.

TurnTranslationOn [out]
Specifies, if TRUE, to turn translation on. Otherwise, translation is turned off.

Return value
KbFilter_InitializationRoutine returns an appropriate NTSTATUS code.
*/

NTSTATUS KbFilter_InitializationRoutine(
  In  PDEVICE_OBJECT          DeviceObject,
  In  PVOID                   SynchFuncContext,
  In  PI8042_SYNCH_READ_PORT  ReadPort,
  In  PI8042_SYNCH_WRITE_PORT WritePort,
  Out PBOOLEAN                TurnTranslationOn
);

KbFilter_IsrHook

Veja PI8042_KEYBOARD_ISR. Esse retorno de chamada não será necessário se a operação padrão do I8042prt for suficiente.

O ISR do teclado I8042prt chama KbFilter_IsrHook depois que ele valida a interrupção e lê o código de verificação.

KbFilter_IsrHook é executado no modo kernel no IRQL do teclado I8042prt.

/*
Parameters
DeviceObject [in]
Pointer to the filter device object of the driver that supplies this callback.

CurrentInput [in]
Pointer to the input KEYBOARD_INPUT_DATA structure that is being constructed by the ISR.

CurrentOutput [in]
Pointer to an OUTPUT_PACKET structure that specifies the bytes that are being written to the hardware device.

StatusByte [in, out]
Specifies the status byte that is read from I/O port 60 when an interrupt occurs.

DataByte [in]
Specifies the data byte that is read from I/O port 64 when an interrupt occurs.

ContinueProcessing [out]
Specifies, if TRUE, to continue processing in the I8042prt keyboard ISR after this callback returns; otherwise, processing is not continued.

ScanState [in]
Pointer to a KEYBOARD_SCAN_STATE structure that specifies the keyboard scan state.

Return value
KbFilter_IsrHook returns TRUE if the interrupt service routine should continue; otherwise it returns FALSE.
*/

KbFilter_IsrHook KbFilter_IsrHook(
  In    PDEVICE_OBJECT       DeviceObject,
  In    PKEYBOARD_INPUT_DATA CurrentInput,
  In    POUTPUT_PACKET       CurrentOutput,
  Inout UCHAR                StatusByte,
  In    PUCHAR               DataByte,
  Out   PBOOLEAN             ContinueProcessing,
  In    PKEYBOARD_SCAN_STATE ScanState
);

KbFilter_ServiceCallback

Veja PSERVICE_CALLBACK_ROUTINE.

A rotina de conclusão de despacho ISR do driver de função chama KbFilter_ServiceCallback, que então chama a implementação do driver de classe de teclado de PSERVICE_CALLBACK_ROUTINE. Um fornecedor pode implementar um retorno de chamada de serviço de filtro para modificar os dados de entrada que são transferidos do buffer de entrada do dispositivo para a fila de dados de classe. Por exemplo, o retorno de chamada pode excluir, transformar ou inserir dados.

/*
Parameters
DeviceObject [in]
Pointer to the class device object.

InputDataStart [in]
Pointer to the first keyboard input data packet in the input data buffer of the port device.

InputDataEnd [in]
Pointer to the keyboard input data packet that immediately follows the last data packet in the input data buffer of the port device.

InputDataConsumed [in, out]
Pointer to the number of keyboard input data packets that are transferred by the routine.

Return value
None
*/

VOID KbFilter_ServiceCallback(
  In    PDEVICE_OBJECT       DeviceObject,
  In    PKEYBOARD_INPUT_DATA InputDataStart,
  In    PKEYBOARD_INPUT_DATA InputDataEnd,
  Inout PULONG               InputDataConsumed
);

Amostra de Moufiltr

Moufiltr é usado com Mouclass, o driver de classe de sistema para dispositivos de mouse usado com o Windows 2000 e versões posteriores, e I8042prt, o driver de função para um mouse estilo PS/2 usado com o Windows 2000 e posterior. O Moufiltr demonstra como filtrar solicitações de E/S e adicionar rotinas de retorno de chamada que modificam a operação do Mouclass e do I8042prt.

Para obter mais informações sobre a operação do Moufiltr, consulte estes recursos:

• O arquivo de cabeçalho WDK ntddmou.h .

• O código-fonte Moufiltr de exemplo.

Códigos de controle de E/S Moufiltr

As seguintes IOCTLs são usadas pela Moufiltr.

IOCTL_INTERNAL_I8042_HOOK_MOUSE

A solicitação IOCTL_INTERNAL_I8042_HOOK_MOUSE adiciona uma rotina de retorno de chamada ISR ao ISR do mouse I8042prt. O retorno de chamada ISR é opcional e é fornecido por um driver de filtro de mouse de nível superior.

O I8042prt envia essa solicitação depois de receber uma solicitação de IOCTL_INTERNAL_MOUSE_CONNECT . O I8042prt envia uma solicitação de IOCTL_INTERNAL_I8042_HOOK_MOUSE síncrona para a parte superior da pilha de dispositivos do mouse.

Depois que o Moufiltr recebe a solicitação do mouse de gancho, ele filtra a solicitação da seguinte maneira:

• Salva as informações de nível superior passadas para o Moufiltr, que inclui o contexto de um objeto de dispositivo de nível superior e um ponteiro para um retorno de chamada ISR.
• Substitui as informações de nível superior por suas próprias.
• Salva o contexto de I8042prt e ponteiros para retornos de chamada que os retornos de chamada ISR Moufiltr podem usar.

IOCTL_INTERNAL_MOUSE_CONNECT

A solicitação IOCTL_INTERNAL_MOUSE_CONNECT conecta o serviço Mouclass a um dispositivo de mouse.

IOCTL_INTERNAL_MOUSE_DISCONNECT

O Moufiltr conclui a solicitação de IOCTL_INTERNAL_MOUSE_DISCONNECT com um status de erro de STATUS_NOT_IMPLEMENTED.

Para todas as outras solicitações, o Moufiltr ignora a pilha IRP atual e envia a solicitação para a pilha de dispositivos sem processamento adicional.

Rotinas de retorno de chamada Moufiltr

O MouFiltr implementa as seguintes rotinas de retorno de chamada.

MouFilter_IsrHook

Veja PI8042_MOUSE_ISR.

/*
Parameters
DeviceObject
Pointer to the filter device object of the driver that supplies this callback.

CurrentInput
Pointer to the input MOUSE_INPUT_DATA structure being constructed by the ISR.

CurrentOutput
Pointer to the OUTPUT_PACKET structure that specifies the bytes being written to the hardware device.

StatusByte
Specifies a status byte that is read from I/O port 60 when the interrupt occurs.

DataByte
Specifies a data byte that is read from I/O port 64 when the interrupt occurs.

ContinueProcessing
Specifies, if TRUE, that the I8042prt mouse ISR continues processing after this callback returns. Otherwise, processing is not continued.

MouseState
Pointer to a MOUSE_STATE enumeration value, which identifies the state of mouse input.

ResetSubState
Pointer to MOUSE_RESET_SUBSTATE enumeration value, which identifies the mouse reset substate. See the Remarks section.

Return value
MouFilter_IsrHook returns TRUE if the interrupt service routine should continue; otherwise it returns FALSE.
*/

BOOLEAN MouFilter_IsrHook(
   PDEVICE_OBJECT        DeviceObject,
   PMOUSE_INPUT_DATA     CurrentInput,
   POUTPUT_PACKET        CurrentOutput,
   UCHAR                 StatusByte,
   PUCHAR                DataByte,
   PBOOLEAN              ContinueProcessing,
   PMOUSE_STATE          MouseState,
   PMOUSE_RESET_SUBSTATE ResetSubState
);

Um retorno de chamada MouFilter_IsrHook não será necessário se a operação padrão do I8042prt for suficiente.

O ISR do mouse I8042prt chama MouFilter_IsrHook depois de validar a interrupção.

Para redefinir um mouse, o I8042prt passa por uma sequência de subestados operacionais. Um valor de enumeração MOUSE_RESET_SUBSTATE identifica cada subestado. Para obter mais informações sobre como I8042prt redefine um mouse e os subestados de redefinição de mouse correspondentes, consulte a documentação do MOUSE_RESET_SUBSTATE em ntdd8042.h.

MouFilter_IsrHook é executado no modo kernel no IRQL do ISR do mouse I8042prt.

MouFilter_ServiceCallback

Visualizar PSERVICE_CALLBACK_ROUTINE

/*
Parameters
DeviceObject [in]
Pointer to the class device object.

InputDataStart [in]
Pointer to the first mouse input data packet in the input data buffer of the port device.

InputDataEnd [in]
Pointer to the mouse input data packet immediately following the last data packet in the port device's input data buffer.

InputDataConsumed [in, out]
Pointer to the number of mouse input data packets that are transferred by the routine.

Return value
None
*/

VOID MouFilter_ServiceCallback(
  _In_    PDEVICE_OBJECT    DeviceObject,
  _In_    PMOUSE_INPUT_DATA InputDataStart,
  _In_    PMOUSE_INPUT_DATA InputDataEnd,
  _Inout_ PULONG            InputDataConsumed
);

O ISR DPC de I8042prt chama MouFilter_ServiceCallback, que chama MouseClassServiceCallback. Um retorno de chamada de serviço de filtro pode ser configurado para modificar os dados de entrada transferidos do buffer de entrada do dispositivo para a fila de dados de classe. Por exemplo, o retorno de chamada pode excluir, transformar ou inserir dados.