Supporting I/O in a sensor driver

The sensor sample driver communicates with a HID sensor over a USB connection. The sensor’s firmware is programmed to send periodic readings and receive requests from the driver to update its report interval or its change-sensitivity setting.

The sensor firmware uses the HID protocol to transmit the sensor data. The following diagram shows the data flow between the sample driver and 3-axis accelerometer:

  1. The sensor sends either a feature report or an input report to the HID class driver. A feature report is sent in response to a request from the driver. This report contains property data, including the sensor’s change-sensitivity setting, its report interval, and its reporting state. An input report is sent either upon request, or asynchronously in response to an event. This report contains the actual sensor data. For example, for an accelerometer, the report contains the G-forces along the x-, y-, and z-axes.
  2. The HID class driver sends feature reports to the sensor. For example, when the application requests a new change sensitivity or report interval, the driver packages these values into a feature report and uses this report to send the request to the sensor’s firmware.
The HID driver stack

The sample driver is hosted in the User Mode Driver Framework (UMDF) host process. This is labeled as the “WUDF Host Process” in the diagram. The driver receives requests from a sensor application. The driver exchanges data with the kernel-mode HID driver by way of a UMDF I/O target object.

The I/O target management and completion callback methods are implemented in the CReadWriteRequest object found in the ReadWriteRequest.cpp module.

  1. When the driver is initialized in CSensorDDI::InitSensorDevice, it creates the read, write, and IOCTL HID objects.
  2. The sample driver uses IWDFDevice::GetDefaultIoTarget to retrieve an I/O target object. (This I/O target provides a linkage to the kernel mode HID driver that sits below the sample driver in the stack.) The IWDFDevice::GetDefaultIoTarget method is invoked in the CReadWriteRequest::InitializeRequest method.
  3. After the I/O target is created, the sample driver can start to process asynchronous read and write operations.

    Read operations receive HID feature and input reports from the sensor. Input reports are handled asynchronously, while feature reports are handled synchronously. Write operations send requests to the sensor to update the change sensitivity or read report interval settings. These requests are sent as HID feature reports.

    The file Internal.h contains the HID feature and input reports for a sensor collection. Individual report descriptors are contained in the header files for each sensor.

HID read requests are implemented as shown in the following steps:

  1. They are generated in CReadWriteRequest::CreateAndSendReadRequest as IWDFIoRequest objects.
  2. They are initialized by using IWDFDevice::CreateRequest.
  3. They are forwarded by using IWDFIoRequest::Send.
  4. The CReadWriteRequest::OnCompletion callback routine processes the request data and sends the next read request. When this method processes the request data, it passes the buffer that it received from the sensor to the CSensorDDI::OnAsyncReadCallback method. This method, in turn, passes the buffer of data to a sensor-specific read method. For example, for the accelerometer, the buffer is passed to the CAccelerometer::ProcessAccelerometerAsyncRead method. The buffer contains an input report that has the most recent sensor reading.

HID write requests are implemented as follows:

  1. They are generated in CReadWriteRequest::CreateAndSendWriteRequest as IWDFIoRequest objects.
  2. They are initialized by using IWDFDevice::CreateRequest.
  3. They are forwarded by using IWDFIoRequest::Send.

For write requests, the buffer may contain only feature reports. These reports correspond to requests from the application to set the change sensitivity or report interval to a new value.

UMDF I/O targets provide multiple benefits that include state management and error handling, and lead to simpler and more robust driver code. For more advanced driver scenarios or stack configurations, UMDF I/O targets also natively support cancellation, request queuing, and request forwarding to the next lower driver.

Related topics

The Sensor Diagnostic Tool
The Sensors HID Driver Sample
Writing a Sensor Device Driver

 

 

Send comments about this topic to Microsoft

Build date: 11/29/2012

Show:
© 2015 Microsoft