WDF_USB_CONTINUOUS_READER_CONFIG structure (wdfusb.h)
[Applies to KMDF and UMDF]
The WDF_USB_CONTINUOUS_READER_CONFIG structure contains information that the framework uses to configure a continuous reader for a USB pipe.
Syntax
typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
ULONG Size;
size_t TransferLength;
size_t HeaderLength;
size_t TrailerLength;
UCHAR NumPendingReads;
PWDF_OBJECT_ATTRIBUTES BufferAttributes;
PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
WDFCONTEXT EvtUsbTargetPipeReadCompleteContext;
PFN_WDF_USB_READERS_FAILED EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;
Members
Size
The size, in bytes, of this structure.
TransferLength
The maximum length, in bytes, of data that can be received from the device.
HeaderLength
An offset, in bytes, into the buffer that receives data from the device. The framework will store data from the device in a read buffer, beginning at the offset value. In other words, this space precedes the TransferLength-sized space in which the framework stores data from the device.
TrailerLength
The length, in bytes, of a trailing buffer space. This space follows the TransferLength-sized space in which the framework stores data from the device.
NumPendingReads
The number of read requests that the framework will queue to receive data from the I/O target. If this value is zero, the framework uses a default number of read requests. If the specified value is greater than the permitted maximum, the framework uses the permitted maximum. For more information about the NumPendingReads member, see the following Remarks section.
BufferAttributes
A WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the framework memory object that the framework creates for each read request. This member can be NULL. You cannot set the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure.
EvtUsbTargetPipeReadComplete
A pointer to the driver's EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadCompleteContext
An untyped pointer to driver-defined context information that the framework passes to the driver's EvtUsbTargetPipeReadComplete callback function.
EvtUsbTargetPipeReadersFailed
A pointer to the driver's EvtUsbTargetPipeReadersFailed callback function. This pointer is optional and can be NULL. For more information about this parameter, see the Remarks section of WdfUsbTargetPipeConfigContinuousReader.
Remarks
The WDF_USB_CONTINUOUS_READER_CONFIG structure is used as input to the WdfUsbTargetPipeConfigContinuousReader method.
To initialize a WDF_USB_CONTINUOUS_READER_CONFIG structure, the driver must call WDF_USB_CONTINUOUS_READER_CONFIG_INIT.
Use the following guidelines when choosing a value for the NumPendingReads member:
-
Set NumPendingReads to 0 if you want your driver to use the framework's default value.
The default value is greater than 1 and has been determined to provide reasonably good performance for many devices on many processor configurations.
- Set NumPendingReads to 1 if it is important that your driver receive data buffers in the exact order that the device delivers the data.
-
Set NumPendingReads to a number that meets the performance requirements for your device, based on thorough performance measurements.
First, test your device with the default value (0) for NumPendingReads. Your tests should include various hardware configurations, including different types and numbers of processors and different USB host controllers and USB configurations. You can then experiment with higher values, using the same tests. A driver that might require a higher value is one for a device that has a high interrupt rate, where data can be lost if interrupts are not serviced rapidly.
Requirements
| Requirement | Value |
|---|---|
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfusb.h (include Wdfusb.h) |