struktur WDF_USB_CONTINUOUS_READER_CONFIG (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Struktur WDF_USB_CONTINUOUS_READER_CONFIG berisi informasi yang digunakan kerangka kerja untuk mengonfigurasi pembaca berkelanjutan untuk pipa USB.

Sintaks

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;

Anggota

Size

Ukuran, dalam byte, dari struktur ini.

TransferLength

Panjang maksimum, dalam byte, data yang dapat diterima dari perangkat.

HeaderLength

Offset, dalam byte, ke dalam buffer yang menerima data dari perangkat. Kerangka kerja akan menyimpan data dari perangkat dalam buffer baca, dimulai dari nilai offset. Dengan kata lain, ruang ini mendahului ruang berukuran TransferLength tempat kerangka kerja menyimpan data dari perangkat.

TrailerLength

Panjangnya, dalam byte, dari ruang buffer berikutnya. Ruang ini mengikuti ruang berukuran TransferLength tempat kerangka kerja menyimpan data dari perangkat.

NumPendingReads

Jumlah permintaan baca yang akan diantrekan kerangka kerja untuk menerima data dari target I/O. Jika nilai ini nol, kerangka kerja menggunakan jumlah permintaan baca default. Jika nilai yang ditentukan lebih besar dari maksimum yang diizinkan, kerangka kerja menggunakan maksimum yang diizinkan. Untuk informasi selengkapnya tentang anggota NumPendingReads , lihat bagian Keterangan berikut ini.

BufferAttributes

Struktur WDF_OBJECT_ATTRIBUTES yang menentukan atribut objek untuk objek memori kerangka kerja yang dibuat kerangka kerja untuk setiap permintaan baca. Anggota ini bisa NULL. Anda tidak dapat mengatur anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES.

EvtUsbTargetPipeReadComplete

Penunjuk ke fungsi panggilan balik EvtUsbTargetPipeReadComplete driver.

EvtUsbTargetPipeReadCompleteContext

Penunjuk yang tidak ditik ke informasi konteks yang ditentukan driver yang diteruskan kerangka kerja ke fungsi panggilan balik EvtUsbTargetPipeReadComplete driver.

EvtUsbTargetPipeReadersFailed

Penunjuk ke fungsi panggilan balik EvtUsbTargetPipeReadersFailed driver. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan dari WdfUsbTargetPipeConfigContinuousReader.

Keterangan

Struktur WDF_USB_CONTINUOUS_READER_CONFIG digunakan sebagai input ke metode WdfUsbTargetPipeConfigContinuousReader .

Untuk menginisialisasi struktur WDF_USB_CONTINUOUS_READER_CONFIG, driver harus memanggil WDF_USB_CONTINUOUS_READER_CONFIG_INIT.

Gunakan panduan berikut saat memilih nilai untuk anggota NumPendingReads :

Atur NumPendingReads ke 0 jika Anda ingin driver Anda menggunakan nilai default kerangka kerja.
Nilai default lebih besar dari 1 dan telah ditentukan untuk memberikan performa yang cukup baik untuk banyak perangkat pada banyak konfigurasi prosesor.
Atur NumPendingReads ke 1 jika penting bahwa driver Anda menerima buffer data dalam urutan yang tepat bahwa perangkat mengirimkan data.
Atur NumPendingReads ke angka yang memenuhi persyaratan performa untuk perangkat Anda, berdasarkan pengukuran performa menyeluruh.
Pertama, uji perangkat Anda dengan nilai default (0) untuk NumPendingReads. Pengujian Anda harus mencakup berbagai konfigurasi perangkat keras, termasuk berbagai jenis dan jumlah prosesor serta pengontrol host USB dan konfigurasi USB yang berbeda. Anda kemudian dapat bereksperimen dengan nilai yang lebih tinggi, menggunakan pengujian yang sama. Driver yang mungkin memerlukan nilai lebih tinggi adalah salah satu untuk perangkat yang memiliki tingkat interupsi tinggi, di mana data dapat hilang jika gangguan tidak dilayanakan dengan cepat.

Nilai NumPendingReads yang terlalu besar dapat memperlambat performa sistem. Anda harus menggunakan nilai terendah yang memenuhi persyaratan performa Anda. Biasanya, nilai yang lebih tinggi dari 3 atau 4 tidak meningkatkan throughput data. Tetapi nilai yang lebih tinggi dapat mengurangi latensi, atau kemungkinan data hilang, pada pipa frekuensi tinggi.