WDF_USB_CONTINUOUS_READER_CONFIG Struktur (wdfusb.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WDF_USB_CONTINUOUS_READER_CONFIG-Struktur enthält Informationen, die das Framework zum Konfigurieren eines kontinuierlichen Lesegeräts für eine USB-Pipe verwendet.

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;

Angehörige

Size

Die Größe dieser Struktur in Byte.

TransferLength

Die maximale Länge von Daten in Bytes, die vom Gerät empfangen werden können.

HeaderLength

Ein Offset in Bytes in den Puffer, der Daten vom Gerät empfängt. Das Framework speichert Daten vom Gerät in einem Lesepuffer, beginnend mit dem Offsetwert. Mit anderen Worten, dieser Bereich steht vor dem TransferLength-Größenbereich, in dem das Framework Daten vom Gerät speichert.

TrailerLength

Die Länge eines nachgestellten Pufferraums in Bytes. Dieser Bereich folgt dem TransferLengthGröße, in dem das Framework Daten vom Gerät speichert.

NumPendingReads

Die Anzahl der Leseanforderungen, die vom Framework in die Warteschlange gestellt werden, um Daten vom E/A-Ziel zu empfangen. Wenn dieser Wert null ist, verwendet das Framework eine Standardanzahl von Leseanforderungen. Wenn der angegebene Wert größer als der zulässige Höchstwert ist, verwendet das Framework das zulässige Maximum. Weitere Informationen zum NumPendingReads Member finden Sie im folgenden Abschnitt "Hinweise".

BufferAttributes

Eine WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für das Framework-Speicherobjekt angibt, das vom Framework für jede Leseanforderung erstellt wird. Dieses Element kann NULL-sein. Sie können das ParentObject Member der WDF_OBJECT_ATTRIBUTES-Struktur nicht festlegen.

EvtUsbTargetPipeReadComplete

Ein Zeiger auf die EvtUsbTargetPipeReadComplete Rückruffunktion des Treibers.

EvtUsbTargetPipeReadCompleteContext

Ein nicht typisierter Zeiger auf treiberdefinierte Kontextinformationen, die das Framework an die EvtUsbTargetPipeReadComplete Rückruffunktion des Treibers übergibt.

EvtUsbTargetPipeReadersFailed

Ein Zeiger auf die EvtUsbTargetPipeReadersFailed Rückruffunktion. Dieser Zeiger ist optional und kann NULL-sein. Weitere Informationen zu diesem Parameter finden Sie im Abschnitt "Hinweise" WdfUsbTargetPipeConfigContinuousReader.

Bemerkungen

Die WDF_USB_CONTINUOUS_READER_CONFIG Struktur wird als Eingabe für die WdfUsbTargetPipeConfigContinuousReader-Methode verwendet.

Um eine WDF_USB_CONTINUOUS_READER_CONFIG-Struktur zu initialisieren, muss der Treiber WDF_USB_CONTINUOUS_READER_CONFIG_INITaufrufen.

Verwenden Sie die folgenden Richtlinien, wenn Sie einen Wert für das NumPendingReads Member auswählen:

Legen Sie NumPendingReads auf 0 fest, wenn Ihr Treiber den Standardwert des Frameworks verwenden soll.
Der Standardwert ist größer als 1 und wurde festgelegt, dass für viele Geräte mit vielen Prozessorkonfigurationen eine vernünftige Leistung erzielt wird.
Legen Sie NumPendingReads auf 1 fest, wenn es wichtig ist, dass Ihr Treiber Datenpuffer in der genauen Reihenfolge empfängt, in der das Gerät die Daten übermittelt.
Legen Sie NumPendingReads- auf eine Zahl fest, die die Leistungsanforderungen für Ihr Gerät basierend auf gründlichen Leistungsmessungen erfüllt.
Testen Sie zunächst Ihr Gerät mit dem Standardwert (0) für NumPendingReads. Ihre Tests sollten verschiedene Hardwarekonfigurationen enthalten, einschließlich verschiedener Typen und Nummern von Prozessoren und unterschiedlichen USB-Hostcontrollern und USB-Konfigurationen. Sie können dann mit höheren Werten experimentieren, indem Sie dieselben Tests verwenden. Ein Treiber, der möglicherweise einen höheren Wert erfordert, ist eine für ein Gerät mit hoher Unterbrechungsrate, bei dem Daten verloren gehen können, wenn Unterbrechungen nicht schnell gewartet werden.

Ein NumPendingReads- Wert, der zu groß ist, kann die Leistung eines Systems verlangsamen. Sie sollten den niedrigsten Wert verwenden, der Ihren Leistungsanforderungen entspricht. In der Regel verbessern werte, die höher als 3 oder 4 sind, den Datendurchsatz nicht. Höhere Werte können jedoch die Latenz oder die Wahrscheinlichkeit fehlender Daten auf einer Hochfrequenzpipeline verringern.