WDF_USB_CONTINUOUS_READER_CONFIG-Struktur (wdfusb.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WDF_USB_CONTINUOUS_READER_CONFIG-Struktur enthält Informationen, die das Framework verwendet, um einen kontinuierlichen Reader für eine USB-Pipe zu konfigurieren.

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;

Member

Size

Die Größe (in Bytes) dieser Struktur.

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 ab dem Offsetwert. Mit anderen Worten, dieser Bereich geht dem Bereich von TransferLength voran, in dem das Framework Daten vom Gerät speichert.

TrailerLength

Die Länge eines nachgestellten Pufferraums in Bytes. Dieser Bereich folgt dem TransferLength-großen Bereich, in dem das Framework Daten vom Gerät speichert.

NumPendingReads

Die Anzahl der Leseanforderungen, die das Framework in die Warteschlange stellt, um Daten vom E/A-Ziel zu empfangen. Wenn dieser Wert 0 ist, verwendet das Framework eine Standardanzahl von Leseanforderungen. Wenn der angegebene Wert größer als das zulässige Maximum 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 das Framework für jede Leseanforderung erstellt. Dieses Element kann NULL sein. Sie können das ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur nicht festlegen.

EvtUsbTargetPipeReadComplete

Ein Zeiger auf die EvtUsbTargetPipeReadComplete-Rückruffunktion des Treibers.

EvtUsbTargetPipeReadCompleteContext

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

EvtUsbTargetPipeReadersFailed

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

Hinweise

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_INIT aufrufen.

Verwenden Sie die folgenden Richtlinien, wenn Sie einen Wert für das NumPendingReads-Element 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 als relativ gute Leistung für viele Geräte auf vielen Prozessorkonfigurationen festgelegt.
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 erfüllt, basierend auf gründlichen Leistungsmessungen.
Testen Sie zunächst Ihr Gerät mit dem Standardwert (0) für NumPendingReads. Ihre Tests sollten verschiedene Hardwarekonfigurationen umfassen, einschließlich unterschiedlicher Typen und Anzahl von Prozessoren und verschiedenen USB-Hostcontrollern und USB-Konfigurationen. Anschließend können Sie mit höheren Werten experimentieren, indem Sie dieselben Tests verwenden. Ein Treiber, der möglicherweise einen höheren Wert erfordert, ist ein Treiber für ein Gerät mit einer hohen Unterbrechungsrate, bei dem Daten verloren gehen können, wenn Interrupts nicht schnell gewartet werden.

Ein zu großer NumPendingReads-Wert kann die Leistung eines Systems verlangsamen. Sie sollten den niedrigsten Wert verwenden, der Ihre Leistungsanforderungen erfüllt. 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 das Risiko, dass Daten in einer Hochfrequenzpipe fehlen, verringern.