Driver client HID da tastiera e mouse

Questo articolo illustra i driver client HID della tastiera e del mouse. Le tastiere e i mouse rappresentano il primo set di client HID standardizzati nelle tabelle di utilizzo HID e implementati nei sistemi operativi Windows.

I driver client HID della tastiera e del mouse vengono implementati sotto forma di driver HID Mapper. Un driver del mapper HID è un driver filtro WDM in modalità kernel che fornisce un'interfaccia bidirezionale per le richieste di I/O tra un driver di classe non HID e il driver di classe HID. Il driver del mapper esegue il mapping delle richieste di I/O e dei protocolli di dati di uno all'altro.

Windows fornisce driver del mapper HID forniti dal sistema per la tastiera HID e i dispositivi mouse HID.

Architettura e panoramica

La figura seguente illustra gli stack di driver forniti dal sistema per dispositivi da tastiera USB, mouse e touchpad.

La figura mostra i componenti seguenti:

• KBDHID.sys: driver del mapper client HID per le tastiere. Converte gli utilizzi HID in codici di analisi in interfaccia con il driver di classe della tastiera esistente.
• MOUHID.sys: driver del mapper client HID per mouse/touchpad. Converte gli utilizzi HID in comandi del mouse (X/Y, pulsanti, rotellina) in interfaccia con il driver di classe della tastiera esistente.
• KBDCLASS.sys: il driver di classe della tastiera fornisce funzionalità per tutte le tastiere e i tastieri del sistema in modo sicuro.
• MOUCLASS.sys: il driver della classe mouse fornisce funzionalità per tutti i mouse e i touchpad nel sistema. Il driver supporta sia i dispositivi assoluti che i dispositivi di puntamento relativi. MOUCLASS.sys non è il driver windows per i touchscreen.
• HIDCLASS.sys: driver di classe HID. Il driver di classe HID è l'associazione tra KBDHID.sys e MOUHID.sys client HID e vari trasporti, ad esempio USB, Bluetooth e così via.

Il sistema compila lo stack di driver come segue:

• Lo stack di trasporto crea un oggetto dispositivo fisico (PDO) per ogni dispositivo HID collegato e carica il driver di trasporto HID appropriato, che a sua volta carica il driver di classe HID.
• Il driver di classe HID crea un PDO per ogni tastiera o TLC del mouse. I dispositivi HID complessi (più TLC) vengono esposti come più PDO creati dal driver di classe HID. Ad esempio, una tastiera con un mouse integrato potrebbe avere una raccolta per i controlli della tastiera standard e una raccolta diversa per il mouse.
• I driver del mapper client HID della tastiera o del mouse vengono caricati nell'fdO appropriato.
• I driver del mapper HID creano fdO per tastiera e mouse e caricano i driver di classe.

Note importanti

• I driver fornitore non sono necessari per le tastiere e i mouse conformi alle raccolte HID Usages e top level supportate.
• I fornitori forniscono facoltativamente driver di filtro nello stack HID per modificare/migliorare la funzionalità di questi TLC specifici.
• I fornitori devono creare controller di dominio separati, specifici del fornitore, per scambiare dati proprietari tra il client HID e il dispositivo. Evitare di usare driver di filtro a meno che non sia critico.
• Il sistema apre tutte le raccolte di tastiera e mouse per il suo uso esclusivo.
• Il sistema impedisce la disabilitazione o l'abilitazione di una tastiera.
• Il sistema fornisce supporto per ruote orizzontali/verticali con funzionalità di scorrimento uniformi.

Linee guida per i driver

Microsoft fornisce queste linee guida per la scrittura di driver IHV:

1. Gli sviluppatori di driver possono aggiungere altri driver sotto forma di driver di filtro o di un nuovo driver client HID.

   1. Filtri driver: gli sviluppatori di driver devono assicurarsi che il driver aggiunto di valore sia un driver di filtro e non sostituisca (o venga usato al posto di) driver HID windows esistenti nello stack di input.

      • I driver di filtro sono consentiti in questi scenari:
        • Come filtro superiore per kbdhid/mouhid
        • Come filtro superiore per kbdclass/mouclass
      • I driver di filtro non sono consigliati come filtro tra minidriver di trasporto HIDCLASS e HID

   2. Driver di funzione: in alternativa, i fornitori possono creare un driver di funzione (anziché un driver di filtro), ma solo per i PDO HID specifici del fornitore (se necessario, con un servizio in modalità utente).

      I driver di funzione sono consentiti in questi scenari:

      • Carico solo sull'hardware del fornitore specifico

   3. Driver di trasporto: il team di Windows non consiglia di creare minidriver di trasporto HID più complessi da scrivere e gestire. Se un partner sta creando un nuovo minidriver di trasporto HID, in particolare nei sistemi SoC, è consigliabile una revisione architetturale dettagliata per comprendere il ragionamento e assicurarsi che il driver sia sviluppato correttamente.

