Keyboard and mouse HID client drivers

Keyboards and mice represent the first set of HID clients that were standardized in the HID Usage tables and implemented in Windows operating systems. Their implementation is in the form of HID Mapper Drivers (kernel-mode WDM filter driver that provides a bidirectional interface for I/O requests between a non-HIDClass driver and the HID class driver).

A subset of HID Clients is called HID Mapper Drivers. A HID mapper driver is a kernel-mode WDM filter driver that provides a bidirectional interface for I/O requests between a non-HIDClass driver and the HID class driver. The mapper driver maps the I/O requests and data protocols of one to the other. Windows provides system-supplied HID mapper drivers for HID keyboard, and HID mice devices.

Architecture and overview

The following figure illustrates the system-supplied driver stacks for USB keyboard and mouse/touchpad devices.

JJ128406.keyboard_driver_stack(en-us,VS.85).png

The figure above includes the following components:

  • KBDHID.sys – HID client mapper driver for keyboards. Converts HID usages into scancodes to interface with the existing keyboard class driver.
  • MOUHID.sys – HID client mapper driver for mice/touchpads. Converts HID usages into mouse commands (X/Y, buttons, wheel) to interface with the existing keyboard class driver.
  • KBDCLASS.sys – The keyboard class driver maintains functionality for all keyboards and keypads on the system in a secure manner.
  • MOUCLASS.sys – The mouse class driver maintains functionality for all mice / touchpads on the system. The driver does support both absolute and relative pointing devices. This is not the driver for touchscreens as that is managed by a different driver in Windows.

The system builds the driver stack as follows:

  • The transport stack creates a physical device object (PDO) for each HID device attached and loads the appropriate HID transport driver which in turn loads the HID Class Driver.
  • The HID class driver creates a PDO for each keyboard or mouse TLC. Complex HID devices (more than 1 TLC) are exposed as multiple PDOs created by HID class driver. For example, a keyboard with an integrated mouse might have one collection for the standard keyboard controls and a different collection for the mouse.
  • The keyboard or mouse hid client mapper drivers are loaded on the appropriate FDO.
  • The HID mapper drivers create FDOs for keyboard and mouse, and load the class drivers.

Important notes:

  • Vendor drivers are not required for keyboards and mice that are compliant with the supported HID Usages and top level collections.
  • Vendors may optionally provide filter drivers in the HID stack to alter/enhance the functionality of these specific TLC.
  • Vendors should create separate TLCs, that are vendor specific, to exchange vendor proprietary data between their hid client and the device. Avoid using filter drivers unless critical.
  • The system opens all keyboard and mouse collections for its exclusive use.
  • The system prevents disable/enabling a keyboard.
  • The system provides support for horizontal/vertical wheels with smooth scrolling capabilities.

Driver Guidance

Microsoft provides the following guidance for IHVs writing drivers:

  1. Driver developers are allowed to add additional drivers in the form of a filter driver or a new HID Client driver. The criteria are described below:
    1. Filters Drivers: Driver developers should ensure that their value-add driver is a filter driver and does not replace (or be used in place of) existing Windows HID drivers in the input stack.
      • Filter drivers are allowed in the following scenarios:
        • As an upper filter to kbdhid/mouhid
        • As an upper filter to kbdclass/mouclass
      • Filter drivers are NOT recommended in the following scenarios:
        • As a lower filter to the HID transport (e.g. HIDI2C)
        • As a filter between HIDCLASS and HID Transport minidriver
    2. Function Drivers: Alternatively vendors can create a function driver (instead of a filter driver) but only for vendor specific HID PDOs (with a user mode service if necessary).

      Function drivers are allowed in the following scenarios:

      • Only load on the specific vendor’s hardware
    3. Transport Drivers: Windows team does not recommend creating additional HID Transport minidriver as they are complex drivers to write/maintain. If a partner is creating a new HID Transport minidriver, especially on SoC systems, we recommend a detailed architectural review to understand the reasoning and ensure that the driver is developed correctly.
  2. Driver developers should leverage driver Frameworks (KMDF or UMDF) and not rely on WDM for their filter drivers.
  3. Driver developers should reduce the number of kernel-user transitions between their service and the driver stack.
  4. Driver developers should ensure ability to wake the system via both keyboard and touchpad functionality (adjustable by the end user (device manager) or the PC manufacturer). In addition on SoC systems, these devices must be able to wake themselves from a lower powered state while the system is in a working S0 state.
  5. Driver developers should ensure that their hardware is power managed efficiently.
    • Device can go into its lowest power state when the device is idle.
    • Device is in the lowest power state when the system is in a low power state (for example, standby (S3) or connected standby).

