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 的值不會改善數據輸送量。但較高的值可能會降低高頻率管道上遺失數據的延遲或機率。