2. Gli sviluppatori di driver devono usare framework driver (KMDF o UMDF) e non basarsi su WDM per i driver di filtro.

3. Gli sviluppatori di driver devono ridurre il numero di transizioni utente kernel tra il servizio e lo stack di driver.

4. Gli sviluppatori di driver devono garantire la possibilità di riattivare il sistema tramite la funzionalità della tastiera e del touchpad (regolabile dall'utente finale (gestione dispositivi) o dal produttore del PC. Oltre ai sistemi SoC, questi dispositivi devono essere in grado di riattivarsi da uno stato inferiore alimentato mentre il sistema è in uno stato S0 funzionante.

5. Gli sviluppatori di driver devono assicurarsi che l'hardware sia gestito in modo efficiente.

   • Il dispositivo può passare allo stato di alimentazione più basso quando il dispositivo è inattiva.
   • Il dispositivo è nello stato di alimentazione più basso quando il sistema si trova in uno stato di basso consumo (ad esempio, standby (S3) o standby connesso.

Layout della tastiera

Un layout di tastiera descrive completamente le caratteristiche di input di una tastiera per Microsoft Windows 2000 e versioni successive. Ad esempio, un layout di tastiera specifica la lingua, il tipo di tastiera e la versione, modificatori, codici di analisi e così via.

Per informazioni sui layout di tastiera, vedere queste risorse:

• File di intestazione della tastiera, kdb.h, in Windows Driver Development Kit (DDK), che documenta informazioni generali sui layout della tastiera.

• Layout di tastiera di esempio.

Per visualizzare il layout di una tastiera specifica, vedi Layout di tastiera di Windows.

Per altre informazioni sul layout della tastiera, visitare Pannello di controllo\Clock, Language e Region\Language.For more details around the keyboard layout, visit Pannello di controllo\Clock, Language, and Region\Language.

Pulsanti e ruote supportati sui mouse

La tabella seguente identifica le funzionalità supportate in diverse versioni client del sistema operativo Windows.

Attivazione dei pulsanti da 4 a 5 e rotellina sui mouse PS/2

Il metodo utilizzato da Windows per attivare la nuova modalità a quattro e cinque pulsanti e rotellina è un'estensione del metodo usato per attivare il terzo pulsante e la rotellina nei mouse compatibili con IntelliMouse:

• Il mouse viene impostato sulla modalità a tre pulsanti impostando la frequenza del report su 200 report al secondo, quindi su 100 report al secondo, quindi su 80 report al secondo. Quindi, leggere l'ID dal mouse. Quando questa sequenza viene completata, il mouse dovrebbe segnalare un ID pari a 3.

• Il mouse viene quindi impostato sulla modalità rotellina a cinque pulsanti impostando la frequenza del report su 200 report al secondo, quindi su 200 report al secondo, quindi su 80 report al secondo. Quindi, leggere l'ID dal mouse. Una volta completata la sequenza, un mouse con rotellina a cinque pulsanti dovrebbe segnalare un ID pari a 4 (mentre un mouse della rotellina a tre pulsanti compatibile con IntelliMouse segnala ancora un ID pari a 3).

Questo metodo è applicabile solo ai topi PS/2, non ai topi HID. I topi HID devono segnalare utilizzi accurati nel descrittore del report.

Formato di pacchetto di dati del mouse compatibile con PS/2 standard (due pulsanti)

Formato di pacchetto di dati del mouse compatibile con PS/2 standard (tre pulsanti + rotellina verticale)

Formato di pacchetto di dati del mouse compatibile con PS/2 standard (cinque pulsanti + rotellina verticale)

Dispositivi che non richiedono driver fornitore

I driver fornitore non sono necessari per i dispositivi seguenti:

• Dispositivi conformi allo standard HID.
• Dispositivi di tastiera, mouse o porta di gioco gestiti dai driver non HIDClass forniti dal sistema.

Esempio di Kbfiltr

Kbfiltr viene usato con Kbdclass, il driver di classe di sistema per i dispositivi da tastiera e I8042prt, il driver di funzione per una tastiera di tipo PS/2. Kbfiltr illustra come filtrare le richieste di I/O e come aggiungere routine di callback che modificano l'operazione di Kbdclass e I8042prt.

Per altre informazioni sull'operazione Kbfiltr, vedere:

• File di intestazione WDK ntddkbd.h .

• Codice sorgente Kbfiltr di esempio.

Codici di controllo I/O Kbfiltr

IOCTLs seguenti vengono usati da Kbfiltr.

IOCTL_INTERNAL_I8042_HOOK_KEYBOARD

Richiesta di IOCTL_INTERNAL_I8042_HOOK_KEYBOARD:

• Aggiunge una routine di callback di inizializzazione alla routine di inizializzazione della tastiera I8042prt.
• Aggiunge una routine di callback ISR all'ISR della tastiera I8042prt.

I callback di inizializzazione e ISR sono facoltativi e vengono forniti da un driver di filtro di livello superiore per un dispositivo da tastiera di tipo PS/2.

Dopo che I8042prt riceve una richiesta di IOCTL_INTERNAL_KEYBOARD_CONNECT , invia una richiesta sincrona IOCTL_INTERNAL_I8042_HOOK_KEYBOARD all'inizio dello stack di dispositivi da tastiera.

Dopo che Kbfiltr riceve la richiesta di tastiera hook, Kbfiltr filtra la richiesta nel modo seguente:

• Salva le informazioni di livello superiore passate a Kbfiltr, che include il contesto di un oggetto dispositivo di livello superiore, un puntatore a un callback di inizializzazione e un puntatore a un callback ISR.
• Sostituisce le informazioni di livello superiore con le proprie.
• Salva il contesto di I8042prt e puntatori ai callback che possono essere usati dal callback ISR Kbfiltr.

IOCTL_INTERNAL_KEYBOARD_CONNECT

La richiesta di IOCTL_INTERNAL_KEYBOARD_CONNECT connette il servizio Kbdclass al dispositivo da tastiera. Kbdclass invia questa richiesta nello stack di dispositivi da tastiera prima di aprire il dispositivo da tastiera.

Dopo che Kbfiltr ha ricevuto la richiesta di connessione tramite tastiera, Kbfiltr filtra la richiesta di connessione nel modo seguente:

• Salva una copia della struttura di CONNECT_DATA (Kbdclass) di Kbdclass passata al driver di filtro da Kbdclass.
• Sostituisce le proprie informazioni di connessione per le informazioni di connessione del driver di classe.
• Invia la richiesta di IOCTL_INTERNAL_KEYBOARD_CONNECT nello stack di dispositivi.

Se la richiesta non riesce, Kbfiltr completa la richiesta con uno stato di errore appropriato.

Kbfiltr fornisce un modello per una routine di callback del servizio di filtro che può integrare l'operazione di KeyboardClassServiceCallback, la routine di callback del servizio classi Kbdclass. Il callback del servizio di filtro può filtrare i dati di input trasferiti dal buffer di input del dispositivo alla coda dei dati della classe.

IOCTL_INTERNAL_KEYBOARD_DISCONNECT

La richiesta di IOCTL_INTERNAL_KEYBOARD_DISCONNECT viene completata con lo stato di STATUS_NOT_IMPLEMENTED. Il gestore Plug and Play può aggiungere o rimuovere una tastiera Plug and Play.

Per tutte le altre richieste di controllo del dispositivo, Kbfiltr ignora lo stack IRP corrente e invia la richiesta nello stack di dispositivi senza ulteriore elaborazione.

Routine di callback implementate da Kbfiltr

Kbfiltr implementa le routine di callback seguenti.

KbFilter_InitializationRoutine

Vedere PI8042_KEYBOARD_INITIALIZATION_ROUTINE

Il KbFilter_InitializationRoutine non è necessario se l'inizializzazione predefinita di I8042prt di una tastiera è sufficiente.

I8042prt chiama KbFilter_InitializationRoutine quando inizializza la tastiera. L'inizializzazione predefinita della tastiera include le operazioni seguenti:

• reimpostare la tastiera
• impostare la frequenza tipitica e il ritardo
• impostare i diodi che generano luce (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

Vedere PI8042_KEYBOARD_ISR. Questo callback non è necessario se l'operazione predefinita di I8042prt è sufficiente.

La tastiera I8042prt chiama KbFilter_IsrHook dopo aver convalidato l'interrupt e letto il codice di analisi.

KbFilter_IsrHook viene eseguito in modalità kernel in IRQL della tastiera 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

Vedere PSERVICE_CALLBACK_ROUTINE.

La routine di completamento dell'invio ISR del driver di funzione chiama KbFilter_ServiceCallback, che chiama quindi l'implementazione del driver della classe della tastiera di PSERVICE_CALLBACK_ROUTINE. Un fornitore può implementare un callback del servizio di filtro per modificare i dati di input trasferiti dal buffer di input del dispositivo alla coda dei dati della classe. Ad esempio, il callback può eliminare, trasformare o inserire dati.

/*
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
);

Esempio di Moufiltr

Moufiltr viene usato con Mouclass, il driver di classe di sistema per i dispositivi mouse usati con Windows 2000 e versioni successive e I8042prt, il driver di funzione per un mouse di tipo PS/2 usato con Windows 2000 e versioni successive. Moufiltr illustra come filtrare le richieste di I/O e aggiungere routine di callback che modificano l'operazione di Mouclass e I8042prt.

Per altre informazioni sull'operazione Moufiltr, vedere queste risorse:

• File di intestazione WDK ntddmou.h .

• Codice sorgente Moufiltr di esempio.

Codici di controllo di I/O Moufiltr

IOCTLs seguenti vengono usati da Moufiltr.

IOCTL_INTERNAL_I8042_HOOK_MOUSE

La richiesta di IOCTL_INTERNAL_I8042_HOOK_MOUSE aggiunge una routine di callback ISR all'ISR del mouse I8042prt. Il callback ISR è facoltativo e viene fornito da un driver di filtro del mouse di livello superiore.

I8042prt invia questa richiesta dopo che riceve una richiesta di IOCTL_INTERNAL_MOUSE_CONNECT . I8042prt invia una richiesta sincrona IOCTL_INTERNAL_I8042_HOOK_MOUSE all'inizio dello stack di dispositivi del mouse.

Dopo che Moufiltr riceve la richiesta del mouse hook, filtra la richiesta nel modo seguente:

• Salva le informazioni di livello superiore passate a Moufiltr, che include il contesto di un oggetto dispositivo di livello superiore e un puntatore a un callback ISR.
• Sostituisce le informazioni di livello superiore con le proprie.
• Salva il contesto di I8042prt e puntatori ai callback che possono essere usati dai callback ISR Moufiltr.

IOCTL_INTERNAL_MOUSE_CONNECT

La richiesta di IOCTL_INTERNAL_MOUSE_CONNECT connette il servizio Mouclass a un dispositivo mouse.

IOCTL_INTERNAL_MOUSE_DISCONNECT

Moufiltr completa la richiesta di IOCTL_INTERNAL_MOUSE_DISCONNECT con lo stato di errore di STATUS_NOT_IMPLEMENTED.

Per tutte le altre richieste, Moufiltr ignora lo stack IRP corrente e invia la richiesta allo stack di dispositivi senza ulteriore elaborazione.

Routine di callback Moufiltr

MouFiltr implementa le routine di callback seguenti.

MouFilter_IsrHook

Vedere 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
);

Un callback MouFilter_IsrHook non è necessario se l'operazione predefinita di I8042prt è sufficiente.

L'ISR del mouse I8042prt chiama MouFilter_IsrHook dopo la convalida dell'interrupt.

Per reimpostare un mouse, I8042prt passa attraverso una sequenza di sottostate operativi. Un valore di enumerazione MOUSE_RESET_SUBSTATE identifica ogni sottostato. Per altre informazioni su come I8042prt reimposta un mouse e le relative sottostate di reimpostazione del mouse, vedere la documentazione di MOUSE_RESET_SUBSTATE in ntdd8042.h.

MouFilter_IsrHook viene eseguito in modalità kernel in IRQL dell'ISR del mouse I8042prt.

MouFilter_ServiceCallback

Vedere 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
);

L'ISR DPC di I8042prt chiama MouFilter_ServiceCallback, che chiama quindi MouseClassServiceCallback. È possibile configurare un callback del servizio di filtro per modificare i dati di input trasferiti dal buffer di input del dispositivo alla coda dei dati della classe. Ad esempio, il callback può eliminare, trasformare o inserire dati.