WDF_USB_CONTINUOUS_READER_CONFIG 结构 (wdfusb.h)

项目
02/27/2024

[适用于 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 的值不会提高数据吞吐量。但较高的值可能会降低高频率管道上的延迟或丢失数据的可能性。