WDF_USB_CONTINUOUS_READER_CONFIG结构(wdfusb.h)

[适用于 KMDF 和 UMDF]

WDF_USB_CONTINUOUS_READER_CONFIG 结构包含框架用来为 USB 管道配置连续读取器的信息。

语法

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;

成员

Size

此结构的大小(以字节为单位)。

TransferLength

可从设备接收的数据的最大长度(以字节为单位)。

HeaderLength

从设备接收数据的缓冲区中的偏移量(以字节为单位)。 从偏移值开始,框架会将设备中的数据存储在读取缓冲区中。 换句话说,此空间位于 TransferLength大小的空间,框架在其中存储来自设备的数据。

TrailerLength

尾随缓冲区空间的长度(以字节为单位)。 此空间遵循 TransferLength大小的空间,框架在其中存储来自设备的数据。

NumPendingReads

框架将排队接收来自 I/O 目标的数据的读取请求数。 如果此值为零,框架将使用默认数量的读取请求。 如果指定的值大于允许的最大值,框架将使用允许的最大值。 有关 NumPendingReads 成员的详细信息,请参阅以下“备注”部分。

BufferAttributes

WDF_OBJECT_ATTRIBUTES 结构,该结构指定框架为每个读取请求创建的框架内存对象的对象属性。 此成员可以 NULL。 无法设置WDF_OBJECT_ATTRIBUTES结构的 ParentObject 成员。

EvtUsbTargetPipeReadComplete

指向驱动程序 EvtUsbTargetPipeReadComplete 回调函数的指针。

EvtUsbTargetPipeReadCompleteContext

框架传递给驱动程序的 EvtUsbTargetPipeReadComplete 回调函数的驱动程序定义的上下文信息的非类型化指针。

EvtUsbTargetPipeReadersFailed

指向驱动程序 EvtUsbTargetPipeReadersFailed 回调函数的指针。 此指针是可选的,可以 NULL。 有关此参数的详细信息,请参阅 WdfUsbTargetPipeConfigContinuousReader的“备注”部分。

言论

WDF_USB_CONTINUOUS_READER_CONFIG 结构用作 WdfUsbTargetPipeConfigContinuousReader 方法的输入。

若要初始化WDF_USB_CONTINUOUS_READER_CONFIG结构,驱动程序必须调用 WDF_USB_CONTINUOUS_READER_CONFIG_INIT

NumPendingReads 成员选择值时,请使用以下准则:

  • 如果希望驱动程序使用框架的默认值,请将 NumPendingReads 设置为 0。

    默认值大于 1,并且已确定在许多处理器配置上为许多设备提供相当良好的性能。

  • 如果将 NumPendingReads 设置为 1(如果驱动程序按设备传送数据的确切顺序接收数据缓冲区很重要)。
  • 根据全面的性能度量,将 NumPendingReads 设置为满足设备性能要求的数字。

    首先,使用 NumPendingReads的默认值 (0) 测试设备。 测试应包括各种硬件配置,包括不同类型的处理器和数量以及不同的 USB 主机控制器和 USB 配置。 然后,可以使用相同的测试来试验更高的值。 可能需要较高值的驱动程序是具有高中断率的设备,如果中断未快速提供服务,可能会丢失数据。

NumPendingReads 值,过大可能会降低系统的性能。 应使用满足性能要求的最低值。 通常,高于 3 或 4 的值不会提高数据吞吐量。 但是,较高的值可能会降低高频率管道上的延迟或缺失数据的可能性。

要求

要求 价值
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfusb.h (包括 Wdfusb.h)

另请参阅

EvtUsbTargetPipeReadComplete

EvtUsbTargetPipeReadersFailed

WDF_OBJECT_ATTRIBUTES

WDF_USB_CONTINUOUS_READER_CONFIG_INIT

WdfUsbTargetPipeConfigContinuousReader