struttura WDF_USB_CONTINUOUS_READER_CONFIG (wdfusb.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

La struttura WDF_USB_CONTINUOUS_READER_CONFIG contiene informazioni usate dal framework per configurare un lettore continuo per una pipe USB.

Sintassi

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;

Members

Size

Dimensione, in byte, della struttura.

TransferLength

Lunghezza massima, in byte, dei dati che possono essere ricevuti dal dispositivo.

HeaderLength

Offset, in byte, nel buffer che riceve i dati dal dispositivo. Il framework archivierà i dati dal dispositivo in un buffer di lettura, a partire dal valore di offset. In altre parole, questo spazio precede lo spazio di dimensioni TransferLength in cui il framework archivia i dati dal dispositivo.

TrailerLength

Lunghezza, in byte, di uno spazio del buffer finale. Questo spazio segue lo spazio di dimensioni TransferLength in cui il framework archivia i dati dal dispositivo.

NumPendingReads

Numero di richieste di lettura che il framework accoderà per ricevere dati dalla destinazione di I/O. Se questo valore è zero, il framework usa un numero predefinito di richieste di lettura. Se il valore specificato è maggiore del massimo consentito, il framework usa il valore massimo consentito. Per altre informazioni sul membro NumPendingReads , vedere la sezione Osservazioni seguente.

BufferAttributes

Struttura WDF_OBJECT_ATTRIBUTES che specifica gli attributi oggetto per l'oggetto memoria framework creato dal framework per ogni richiesta di lettura. Questo membro può essere NULL. Non è possibile impostare il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES.

EvtUsbTargetPipeReadComplete

Puntatore alla funzione di callback EvtUsbTargetPipeReadComplete del driver.

EvtUsbTargetPipeReadCompleteContext

Puntatore non tipizzato alle informazioni sul contesto definite dal driver che il framework passa alla funzione di callback EvtUsbTargetPipeReadComplete del driver.

EvtUsbTargetPipeReadersFailed

Puntatore alla funzione di callback EvtUsbTargetPipeReadersFailed del driver. Questo puntatore è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni di WdfUsbTargetPipeConfigContinuousReader.

Commenti

La struttura WDF_USB_CONTINUOUS_READER_CONFIG viene usata come input per il metodo WdfUsbTargetPipeConfigContinuousReader .

Per inizializzare una struttura di WDF_USB_CONTINUOUS_READER_CONFIG, il driver deve chiamare WDF_USB_CONTINUOUS_READER_CONFIG_INIT.

Usare le linee guida seguenti quando si sceglie un valore per il membro NumPendingReads :

Impostare NumPendingReads su 0 se si vuole che il driver usi il valore predefinito del framework.
Il valore predefinito è maggiore di 1 ed è stato determinato a garantire prestazioni ragionevolmente ottimali per molti dispositivi in molte configurazioni del processore.
Impostare NumPendingReads su 1 se è importante che il driver riceva buffer di dati nell'ordine esatto in cui il dispositivo recapita i dati.
Impostare NumPendingReads su un numero che soddisfi i requisiti di prestazioni per il dispositivo, in base a misurazioni approfondite delle prestazioni.
Prima di tutto, testare il dispositivo con il valore predefinito (0) per NumPendingReads. I test devono includere varie configurazioni hardware, tra cui diversi tipi e numeri di processori e diversi controller host USB e configurazioni USB. È quindi possibile sperimentare valori più elevati usando gli stessi test. Un driver che potrebbe richiedere un valore superiore è uno per un dispositivo con una frequenza di interruzione elevata, in cui i dati possono essere persi se gli interrupt non vengono gestiti rapidamente.

Un valore NumPendingReads troppo grande può rallentare le prestazioni di un sistema. È consigliabile usare il valore più basso che soddisfi i requisiti di prestazioni. In genere, i valori superiori a 3 o 4 non migliorano la velocità effettiva dei dati. Ma valori più elevati potrebbero ridurre la latenza o la probabilità di dati mancanti su una pipe ad alta frequenza.