Implementing Best Practices for Touch Calibration in KMDF HID Minidrivers (I2C) Author: Technical Systems Engineering Subject: Windows Driver Development / HID Minidrivers Complexity: Advanced Abstract When developing a Kernel-Mode Driver Framework (KMDF) HID minidriver for an I2C touch controller, one of the most critical phases is the management and application of calibration data. Unlike generic HID devices, touch controllers require precise linearization and offset correction to map physical coordinates to logical screen coordinates. This article explores the best practices for retrieving, storing, and applying calibration data within a KMDF driver, ensuring compatibility with the Windows HID stack and maximizing touch accuracy.
1. The Architecture: HID over I2C Before addressing calibration, it is essential to understand where the KMDF minidriver sits. Windows provides a native Hidi2c.sys driver stack. However, many vendors choose to write a proprietary KMDF HID minidriver to handle specific hardware quirks, power management, or proprietary calibration protocols. The stack typically looks like this:
Touch Hardware (I2C Device) SPB (Simple Peripheral Bus) Controller Vendor KMDF HID Minidriver (The focus of this article) HIDClass.sys (Microsoft HID Class Driver) User Mode Applications (via Raw Input or WM_TOUCH)
2. The Calibration Data Source Calibration data generally consists of factory-set values (stored in One-Time Programmable memory or external EEPROM) or dynamic values generated by the OS (e.g., the "Tablet PC Settings" calibration tool). Best Practice: Hybrid Storage Strategy Do not rely solely on the hardware to store calibration. The driver should implement a "First Load" mechanism: kmdf hid minidriver for touch i2c device calibration best
Read factory calibration from hardware registers (via I2C). Compare against registry-stored calibration (applied by OEMs or User calibration). Use the most recent/valid dataset.
3. Implementation: Retrieving Calibration Data In a KMDF driver, I2C communication is handled asynchronously via the SPB (Simple Peripheral Bus) target. Step 3.1: Defining the Registry Interface It is a best practice to allow calibration updates via the Registry (PnP keys) rather than forcing a firmware flash. You can retrieve OEM-defined calibration data during EvtDevicePrepareHardware . // Pseudo-code for Registry Retrieval NTSTATUS RetrieveCalibrationFromRegistry(WDFDEVICE Device) { WDFKEY hKey = NULL; NTSTATUS status; DECLARE_CONST_UNICODE_STRING(valueName, L"CalibrationMatrix");
status = WdfDeviceOpenRegistryKey(Device, PLUGPLAY_REGKEY_DEVICE, KEY_READ, NULL, &hKey); Implementing Best Practices for Touch Calibration in KMDF
if (NT_SUCCESS(status)) { // Read the raw binary calibration block status = WdfRegistryQueryValue(hKey, &valueName, &CalibrationData, sizeof(CALIBRATION_STRUCT), NULL, NULL); WdfRegistryClose(hKey); } return status; }
Step 3.2: Reading from Hardware (I2C) If calibration must be read from the device, use the SPB target. This involves creating an I2C Write-Read sequence (Write the register address, Read the data). Critical: Perform this initialization in EvtDeviceD0Entry or EvtDevicePrepareHardware , never in the ISR (Interrupt Service Routine). // Simplified SPB I2C Read logic NTSTATUS ReadFactoryCalibration(WDFIOTARGET SpbTarget) { // 1. Build the Write-Read request // Write: The Register Address to read from // Read: The buffer to hold calibration data
// Ensure the I2C lock is acquired if the bus is shared // ... Submit request synchronously or asynchronously via WdfIoTargetSendIoctlSynchronously } However, many vendors choose to write a proprietary
4. Applying Calibration: The Report Descriptor This is the area where most driver implementations fail. The "Don't" Do not attempt to modify the HID Report Descriptor dynamically to inject calibration values. The HID Report Descriptor should be static and defined in the driver's resources or code. Modifying it on the fly creates cache coherency issues with HIDClass.sys . The "Do": The HIDI2C_DEVICE_RESPONSE If you are adhering to the Microsoft HID over I2C specification, the protocol defines a specific response packet: HIDI2C_DEVICE_RESPONSE . When the host requests the Report Descriptor, the device (or the driver acting as the device) responds.
Logical vs. Physical: Ensure your Report Descriptor defines the Logical Minimum and Logical Maximum correctly. Coordinate Processing: The minidriver should intercept the raw touch packets (in EvtIoRead or similar), apply the matrix transformation logic, and pass the corrected coordinates to the HID stack.