Keyboard layout

A keyboard layout fully describes a keyboard's input characteristics for Microsoft Windows 2000 and later versions. For example, a keyboard layout specifies the language, keyboard type and version, modifiers, scan codes, and so on.

See the following for information about keyboard layouts:

  • Keyboard header file, kdb.h, in the Windows Driver Development Kit (DDK), which documents general information about keyboard layouts.

  • Sample keyboard layouts in the MSDN Code Gallery.

To visualize the layout of a specific keyboard, please review to the “Windows Keyboard Layout” article in MSDN.

For additional details around the keyboard layout, visit Control Panel\Clock, Language, and Region\Language.

Supported buttons and wheels on mice

The following table identifies the features supported across different client versions of the Windows operating system.

FeatureWindows XPWindows VistaWindows 7Windows 8
Buttons 1-5Supported (PS/2 & HID) Supported (PS/2 & HID) Supported (PS/2 & HID) Supported (PS/2 & HID)
Vertical Scroll WheelSupported (PS/2 & HID) Supported (PS/2 & HID) Supported (PS/2 & HID) Supported (PS/2 & HID)
Horizontal Scroll WheelNot SupportedSupported (HID only) Supported (HID only) Supported (HID only)
Smooth Scroll Wheel Support (Horizontal and Vertical)Not SupportedPartly SupportedSupported (HID only)Supported (HID only)

 

Activating buttons 4-5 and wheel on PS/2 mice

The method used by Windows to activate the new 4&5-button + wheel mode is an extension of the method used to activate the third button and the wheel in IntelliMouse-compatible mice:

  • First, the mouse is set to the 3-button wheel mode, which is accomplished by setting the report rate consecutively to 200 reports/second, then to 100 reports/second, then to 80 reports/second, and then reading the ID from the mouse. The mouse should report an ID of 3 when this sequence is completed.
  • Next, the mouse is set to the 5-button wheel mode, which is accomplished by setting the report rate consecutively to 200 reports/second, then to 200 reports/second again, then to 80 reports/second, and then reading the ID from the mouse. Once this sequence is completed, a 5-button wheel mouse should report an ID of 4 (whereas an IntelliMouse-compatible 3-button wheel mouse would still report an ID of 3).

Note that this is applicable to PS/2 mice only and is not applicable to HID mice (HID mice must report accurate usages in their report descriptor).

Standard PS/2-compatible mouse data packet format (2 Buttons)

ByteD7D6D5D4D3D2D1D0Comment
1YoverXoverYsignXsignTagMRLX/Y overvlows and signs, buttons
2X7X6X5X4X3X2X1X0X data byte
3Y7Y6Y5Y4Y3Y2Y1Y0Y data bytes

 

Note  Windows mouse drivers do not check the overflow bits. In case of overflow, the mouse should simply send the maximal signed displacement value.

Standard PS/2-compatible mouse data packet format (3 Buttons + VerticalWheel)

ByteD7D6D5D4D3D2D1D0Comment
100YsignXsign1MRLX/Y signs and R/L/M buttons
2X7X6X5X4X3X2X1X0X data byte
3Y7Y6Y5Y4Y3Y2Y1Y0Y data bytes
4Z7Z6Z5Z4Z3Z2Z1Z0Z/wheel data byte

 

Standard PS/2-compatible mouse data packet format (5 Buttons + VerticalWheel)

ByteD7D6D5D4D3D2D1D0Comment
100YsignXsign1MRLX/Y signs and R/L/M buttons
2X7X6X5X4X3X2X1X0X data byte
3Y7Y6Y5Y4Y3Y2Y1Y0Y data bytes
400B5B4Z3Z2Z1Z0Z/wheel data data and buttons 4 and 5

 

Important note:

  • Notice that the Z/wheel data for a 5-button wheel mouse has been reduced to four bits instead of the 8 bits used in the IntelliMouse-compatible 3-button wheel mode. This reduction is made possible by the fact that the wheel typically cannot generate values beyond the range +7/-8 during any given interrupt period. Windows mouse drivers will sign extend the four Z/wheel data bits when the mouse is in the 5-button wheel mode, and the full Z/wheel data byte when the mouse operates in the 3-button wheel mode.
  • Buttons 4 & 5 on are mapped to WM_APPCOMMAND messages and correspond to App_Back and App_Forward.

Devices not requiring vendor drivers

Vendor drivers are not required for the following devices:

  • Devices that comply with the HID Standard.
  • Keyboard, mouse, or game port devices operated by the system-supplied non-HIDClass drivers.

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft